gqlgen仅生成类型安全的Go代码，不提供HTTP服务；需手动实现http.Handler并注入NewExecutableSchema，正确配置resolver、模型映射及自定义标量。

gqlgen 不能直接“搭建 GraphQL”，它只生成类型安全的 Go 代码；真正提供 GraphQL endpoint 的是 http.HandlerFunc 或你选的 Web 框架（如 net/http、gin、echo），这点很多人一开始就被误导。

为什么 gqlgen generate 后没有跑起来？

常见错误现象：gqlgen generate 成功但访问 /query 返回 404 或 panic；或 go run server.go 报错说找不到 graphql.Resolver。

• 根本原因：gqlgen 只生成 generated.go 和 models_gen.go，不生成 HTTP handler，也不启动服务
• 你必须自己写一个 http.Handler，把 gqlgen/graphql.NewExecutableSchema 包进去
• 如果用了自定义 Resolver 接口（比如 QueryResolver），要确保实现体（如 server.QueryResolver）被正确传入 Config.Resolvers
• 别漏掉 gqlgen.yml 中的 resolver 配置——否则生成的 resolver 方法全是空实现

gqlgen init 生成的代码为什么不能直接用？

它只是骨架，关键部分留空且带注释提示，比如：

func (r *queryResolver) Users(ctx context.Context) ([]*model.User, error) {
    panic(fmt.Errorf("not implemented"))
}

使用场景：适合快速验证 schema 是否可解析，但上线前必须替换所有 panic 为真实逻辑。

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

立即学习“go语言免费学习笔记（深入）”；

• 返回值类型必须严格匹配 models_gen.go 中生成的 struct，不能用 map[string]interface{} 或自定义未映射 struct
• 参数顺序和类型必须与 schema.graphql 定义一致，例如 Users(ctx context.Context, first *int) 中 first 是指针，不是 int
• 如果 resolver 方法签名不对，gqlgen generate 不报错，但运行时会 panic：“no such method”

如何让 gqlgen 正确识别自定义模型（比如 GORM 结构体）？

默认情况下，gqlgen 会为每个 type 生成新 struct，导致数据层和 GraphQL 层类型割裂。

• 在 gqlgen.yml 的 models 段手动映射：

  models:
    User:
      model:
        - github.com/your/app/model.User

• 确保 model.User 字段名首字母大写（Go 导出要求），且 tag 匹配 schema 字段，例如 Name string `json:"name"`
• 如果字段名不一致（如数据库列是 user_name，schema 要 name），用 mapstructure tag 或在 resolver 中显式赋值，gqlgen 不自动做蛇形转驼峰
• 切忌在 models 映射里写错包路径——编译失败时错误信息往往不提 gqlgen，只报 “undefined: xxx”

最常被忽略的是：gqlgen 对 interface{}、json.RawMessage、嵌套 slice/map 的支持极弱，一旦 schema 里出现 JSON 类型，几乎必须手写 UnmarshalGQL/MarshalGQL 方法，且要注册到 Config.Directives 或 Config.Scalar —— 这块没文档示例，容易卡死。