根本原因是测试请求未触发multipart解析流程；Gin仅在首次调用c.FormFile等方法时解析body，若中间件提前读取Body、method非POST/PUT或未调用writer.Close()，均导致c.FormFile返回nil。
为什么 c.FormFile() 在测试里总是返回 nil
根本原因不是 Gin 有 bug，而是测试请求没触发 multipart 解析流程。Gin 只在首次调用 c.MultipartForm()、c.FormFile() 或 c.PostForm() 时才解析 body；如果 handler 没走到这一步（比如 panic 早于解析、中间件提前读了 c.Request.Body 但没重放），c.FormFile("file") 就会返回 nil。
常见诱因：
- 忘记调用
writer.Close()→ 请求体不完整 →ParseMultipartForm失败 - 请求 method 不是
POST或PUT→ Gin 直接跳过 multipart 解析 - 中间件（如鉴权、日志）调用了
c.Request.Body.Read()但没用io.NopCloser重放 → body 流已关闭，后续FormFile读不到数据
验证方式：在 handler 开头加 fmt.Printf("form: %+v\n", c.MultipartForm())，看是否为 nil。
怎么构造合法的 multipart/form-data 测试请求
不能手写 raw body，也不能传 JSON 字符串——Gin 的 c.FormFile() 依赖底层 *http.Request 的 multipart.Form 字段，必须用标准库 multipart.Writer 构建。
关键三步：
- 用
bytes.Buffer+multipart.NewWriter(buf)创建写入器 - 字段名（如
"file"）必须和 handler 中c.FormFile("file")的参数完全一致 - 请求头
Content-Type必须设为writer.FormDataContentType()，不能硬编码或漏掉boundary
示例片段：
buf := &bytes.Buffer{}
writer := multipart.NewWriter(buf)
file, _ := writer.CreateFormFile("file", "test.png")
file.Write([]byte("fake-image-content"))
writer.Close() // 这行不能少
req, _ := http.NewRequest("POST", "/upload", buf)
req.Header.Set("Content-Type", writer.FormDataContentType())
为什么 gin.Default() 会让单元测试不可靠
gin.Default() 默认注入 Logger 和 Recovery 中间件，这两者在测试中会干扰预期行为：
-
Recovery会捕获 panic 并转成 500 响应，导致你 mock 的 panic 不抛出，测试通过但线上 crash -
Logger写 stdout/stderr，污染测试输出，还可能因格式差异让断言失败 - 中间件执行顺序不可控，比如你 mock 一个
*gin.Context，实际运行时却被 recovery 包裹了一层
正确做法是显式初始化：
r := gin.New() r.Use(middleware.Recovery()) r.Use(middleware.LoggerWithWriter(customWriter)) // 然后注册路由
这样所有中间件生命周期、错误传播路径都可预测，测试才真正反映运行时行为。
全局变量未初始化导致测试失败
常见现象：代码里定义了全局 struct 变量，并在 init() 函数中赋值；但在单元测试中，调用 controller 时发现该变量字段全为 nil。
根本原因是 Go 的包初始化顺序问题：测试文件所在的包（如 test）可能先于定义全局变量的包（如 pkg/server）完成初始化，导致 init() 还没执行。
解决方向：
- 避免在
init()中做跨包依赖的初始化，改用 lazy init（首次访问时检查并初始化） - 把全局变量封装成函数返回，例如
func GetConfig() *Config，内部加 sync.Once - 测试前显式调用一次目标包的初始化逻辑（如
import _ "yourapp/pkg/server"）
最稳妥的是彻底去掉全局状态，改用依赖注入——测试时直接传入已初始化的实例，不依赖包级生命周期。
