90%新项目应选gqlgen但禁用自动Resolver生成，仅生成schema到Go struct映射和空壳resolver；手动按领域组织实现，管控context传递、HTTP客户端分层超时、json.RawMessage映射为JSON标量，并启用MaxDepth防栈溢出。
GraphQL服务端用gqlgen还是手写Resolver？
直接结论：90%的新项目该用gqlgen，但别让它自动生成全部Resolver——否则后续维护会卡在类型断层上。
它生成的Resolver接口强制你实现所有字段，哪怕某个字段只在管理后台用、另一个只在移动端用。结果就是业务逻辑被拆得支离破碎，改一个查询要翻5个文件。
- 真正该生成的只有 schema → Go struct 的映射（
models_gen.go）和schema.resolvers.go的空壳 -
gqlgen.yml里关掉resolver_layout: follow-schema，改用resolver_layout: none，自己按领域组织Resolver实现 - 别让
gqlgen碰context.Context传递逻辑——比如 auth token、trace ID，这些必须在顶层graphql.Handler中间件里塞进context，再由各Resolver自行取用
微服务间数据聚合时，http.Client超时怎么设才不拖垮整个GraphQL响应？
常见错误是给所有下游服务统一配Timeout: 5 * time.Second，结果一个慢接口就把整个 GraphQL 查询卡死，连带其他字段也无法返回。
GraphQL 允许部分字段失败而其余继续执行，但前提是你的 HTTP 调用不阻塞整个 goroutine。关键不是调大 timeout，而是分层控制。
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 对每个下游服务单独建
*http.Client，并设置Timeout（连接+读）和Transport.IdleConnTimeout（复用连接） - 在
Resolver里用ctx, cancel := context.WithTimeout(parentCtx, 800*time.Millisecond)，比全局 timeout 更细粒度 - 如果下游返回 5xx 或超时，立刻返回
nil+ 错误，不要重试——GraphQL 本身不保证字段顺序或原子性，重试反而可能造成数据不一致
如何让gqlgen生成的模型支持json.RawMessage字段？
微服务聚合常要透传第三方 JSON 字段（比如支付回调里的extra），但gqlgen默认把json.RawMessage当普通字节切片，生成的 GraphQL 类型是String，丢失结构信息，前端还得自己JSON.parse。
这不是 bug，是设计选择：GraphQL 类型系统不原生支持任意 JSON。你要主动告诉gqlgen这是“可解析的 JSON”，而不是“一坨字符串”。
- 在 schema 中定义为
JSON标量：scalar JSON，并在gqlgen.yml中配置maps映射到json.RawMessage - 实现
MarshalJSON和UnmarshalJSON方法时，别直接return r, nil——要检查r是否为空、是否合法 JSON，否则 GraphQL 执行期 panic - 注意：
json.RawMessage字段不能参与@deprecated或@skip等指令，因为它的解析发生在 resolver 返回之后
GraphQL 查询嵌套过深导致panic: runtime error: invalid memory address
典型现象是前端发了个 8 层嵌套的查询（比如user { orders { items { product { category { parent { ... } } } } } }），Go 服务突然 crash，日志里只有一行空 panic。
根本原因不是内存溢出，而是gqlgen默认没开查询深度限制，深层嵌套触发了 Go runtime 的栈溢出保护，但错误没被捕获。
- 在
graphql.NewExecutableSchema前加graphql.MaxDepth(6)（数值按业务定，一般 4~6 足够） - 别依赖前端传来的
variables做深度校验——攻击者可以绕过前端直接 POST 查询字符串 - 如果必须支持深查询（比如报表导出），单独开一个 bypass endpoint，走 REST + JWT 鉴权，不走 GraphQL 入口
最麻烦的其实是 schema 设计阶段没人想这个问题，等上线后发现查一次用户订单树要 2s，才回头砍字段——这时候前端已经写死了嵌套结构，改起来比重构还疼。
