Gin单元测试应直接调用router.ServeHTTP配合httptest.NewRequest和NewRecorder，避免router.Run()；需显式注册中间件、设TestMode、用ShouldBindJSON而非BindJSON，并正确模拟URL和query参数。
直接用 httptest.NewRequest + httptest.NewRecorder 调 router.ServeHTTP，不启服务、不走网络，才是 Gin 单元测试的正路。其他方式（比如调 router.Run() 或发真实 HTTP 请求）本质是集成测试，慢、不稳定、难定位问题。
为什么不能调 router.Run() 做单元测试
调 router.Run() 会真正监听端口、启动 HTTP server，测试进程被阻塞，无法并发执行，且每次测试都要等端口释放；更关键的是，它把 handler、中间件、网络栈、TLS、超时逻辑全裹在一起，你本想测一个 JSON 解析逻辑，结果失败原因可能是 DNS 解析超时或 TLS 握手失败。
- 单元测试必须控制边界：只验证 handler 行为，不牵扯网络层
-
router.Run()是运行时行为，不是可测接口；router.ServeHTTP才是 handler 的函数式入口 - 真实端口还可能被占用，CI 环境下极易因端口冲突失败
测试带 URL 参数和 query 参数的路由
Gin 不从请求 URL 字符串里自动拆参数，而是靠注册时的路径模式（如 /users/:id）配合内部解析器匹配。测试时要模拟“已匹配成功”的状态，而不是让测试代码去重现实现逻辑。
- URL 参数（path param）：请求路径写死具体值，例如
"/users/123"，Gin 会在c.Param("id")中返回"123" - Query 参数：拼在 URL 后，如
"/users?role=admin&page=2"；也可用req.URL.RawQuery = "role=admin&page=2"显式设置 - 别手动改
c.Params—— 这是 Gin 内部字段，直接操作会绕过类型校验和绑定逻辑
c.BindJSON 和 c.ShouldBindJSON 在测试中必须分清
这是 Gin 测试里最常翻车的点：c.BindJSON 遇错直接写响应并 return，handler 后续逻辑不执行；c.ShouldBindJSON 只校验、不响应，把错误交给你自己处理。单元测试需要后者来掌控流程。
- 用
c.BindJSON时，测试断言必须检查w.Code（比如是否为http.StatusBadRequest），否则可能误判“空响应 = 成功” - 用
c.ShouldBindJSON更利于测试分支：构造非法 JSON → 断言错误类型 → 验证自定义错误响应格式 - handler 里优先用
c.ShouldBindJSON，避免隐式终止，让错误处理逻辑显性化、可测化
中间件没生效？不是框架问题，是测试初始化漏了
你在 main.go 里写的 r.Use(AuthMiddleware()) 对测试文件里新建的 gin.New() 实例完全无效。测试上下文干净独立，所有中间件必须显式注册。
- 漏注册中间件 → 测试通过但线上 401，或者测试报 404（CORS 没生效被浏览器拦截）
- 推荐把 router 初始化抽成函数，例如
func NewRouter(mws ...gin.HandlerFunc) *gin.Engine，测试时传入 mock 版中间件 - JWT 类中间件测试时用固定 token + fake 验证逻辑，别连真实密钥服务或 Redis
- 记得设
gin.SetMode(gin.TestMode)，否则默认的Logger和Recovery中间件会往w.Body写日志、吞 panic，干扰断言
真正难的不是写测试，而是守住边界：handler 就只管业务逻辑，中间件就只管横切关注点，测试就只驱动这两者协作——任何一处越界，都会让测试变脆、变慢、变不可信。
