{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/zh/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API 版本与废弃策略"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-版本与废弃策略","__idx":0},"children":["API 版本与废弃策略"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["MoreLogin 在每份 OpenAPI 文档的 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.version"]}," 中发布机器可读的契约快照版本。该版本采用日历格式 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},"，标识的是文档契约，而不是请求 URL 里的版本段。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"兼容性规则","__idx":1},"children":["兼容性规则"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"变更"},"children":["变更"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"归类"},"children":["归类"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"文档处理方式"},"children":["文档处理方式"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["新增可选请求字段、响应字段、操作或枚举值"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["增量变更"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["记入变更日志，并更新全部本地化规格"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["澄清说明或修正示例，且不改变运行时行为"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["文档修正"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["当它改变了接入指引时记入"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["把可选字段改为必填、删除或重命名字段/操作、收窄可接受值、改变既有语义"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["破坏性变更"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["在移除前提供迁移路径与单独版本化的契约"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["给操作标注 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated: true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["废弃"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["记录替代方案、公告日期，以及在获批后记录计划移除日期"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["客户端应在业务逻辑允许的前提下忽略未知的响应字段与枚举值，这能减少增量发布带来的破坏。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"废弃元数据","__idx":2},"children":["废弃元数据"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 操作是权威的机器可读位置。被废弃的操作必须包含："]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated: true"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["说明中指明替代方案，或明确说明没有替代"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API 变更日志中的公告条目"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["仅在产品与网关负责人批准后才写入的计划移除日期"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["目前不保证统一的最短废弃期。在明确公布移除日期之前，客户端应把该操作视为仍受支持，但应安排迁移。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"事实来源","__idx":3},"children":["事实来源"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["运行时行为始终具有权威性。OpenAPI、示例、本地化副本、端点行为清单与变更日志在 CI 中一并校验，以防契约漂移。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"验证级别","__idx":4},"children":["验证级别"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["仓库质量门禁通过，证明 OpenAPI 文件、示例、链接、本地化副本和治理产物在仓库内部保持一致。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["页面渲染检查通过，证明抽查的文档路由能够加载和显示，且没有客户端错误。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["只有使用凭证对已部署 API 执行冒烟测试，才能证明生产行为与发布契约一致。该仓库默认不执行此测试，因此发行说明必须单独注明是否完成了生产验证。"]}]},"headings":[{"value":"API 版本与废弃策略","id":"api-版本与废弃策略","depth":1},{"value":"兼容性规则","id":"兼容性规则","depth":2},{"value":"废弃元数据","id":"废弃元数据","depth":2},{"value":"事实来源","id":"事实来源","depth":2},{"value":"验证级别","id":"验证级别","depth":2}],"frontmatter":{"seo":{"title":"API 版本与废弃策略"}},"lastModified":"2026-09-05T06:38:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/zh/api-reference/appendix/versioning-and-deprecation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}