文件上传接口设计：从单文件到分片上传，一篇把 multipart / Base64 / 分片 / 断点续传 / 秒传讲透

去年帮一个视频团队做后台。使用者上传 0.2GB 的素材，传到一半网络掉线，重连后又得从头开始。那天我重新审视了一下「上传」这件事——看似是 HTTP 最基础的功能，却暗藏着大量细节。

先抛三个主要：

1. multipart、Base64、分片这几种方式不是「哪个更适合」的竞争关系，而是「哪个场景该用哪个」——选型比实现更关键。
2. 分片上传的主要不在切片，而在状态管理。客户端断点续传、服务端合并校验、秒传判定，都围绕一个统一的 file_hash 进行。
3. 上线后真正让人加班的坑，往往藏在并发控制、分片大小、临时文件清理还有安全防护上。不过，

一、三种基础上传方式：先搞清楚为什么会有这么多方案

1️⃣ multipart/form-data —— 标准做法。但不是万能

使用者痛点：大文件无法断点续传； 网关/代理对请求体大小有限制； 某些框架会把整个文件读入内存导致 OOM。不过，

HTTP 的 multipart 编码本身就是为文件设计的。浏览器的 就使用它。FastAPI 中接收非常简洁：

# server.py —— multipart 上传
import aiofiles
from pathlib import Path
from fastapi import FastAPI,UploadFile,File
app = FastAPI
UPLOAD_DIR = Path
UPLOAD_DIR.mkdir
@app.post
async def upload_multipart):
save_path = UPLOAD_DIR / file.filename
# 流式写入，避免一次性占满内存
async with aiofiles.open as f:
while chunk := await file.read:
await f.write
return {"filename": file.filename。
"size": save_path.stat.st_size}

客户端只需一行代码：

# client.py —— multipart 客户端
import requests
def upload_multipart:
with open as f:
r = requests.post(
说到"http，//localhost:8000/upload/multipart",files={"file":,f)},)
return r.json

适用场景：中小体积的“一次性提交”，如头像、Excel 导入、表单附件等。

2️⃣ Base64 上传：被诟病但仍有不可替代的地方

使用者痛点：数据体积膨胀约 33%；若未做好大小校验会导致服务器 OOM；不适合大文件，

Base64 把二进制塞进 JSON，虽然增加了约 33% 的体积。但在以下情况下仍然是比较好的选择：

• 移动端统一走 JSON 接口，不想额外实现 multipart。
• 文件极小，必须随其它字段一起提交。
• 业务要求所有请求都是纯文本。

# server.py —— Base64 上传
import base64
from fastapi import Request,HTTPException
MAX_SIZE_MB = 10
@app.post
async def upload_base64:
body = await request.json
filename = body
raw = body.encode
# 估算原始大小
estimated_size = len * 3 // 4
if estimated_size> MAX_SIZE_MB * 1024 * 1024:
raise HTTPException(status_code=413,detail=f"Base64 上传限制 {MAX_SIZE_MB} MB以内")
data = base64.b64decode
save_path = UPLOAD_DIR / filename
async with aiofiles.open as f:
await f.write
return {"filename": filename。"size": len}

# client.py —— Base64 客户端
import base64
import requests
def upload_base64:
with open as f:
data = base64.b64encode).decode
r = requests.post(
从"http来看，//localhost:8000/upload/base64",json={"filename": path.split,"data": data},)
return r.json

3️⃣ 分片上传：解决大文件、断点续传与秒传需求

使用者痛点：

• 网络不稳定时需要手动重试，每次都重新上传全部数据。
• 服务器收到巨大的单体请求，会导致超时或占满磁盘临时空间。
• SaaS 场景下同一资源被多次上传，不要重复存储。老实说，

The core of a robust chunked upload is a **统一标识** . With this identifier you can:

• 判断该文件是否已经存在实现秒传；怎么说呢，

服务端 API 示例

# server_chunk.py —— 分片上传主要原因
import hashlib
import os
from pathlib import Path
from fastapi import FastAPI,HTTPException,UploadFile,File,Form

app = FastAPI BASEDIR = Path MERGEDIR = Path BASEDIR.mkdir MERGEDIR.mkdir

CHUNK_SIZE = 5 * 1024 * 1024 # 默认每块 5 MB。可根据业务调优

def hashfile -> str: md5 = hashlib.md5 while chunk := fp.read: md5.update return md5.hexdigest

@app.post async def initupload( filename: str = Form,totalsize: int = Form,filehash: str = Form): """ 返回值示例： { "uploadid": "","need_chunks": # 服务端已存在哪些块，可用于秒传/断点续传 } """