GraphQL API 合并请求检查清单

GitLab GraphQL API 相当复杂，因此包含 GraphQL 变更的合并请求需要由熟悉 GraphQL 的人员进行审查。 您可以通过 MR 中的 @gitlab-org/graphql-experts 群组或在 Slack 的 #f_graphql 频道（仅限 GitLab 团队成员）联系相关专家。

GraphQL 查询需要审查以下内容：

• 破坏性变更
• 授权
• 性能

审查标准

这并非详尽无遗的列表。

包含示例查询的描述

确保描述包含带有设置说明的示例查询。 尝试在您本地的 GDK 实例上使用 GraphiQL 运行查询。

无破坏性变更（除非经过完整的弃用周期）

检查合并请求中是否存在任何 破坏性变更。

如果某个功能被标记为 实验性功能，您可以立即进行破坏性变更，无需经过弃用周期。

更多信息请参见 弃用和移除流程。

多版本兼容性

确保保证多版本兼容性。 这通常意味着同一 GraphQL 功能的前端和后端代码不能在同一版本中发布。

详细信息请参见 多版本兼容性。

技术写作审查

对生成的 API 文档的更改需要技术作者进行审查。

变更日志

面向公众的变更，如果未标记为 实验性功能，则需要添加 变更日志条目。

使用框架

GraphQL 是一个包含许多组件的框架。遵循框架规范非常重要。

• 不要手动调用框架组件。例如，不要在执行过程中实例化解析器，而是让框架来处理。
• 您可以继承解析器，如 MyResolver.single（参见 派生解析器）。
• 对于更复杂的参数逻辑，使用 ready? 方法（参见 正确使用 resolver#ready）。
• 对于更复杂的参数验证，使用 prepare 方法（参见 预处理）。

详细信息请参见 解析器指南。

授权

确保遵循适当的授权规范，并在测试规范中测试 authorize :some_ability。

详细信息请参见 授权指南。

性能

确保：

• 您已经 检查了 N+1 问题 并尽可能使用 优化 来消除 N+1 问题。
• 您适当使用 延迟加载。

使用适当的类型

例如：

• 用于 Ruby Time 和 DateTime 对象的 TimeType。
• id 字段使用全局 ID

详细信息请参见 类型。

适当的复杂度

查询复杂度是一种量化查询可能有多昂贵的方法。查询复杂度限制在模式中定义为常量。 当解析器或类型的调用成本很高时，我们需要确保查询复杂度能够反映这一点。

详细信息请参见 最大复杂度、字段复杂度 和 查询限制。

测试

• 解析器（单元）规范已被弃用，转而使用请求（集成）规范。
• 我们框架的许多方面都在 resolve 方法之外，请求规范是确保它们正常行为的唯一方法。
• 理想情况下，每个 GraphQL 变更的合并请求都应该包含 API 规范的更改。

详细信息请参见 测试指南。