gqlgen可构建类型安全、可维护的graphql服务，但上线前须避开五大坑：schema变更后未运行generate导致运行时panic；resolver签名与生成接口不一致引发反射匹配失败；http路由注册错误致404；context未透传丢失超时与追踪；error未用graphql.errorf包装致客户端无法获取错误信息。
用 gqlgen 能搭出类型安全、可维护的 GraphQL 服务，但“能跑”和“能上线”之间隔着五个常见坑：schema 变了不重新生成、resolver 签名对不上、HTTP 路由注册错、context 没透传、错误没包装成 graphql.Error。
schema 修改后必须手动运行 gqlgen generate
gqlgen 不监听文件变化，改了 schema.graphql 后不执行生成命令，generated.go 里接口就还是旧的——编译时不会报错，但运行时一调用就 panic：“no such method”。
- 每次保存
schema.graphql后，立刻执行：go run github.com/99designs/gqlgen generate - 别依赖
gqlgen serve的自动重载；它只重启 HTTP server，不触发代码生成 - 如果新增了
Mutation或input类型，检查gqlgen.yml的models段是否已映射对应 Go 结构体，否则生成器会跳过整个链路 - 生成的
generated.go是只读契约文件，所有业务逻辑只写在resolver.go里
resolver 函数签名必须和 generated 接口完全一致
Go 编译器不校验你实现的 resolver 是否满足 gqlgen 生成的接口，但 runtime 会严格按反射匹配：参数顺序、指针与否、返回值个数，错一个就 panic。
- 根级字段（如
Query.users）签名示例：func (r *queryResolver) Users(ctx context.Context, first *int) ([]*model.User, error) -
first *int是指针，不是int；[]*model.User是指针切片，不是[]model.User - 如果 schema 定义的是
User!（非空），返回值类型必须是*model.User，不能是model.User；否则 nil 值会被当成有效数据返回 - 方法名大小写必须和 schema 字段名完全一致：
userName≠Username
HTTP handler 注册错，请求直接 404 或 panic
gqlgen 不自带 HTTP server，只提供 http.Handler。漏掉注册、路径写错、用错注册方式，都会导致前端发请求却收不到响应。
- 正确注册方式：
http.Handle("/graphql", handler)（注意是Handle，不是HandleFunc） - 别写成
http.HandleFunc("/graphql", handler.ServeHTTP)——handler 本身已是http.Handler，不需要再拆 - 用 Gin 时，必须包装：
r.POST("/graphql", gin.WrapH(handler))；只写r.POST("/graphql", handler)会编译失败 - GraphQL 默认只响应 POST 请求；如果 Nginx 或中间件限制了 method，需显式放开
POST和GET（GraphiQL 需要 GET）
resolver 里不传 ctx，超时、日志、trace 全断
GraphQL 执行层为每个字段注入独立的 context.Context，它携带请求生命周期、取消信号、中间件注入的值。丢掉它，等于放弃可观测性和稳定性控制。
- 所有 resolver 方法第一个参数必须是
ctx context.Context，不可省略 - 下游调用必须透传：
db.CreateContext(ctx, &u)（GORM v2）、tx.QueryRowContext(ctx, ...)（database/sql） - 中间件注入的值（如用户 ID）只能从
ctx.Value("user_id")取，不能靠全局变量或 struct 字段存 - 别在 resolver 里起 goroutine 并传
context.Background()；要用ctx，并监听ctx.Done()
最易被忽略的一点：error 必须用 graphql.Errorf 包装，而不是裸 return nil, fmt.Errorf(...)——否则客户端收不到 errors 字段，只看到空数据和 200 状态码。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
