gqlgen init卡住或报错“module not found”“no Go files”，本质是Go module未初始化或GOPROXY配置失效；需先在项目根目录执行go mod init、设有效代理（如https://goproxy.cn）、避免GOPATH混用，并确保schema与gqlgen.yml一致。
gqlgen init卡在module初始化或代理失败
直接跑 gqlgen init 报错“no Go files in current directory”或“module not found”，不是工具问题，是环境没准备好。
- 必须先在项目根目录执行
go mod init example.com/myapp，且确保go.mod文件已生成并可读 - 运行
go env GOPROXY，如果输出为空或direct，立刻设为国内可用源：go env -w GOPROXY=https://goproxy.cn - 绝对不要在
$GOPATH/src下初始化——gqlgen强制要求纯 module 模式，混用GOPATH会导致路径解析失败、schema 找不到 - 若仍卡住，手动拉稳定版再试：
go get github.com/99designs/gqlgen@v0.17.49
schema改了但resolver不生效或编译报错
这是最常被忽略的步骤断点：gqlgen 不自动监听 schema 变更，也不增量更新代码。
- 每次修改
schema.graphqls后，必须显式运行：go run github.com/99designs/gqlgen generate - 务必先删掉旧的
graph/generated/generated.go，否则新旧代码混在一起，编译器会报方法签名冲突或未实现接口 - 检查
gqlgen.yml的models配置是否覆盖新增类型（比如加了CreateUserInput却没配映射），漏配会导致生成器跳过整个链路 - 生成后打开
graph/generated/generated.go，确认你写的*queryResolver真实实现了它——方法名大小写、参数顺序、ctx context.Context是否在第一位，一个都不能错
resolver函数里context和错误处理怎么写才不出错
忽略 ctx 或直返 fmt.Errorf 是两个高频崩溃点，尤其在 DB 调用和中间件透传时。
- 所有 resolver 函数签名第一参数必须是
ctx context.Context，且要透传给下游调用（如db.QueryContext(ctx, ...)），否则超时、取消信号全丢 - 错误必须用
gqlerror.Errorf构造，不能用fmt.Errorf或裸errors.New；前者带 GraphQL 标准错误结构（extensions、locations），后者会被吞成空响应或 panic - 返回值类型必须与 schema 字段类型严格对齐：schema 写
String!→ resolver 返回*string；写[User!]!→ 返回[]*User；基本类型非指针（如Int!）返回int，但要注意零值（如0）会被当有效数据，不是null
Gin路由注册GraphQL handler时容易踩的坑
gqlgen 本身不启动 HTTP 服务，也不注册路由——它只提供 http.Handler，你得自己塞进 Gin。
- 别用
GET /graphql接 query 字符串（如?query={hello}），GraphQL 规范要求 POST + JSON body，Gin 默认不解析 query string 里的嵌套结构，会丢字段 - Playground 和 query endpoint 必须分离路径：比如 Playground 用
/playground，实际 API 用/query，否则graphiql:true会干扰生产请求 - 正确注册方式：
r.POST("/query", graphqlHandler)，其中graphqlHandler是graphql/handler.NewDefaultServer(...)包装后的gin.HandlerFunc - 如果你用 Dig 做依赖注入，注意
generated.NewExecutableSchema的Config.Resolvers必须传入真实实现体（如&graph.Resolver{Services: s}），不能传 nil 或空 struct
真正麻烦的从来不是写 resolver，而是 schema 变更后忘记 regenerate、ctx 没透传导致 DB 连接堆积、或者 handler 路径配错让前端一直收 404。这些点不盯紧，调试成本远高于写业务逻辑本身。
