graphql-expert-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GraphQL Expert Best Practices

GraphQL专家最佳实践

Comprehensive performance optimization and best practices guide for GraphQL APIs. Contains rules for resolver optimization, query performance, data fetching patterns, and schema design, prioritized by impact to guide automated refactoring and code generation.

GraphQL API全面性能优化与最佳实践指南。包含Resolver优化、查询性能、数据获取模式及Schema设计的规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing GraphQL schemas, resolvers, or type definitions
Implementing data fetching and resolver logic
Reviewing GraphQL code for performance issues
Refactoring existing GraphQL APIs
Optimizing query execution or resolver performance
Designing GraphQL server architecture

在以下场景参考本指南：

编写GraphQL Schema、Resolver或类型定义
实现数据获取与Resolver逻辑
评审GraphQL代码以排查性能问题
重构现有GraphQL API
优化查询执行或Resolver性能
设计GraphQL服务器架构

Rule Categories by Priority

按优先级划分的规则类别


dataloader-
schema-
mutation-
pagination-
security-
operations-

Priority	Category	Impact	Prefix
1	Query Optimization	CRITICAL	`dataloader-`
2	Schema Design	CRITICAL-HIGH	`schema-`
3	Mutation Design	CRITICAL-HIGH	`mutation-`
4	Pagination	HIGH	`pagination-`
5	Security	CRITICAL-MEDIUM	`security-`
6	Operations	MEDIUM	`operations-`


dataloader-
schema-
mutation-
pagination-
security-
operations-

优先级	类别	影响程度	前缀
1	查询优化	关键	`dataloader-`
2	Schema设计	关键-高	`schema-`
3	Mutation设计	关键-高	`mutation-`
4	分页	高	`pagination-`
5	安全	关键-中	`security-`
6	操作规范	中	`operations-`

Quick Reference

速查参考

```
dataloader-n-plus-one
```
- Use DataLoader to batch queries and prevent N+1 performance issues
```
query-unique-identifiers
```
- Use unique identifiers over composite parameters to simplify API surface
```
schema-no-json-filters
```
- Ban arbitrary JSON filter scalars to prevent NoSQL injection vulnerabilities
```
schema-no-binary-data
```
- Avoid large binary data in schema to prevent payload bloat and memory issues
```
schema-stable-identifiers
```
- Use globally stable opaque identifiers to prevent information leakage and enumeration attacks
```
schema-structured-types
```
- Use structured types over unstructured String/JSON fields to improve type safety
```
schema-split-types-by-role
```
- Split types by role to prevent privacy field leakage and eliminate runtime authorization
```
schema-prefer-deprecation
```
- Prefer deprecation over versioning to enable continuous API evolution
```
schema-field-overload
```
- Avoid field overloads for viewer vs user to prevent security issues and improve API clarity
```
schema-minimize-nullable-args
```
- Minimize nullable arguments to improve API clarity and type safety
```
schema-no-duplicate-fields
```
- Prevent duplicate fields accessible through nested objects to maintain single source of truth
```
mutation-no-file-uploads
```
- Avoid file uploads through GraphQL to prevent memory exhaustion and security vulnerabilities
```
mutation-single-input-object
```
- Use single input object argument instead of multiple scalars to improve API evolvability
```
mutation-union-result-types
```
- Return union types with dedicated success and specific error types for type-safe error handling
```
mutation-explicit-actions
```
- Design mutations around explicit actions rather than generic update patterns
```
mutation-separate-input-types
```
- Separate input types for create and update to improve type safety
```
mutation-avoid-validation-scalars
```
- Avoid custom validation scalars to prevent multi-request error loops
```
pagination-no-default-totalcount
```
- Avoid default totalCount in connections to prevent performance degradation
```
security-complexity-limits
```
- Require complexity and query node limits to prevent resource exhaustion attacks
```
security-disable-introspection
```
- Disable introspection in production to prevent schema disclosure
```
operations-require-client-headers
```
- Require client identification headers for debugging and monitoring

```
dataloader-n-plus-one
```
- 使用DataLoader批量查询，避免N+1性能问题
```
query-unique-identifiers
```
- 使用唯一标识符替代复合参数，简化API接口
```
schema-no-json-filters
```
- 禁止使用任意JSON过滤标量，防止NoSQL注入漏洞
```
schema-no-binary-data
```
- 避免在Schema中使用大型二进制数据，防止负载膨胀与内存问题
```
schema-stable-identifiers
```
- 使用全局稳定的不透明标识符，防止信息泄露与枚举攻击
```
schema-structured-types
```
- 使用结构化类型替代非结构化String/JSON字段，提升类型安全性
```
schema-split-types-by-role
```
- 按角色拆分类型，防止隐私字段泄露并消除运行时授权需求
```
schema-prefer-deprecation
```
- 优先使用弃用而非版本化，支持API持续演进
```
schema-field-overload
```
- 避免针对查看者与用户的字段重载，防止安全问题并提升API清晰度
```
schema-minimize-nullable-args
```
- 尽量减少可空参数，提升API清晰度与类型安全性
```
schema-no-duplicate-fields
```
- 防止通过嵌套对象访问重复字段，保持单一数据源
```
mutation-no-file-uploads
```
- 避免通过GraphQL上传文件，防止内存耗尽与安全漏洞
```
mutation-single-input-object
```
- 使用单个输入对象参数替代多个标量，提升API可演进性
```
mutation-union-result-types
```
- 返回包含专用成功类型与特定错误类型的联合类型，实现类型安全的错误处理
```
mutation-explicit-actions
```
- 围绕明确操作设计Mutation，而非通用更新模式
```
mutation-separate-input-types
```
- 为创建与更新操作分离输入类型，提升类型安全性
```
mutation-avoid-validation-scalars
```
- 避免使用自定义验证标量，防止多请求错误循环
```
pagination-no-default-totalcount
```
- 避免在连接中默认返回totalCount，防止性能下降
```
security-complexity-limits
```
- 要求设置复杂度与查询节点限制，防止资源耗尽攻击
```
security-disable-introspection
```
- 在生产环境禁用自省功能，防止Schema泄露
```
operations-require-client-headers
```
- 要求客户端提供身份识别标头，用于调试与监控

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/dataloader-n-plus-one.md
rules/query-unique-identifiers.md
rules/schema-no-json-filters.md
rules/schema-no-binary-data.md
rules/schema-stable-identifiers.md
rules/schema-structured-types.md
rules/schema-split-types-by-role.md
rules/schema-prefer-deprecation.md
rules/schema-field-overload.md
rules/schema-minimize-nullable-args.md
rules/schema-no-duplicate-fields.md
rules/mutation-no-file-uploads.md
rules/mutation-single-input-object.md
rules/mutation-union-result-types.md
rules/mutation-explicit-actions.md
rules/mutation-separate-input-types.md
rules/mutation-avoid-validation-scalars.md
rules/pagination-no-default-totalcount.md
rules/security-complexity-limits.md
rules/security-disable-introspection.md
rules/operations-require-client-headers.md

Each rule file contains:

Brief explanation of why it matters
When to use and when not to use the pattern
Implementation requirements
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件获取详细说明与代码示例：

rules/dataloader-n-plus-one.md
rules/query-unique-identifiers.md
rules/schema-no-json-filters.md
rules/schema-no-binary-data.md
rules/schema-stable-identifiers.md
rules/schema-structured-types.md
rules/schema-split-types-by-role.md
rules/schema-prefer-deprecation.md
rules/schema-field-overload.md
rules/schema-minimize-nullable-args.md
rules/schema-no-duplicate-fields.md
rules/mutation-no-file-uploads.md
rules/mutation-single-input-object.md
rules/mutation-union-result-types.md
rules/mutation-explicit-actions.md
rules/mutation-separate-input-types.md
rules/mutation-avoid-validation-scalars.md
rules/pagination-no-default-totalcount.md
rules/security-complexity-limits.md
rules/security-disable-introspection.md
rules/operations-require-client-headers.md

每个规则文件包含：

规则重要性的简要说明
适用与不适用该模式的场景
实现要求
错误代码示例及说明
正确代码示例及说明
额外背景信息与参考资料