gqlgen是Go生态唯一可落地的GraphQL方案：先执行gqlgen init生成骨架，再运行gqlgen generate生成强类型代码，resolver业务逻辑须严格匹配接口签名，依赖注入推荐dig，N+1问题需DataLoader解决。
直接用 gqlgen 初始化 + 生成代码 + 实现 resolver，是目前 Go 生态中唯一可落地的 GraphQL 查询服务构建路径。其他方案（如 graphql-go）要么不支持订阅、要么缺乏强类型绑定和代码生成能力，实际项目中容易失控。
初始化项目必须执行 gqlgen init
这一步不是可选——它会自动生成标准目录结构和最小可运行骨架，包括：
-
graph/schema.graphqls：Schema 定义文件，所有类型、Query/Mutation 都从这里开始 -
graph/resolver.go：空的 resolver 实现模板，函数签名已由工具预设 -
graph/generated/generated.go：强类型绑定代码，含 Schema 解析器、模型结构体、resolver 接口 -
gqlgen.yml：配置文件，控制生成行为（比如模型包路径、是否导出字段）
常见错误：手动创建 schema.graphqls 后直接写 resolver，跳过 gqlgen init —— 这会导致生成代码缺失、接口不匹配、编译失败。
gqlgen generate 必须在每次改完 schema 后运行
Schema 和 Go 代码之间没有运行时反射对齐机制，全靠生成代码硬绑定。改了 schema.graphqls 却不执行 gqlgen generate，会出现两类典型报错：
立即学习“go语言免费学习笔记（深入）”；
-
missing method UserResolver.ID：字段新增/删除后，resolver 接口未更新 -
cannot use &Resolver{} as graph.Resolver (missing XXX method)：函数签名变更未同步
关键约束：只在 resolver.go 的函数体里写业务逻辑，别动函数声明——它会被下次 generate 覆盖。
resolver 中依赖注入要用 dig，别手写构造函数
硬编码 db := sql.Open(...) 在 resolver 方法里，会导致测试难、连接泄漏、无法复用。正确做法是把依赖交给容器管理：
- 在
main()或启动入口中初始化dig.Container - 用
container.Provide(func() *sql.DB { return dbConn })注册单例依赖 - 用
container.Invoke(func(r *graph.Resolver) { r.DB = ... })或构造函数注入（推荐）
注意：context.Context 不是依赖，不能塞进 dig；它必须作为 resolver 方法参数传入，由 GraphQL 执行引擎注入。
N+1 查询必须用 DataLoader，别指望 ORM 预加载
GraphQL 嵌套查询（如 { users { posts { author } } }）天然触发 N+1：查 100 个 user，再为每个 user 查一次 author。ORM 的 Preload 或 EagerLoad 只能解决一级嵌套，对深层或动态字段无效。
必须引入 DataLoader 模式：
- 使用
vektah/gqlgen-contrib/dataloader或自己封装批处理逻辑 - loader 实例应按请求生命周期创建（例如在 HTTP handler 中 new 一个），避免跨请求污染
- 调用
loader.Load(ctx, id)返回闭包，所有同层Load调用会被收集，最终合并为一次IN查询
最容易被忽略的一点：DataLoader 不是开箱即用的中间件，它需要你显式在每个 resolver 字段里调用 Load，漏掉任何一个字段，N+1 就照常发生。
