c.Request.MultipartForm 不能直接用于日志，因其惰性解析——未调用 c.FormFile/c.PostForm 或显式 ParseMultipartForm 前为 nil；一旦解析，Request.Body 即被消费，导致后续签名校验等失败。
为什么 c.Request.MultipartForm 不能直接用在日志里
因为 MultipartForm 是惰性解析的，Gin 默认不会主动解析 multipart 请求体——只有调用 c.FormFile、c.PostForm 或显式 c.ParseMultipartForm 后，它才被填充。直接读 c.Request.MultipartForm 可能是 nil，或字段为空，导致日志漏掉文件名、大小等关键信息。
更麻烦的是，一旦触发了解析，Request.Body 就被消费掉了，后续中间件或 handler 再想读原始 body（比如做签名校验、重放）会失败。
- 必须在解析前记录，但又需要解析才能拿到文件元信息 → 矛盾点就在这里
- 推荐做法：用
c.Request.Header.Get("Content-Type")初步判断是否为 multipart；再用c.Request.ContentLength记录总上传体积 - 若确定要记具体文件名，必须在首次调用
c.FormFile后立即记录，且确保这是整个请求生命周期中唯一一次解析
如何安全地在中间件中记录上传基本信息
中间件里不碰 FormFile，只提取 HTTP 层可读字段，避免破坏 body 流。这是最稳妥的日志起点。
func UploadLogMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
if strings.HasPrefix(c.GetHeader("Content-Type"), "multipart/form-data") {
c.Set("upload_start_time", time.Now())
c.Set("upload_content_length", c.Request.ContentLength)
// 注意：boundary 在 header 里，但一般没必要记
}
c.Next()
}
}
-
c.Request.ContentLength是客户端声明的总长度，含所有字段和文件，精度高、无副作用 - 不要尝试从
c.Request.Body读取并重写，Gin 的ShouldBind等操作依赖原始 body，篡改会导致 panic 或空表单 - 如果用了
gin.BasicAuth或 JWT 中间件，确保日志中间件放在它们之后，否则可能拿不到用户 ID
怎样在 handler 里记录真实文件名和大小
真正拿到文件信息的时机，只能是调用 c.FormFile 之后。此时应立刻构造结构化日志，避免后续逻辑出错导致遗漏。
func uploadHandler(c *gin.Context) {
file, err := c.FormFile("file")
if err != nil {
c.JSON(400, gin.H{"error": "no file provided"})
return
}
// ✅ 此刻 file.Filename 和 file.Size 是可靠的
log.Printf("[UPLOAD] user=%s name=%s size=%d path=%s",
c.GetString("user_id"),
file.Filename,
file.Size,
file.Filename, // 实际保存路径需另算，这里仅示意
)
dst := fmt.Sprintf("./uploads/%s", file.Filename)
if err := c.SaveUploadedFile(file, dst); err != nil {
c.JSON(500, gin.H{"error": "save failed"})
return
}
c.JSON(200, gin.H{"saved": dst})
}
-
c.FormFile内部已调用ParseMultipartForm，所以之后再调用c.PostForm("desc")也能拿到文本字段 - 注意
file.Size是文件内容长度，不含 base64 编码膨胀或 form 字段开销，比ContentLength更精确反映实际文件体积 - 如果前端传多个同名文件（如
<input type="file" multiple>），需用c.FormFile循环调用，每次都会返回一个*multipart.FileHeader
日志字段设计要注意哪些兼容性问题
不同客户端（curl / iOS / Android / Web）上传时，Filename 字段差异极大：空值、含路径（C:\fakepath\abc.jpg）、Unicode、控制字符都可能出现。不清洗直接入库或打到日志系统，容易引发解析失败或安全问题。
- 永远对
file.Filename做 sanitize：用path.Base去掉路径，用正则过滤非打印字符，长度限制建议 ≤255 - 不要把
file.Header整个序列化进日志——它包含原始 HTTP 头，可能含敏感 Cookie 或认证 token - 如果使用 ELK 或 Loki，建议将
upload_size_bytes定义为数字类型字段，而非字符串，方便后续聚合统计 - 并发上传场景下，
c.ClientIP()可能是反代 IP，需确认X-Forwarded-For是否可信并配置gin.ForwardedByClientIP = true
Content-Length 或 file.Size，结果无法区分“小图上传慢”和“大视频卡顿”。这两个字段必须同时存在，才有分析价值。 
