跳到正文
Code Review
← 规则库/数据与接口

评审检查清单

Graphql

数据与接口27 个检查项6 个章节
**/*.{graphql,gql}
精确优先于召回:仅在确信是真实缺陷时才提出问题,当周边上下文不明确时保持沉默——误报比漏报一个次要问题更损耗评审者的信任。将安全与正确性发现视为阻塞项,风格或惯用法建议视为非阻塞项。仅评审 schema(SDL)或操作文本中可观察到的内容;不要推断位于本文件之外代码中的 resolver 行为。
01

明显的拼写错误

2 项
  • 类型、字段、枚举值、参数、输入类型、指令或片段名称在其声明处的拼写错误;不要报告引用处的拼写错误
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 描述或字段名称中影响公共 API 表面可读性的笔误
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

02

Schema 演进与破坏性变更

6 项
  • 移除或重命名客户端可能已依赖的既有类型、字段、枚举值或参数
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 将先前可空的输入字段或参数改为非空,或给既有字段新增必需(非空、无默认值)的参数
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 将字段或参数类型改为不兼容的类型
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 使用 @deprecated 时未提供非空的 reason
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 不要标记纯增量变更:新增类型、新增字段、追加新枚举值,或新增可选(可空/带默认值)参数
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GraphQL 没有数字字段标签——不要引入 Protocol Buffers 的字段编号或重编号概念
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

03

命名规范

3 项
  • GRAPHQL-NAMING-CONVENTIONS-001状态加载中
    类型(object、interface、union、enum、input、scalar)应为 PascalCase;字段、参数与输入字段为 camelCase;枚举值为 UPPER_CASE
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-NAMING-CONVENTIONS-002状态加载中
    Query 字段上冗余的 query/get 前缀、根字段上冗余的 mutation/subscription 前后缀,以及类型名称中冗余的 type/enum/interface/union 前后缀
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-NAMING-CONVENTIONS-003状态加载中
    不要仅为建议同义词而标记已符合这些规范的名称
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

04

Schema 设计

5 项
  • GRAPHQL-SCHEMA-DESIGN-001状态加载中
    掩盖必填与可选意图的可空性(例如永不为空的字段声明为可空,或真正的可选字段声明为非空)
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-SCHEMA-DESIGN-002状态加载中
    无法从任何根字段(Query/Mutation/Subscription)触达的类型——死 schema
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-SCHEMA-DESIGN-003状态加载中
    构成 API 契约的公共类型与字段缺少描述
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-SCHEMA-DESIGN-004状态加载中
    以 __ 为前缀的名称(保留给内省使用)
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-SCHEMA-DESIGN-005状态加载中
    列表字段返回集合却没有分页或限量参数(first/last/limit/after),从而允许无界结果集
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

05

操作与片段

5 项
  • GRAPHQL-OPERATIONS-AND-FRAGMENTS-001状态加载中
    在查询、变更或片段中选择 @deprecated 字段
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-OPERATIONS-AND-FRAGMENTS-002状态加载中
    片段循环、未使用的片段,以及未使用或未定义的操作变量
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-OPERATIONS-AND-FRAGMENTS-003状态加载中
    使用命名操作有助于缓存与调试时仍使用匿名操作
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-OPERATIONS-AND-FRAGMENTS-004状态加载中
    返回 object/interface/union 类型的字段缺少叶子选择
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • GRAPHQL-OPERATIONS-AND-FRAGMENTS-005状态加载中
    不要标记仅因风格偏好不同而格式良好的操作
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

06

安全与资源限制

6 项
  • 仅当条件在受评审的 schema 或操作文本中可观察时才标记
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 无界列表字段(见 Schema 设计)或缺少文档化深度/复杂度限制的深层嵌套/递归选择(查询深度 DoS 攻击面)
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 携带明显敏感数据(按名称或描述判断为 token、密钥、密码或 PII)的字段在暴露时未伴随鉴权相关指令或注释
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • diff 中显式在不可信表面启用内省的指令、配置或注释
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 不要推断 resolver 层的 N+1 开销、dataloader/批处理使用情况或运行时内省状态——它们位于 resolver 代码中,而非 schema 或操作文件里
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

  • 当限制已在 schema 之外强制执行且有清晰文档时,不要报告
    内置
    来源与改动说明

    来源

    本站调整:沿用原规则,提供中文说明并补充编号。

返回本页顶部 ↑继续浏览规则库

手动复制规则链接

浏览器未允许自动复制,请选中下方链接复制。