升级至 v0.3.0

本文对应 Agent Java SDK v0.3.0、Java 8+ 与该标签的公开契约。示例在合作方后端运行；先按快速开始初始化 client。

旧 SDK 升级

是否必须升级

升级后客户端 baseUrl、agentCode、apiSecret 配置方式不变；已有订单和用户映射继续保留。

固定稳定源码标签安装

公开 Java SDK：6mm-com/agent-java-sdk。本指南固定 v0.3.0，使用 Java 8 字节码目标。安装时核对 HEAD 与该标签解析出的提交一致。

在新的 SDK 源码目录安装，避免覆盖已有商户改动：

git clone --branch v0.3.0 --single-branch https://github.com/6mm-com/agent-java-sdk.git agent-java-sdk-v0.3.0
cd agent-java-sdk-v0.3.0
git rev-parse HEAD
git rev-parse 'v0.3.0^{commit}'
mvn install

核对两条 git rev-parse 输出一致后，在商户项目声明：

<dependency>
    <groupId>com.sixmm.exchange.sdk</groupId>
    <artifactId>agent</artifactId>
    <version>0.3.0</version>
</dependency>

该坐标来自 v0.3.0 POM。GitHub 标签发布不等于 Maven Central 发布：本地 mvn install 后本机可以解析；CI 和其他开发机需执行同样安装，或从商户自己的制品私服获取已核对的 JAR/POM。

使用 Maven 检查依赖树，确保只有预期版本：

mvn dependency:tree -Dincludes=com.sixmm.exchange.sdk:agent

若旧项目已有自建 0.3.0 制品，核对其是否来自公开 v0.3.0 标签，并确认包含六类查询方法及新的请求/响应模型。共享私服中的既有同坐标制品由商户按私服策略处理，不静默覆盖。

升级后适配点

1. 请求/响应支持 environment。旧请求省略环境保持实盘兼容；显式传环境会回显环境，旧严格 JSON 模型可能不能解析，需升级模型。
2. 资产查询新增可选 Funding：使用 withFunding() 后读取 funding，避免拿 Contract 余额显示秒合约余额。
3. Funding 使用新 /wallet-transfer、/wallet-transfer-status 路径；不要调用旧拼写或原合约查单接口。
4. 六查询使用 platformUserIds 字符串数组和游标，签名器必须支持紧凑 JSON 数组。旧 Java List.toString() 格式不符合新接口签名。
5. 划转订单、永续交易委托、条件单及成交分别保存，响应状态字段按各接口契约解析。
6. 模拟环境回调增加 environment；原始请求体验签方式不变，幂等时同时校验原单环境。
7. 后端 Java SDK 与浏览器 Widget SDK 分别管理版本。后端升级不自动改变页面或前端交易模式；已有通用内嵌认证无需增加预测专用鉴权。

自研 HTTP 客户端

不使用 Java SDK 的商户可按 Agent HTTP 契约自行接入。新增能力需要同步适配请求字段、响应模型、环境选择、数组签名和分页逻辑；签名规则见密钥与 HMAC 签名。

来源与相关指南

• 官方 v0.3.0 源码
• 合约查询与分页
• Funding 钱包