gqlgen必须schema-first，因其代码生成完全依赖schema.graphqls文件定义的类型、字段、参数及非空标记，用于生成go结构体、resolver接口和执行引擎；若先写go再反推schema，将导致字段缺失、类型错位、嵌套断裂，引发编译错误或运行时panic。
Go 本身不处理 GraphQL 请求，必须靠第三方库解析 query 字符串、校验 schema、调度 resolver 并序列化响应；选错库或配置不当，请求会静默失败或返回空体。
gqlgen 为什么必须 schema-first？
因为 gqlgen 的代码生成逻辑完全依赖 schema.graphqls 文件：它读取类型定义、字段、参数、非空标记（!），然后生成 Go struct、resolver 接口和 generated.go 执行引擎。如果你先写 Go struct 再反推 schema，字段缺失、参数类型错位、嵌套关系断裂都会导致生成的 resolver 接口与实际实现不匹配。
-
gqlgen.yml中的schema路径必须指向真实文件，比如graph/schema.graphqls，而不是默认的schema.graphqls - 新增一个
type Product后，不运行gqlgen generate，graph/generated/generated.go里就不会有对应类型，编译直接报错 - 字段名大小写敏感：
productName和productname在 schema 里是两个不同字段，但 Go 里只有ProductName是导出字段，productname会被忽略
resolver 方法签名不匹配的典型报错
生成的 resolver 接口强制要求每个方法第一个参数是 context.Context，返回值必须是 (interface{}, error)。漏掉 ctx 或把 error 换成 *gqlerror.Error 都会导致赋值失败。
- 错误示例：
func(r *queryResolver) Users() ([]*model.User, error)—— 缺ctx context.Context参数 - 错误示例：
func(r *mutationResolver) CreateUser(input model.CreateUserInput) (*model.User, *gqlerror.Error)—— 返回值类型不是error - 正确签名：
func(r *queryResolver) Users(ctx context.Context) ([]*model.User, error) - 调试技巧：在方法开头加
log.Printf("ctx deadline: %+v", ctx.Deadline())，确认上下文是否传入
POST 请求体被忽略的底层原因
gqlgen 默认的 handler.NewDefaultServer 只支持 URL 查询参数（?query={...}），对 POST 的 JSON body 完全不解析——它甚至不读 r.Body，直接返回空响应，也不报错、不打日志。
- 必须用
handler.New替代NewDefaultServer，并显式传入executableSchema - HTTP handler 必须手动读 body：
body, _ := io.ReadAll(r.Body)，再解码为struct{ Query, Variables, OperationName string } - Content-Type 必须是
application/json，否则 Apollo Client 等会拒绝发送variables字段 - 常见卡点：用 curl 测试时忘了
-H "Content-Type: application/json"，结果返回 200 空体，前端收不到任何错误提示
resolver 中并发安全与 N+1 的真实代价
GraphQL resolver 默认并行执行同级字段（如 users { name posts { title } } 中所有 posts resolver 会并发跑），但数据库连接池、缓存访问、批处理器状态都可能被多 goroutine 同时修改。
- 别在 resolver 里直接调
db.FindPostsByUserID(id)—— 10 个用户触发 10 次查询，不是 1 次批量查 - 用
sync.Map存缓存结果，key 是 user_id，value 是[]*Post；或者用graphql-go/dataloader封装批加载逻辑 - 如果把 batch ID 收集放在全局 map 里，没加锁，高并发下会 panic：“concurrent map writes”
- 更隐蔽的问题：resolver 函数里用了
time.Sleep模拟延迟，会拖慢整个响应，而 GraphQL 规范不提供字段级 timeout 控制
真正难的不是写完第一个 query，而是当嵌套层级超过 3 层、并发数超 50、错误需要按业务码分类返回时，context 传递、错误包装、批处理边界、并发状态管理这些细节才开始咬人。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
