迁移与版本控制策略
公共 API 在 v1 范围内保持兼容性。破坏性变更需要经过明确的策略审查、一条变更日志条目以及一条迁移路径。
兼容性承诺
- 可在
v1范围内交付附加字段和端点。 - 现有响应字段在
v1范围内不会改变含义。 - 不会在没有兼容性计划的情况下向现有
v1写操作添加必填请求字段。 - SDK 和 MCP 接口会对照相同的 OpenAPI 作用域和操作模型进行检查。
这对你意味着什么
- 容忍响应中出现的新的、无法识别的字段（不要因此失败）。
- 将 SDK 固定到已知版本，并审慎地升级。
- 关注变更日志以获知附加变更。
源策略
破坏性变更策略维护于 docs/developer-platform/openapi-breaking-change-policy.md，并由契约检查强制执行。