Mode决定生成代码的调用契约，必须与实际使用方式严格匹配：gen.WithDefaultQuery需配合query.Use(db)调用，gen.WithoutContext省略context参数，gen.WithQueryInterface生成接口需手动实现，混用可能导致签名冲突或运行panic。
必须先配对 Mode 和实际调用方式，否则生成的代码根本跑不起来
gen.Mode 决定你写代码时怎么调用 query
Mode 不是开关列表，而是契约风格——它直接决定生成的函数签名和初始化要求。常见错误都是 Mode 和后续使用不匹配导致的：
-
gen.WithDefaultQuery：生成query.User这类类型别名，但真正能用的是query.Use(db).User返回的实例；忘记调用query.Use(db)就会 panic “no db instance” -
gen.WithoutContext：生成的方法参数里没有context.Context，如果你业务中所有 DAO 调用都传了 ctx（比如带超时），编译直接报too many arguments -
gen.WithQueryInterface：生成UserDo接口类型，不能直接链式调用.Find()，得手动实现或用WithCtx包装，否则编译过、运行崩 - 混用
gen.WithDefaultQuery | gen.WithoutContext是合法的；但gen.WithDefaultQuery | gen.WithoutContext+gen.WithQueryInterface会导致Use()方法签名冲突，生成失败
字段类型映射错位，编译通过但运行 panic
MySQL 的 TINYINT(1) 默认被映射为 int8，而 Go 字面量 1 是 int 类型，传给 q.Status.Eq(1) 就会类型不匹配——这不是 bug，是 Go 类型系统在起作用。
- 别靠强制转换补救：
q.Status.Eq(int8(1))看似能跑，但后续所有人改逻辑都要记得转，维护成本爆炸 - 统一用
gen.FieldType("status", "int")把字段映射成int，适配业务习惯 - 布尔字段优先用
gen.FieldType("is_active", "bool")+gen.FieldRelate("is_active", "Active")，避免uint8带来的判断歧义（比如if u.IsActive == 1） -
DECIMAL字段强烈建议用gen.FieldType("amount", "int64")，单位转“分”，再加 JSON tag：json:"amount,string"，规避 float64 精度丢失
生成后 query.User.Where() 编译失败？检查三件事
生成的代码在 query/ 目录下，query.User 是结构体类型别名，不是变量；真正可调用的是 query.Use(db).User 实例。
立即学习“go语言免费学习笔记（深入）”；
- 确认已
import "your_project/query"，否则 IDE 提示undefined: query - 确保
query.Use(db)在db初始化之后调用；在init()或全局变量里提前执行，db是 nil 就会 panic - 检查
go.mod中 module 名是否与导入路径一致；比如 module 是github.com/your/project，但生成路径写了../query，Go 会找不到包
动态 SQL 注释必须写在 interface 方法的 doc comment 里
GEN 只识别 interface 方法上方的注释块作为 SQL 模板源，裸写 db.Raw() 或字符串拼接不会被保护，照样有注入风险。
- 正确写法：
// SELECT * FROM users WHERE name = @name {{if role != ""}} AND role = @role {{end}} FilterWithNameAndRole(name, role string) ([]gen.T, error) - 注释里的
@name会被转成类型安全参数，字段名拼错、参数类型不对，编译直接报错 - 自定义 SQL 必须走这个路径才能享受预编译 + 类型校验；其他任何绕过 GEN 的 raw SQL 都得自己做防护
最常被忽略的是 Mode 和调用方式的绑定关系——它不像配置项可以随便开/关，而是一套契约：生成什么，你就得怎么用。一旦错配，不是编译失败就是运行 panic，而且错误信息往往不直观。动手前先想清楚你团队的调用习惯（要不要 ctx？要不要全局 query 实例？），再选 Mode，比事后 debug 快得多。
