添加枚举值是 GraphQL 的重大更改吗?

Question

根据 GraphQL最佳实践，GraphQL 服务应遵循"始终避免中断性更改并提供无版本 API 的常见做法"。

向枚举添加值是否被视为遵循最佳实践时应避免的重大更改？

为了说明这一点，假设架构具有以下枚举：

enum Episode {
NEWHOPE
EMPIRE
JEDI
}

将来某个时候将枚举演变成这样是一种不好的做法：

enum Episode {
NEWHOPE
EMPIRE
JEDI
FORCEAWAKENS
ROGUEONE
}

Answer 1

具体而言，中断性更改是对架构结构的更改，会导致已编写的查询失败。我在网上找不到详尽的列表，但这里有一些示例中断性更改：

• 从对象类型中删除字段(使用该字段的查询将变为无效)
• 向字段添加必需参数(使用该字段而不使用该参数的查询将变为无效)
• 当新类型不是旧类型的超类型时，更改字段的返回类型(例如，从Int更改为String，使用该字段的客户端可能会从新响应中出现类型错误)。

新的枚举值可能会破坏客户端(如果它没有代码来处理新情况，则可能会出现运行时错误)，但我认为这是客户端设计问题，但不是对架构的重大更改！

Answer 2

TLDR：向枚举添加值被认为是"潜在的危险更改"。

根据规格 (http://spec.graphql.org/October2021/#sec-Validation.Type-system-evolution)

任何可能导致以前有效的请求变得无效的更改都被视为中断性更改。

我试图找到一个明确的重大更改列表，这比我预期的要困难得多。似乎在 graphql-js 中同时存在"重大更改"和"危险更改"的概念，以响应两个函数findBreakingChanges和findDangerousChanges。findDangerousChanges建议由此 PR 添加：https://github.com/graphql/graphql-js/pull/701#issuecomment-277851631 因为虽然某些更改不符合规范中"中断"的定义，但它们仍然"具有潜在危险"。根据代码，向枚举添加值被视为"潜在危险的更改"： https://github.com/graphql/graphql-js/blob/40ff40a21c710372330e65f0fb58f13c2df92a77/src/utilities/findBreakingChanges.ts#L37-L63

• 查找中断性更改 - https://github.com/graphql/graphql-js/blob/a24a9f35b876bdd0d5050eca34d3020bd0db9a29/src/utilities/findBreakingChanges.ts#L79)
• 发现危险变化 - https://github.com/graphql/graphql-js/blob/a24a9f35b876bdd0d5050eca34d3020bd0db9a29/src/utilities/findBreakingChanges.ts#L93