【Python开发】FastAPI 05：请求表单与文件

类似之前的路径参数、查询参数和请求参数，表单与文件也可以算是请求参数中的一员，不过表单与文件更为特殊一些，表单是处理键值对数据、文件则是处理文件数据（图片、音频、视频等文件）。

目录

1 请求表单数据

1.1 表单字段

1.2 Form 使用

2 请求文件

2.1 File 使用

2.2 UploadFile 使用

2.3 更多方式

① 可选文件上传

② 多文件上传

---

源码地址：

https://gitee.com/yinyuu/fast-api_study_yinyu

1 请求表单数据

1.1 表单字段

HTML 表单（

）向服务器发送数据通常使用「特殊」的编码。

比如，包含一个普通输入框和一个密码输入框：

Username: 

Password: 

FastAPI 的目的是要确保从正确的位置读取数据，而不是读取 JSON。

表单数据的「媒体类型」编码一般为 application/x-www-form-urlencoded。

HTTP 协议规定：可在一个路径操作中声明多个 Form 参数，但不能同时声明接收 JSON 的 Body 字段，此时请求体的编码是 application/x-www-form-urlencoded，而不是不是 application/json。 

1.2 Form 使用

如果接口接收的不是 JSON，而是表单字段时，要使用 Form。

预先安装：pip install python-multipart

from fastapi import FastAPI, Form　＃从 fastapi 导入 Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):　＃定义 Form 参数
    return {"username": username}

创建表单（Form）参数的方式与 Body 和 Query 一样，也可以使用 default、description、title、gt 等元数据和验证！

OAuth2 规范的 "密码流" 模式规需要通过表单字段发送 username 和 password。 该规范要求字段必须命名为 username 和 password，并通过表单字段发送，不能用 JSON。

2 请求文件

2.1 File 使用

File 用于定义客户端的上传文件。

预先安装：pip install python-multipart

from fastapi import FastAPI, File, UploadFile　＃从 fastapi 导入 File

app = FastAPI()


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

创建文件（File）参数的方式与 Body 和 Query 一样，也可以使用 default、description、title、gt 等元数据和验证！

此时路径操作函数参数的类型声明为 bytes，FastAPI 将以 bytes 形式读取和接收文件内容。这种方式把文件的所有内容都存储在内存里，适用于小型文件。

上传文件以「表单数据」形式发送，表单包含文件时，编码为 multipart/form-data。使用了 File，FastAPI 就知道要从请求体的正确位置获取文件。

2.2 UploadFile 使用

很多情况下，UploadFile 更好用。

from fastapi import FastAPI,　UploadFile　＃从 fastapi 导入 UploadFile

app = FastAPI()

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):　＃定义文件参数时使用 UploadFile
    return {"filename": file.filename}

 UploadFile 与 bytes 相比：

• 使用 spooled 文件：存储在内存的文件超出最大上限时，FastAPI 会把文件存入磁盘；
• 这种方式更适于处理图像、视频、二进制文件等大型文件，好处是不会占用所有内存；
• 可获取上传文件的元数据；

 UploadFile 属性如下：

• filename：上传文件名字符串（str），例如， myimage.jpg；
• content_type：内容类型（MIME 类型 / 媒体类型）字符串（str），例如，image/jpeg；
• file： SpooledTemporaryFile（ file-like 对象）。其实就是 Python文件，可直接传递给其他预期 file-like 对象的函数或支持库。

2.3 更多方式

① 可选文件上传

如果熟悉其他请求参数的话，你可以通过 None 作为默认值将一个文件参数设为可选:

from typing import Union

from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/files/")
async def create_file(file: Union[bytes, None] = File(default=None)):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}

@app.post("/uploadfile/")
async def create_upload_file(file: Union[UploadFile, None] = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

② 多文件上传

可用同一个「表单字段」发送含多个文件的「表单数据」。

上传多个文件时，要声明含 bytes 或 UploadFile 的列表（List）：

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]):
    return {"filenames": [file.filename for file in files]}

@app.get("/")
async def main():
    content = """










    """
    return HTMLResponse(content=content)

接收的也是含 bytes 或 UploadFile 的列表（list）。