模式弃用

利用SDL和工具管理弃用

您的图谱治理组应概述一个涵盖整个公司的字段轮换策略，以优雅地处理统一图谱中类型的字段降级。

GraphQL API可以进行版本控制，但我们在Apollo发现，组织利用GraphQL固有的进化特性，快速迭代API的情况更为普遍。然而，这样做需要与API消费者进行清晰的沟通，尤其是在执行字段降级时。

使用@deprecated 类型系统指令

作为第一步，@deprecated 指令，该指令在GraphQL规范中定义，应在降级架构中的字段或枚举值时应用。它的单个reason 参数也可以为API消费者提供关于使用哪些字段或枚举值的一些指导。例如，下面的示例可以指示相关的topProducts 查询已被降级如下：

1
extend type Query {
2
  """
3
  Fetch a simple list of products with an offset
4
  """
5
  topProducts(
6
    "How many products to retrieve per page."
7
    first: Int = 5
8
  ): [Product] @deprecated(reason: "Use `products` instead.")
9

10
  """
11
  Fetch a paginated list of products based on a filter type.
12
  """
13
  products(
14
    "How many products to retrieve per page."
15
    first: Int = 5
16
    "Begin paginating results after a product ID."
17
    after: Int = 0
18
    "Filter products based on a type."
19
    type: ProductType = LATEST
20
  ): ProductConnection
21
}

使用字段使用度指标来评估何时可安全移除字段

在更新服务模式的schema并添加新@deprecated指令之后，将弃用信息传达给所有相关人员同样重要。利用专门的Slack频道或团队会议可能是传达这种通知的合适渠道，并且应该与任何附加的迁移指导一并提供。

在此阶段，一个关键问题仍然存在：“何时可以安全地移除弃用的字段？”为了确定答案而不会对客户端应用程序造成任何破坏性更改，您必须依赖您的可观察性工具。

具体来说，位于客户端与操作表页面中的洞察页面的GraphOS Studio可以为了解客户端可能仍在使用哪些弃用的字段提供洞察。

此外，模式检查将检查推送到已注册schema的最新操作跟踪数据中的任何更改，以确保可以在不破坏现有客户端的情况下完成弃用字段滚动更新。通常需要客户端识别自身以便在做出破坏性更改之前与他们联系。