GraphQL API 中已弃用的参数（规范 2021）

Question

我有一个根据 2021 年 10 月的规范描述的 GraphQL API。

我有一个论点

size

我想删除。

type Product {
  picture(size: Int): Url
}

但是如果没有在 API 规范中通知消费者，我无法立即删除它。我知道

工作草案规范允许使用带有参数的@deprecated指令，但2021规范不允许这样做。

如何在不违反2021规范的情况下以知情的方式删除该字段？

我有一个想法来弃用该字段并在其旁边创建一个具有相同名称但不带参数的字段，但不幸的是这不是一个有效的操作。

Answer 1

这里没有一个

伟大的解决方案，但我可以告诉你我的团队决定做什么：要么创建“旁边具有相同名称的字段”（+V2

），要么创建一个同级字段一个“更好的名字”，如果你有一个更好的名字。

版本和新名称之间的权衡：

如果您选择使用
• V2

  ，它并不那么“干净”，但很容易看出API使用者应该做什么以及他们应该使用什么。有时，您甚至可以在弃用原始版本之前创建 V2，并且阅读该架构的人可能会看到 V2 并开始为此努力。此外，这些客户已经在查看 

  picture

  ，因此他们更有可能在您告诉他们之前看到 

  pictureV2

  。

如果你选择一个“更好的名字”，那么最终的模式就是“干净的”；它不包含过去有什么不同的历史信息。但是，如果引入新名称，则在弃用时必须明确，并且可能需要更仔细地沟通。 API 使用者需要
• 阅读弃用通知以了解下一步该做什么，因为发生的情况并不是立即显而易见的。

同样值得一提的是，“清洁”问题是真实存在的，而且不仅仅是美观问题。第一次将

V*

 添加到某些东西时可能会感觉很糟糕，但我发现，从长远来看，大规模*会更容易。

* 这里的“大规模”可能意味着一些不同的事情，包括

模式增长：当您有一个不断增长的大型代码库或模式时，这个问题会经常出现。选择简单的版本控制策略可以使团队不必每次都放慢速度做出新的决策。只需升级版本并继续前进即可。
客户群增长：当您拥有庞大的 API 消费者群时，这样的版本控制策略很容易理解，因此您不必一遍又一遍地重新教授它。
团队成长：当你拥有一个大型团队时，新团队成员一目了然的版本控制策略也不必重新教授。新人很容易“复制意大利面”并知道下一步该做什么。
架构增长：如果您最终选择子图以及联合、拼接或类似的方式，那么在所有系统中采用简单且一致的策略将为您的客户带来一致性和可读性，即使您有单独的团队在处理独立的系统。

---

因此，如果队友专门向我展示了你的示例并询问下一步该做什么，我会给出这些选项，他们应该做适合他们的产品和客户的事情。

1. pictureV2

   ：您了解您的域名和客户。如果 

   picture

    是正确的词，请使用 

   pictureV2

   。

2. pictureUrl

   ：您返回的是一个 URL，它是一个标量。您不会返回“图片”，它可能具有尺寸、altText、标题等。此外，如果您今天使用名称 

   pictureUrl

   （当您仅返回 URL 时），将来如果您这样做了想要引入这些其他属性，您可以使用 

   picture

   （非标量名称）来表示 

   that。我不建议对“可能发生的情况”进行过度设计，但如果您牢记这一原则来命名事物，那么您就可以在将来添加功能，而不必为今天的情况进行过度设计。
3. image

   ：该术语传达与“图片”相同的相对含义，但在 API 设计中更常见。

4. imageUrl

   ：由于前两个要点，我通常推荐这个。