graphql

用途：在构建 GraphQL API、编写 schema、resolver 或客户端查询时提供模式与规范参考，适用于 Apollo Server、Pothos、graphql-yoga 和 Apollo Client。

主要能力与要求：

1. N+1 预防：按外键取数的 resolver 必须使用 DataLoader 批量加载，且每个请求单独实例化，不可跨请求共享，否则会串数据。
2. 模式风格：schema-first（SDL/.graphql 文件）或 code-first（Pothos、NestJS 装饰器）二选一，同一项目不得混用。
3. 可空性：仅在结构上必然存在的字段（主键、注册必填项）使用非空 !，可能被删除或可选的关系用可空，避免客户端崩溃。
4. 分页：优先 Relay 风格游标分页（first/after、Connection/Edge/PageInfo），offset 分页在并发写入下不稳定。
5. 客户端复用：重复字段选择抽取为 fragment。
6. 安全：不要暴露自增内部 ID，改用 UUID 或编码后的全局 ID；公开 API 加深度限制（如 depthLimit(7)）与复杂度限制；私有或敏感 schema 在生产关闭 introspection。
7. Mutation：返回被修改对象而非布尔值，并带上客户端可能需要的关联数据；领域错误（校验、冲突）优先用 union 返回类型而非抛异常。

使用方式：按决策树选择——外键取数用 DataLoader；小团队偏好显式 SDL 用 schema-first，TypeScript 重度项目用 code-first；并发写入场景用游标分页；公开 API 加深度与复杂度限制。

适用场景：GraphQL schema 设计、服务端 resolver 实现、客户端查询/变更/片段编写、N+1 与过度取数诊断。

限制与不适用：不用于 REST API 设计（用 express 或 hono）、tRPC、数据库查询优化（用相应 ORM 技能）。订阅需在 onConnect 校验令牌并在过期时关闭连接；文件上传建议改用预签名 URL；多子图拆分用 Apollo Federation，不要手工拼接 schema。具体安装命令与版本信息暂未提供。