基于GraphQL 2021规范，如何合规移除API的size参数？

针对你遇到的问题，以下是几个符合2021年GraphQL规范的可行方案：

方案1：新增无参数字段+废弃原字段 #

2021规范支持字段级的@deprecated指令（仅不支持参数单独标记），你可以按以下步骤操作：

• 新增一个无参数的字段（比如defaultPicture），用于返回默认尺寸的图片：

  type Product {
    picture(size: Int): Url @deprecated(reason: "该字段将被移除，请使用defaultPicture获取默认尺寸图片")
    defaultPicture: Url
  }
  

• 在API文档、变更日志里明确告知用户：原picture字段的size参数即将被移除，建议迁移到defaultPicture字段。
• 等待足够的迁移周期（比如1-2个版本迭代），待大部分用户完成迁移后，删除原picture字段，再把defaultPicture重命名为picture（这一步可选，取决于你是否需要保持字段名一致）。

方案2：保留字段但忽略参数+明确告知 #

如果不想新增字段，可以保留原字段，但在定义中明确标记废弃并说明参数失效：

type Product {
  """
  获取商品图片：size参数已废弃，不再生效，将始终返回默认尺寸图片。后续版本将彻底移除该参数。
  """
  picture(size: Int): Url @deprecated(reason: "size参数已废弃，请调用时不传该参数，后续版本将移除该参数")
}

• 在业务逻辑中忽略传入的size参数，统一返回默认尺寸图片。
• 通过文档、开发者通知等方式，提醒用户不要再传递size参数。
• 经过缓冲期后，直接移除size参数，此时用户已经习惯不传参数，不会影响业务。

方案3：API版本化 #

如果你的API支持版本化，可以推出新版本（比如v2）：

• 在v1版本中，保留原picture(size: Int)字段并标记废弃，告知用户升级到v2。
• 在v2版本中，直接定义无参数的picture字段：

  type Product {
    picture: Url
  }
  

• 引导用户逐步从v1迁移到v2，待v1用户量足够低后，下线v1版本。

关键注意事项 #

• 无论采用哪种方案，都要在开发者文档、变更日志、GraphiQL字段描述等显眼位置明确告知变更内容和迁移时间线。
• 给用户留足缓冲周期，避免突然变更导致业务故障。

内容的提问来源于stack exchange，提问作者nik0x1