跳到主要内容

API 版本策略

税鹰眼数据开放平台遵循语义化版本管理，确保向后兼容性。

版本格式​

API 基础路径包含主版本号：

https://api.shuiyingyan.com/api/v1/developer/...
                            ^^^
                          主版本号

兼容性承诺​

向后兼容（不影响已有集成）​

以下变更被视为向后兼容，可能随时上线：

  • ✅ 新增可选请求参数
  • ✅ 新增响应字段
  • ✅ 新增 API 端点
  • ✅ 新增枚举值（在非必填字段中）
  • ✅ 修正错误行为
  • ✅ 性能优化

破坏性变更（需要主版本升级）​

以下变更会通过新版本（如 v2）发布：

  • ❌ 移除已有字段或端点
  • ❌ 重命名字段
  • ❌ 变更字段数据类型
  • ❌ 新增必填参数
  • ❌ 变更认证方式

版本生命周期​

阶段说明时长
Active正常维护，接受新功能—
Deprecated不再添加新功能，仅修复安全问题≥ 6 个月
Sunset停止服务—

废弃通知​

当 API 版本进入 Deprecated 阶段：

  1. 响应头中包含废弃警告：

    Deprecation: true
    Sunset: Sat, 31 Dec 2026 23:59:59 GMT
    Link: </docs/migration/v2>; rel="successor-version"

  2. 控制台和文档站发布迁移指南

当前版本​

版本状态说明
v1Active当前稳定版本

最佳实践​

建议
  1. 固定版本 — 始终使用明确的版本路径 (/api/v1/...)
  2. 宽容解析 — 忽略未知的响应字段（新字段可能随时添加）
  3. 关注更新 — 订阅变更日志，及时了解新功能和废弃计划
  4. 提前迁移 — 收到废弃通知后尽早完成迁移