SDK 版本、支持范围与升级
本页内容
接入或升级 SDK 前,先核对运行环境、版本和实际需要的能力。本页说明源码包的交付方式、环境限制,以及保留原任务的升级步骤。
选择接入方式
服务端项目使用与项目语言一致的 SDK。浏览器、Vue、iOS 和安卓应用通过自己的后端或已登记并获准的 OAuth 接入;Java 服务端包不能直接视为安卓 SDK。
当前交付源码预览和本地包配置,尚未正式发布到公共包仓库。请从本站下载并固定源码包,不要据本地包名直接假定 Composer、npm、PyPI 或 Maven 中已有同名官方版本。
核对版本和环境
当前六种服务端 SDK 属于 1.26.0-preview.1 预览系列;Python 使用 alpha 版本格式,Java 使用 SNAPSHOT 格式。C 单独使用 0.8.0-preview.1,升级时分别核对。接口定义版本为 1.22.0-preview.1。
| 语言 | 源码要求 | 开始使用 |
|---|---|---|
| Python | 3.10+ | 下载与首次调用 |
| PHP | 8.3+,启用 ext-curl | 下载与首次调用 |
| Node.js / TypeScript | Node.js 20+ | 下载与首次调用 |
| Go | 1.22+ | 下载与首次调用 |
| Java | JDK 17+ | 下载与首次调用 |
| Rust | 1.88+,使用 Tokio | 下载与首次调用 |
| C | C11、CMake 3.20+,需原生依赖 | 下载与首次调用 |
最低版本表示源码的运行基线。实际项目还要检查操作系统、TLS、扩展和文件系统权限。PHP 当前验证 8.3、8.4、8.5;C 的文件助手使用 Linux / POSIX 接口,其他系统可能返回 UnsupportedPlatform。原生库与依赖说明见对应语言指南。
下载后核对包内 SHA256SUMS,并独立保存源码包摘要与所用提交。包内清单用于发现文件损坏,不能单独证明一个不可信来源就是官方来源。
确认能力与限制
七种现有服务端 SDK 覆盖当前 57 个用户 API 操作。能否调用某个操作,仍由账号接入许可、动作、应用归属、来源 IP 和预算共同决定。更新 SDK 不会自动增加这些权限。
| 需要完成的任务 | 使用方式 | 需要另外确认 |
|---|---|---|
| 单次查询或写入 | 使用具体接口对应的 SDK 方法。 | 所属产品、完整资源 ID、JSON 字段和写入幂等键。 |
| 上传、等待或下载 | 使用任务助手组合调用。 | 原任务状态、文件身份、可信摘要和受信存储来源。 |
| 接收业务通知 | 使用 SDK 验签并在持久事务提交后返回回执。 | 受信订阅、回调密钥、去重和应用归属。 |
| 网页或移动端访问 | 使用自己的后端或 OAuth。 | 终端授权范围,且不内置长期 Secret。 |
上传使用统一入口:平台选择文件传输服务,SDK 按短期指令自动传输。业务代码无需选择存储厂商、配置存储账号或处理后台启用流程。
文件下载助手不覆盖已经存在的目标文件。请为每次独立下载选择新路径,并从可信业务记录取得预期摘要。
升级前准备
- 保存旧源码包、包配置、依赖锁文件及摘要,保留可回退的部署版本。
- 记录正在执行的应用 ID、上传任务 ID、签名任务 ID、报价 ID 和原幂等键。保留对应文件身份与请求内容,不把 Secret 或短期存储地址写入业务检查点。
- 阅读版本说明,确认新字段是否可空、默认行为是否变化,以及是否涉及 C 的类型或 ABI。C 预览升级后重新编译调用方。
- 在独立测试目录或预发布环境准备新包,保留原账号权限、来源 IP 和预算设置。
执行升级与验证
- 核对新包摘要,按语言指南安装。保留 Go 的本地模块配置、Rust 的 Cargo.lock 和 C 的配套头文件。
- 先执行身份查询,核对账号和权限,再查询一个自己的应用。记录 HTTP 状态与 request_id。
- 使用已有任务验证查询和恢复。等待超时后继续原任务,不通过重新提交签名、付款或核销来测试升级。
- 检查本项目实际使用的分页、空值、金额字符串、通知验签与文件助手,再逐步切换服务端实例。
- 确认请求正常后保留升级记录,按原策略处理旧版本和仍在执行的任务。
预览版本可能收紧非法输入或增加类型要求。升级前验证调用方,不能仅凭“编译成功”判断原有业务流程都已兼容。
回退与问题报告
发现兼容问题时先暂停新增写入,保留原资源和操作记录。恢复旧 SDK 后,先查询已有上传、签名、报价或回执,确认真实结果,再决定是否继续原操作。不要更换幂等键重复扣款。
提供 SDK 版本、运行环境、操作名、失败时间、HTTP 状态、错误码、request_id 和脱敏的最小复现。不要提交 Secret、安全令牌、开通密钥、带授权的链接或设备明细。接入排查步骤见接入常见问题。