生命周期

API 围绕单一的、持续演进的 GraphQL 端点构建。这种架构确保新功能和性能改进能够持续交付，而无需在 API 版本之间进行迁移。

本页概述了 API 中不同的稳定性级别、稳定 API 的稳定性保证、变更的类型（破坏性与非破坏性），以及弃用的管理方式。有关当前处于预览阶段的功能，请参见实验性功能。

功能生命周期

每个功能都处于三个稳定性级别之一：alpha、beta 或 stable。大多数功能会依次经历这些级别，而稳定功能只能通过弃用流程下线。

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

稳定 API

稳定功能代表 API 中可用于生产环境的核心部分。变更分为两类：非破坏性变更和破坏性变更。

非破坏性变更

向后兼容的新增内容，不会影响现有集成。这些变更会持续发布，无需提前通知，也无需弃用流程。

非破坏性变更包括：

• 添加新的查询、变更或订阅。
• 为现有操作添加新的可选输入参数。
• 添加带有默认值且保持现有行为的新参数。
• 为现有操作的输出添加新字段。
• 将必需的输入参数改为可选。
• 为现有枚举类型添加新值。

为非破坏性变更做好准备

非破坏性变更仍可能影响做出严格假设的客户端。为使集成保持稳健：

• 避免严格的对象反序列化，否则当负载中出现额外属性时会失败。
• GraphQL enum 类型是非穷尽的，并会随时间扩展。请始终在客户端逻辑中实现回退的默认分支。
• 检查错误的 extensions.exception.code 值，而不是匹配人类可读的错误字符串。

破坏性变更和弃用

破坏性变更可能会破坏正在运行的现有集成。因此，任何破坏性变更都必须首先经过 12 个月的弃用流程。

破坏性变更包括：

• 删除或重命名现有的查询、变更、订阅、字段或输入参数。
• 删除或重命名枚举值。
• 更改现有字段或输入参数的数据类型。
• 添加新的必需输入参数。
• 将可选输入参数改为必需。
• 更改现有字段的业务逻辑或行为。
• 将输出字段从非空（!）改为可为空。
• 更改输入参数或字段的默认值。
• 更改分页默认值、最大页面大小或文档中说明的排序顺序。

弃用时间线

当破坏性变更需要删除或替换稳定功能时，将遵循严格的三阶段时间线：

1. 弃用公告该功能在 GraphQL schema 中被标记为 @deprecated 指令。如适用，将提供迁移路径。弃用及相应的移除日期会同时通过三个监控渠道公布。
2. 有效通知期（第 1–12 个月）已弃用的功能保持完全可用。如果提供了迁移路径，集成方应在这 12 个月的窗口期内更新其应用并采用新字段。
3. 永久移除到达移除日期时，该功能将被永久移除。此后任何使用该功能的请求都将无法通过 schema 验证，并返回 GraphQL 错误。

跟踪弃用

通过三个渠道识别并跟踪即将下线的功能：

• 在您的 schema 工具中检查 @deprecated(reason: "...") 指令。
• 在 API 的旧版部分或弃用门户中查看停用日期和迁移指南。
• 监控 API 响应中直接返回的 DEPRECATED_FEATURE 警告。

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}