概述版本控制政策向后兼容性 V1至V2迁移端点变更响应格式更新弃用时间表重大变更分步迁移指南支持与资源

API文档

API迁移指南——版本升级

规划并执行无缝API版本升级。了解重大变更、弃用时间表以及Smart Money API版本间迁移的最佳实践。

发布于2026年3月21日 • 阅读时间16分钟 • 高级

迁移概述

Smart Money API持续开发并定期更新。本指南涵盖版本管理、重大变更及如何零停机迁移集成。

迁移核心原则：

语义化版本控制 ——严格遵循MAJOR.MINOR.PATCH格式
长期支持 ——前一主版本提供24个月以上支持
弃用警告 ——所有重大变更提前6个月通知
并行版本 ——迁移期间可同时运行v1和v2
自动化测试 ——提供测试套件兼容性工具

当前状态： v1（现行版本），v2（测试版，2026年Q2全面可用）。v1支持至2028年Q1。

版本控制政策

语义化版本控制

版本格式
API版本：MAJOR.MINOR.PATCH
示例：2.1.3
MAJOR (2) - 重大变更，新架构
MINOR (1) - 向后兼容的功能
PATCH (3) - 错误修复，安全更新

版本发布周期

阶段	持续时间	特性
Alpha	2-4周	频繁重大变更，仅限测试
Beta	4-8周	基本稳定，收集社区反馈
候选版本	2-4周	生产就绪，最终优化
全面可用	24个月以上	完整生产支持

30秒获取API密钥

准备开发？立即获取免费API密钥（每日100次调用，无需绑卡），开始获取实时巨鲸、资金费率及链上数据。

获取API密钥 →

向后兼容性

版本兼容性

在主版本内，可安全升级至更新的次版本/修订版本：

端点URL ——保持不变
必填字段 ——永不删除（仅新增可选字段）
HTTP状态码 ——现有场景保持不变
响应结构 ——核心字段保持一致
认证机制 ——认证方式无变化

渐进式弃用

弃用时间表
// 第1月：发布弃用公告
// 功能标记弃用标头
Deprecation: version="2.2", sunset="2026-09-01"
// 第3-6月：主动弃用期
// API返回警告但仍可用
X-Deprecation-Warning: 该端点将于2026-09-01移除
// 第6月：最终移除
// 端点返回410 Gone
HTTP/1.1 410 Gone

V1至V2迁移

主要变更

REST API重设计 ——更清晰的资源端点
响应格式 ——统一封装，更好的错误处理
认证机制 ——新增OAuth 2.0支持（仍兼容API密钥）
速率限制 ——更精细明确的限制规则
Webhooks ——重新设计事件格式与签名

端点映射表

v1端点	v2端点	变更说明
GET /whales	GET /v2/whales/tracking	重组结构，新增筛选功能
GET /funding	GET /v2/derivatives/funding-heatmap	强制要求交易所参数
GET /positions	GET /v2/derivatives/positions	新增聚合选项

端点变更

请求参数变更

V1请求示例
// V1: 资金费率查询
GET /v1/funding?symbol=BTCUSDT&exchange=binance

V2请求示例
// V2: 相同数据，更清晰的结构
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

响应格式更新

V1响应结构

V1格式
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

V2响应结构

V2格式
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

关键差异： 无状态包装层，字段命名更清晰，元数据标准化。

弃用时间线

计划弃用项

功能	公告日期	终止日期	替代方案
/v1/whales	2026年1月	2028年1月	/v2/whales/tracking
/v1/funding	2026年1月	2028年1月	/v2/derivatives/funding-heatmap
仅API密钥认证	2026年3月	2027年3月	OAuth 2.0（密钥仍可用）
Webhook v1格式	2026年第二季度	2027年第二季度	Webhook v2格式

重大变更详情

移除的端点

/v1/stats — 由/v2/metrics替代
/v1/historical — 由带新参数的/v2/historical替代
/v1/alerts/create — 由POST /v2/alerts替代

参数变更

limit — 默认值从100改为20（需显式指定！）
timeframe — 历史查询现为必填项
sort — 格式从"field asc"改为"field:asc"

响应字段变更

funding → funding_rate
price → mark_price
vol → volume_quote

分步迁移指南

阶段1：规划（第1-2周）

审计现有集成的弃用功能
将v1端点映射到v2对应项
识别影响代码的重大变更
制定测试策略和时间表

阶段2：开发（第3-4周）

在版本控制中创建v2分支
将所有API端点更新为v2 URL
更新请求/响应处理逻辑
在沙箱环境运行单元测试

阶段3：测试（第5-6周）

运行完整集成测试套件
测试错误场景和边界条件
对v2端点进行负载测试
更新代码的安全审计

阶段4：预发布（第7周）

将v2代码部署到预发布环境
运行完整验收测试
获得利益相关方签署
准备回滚计划

阶段5：生产（第8周）

蓝绿部署至生产环境
监控指标和错误率
待命处理支持问题
逐步停用v1代码

支持与资源

可用工具

迁移验证器 — 检查代码中的弃用用法
API升级检查器 — 对比v1和v2兼容性
迁移检查清单 — 含任务和时间表的PDF
代码示例 — 迁移前后的代码示例

获取帮助

邮件：[email protected]
文档：参见changelog-versioning.html
Discord：社区支持频道
企业版：专属迁移工程师

立即开始迁移

使用全面的迁移工具、文档和支持升级至API v2。支持零停机迁移。

探索V2

V1支持持续至2028年1月。立即规划迁移。