跳到正文
Code Review

← 官方规则来源

Graphql · 官方规则原文

OpenCodeReview v1.13.8 · 4236c871 · Apache-2.0。保留固定版本英文原文;item 编号表示原文件中的检查项顺序。实际扫描以当前规则开关和扫描快照为准。

查看当前规则与开关 → · 下载原始 Markdown

版本与文件信息

提交:4236c871fe8130aa840a2a1c0922f469e87e0416

源码路径:internal/config/rules/rule_docs/graphql.md

SHA-256:d366bf4cf234c562c2522bed7ab979fafcccd5498f2f1f004a2638d58fc4ad24

Apache-2.0 许可证 · 基线说明
Favor precision over recall: only raise an issue when you are confident it is a real defect, and stay silent when the surrounding context is unclear — a false alarm costs more reviewer trust than a missed minor issue. Treat security and correctness findings as blocking, and style or idiom suggestions as non-blocking. Review only what is observable in the schema (SDL) or operation text under review; do not infer resolver behavior that lives in code outside this file.

Obvious Typos or Spelling Errors

  • Spelling errors in type, field, enum-value, argument, input, directive, or fragment names at their declaration sites; do not report spelling errors at reference sites
  • Typos in descriptions or field names that affect readability of the public API surface

Schema Evolution and Breaking Changes

  • Removing or renaming an existing type, field, enum value, or argument that clients may already depend on
  • Making a previously nullable input field or argument non-null, or adding a new required (non-null, no-default) argument to an existing field
  • Changing a field or argument type to an incompatible type
  • @deprecated applied without a non-empty reason
  • Do not flag purely additive changes: new types, new fields, new enum values appended, or new optional (nullable / defaulted) arguments
  • GraphQL has no numeric field tags — do not import Protocol Buffers field-number or renumbering concepts

Naming Conventions

  • Types (object, interface, union, enum, input, scalar) should be PascalCase; fields, arguments, and input fields camelCase; enum values UPPER_CASE
  • Redundant query/get prefixes on Query fields, mutation/subscription affixes on their root fields, and type/enum/interface/union affixes in type names
  • Do not flag names that already follow these conventions merely to suggest a synonym

Schema Design

  • Nullability that hides required-vs-optional intent (e.g. a field that can never be null typed as nullable, or a genuinely optional field typed non-null)
  • Types unreachable from any root field (Query/Mutation/Subscription) — dead schema
  • Missing descriptions on public types and fields that form the API contract
  • Names prefixed with __ (reserved for introspection)
  • List fields returning a collection without a pagination or limit argument (first/last/limit/after), which allows unbounded result sets

Operations and Fragments

  • Selecting @deprecated fields in queries, mutations, or fragments
  • Fragment cycles, unused fragments, and unused or undefined operation variables
  • Anonymous operations where a named operation aids caching and debugging
  • Missing leaf selections on fields that return object/interface/union types
  • Do not flag well-formed operations that merely differ in stylistic preference

Security and Resource Limits

  • Only flag when the condition is observable in the schema or operation text under review
  • Unbounded list fields (see Schema Design) or deeply nested / recursive selections with no documented depth or complexity limit (query-depth DoS surface)
  • A field carrying clearly sensitive data (token, secret, password, or PII by name or description) exposed without an accompanying auth-related directive or comment
  • An explicit directive, configuration, or comment in the diff that enables introspection on an untrusted surface
  • Do not infer resolver-level N+1 cost, dataloader/batching usage, or runtime introspection state — those live in resolver code, not in schema or operation files
  • Do not report when a limit is enforced and clearly documented outside the schema