能跑起来不等于能上线，gqlgen服务常见问题：schema修改后未执行go run github.com/99designs/gqlgen generate导致panic“no such method”；HTTP注册错误（如误用HandleFunc而非Handle）引发404；resolver签名缺失ctx context.Context、指针类型或大小写不匹配致运行时反射失败；Content-Type非application/json则静默空响应。
能跑起来不等于能上线，gqlgen 服务卡在 404、panic 或空响应，八成是生成代码没对上、HTTP 注册写错、或 resolver 签名漏了 ctx context.Context。
schema 改了但服务 panic：“no such method”
这是最典型的“能编译但一跑就崩”。gqlgen generate 不监听文件变化，改完 schema.graphql 后不手动执行生成命令，generated.go 里的接口还是旧的——Go 编译器不检查你实现的 resolver 是否满足那个接口，但运行时反射一调用就 panic。
- 每次保存
schema.graphql后，立刻执行：go run github.com/99designs/gqlgen generate - 别依赖
gqlgen serve的自动重载：它只重启 HTTP server，不触发代码生成 - 新增了
Mutation或input类型，要检查gqlgen.yml的models段是否已映射对应 Go 结构体，否则生成器直接跳过整条链路 -
generated.go是只读契约文件，所有业务逻辑只写在resolver.go里
resolver 方法签名不对，编译不报错但运行 panic
签名错一个字符（比如 first *int 写成 first int），或少一个 ctx 参数，gqlgen generate 都不会提示，但 runtime 会严格按反射匹配：参数顺序、指针与否、返回值个数、甚至大小写（userName ≠ Username）。
- 根级字段（如
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 字段名完全一致，GraphQL 字段名是 camelCase，Go 方法名首字母大写，但其余部分大小写必须原样保留
HTTP 路由注册错，请求直接 404 或 panic
gqlgen 只提供 http.Handler，不自带 HTTP server。漏注册、路径写错、用错注册方式，前端发请求就收不到响应，连日志都可能没有。
立即学习“go语言免费学习笔记（深入）”；
- 正确注册方式：
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 里忽略 context 或裸 return error
context 不传透，超时控制失效、trace ID 断裂、中间件上下文丢失；错误不包装，客户端收不到结构化错误信息，只看到泛化的 “internal server error”。
- resolver 方法签名必须包含
ctx context.Context作为第一个参数，例如：func (r *queryResolver) Users(ctx context.Context, first *int) ([]*User, error) - 所有下游调用（DB 查询、HTTP 调用）都必须传入该
ctx，而非context.Background() - 错误不能直接
return fmt.Errorf("xxx")，应使用graphql.Error包装：return nil, graphql.Errorf("user %s not found", id) - 若需携带扩展字段（如
code），用graphql.WithExtensions(map[string]interface{}{"code": "USER_NOT_FOUND"})
真正容易被忽略的，是 Content-Type：GraphQL 请求体是 POST 的 JSON，Content-Type 必须为 application/json；用 curl 测试却忘了加 -H "Content-Type: application/json"，gqlgen 默认的 http.Handler 会静默返回空响应，不报错也不记录日志。
