Gin Handler单元测试必须打桩外部依赖，否则因直连数据库或网络而变慢、不稳定、不可重复，且无法覆盖“用户不存在”等边界场景；打桩本质是将依赖行为解耦为可编程控制的返回值，核心是mock service/repo接口而非HTTP层。
为什么 Gin Handler 测试必须打桩外部依赖
不打桩的 Handler 单元测试不是真单元测试，而是集成测试。Gin 的 Context 本身不隔离业务逻辑依赖——比如一个 GET /user/:id handler 内部调用 userRepo.FindByID()，若该方法直连数据库或 HTTP 服务，测试会变慢、不稳定、不可重复，且无法覆盖如“用户不存在”“网络超时”等边界场景。
真实项目中常见错误现象：
- 测试偶尔失败，日志显示
connect: connection refused或数据库 timeout - 本地能过，CI 环境因缺少 DB 配置直接 panic
- 想测“repo 返回 error”，却要手动停掉 MySQL，成本高且不幂等
打桩的本质是把“依赖行为”从运行时解耦为可编程控制的返回值。对 Gin handler 来说，关键不是 mock HTTP 层（httptest 已解决），而是 mock 它调用的 service/repo 接口。
gomock 生成 mock 时最常卡住的三个路径问题
mockgen 报错 “no interfaces found” 或测试里提示 undefined: NewMockXXX，90% 是路径/包名不匹配。它不读 go.mod，只认文件系统和 -package 参数语义。
- 源 interface 在
internal/user/service.go？mockgen默认扫描不到——改用mockgen -exec_only -source=... -imports=your-module/internal/user - 生成目标文件写在
mocks/mock_user_service.go，但该目录下go list -f '{{.Name}}' mocks返回main？必须确保该文件首行是package mocks，且目录无go.mod干扰（否则可能被识别为独立 module） - 测试文件 import 路径写成
"./mocks"或"myproj/mocks"错了？必须与go list -m输出的 module 名完全一致，例如github.com/your-org/myproj/mocks
Gin handler 构造函数必须接收接口，否则 mock 注入无效
Handler 结构体若在内部 new 具体实现（如 us := &UserService{db: db}），测试时无论你怎么传 mock 实例，它都用不上。Gin 本身不提供 DI 容器，依赖注入全靠显式传递。
- 正确写法：
func NewUserHandler(us UserService) *UserHandler，其中UserService是接口 - 测试中：
ctrl := gomock.NewController(t); defer ctrl.Finish(); mockUS := mocks.NewMockUserService(ctrl); h := NewUserHandler(mockUS) - 漏掉
defer ctrl.Finish()？mock 调用未满足时不会报错，导致测试“假通过”——这是最隐蔽也最常被忽略的坑 - 若项目用 wire/dig，确保 wire.Build 中注册的是 interface 类型，而非 struct；否则生成代码仍会绑定具体实现
用 httptest + gomock 跑通一个带 mock 的 Gin handler 测试
核心是三步：构造 mock 依赖 → 组装 handler → 用 httptest 发请求并断言。不要试图在 handler 里做任何依赖初始化。
- mock 行为需在测试用例内明确设定：
mockUS.EXPECT().FindByID(gomock.Any()).Return(&User{ID: 123}, nil) - router 初始化必须用
gin.New()而非gin.Default()，避免默认 logger/mode 干扰断言 - 注意 Context 取参方式一致性：若 handler 用
c.Param("id")，测试请求路径就得是/user/123；若用c.Query("id")，就得是/user?id=123 - 错误分支测试别只 mock
nil：补一句mockUS.EXPECT().FindByID("999").Return(nil, errors.New("not found"))，再断言返回 404
真正难的不是写这几行代码，而是整个代码库是否从第一行就按“依赖接口”设计。一旦某个 service 方法被 struct 直接调用，mock 就断在那一层，再往后补 interface 成本远高于初期约定。
