graphql-expert-best-practices

GraphQL 专家最佳实践

GraphQL API 性能优化与最佳实践综合指南。包含解析器优化、查询性能、数据获取模式和架构设计相关规则，并按影响程度排序，以指导自动重构和代码生成。

适用场景

在以下情况下请参考这些指南：

• 编写 GraphQL 架构、解析器或类型定义
• 实现数据获取和解析器逻辑
• 审查 GraphQL 代码中的性能问题
• 重构现有 GraphQL API
• 优化查询执行或解析器性能
• 设计 GraphQL 服务架构

按优先级划分的规则类别

优先级	类别	影响	前缀
1	查询优化	关键	dataloader-
2	架构设计	关键-高	schema-
3	变更设计	关键-高	mutation-
4	分页	高	pagination-
5	安全	关键-中	security-
6	运维	中	operations-

快速参考

• dataloader-n-plus-one - 使用 DataLoader 批量处理查询，避免 N+1 性能问题
• query-unique-identifiers - 使用唯一标识符而非复合参数，简化 API 接口
• schema-no-json-filters - 禁止使用任意 JSON 过滤标量，防止 NoSQL 注入漏洞
• schema-no-binary-data - 避免在架构中包含大型二进制数据，防止负载膨胀和内存问题
• schema-stable-identifiers - 使用全局稳定的不透明标识符，防止信息泄露和枚举攻击
• schema-structured-types - 使用结构化类型而非非结构化的 String/JSON 字段，提高类型安全性
• schema-split-types-by-role - 按角色拆分类型，防止隐私字段泄露并消除运行时授权
• schema-prefer-deprecation - 优先采用弃用而非版本控制，以支持 API 持续演进
• schema-field-overload - 避免为 viewer 和 user 重载字段，防止安全问题并提升 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-separate-input-types - 为创建和更新分别定义输入类型，以提升类型安全性
• mutation-avoid-validation-scalars - 避免自定义验证标量，防止多请求错误循环
• pagination-no-default-totalcount - 避免在连接中默认包含 totalCount，防止性能下降
• security-complexity-limits - 设置复杂度和查询节点数限制，防止资源耗尽攻击
• security-disable-introspection - 在生产环境中禁用内省，防止架构泄露
• operations-require-client-headers - 要求客户端标识请求头，以便调试和监控

使用方法

阅读各规则文件，了解详细说明和代码示例：

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

每个规则文件都包含：

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