详解 http multipart/form-data

最新推荐文章于 2025-07-02 14:37:11 发布

原创最新推荐文章于 2025-07-02 14:37:11 发布 · 3.3k 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#http #网络协议 #网络

HTTP multipart/form-data 详解

1. 什么是 multipart/form-data？

multipart/form-data 是一种 HTTP 请求内容类型（Content-Type），主要用于在 Web 表单中上传文件或提交包含二进制数据的表单。它允许在单个 HTTP 请求中发送多个不同类型的数据（如文本字段和文件）。

与其他常见的内容类型（如 application/x-www-form-urlencoded 或 application/json）不同，multipart/form-data 专门设计用于高效传输二进制数据。

2. 为什么需要 multipart/form-data？

传输二进制数据：普通的表单编码（application/x-www-form-urlencoded）不适合传输大型二进制文件，因为它会对所有数据进行 URL 编码，导致数据量膨胀。
同时传输多种数据：可以在一个请求中同时发送文本字段和二进制文件。
保留文件元数据：可以保留文件名、MIME 类型等元数据。

3. multipart/form-data 的格式结构

multipart/form-data 的请求由以下部分组成：

3.1 请求头部

Content-Type: multipart/form-data; boundary=---------------------------12345

其中 boundary 参数定义了用于分隔不同部分的边界字符串。边界字符串必须是唯一的，不能出现在任何数据部分中。

3.2 请求体结构

请求体由多个部分组成，每个部分包含自己的头部和内容，格式如下：

--{boundary}
Content-Disposition: form-data; name="fieldName"[; filename="filename.ext"]
[Content-Type: mimeType]

{field data}
--{boundary}
... 更多字段 ...
--{boundary}--

注意：

每个部分以 --{boundary} 开始
最后一个部分以 --{boundary}-- 结束（额外的两个短横线）
每个部分的头部和内容之间有一个空行
对于文件，通常包含 filename 和 Content-Type 头

4. 实际示例解析

以下是一个包含文本字段和文件的 multipart/form-data 请求的实际内容：

POST /upload HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=---------------------------7d33a816d302b6
Content-Length: 568

-----------------------------7d33a816d302b6
Content-Disposition: form-data; name="username"

johndoe
-----------------------------7d33a816d302b6
Content-Disposition: form-data; name="email"

john@example.com
-----------------------------7d33a816d302b6
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[二进制数据...]
-----------------------------7d33a816d302b6--

在这个例子中：

我们有一个带有 boundary=---------------------------7d33a816d302b6 的 multipart/form-data 请求
请求包含三个部分：
- 名为 “username” 的文本字段，值为 “johndoe”
- 名为 “email” 的文本字段，值为 “john@example.com”
- 名为 “avatar” 的文件字段，文件名为 “photo.jpg”，MIME 类型为 “image/jpeg”
每个部分都有自己的 Content-Disposition 头
文件部分还有一个 Content-Type 头
最后一个部分以 --{boundary}-- 结尾

5. Content-Disposition 头部详解

Content-Disposition 头部用于描述表单字段的属性，格式为：

Content-Disposition: form-data; name="fieldName"[; filename="filename.ext"]

其中：

name 参数指定表单字段的名称
filename 参数（可选）指定上传文件的原始文件名

6. 各种语言/框架中的实现

6.1 HTML 表单

在 HTML 中，要使用 multipart/form-data，需要在 <form> 标签中设置 enctype 属性：

<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="text" name="username">
  <input type="file" name="avatar">
  <button type="submit">上传</button>
</form>

6.2 Qt/C++ 中的实现

在前一个回答中，我提供了 Qt/C++ 中使用 QHttpMultiPart 类实现 multipart/form-data 的示例：

// 创建 multipart 对象
QHttpMultiPart *multiPart = new QHttpMultiPart(QHttpMultiPart::FormDataType);

// 添加文本字段
QHttpPart textPart;
textPart.setHeader(QNetworkRequest::ContentDispositionHeader, 
                  QVariant("form-data; name=\"username\""));
textPart.setBody("johndoe");
multiPart->append(textPart);

// 添加文件
QFile *file = new QFile("photo.jpg");
file->open(QIODevice::ReadOnly);

QHttpPart filePart;
filePart.setHeader(QNetworkRequest::ContentDispositionHeader, 
                  QVariant("form-data; name=\"avatar\"; filename=\"photo.jpg\""));
filePart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("image/jpeg"));
filePart.setBodyDevice(file);
file->setParent(multiPart); // multiPart 负责释放文件
multiPart->append(filePart);

// 发送请求
QNetworkAccessManager manager;
QNetworkRequest request(QUrl("http://example.com/upload"));
QNetworkReply *reply = manager.post(request, multiPart);
multiPart->setParent(reply); // reply 负责释放 multiPart

6.3 JavaScript/Fetch API

在现代 JavaScript 中，可以使用 FormData 对象和 Fetch API：

// 创建 FormData 对象
const formData = new FormData();

// 添加文本字段
formData.append('username', 'johndoe');
formData.append('email', 'john@example.com');

// 添加文件
// 假设 fileInput 是一个 <input type="file"> 元素
const fileInput = document.querySelector('input[type="file"]');
formData.append('avatar', fileInput.files[0]);

// 发送请求
fetch('http://example.com/upload', {
  method: 'POST',
  body: formData
  // 注意：不需要手动设置 Content-Type，fetch 会自动设置为 multipart/form-data 并生成边界
})
.then(response => response.json())
.then(data => console.log('Success:', data))
.catch(error => console.error('Error:', error));

6.4 Python 使用 requests 库

import requests

url = 'http://example.com/upload'

# 文本字段
data = {
    'username': 'johndoe',
    'email': 'john@example.com'
}

# 文件
files = {
    'avatar': ('photo.jpg', open('photo.jpg', 'rb'), 'image/jpeg')
}

# 发送请求
response = requests.post(url, data=data, files=files)
print(response.json())

7. 服务器端接收 multipart/form-data

服务器接收 multipart/form-data 请求时，需要解析复杂的请求体结构。大多数 Web 框架都提供了内置的解析功能：

7.1 Node.js 使用 express 和 multer

const express = require('express');
const multer = require('multer');
const app = express();

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, 'uploads/');
  },
  filename: function (req, file, cb) {
    cb(null, Date.now() + '-' + file.originalname);
  }
});

const upload = multer({ storage: storage });

// 单文件上传
app.post('/upload', upload.single('avatar'), (req, res) => {
  console.log('文本字段:', req.body);
  console.log('文件:', req.file);
  res.send('上传成功');
});

app.listen(3000);

7.2 PHP 接收处理

<?php
// 处理文本字段
$username = $_POST['username'];
$email = $_POST['email'];

// 处理文件
if (isset($_FILES['avatar']) && $_FILES['avatar']['error'] === UPLOAD_ERR_OK) {
    $tempPath = $_FILES['avatar']['tmp_name'];
    $fileName = $_FILES['avatar']['name'];
    $fileType = $_FILES['avatar']['type'];
    $fileSize = $_FILES['avatar']['size'];
    
    // 移动上传的文件到目标目录
    move_uploaded_file($tempPath, "uploads/$fileName");
    
    echo "上传成功！";
}
?>