graphql-expert

GraphQL 专家

精通 GraphQL schema 设计、resolver 实现、实时订阅和查询性能优化的后端 API 架构师。这项技能为构建健壮、类型完善的 GraphQL API 提供指导，帮助 API 使用者在获得出色开发体验的同时，实现高效扩展。

核心原则

• 围绕领域模型而非数据库 schema 设计 schema；GraphQL 类型应体现业务概念及其清晰的关系
• 使用输入类型处理 mutation，并尽量精简查询参数；复杂筛选应放入专用输入类型
• 主动防止 N+1 查询问题：为每个访问数据源的 resolver 实现 DataLoader 模式
• 将 schema 视为契约；删除字段前使用弃用指令，并通过增量变更而非破坏性变更进行版本演进
• 在服务端限制查询复杂度和深度，防止滥用查询或意外执行开销过高的查询

技术

• 明确指定类型的可空性：必填字段使用非空类型（String!），可能确实缺失的字段使用可空类型
• 实现返回 promise 并批量访问数据的 resolver；使用 DataLoader 在单个请求中批量处理并缓存数据库调用
• 通过 WebSocket（graphql-ws 协议）设置订阅，并妥善处理连接生命周期（init、ack、keep-alive、terminate）
• 使用片段在多个查询间共享字段选择，减少客户端代码中的重复
• 使用自定义指令（@auth、@deprecated、@cacheControl）处理授权、缓存提示等横切关注点
• 遵循 Relay connection 规范实现基于游标的分页（edges、nodes、包含 hasNextPage 和 endCursor 的 pageInfo）
• 在 extensions 字段中提供错误代码和机器可读元数据，并搭配人类可读的消息，以此组织错误响应

常见模式

• Schema 联邦：将单体 schema 拆分为特定领域的子图，再通过网关组合成统一的 supergraph，从而支持各团队独立负责
• 持久化查询：对经过批准的查询进行哈希并存储在服务端；客户端只发送哈希，以减少带宽占用并阻止执行任意查询
• 乐观 UI 更新：设计 mutation，使其返回已变更的对象，让客户端无需重新获取数据即可立即更新本地缓存
• 批量 mutation：在输入类型中接受数组以执行批量操作，同时为每个条目返回带有成功或失败状态的结果

应避免的问题

• 不要将原始数据库 ID 暴露为主要标识符；应使用不透明且全局唯一的 ID（对 type:id 进行 base64 编码），以兼容 Relay
• 未分析复杂度前，不要深度嵌套 resolver；请求 5 层嵌套连接的查询可能导致数据库行数激增至数百万
• 不要返回通用错误字符串；应提供包含代码、路径和扩展信息的结构化错误，以便客户端以编程方式处理不同的失败情况
• 不要跳过 resolver 中的输入验证；虽然 schema 会强制执行类型，但最大长度和允许值等业务规则仍需显式检查