GraphQL API 架构师

它解决什么问题

一个列表查询暴露给前端之后，N+1 往往要等到压测或上线后才暴露：posts 的 resolver 返回 N 条记录，每条都会触发一次 author 的数据库请求。浏览器一次操作就是 1 + N 次往返，列表项达到万级时会直接打满连接池；更糟的是恶意客户端能写出深层嵌套查询，让 resolver 链在服务端反复递归，把接口当成免费的枚举通道。这个技能的定位是架构评审与改造：schema 设计、N+1 修复、安全防护三件事一起输出，而不是丢一份模板给团队自己发挥。

它怎么工作

Schema 设计：按领域而非数据库表建模，默认字段设为 null，多态用 Interface / Union（比如 SearchResult = User | Post | Comment），mutation 入参收敛进 Input Type，状态字段优先 Enum 而不是裸字符串，避免拼写错误和边界值漏洞。

N+1 修复：先定位根因——GraphQL resolver 是逐个执行的，列表里每个 item 调一次数据库就是 N+1。改造方式是让 resolver 通过 context.loaders.userLoader.load(post.authorId) 取关联数据。DataLoader 在单个 event loop tick 内收集同类型的加载请求，合并成一条 SELECT ... WHERE id IN (...)，再按请求顺序分发结果，因此 1000 条文章也只有 2 次数据库往返，与 N 无关。关键约束是 loader 实例必须 per request：挂在全局单例上会把用户 A 的数据缓存后返回给用户 B，这等于白做。

分页：建议遵守 Relay Connection 规范，即使不使用 Relay 客户端。edges + node 写入时看着啰嗦，但它带回 cursor 和 hasNextPage，前端做滚动加载真正需要的是这些元信息，而不是牺牲能力去换写法简洁。

安全：graphql-depth-limit 默认限制 5 层嵌套，graphql-query-complexity 给每个字段赋 cost 并设总上限；限流基于 @rateLimit 指令或中间件，按 IP 或 token 限制 QPS；鉴权要下沉到字段级，在 resolver 里检查 context.user，而不是只在 Query 入口判断一次；生产环境关闭 introspection，或只对内部开放。

Subscription：用 graphql-ws，不要再接已废弃的 subscriptions-transport-ws；消息、通知、数据看板这类实时更新用它最合适，大查询结果还可借助 @defer / @stream 渐进交付。

输出是结构化的：SDL + 设计决策说明、完整的 DataLoader 实现与 per-request context 注册、一张安全配置清单。下游可以直接交给 testing-api-contract 做契约测试，或与 rest-api-design 对比选型。

边界

简单的 CRUD API 用 REST 更合适，GraphQL 在这里只是增加成本。文件上传下载也不在它的舒适区——二进制流本来就不是 GraphQL 擅长的部分。工程上还要注意：深度限制设得太死会误伤正常的深层查询，cost 系数需要按真实 resolver 开销调参，照抄默认值常常过松或过紧。这套技能更适合用来做一次认真的架构评审，而不是当成可以粘进代码的现成依赖。