fastapi(十二)-表单数据和文件上传

最新推荐文章于 2026-08-03 19:48:56 发布

翻译最新推荐文章于 2026-08-03 19:48:56 发布 · 7.1k 阅读

9 ·

本内容遵循CC 4.0 BY-SA版权协议

原文链接：https://fastapi.tiangolo.com/tutorial/request-files/

收录于

python

本文介绍如何在FastAPI中使用Form和File处理表单数据及文件上传，包括单文件和多文件上传的实现方式。

开发板推荐：天空星STM32F407VET6开发板

超高性价比 STM32主控 | 超高主频 | 一板兼容百芯 | 比赛神器 | 沉金彩色丝印

点击查看

当你需要接收表单字段而不是json时可以使用Form
为了使用form需要先安装python-multipart
pip install python-ultipart
eg:

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(*, username: str = Form(...), password: str = Form(...)):
    return {"username": username}

定义表单参数就和Body或Query时一样。可以为它添加metadata信息，以及验证等。

表单数据使用的“media type”是application/x-www-form-urlencode.但是当表单中包含文件的时候，可以使用multipart/form-data.
请求文件
eg:

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File(...)):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile = File(...)):
    return {"filename": file.filename}

File是从Form中继承的类，但是记住从fastapi中导入的Qury,Path,File等实际上是返回特殊类的方法。
这个file对象将作为表单数据上传。如果声明参数类型为bytes，fastapi将会以bytes的形式读取文件。同样也以为着整个文件内容将会缓存在内存中，这将在小文件中非常适用。
使用UpliadFile定义File参数
。。。
async def create_upload_file(file: UploadFile = File(…)):
。。。
使用UploadFile有几个优势相对于bytes：

它会使用“spooled”文件，文件存储在内存中并拥有最大的内存大小限制，并且超过了这个限制就会存储在硬盘中。
意味着它同样适用于更大的文件（图片，视频，更大的二进制文件等）又不会消耗很大的内存。
可以从上传文件中得到metadata
它会暴露出一个python的SpooledTemporaryFile对象，你可以直接使用它进行传递。
UploadFile
它拥有一下属性：
1、filename：上传的源文件的名字
2、content_type：（MIME type/media type）（eg:image/jpeg）
3、file:可用于直接传递的SpooledTemporaraFile对象。
同时也拥有一下async方法：
1、write(data):
2、read(data):
3、seek(data):
4、close（）
这些都是async方法，需要使用await调用他们。
eg:
contents = await myfile.read()
注意：当使用async方法的时候，fastapi将在threadpool中运行并等待他们。
多文件上传
eg:

from typing import List

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(files: List[bytes] = File(...)):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile] = File(...)):
    return {"filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
    """
    return HTMLResponse(content=content)