精确优先于召回:仅在确信是真实缺陷时才提出问题,当周边上下文不明确时保持沉默——误报比漏报一个次要问题更损耗评审者的信任。将安全与正确性发现视为阻塞项,风格或惯用法建议视为非阻塞项。仅评审 schema(SDL)或操作文本中可观察到的内容;不要推断位于本文件之外代码中的 resolver 行为。
明显的拼写错误
2 项Schema 演进与破坏性变更
6 项- 移除或重命名客户端可能已依赖的既有类型、字段、枚举值或参数内置
来源与改动说明
- 将先前可空的输入字段或参数改为非空,或给既有字段新增必需(非空、无默认值)的参数内置
来源与改动说明
- 将字段或参数类型改为不兼容的类型内置
来源与改动说明
- 使用
@deprecated时未提供非空的reason内置来源与改动说明
- 不要标记纯增量变更:新增类型、新增字段、追加新枚举值,或新增可选(可空/带默认值)参数内置
来源与改动说明
- GraphQL 没有数字字段标签——不要引入 Protocol Buffers 的字段编号或重编号概念内置
来源与改动说明
命名规范
3 项- 类型(object、interface、union、enum、input、scalar)应为
PascalCase;字段、参数与输入字段为camelCase;枚举值为UPPER_CASE内置来源与改动说明
Query字段上冗余的query/get前缀、根字段上冗余的mutation/subscription前后缀,以及类型名称中冗余的type/enum/interface/union前后缀内置来源与改动说明
- 不要仅为建议同义词而标记已符合这些规范的名称内置
来源与改动说明
Schema 设计
5 项- 掩盖必填与可选意图的可空性(例如永不为空的字段声明为可空,或真正的可选字段声明为非空)内置
来源与改动说明
- 无法从任何根字段(
Query/Mutation/Subscription)触达的类型——死 schema内置来源与改动说明
- 构成 API 契约的公共类型与字段缺少描述内置
来源与改动说明
- 以
__为前缀的名称(保留给内省使用)内置来源与改动说明
- 列表字段返回集合却没有分页或限量参数(
first/last/limit/after),从而允许无界结果集内置来源与改动说明
操作与片段
5 项- 在查询、变更或片段中选择
@deprecated字段内置来源与改动说明
- 片段循环、未使用的片段,以及未使用或未定义的操作变量内置
来源与改动说明
- 使用命名操作有助于缓存与调试时仍使用匿名操作内置
来源与改动说明
- 返回 object/interface/union 类型的字段缺少叶子选择内置
来源与改动说明
- 不要标记仅因风格偏好不同而格式良好的操作内置
来源与改动说明
安全与资源限制
6 项- 仅当条件在受评审的 schema 或操作文本中可观察时才标记内置
来源与改动说明
- 无界列表字段(见 Schema 设计)或缺少文档化深度/复杂度限制的深层嵌套/递归选择(查询深度 DoS 攻击面)内置
来源与改动说明
- 携带明显敏感数据(按名称或描述判断为 token、密钥、密码或 PII)的字段在暴露时未伴随鉴权相关指令或注释内置
来源与改动说明
- diff 中显式在不可信表面启用内省的指令、配置或注释内置
来源与改动说明
- 不要推断 resolver 层的 N+1 开销、dataloader/批处理使用情况或运行时内省状态——它们位于 resolver 代码中,而非 schema 或操作文件里内置
来源与改动说明
- 当限制已在 schema 之外强制执行且有清晰文档时,不要报告内置
来源与改动说明