Go HTTP 客户端怎么同时上传文件和表单字段

Go HTTP 客户端要在一次请求里同时上传文件和表单字段，核心不是手写字符串，而是让 mime/multipart.Writer 负责组织每个 part。文件用 CreateFormFile，文本用 WriteField，最后调用 Close 写完结束 boundary，再把 FormDataContentType() 放进请求头。

最小可靠顺序是：创建 multipart.Writer → 写普通字段 → 写文件 → Close → 创建并发送 HTTP 请求。少了最后一步，服务端常见表现就是表单不完整或报 multipart 解析错误。

先用 bytes.Buffer 接住 multipart body

multipart.NewWriter 接收一个 io.Writer，并为这次消息生成 boundary。把它接到 bytes.Buffer 最容易理解：所有字段和文件内容先写入内存，写完后再交给 http.NewRequest。

var body bytes.Buffer
writer := multipart.NewWriter(&body)

// Content-Type 中必须带上本次 Writer 使用的 boundary。
contentType := writer.FormDataContentType()

这里的 Content-Type 通常类似 multipart/form-data; boundary=...。不要只写 multipart/form-data，否则接收端无法按同一个分隔符找到各个 part。除非协议明确要求固定值，否则也不需要自己调用 SetBoundary。

分别写入表单字段和文件 part

普通字段可以直接用 WriteField；文件则先用字段名和文件名创建 part，再把打开的文件复制进去。字段名必须与服务端读取的 key 完全一致，例如服务端读取 upload，客户端就不能写成 file。

// 先写文本字段，服务端会在普通表单值中读取它。
if err := writer.WriteField("description", "季度报表"); err != nil {
	return err
}

file, err := os.Open("./report.xlsx")
if err != nil {
	return err
}
defer file.Close() // 请求构造结束后释放文件描述符。

part, err := writer.CreateFormFile("upload", "report.xlsx")
if err != nil {
	return err
}
if _, err := io.Copy(part, file); err != nil {
	return err
}

CreateFormFile 是便捷方法，会创建带有 form-data、字段名和文件名的文件 part。它返回的 io.Writer 只代表这个 part；复制完成前不要创建下一个 part，也不要忽略复制错误。

关闭文件与 Writer，再创建 HTTP 请求

文件 Close 和 multipart.Writer.Close 不是一回事。前者释放本地文件资源，后者向请求体写入 multipart 消息的结束 boundary。应在所有 part 写完后检查后者的错误，再创建请求：

if err := writer.Close(); err != nil {
	return err // 结束 boundary 写入失败时不要发送不完整 body。
}

req, err := http.NewRequest(http.MethodPost, "https://api.example.com/upload", &body)
if err != nil {
	return err
}
req.Header.Set("Content-Type", contentType)
req.Header.Set("X-Client", "report-uploader") // 示例自定义头，按接口协议决定是否保留。

resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close() // 读取或丢弃响应后释放连接资源。
if resp.StatusCode = 300 {
	return fmt.Errorf("upload failed: %s", resp.Status)
}

请求体的内容类型必须取自同一个 writer。如果先创建请求、后继续写 part，或者忘记 Close，请求头和 body 的边界就可能不一致。http.Client 的具体超时、认证头和响应 JSON 解析，再按接口实际约定补充。

按请求头和失败点排查上传失败

上传接口返回 400 时，先不要盲目改文件内容。按下面顺序核对，通常能快速把问题收敛到客户端构造还是服务端字段约定。

如果只是一个小文件，bytes.Buffer 的实现简单、便于重试和记录请求大小；文件较大或并发上传时，应该评估内存峰值，再采用生产者与 HTTP 请求并行的流式方案。

常见问题

可以把文件和字段分别发两个请求吗？

可以，但那就不是一次 multipart 表单提交了。需要原子关联时，把二者放在同一个 multipart body 更直接。

为什么不能只设置 multipart/form-data？

因为接收端还需要 boundary 参数来切分 body。完整值由 FormDataContentType 根据当前 Writer 生成。

文件名和字段名分别是什么？

CreateFormFile 的第一个参数是服务端字段名，第二个参数是上传元数据里的文件名；两者不要混用。

把 multipart 请求看成“一个 body、多个 part”就不容易写错：文本通过 WriteField 进入，文件通过 CreateFormFile 进入，所有内容完成后由 Close 封口，HTTP 头则复用同一个 Writer 的内容类型。