FastAPI开发文档教程-请求文件

admin
admin
admin
0
文章
0
评论
2026-01-10 10:54:24 编程 来源：ZONE.CI 全球网 0 阅读模式
  • 导入 File
  • 定义 File 参数
  • 含 UploadFile 的文件参数
    • UploadFile
  • 什么是 「表单数据」
  • 可选文件上传
  • 带有额外元数据的 UploadFile
  • 多文件上传
    • 带有额外元数据的多文件上传
  • 小结

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

    因为上传文件以「表单数据」形式发送。

    所以接收上传文件，要预先安装 python-multipart。

    例如： pip install python-multipart。

    导入 File

    从 fastapi 导入 File 和 UploadFile：

    1. from fastapi import FastAPI, File, UploadFile 
    2. app = FastAPI()
    4. @app.post("/files/")
    5. async def create_file(file: bytes = File()):
    6.     return {"file_size": len(file)}
    8. @app.post("/uploadfile/")
    9. async def create_upload_file(file: UploadFile):
    10.     return {"filename": file.filename}

    定义 File 参数

    创建文件（File）参数的方式与 Body 和 Form 一样：

    1. from fastapi import FastAPI, File, UploadFile
    3. app = FastAPI()
    5. @app.post("/files/")
    6. async def create_file(file: bytes = File()):
    7.     return {"file_size": len(file)}
    9. @app.post("/uploadfile/")
    10. async def create_upload_file(file: UploadFile):
    11.     return {"filename": file.filename}

    说明

    File 是直接继承自 Form 的类。

    注意，从 fastapi 导入的 Query、Path、File 等项，实际上是返回特定类的函数。

    提示

    声明文件体必须使用 File，否则，FastAPI 会把该参数当作查询参数或请求体（JSON）参数。

    文件作为「表单数据」上传。

    如果把路径操作函数参数的类型声明为 bytes，FastAPI 将以 bytes 形式读取和接收文件内容。

    这种方式把文件的所有内容都存储在内存里，适用于小型文件。

    不过，很多情况下，UploadFile 更好用。

    含 UploadFile 的文件参数

    定义文件参数时使用 UploadFile：

    1. from fastapi import FastAPI, File, UploadFile
    3. app = FastAPI()
    5. @app.post("/files/")
    6. async def create_file(file: bytes = File()):
    7.     return {"file_size": len(file)}
    9. @app.post("/uploadfile/")
    10. async def create_upload_file(file: UploadFile):
    11.     return {"filename": file.filename}

    UploadFile 与 bytes 相比有更多优势：

    • 使用 spooled 文件：
      • 存储在内存的文件超出最大上限时，FastAPI 会把文件存入磁盘；
    • 这种方式更适于处理图像、视频、二进制文件等大型文件，好处是不会占用所有内存；
    • 可获取上传文件的元数据；
    • 自带 file-like async 接口；
    • 暴露的 Python SpooledTemporaryFile 对象，可直接传递给其他预期「file-like」对象的库。

    UploadFile

    UploadFile 的属性如下：

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

    UploadFile 支持以下 async 方法，（使用内部 SpooledTemporaryFile）可调用相应的文件方法。

    • write(data)：把 data （str 或 bytes）写入文件；
    • read(size)：按指定数量的字节或字符（size (int)）读取文件内容；
    • seek(offset)：移动至文件 offset （int）字节处的位置；
      • 例如，await myfile.seek(0) 移动到文件开头；
      • 执行 await myfile.read() 后，需再次读取已读取内容时，这种方法特别好用；
    • close()：关闭文件。

    因为上述方法都是 async 方法，要搭配「await」使用。

    例如，在 async 路径操作函数 内，要用以下方式读取文件内容：

    contents = await myfile.read()

    在普通 def 路径操作函数 内，则可以直接访问 UploadFile.file，例如：

    contents = myfile.file.read()

    async 技术细节

    使用 async 方法时，FastAPI 在线程池中执行文件方法，并 await 操作完成。

    Starlette 技术细节

    FastAPI 的 UploadFile 直接继承自 Starlette 的 UploadFile，但添加了一些必要功能，使之与 Pydantic 及 FastAPI 的其它部件兼容。

    什么是 「表单数据」

    与 JSON 不同，HTML 表单（<form></form>）向服务器发送数据通常使用「特殊」的编码。

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

    技术细节

    不包含文件时，表单数据一般用 application/x-www-form-urlencoded「媒体类型」编码。

    但表单包含文件时，编码为 multipart/form-data。使用了 File，FastAPI 就知道要从请求体的正确位置获取文件。

    编码和表单字段详见 MDN Web 文档的 POST 小节。

    警告

    可在一个路径操作中声明多个 File 和 Form 参数，但不能同时声明要接收 JSON 的 Body 字段。因为此时请求体的编码是 multipart/form-data，不是 application/json。

    这不是 FastAPI 的问题，而是 HTTP 协议的规定。

    可选文件上传

    您可以通过使用标准类型注解并将 None 作为默认值的方式将一个文件参数设为可选:

    Python 3.9+Python 3.8+

    1. from fastapi import FastAPI, File, UploadFile
    3. app = FastAPI()
    5. @app.post("/files/")
    6. async def create_file(file: bytes | None = File(default=None)):
    7.     if not file:
    8.         return {"message": "No file sent"}
    9.     else:
    10.         return {"file_size": len(file)}
    12. @app.post("/uploadfile/") async def create_upload_file(file: UploadFile | None = None):
    13.     if not file:
    14.         return {"message": "No upload file sent"}
    15.     else:
    16.         return {"filename": file.filename}
    1. from typing import Union
    3. from fastapi import FastAPI, File, UploadFile
    5. app = FastAPI()
    7. @app.post("/files/")
    8. async def create_file(file: Union[bytes, None] = File(default=None)):
    9.     if not file:
    10.         return {"message": "No file sent"}
    11.     else:
    12.         return {"file_size": len(file)}
    14. @app.post("/uploadfile/")
    15. async def create_upload_file(file: Union[UploadFile, None] = None):
    16.     if not file:
    17.         return {"message": "No upload file sent"}
    18.     else:
    19.         return {"filename": file.filename}

    带有额外元数据的 UploadFile

    您也可以将 File() 与 UploadFile 一起使用，例如，设置额外的元数据:

    1. from fastapi import FastAPI, File, UploadFile
    3. app = FastAPI()
    5. @app.post("/files/")
    6. async def create_file(file: bytes = File(description="A file read as bytes")):
    7.     return {"file_size": len(file)}
    9. @app.post("/uploadfile/")
    10. async def create_upload_file(
    11.  file: UploadFile = File(description="A file read as UploadFile"), ):
    12.     return {"filename": file.filename}

    多文件上传

    FastAPI 支持同时上传多个文件。

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

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

    Python 3.9+Python 3.8+

    1. from fastapi import FastAPI, File, UploadFile
    2. from fastapi.responses import HTMLResponse
    4. app = FastAPI()
    6. @app.post("/files/")
    7. async def create_files(files: list[bytes] = File()):
    8.     return {"file_sizes": [len(file) for file in files]}
    10. @app.post("/uploadfiles/")
    11. async def create_upload_files(files: list[UploadFile]):
    12.     return {"filenames": [file.filename for file in files]}
    14. @app.get("/")
    15. async def main():
    16.     content = """
    17. <body>
    18. <form action="/files/" enctype="multipart/form-data" method="post">
    19. <input name="files" type="file" multiple>
    20. <input type="submit">
    21. </form>
    22. <form action="/uploadfiles/" enctype="multipart/form-data" method="post">
    23. <input name="files" type="file" multiple>
    24. <input type="submit">
    25. </form>
    26. </body>
    27.  """
    28.     return HTMLResponse(content=content)
    1. from typing import List
    3. from fastapi import FastAPI, File, UploadFile
    4. from fastapi.responses import HTMLResponse
    6. app = FastAPI()
    8. @app.post("/files/")
    9. async def create_files(files: List[bytes] = File()):
    10.     return {"file_sizes": [len(file) for file in files]}
    12. @app.post("/uploadfiles/")
    13. async def create_upload_files(files: List[UploadFile]):
    14.     return {"filenames": [file.filename for file in files]}
    16. @app.get("/")
    17. async def main():
    18.     content = """
    19. <body>
    20. <form action="/files/" enctype="multipart/form-data" method="post">
    21. <input name="files" type="file" multiple>
    22. <input type="submit">
    23. </form>
    24. <form action="/uploadfiles/" enctype="multipart/form-data" method="post">
    25. <input name="files" type="file" multiple>
    26. <input type="submit">
    27. </form>
    28. </body>
    29.  """
    30.     return HTMLResponse(content=content)

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

    技术细节

    也可以使用 from starlette.responses import HTMLResponse。

    fastapi.responses 其实与 starlette.responses 相同，只是为了方便开发者调用。实际上，大多数 FastAPI 的响应都直接从 Starlette 调用。

    带有额外元数据的多文件上传

    和之前的方式一样, 您可以为 File() 设置额外参数, 即使是 UploadFile:

    Python 3.9+Python 3.8+

    1. from fastapi import FastAPI, File, UploadFile
    2. from fastapi.responses import HTMLResponse
    4. app = FastAPI()
    6. @app.post("/files/")
    7. async def create_files(
    8.     files: list[bytes] = File(description="Multiple files as bytes"),
    9. ):
    10.     return {"file_sizes": [len(file) for file in files]}
    12. @app.post("/uploadfiles/")
    13. async def create_upload_files(
    14.  files: list[UploadFile] = File(description="Multiple files as UploadFile"), ):
    15.     return {"filenames": [file.filename for file in files]}
    17. @app.get("/")
    18. async def main():
    19.     content = """
    20. <body>
    21. <form action="/files/" enctype="multipart/form-data" method="post">
    22. <input name="files" type="file" multiple>
    23. <input type="submit">
    24. </form>
    25. <form action="/uploadfiles/" enctype="multipart/form-data" method="post">
    26. <input name="files" type="file" multiple>
    27. <input type="submit">
    28. </form>
    29. </body>
    30.  """
    31.     return HTMLResponse(content=content)
    1. from typing import List
    3. from fastapi import FastAPI, File, UploadFile
    4. from fastapi.responses import HTMLResponse
    6. app = FastAPI()
    8. @app.post("/files/")
    9. async def create_files(
    10.     files: List[bytes] = File(description="Multiple files as bytes"),
    11. ):
    12.     return {"file_sizes": [len(file) for file in files]}
    14. @app.post("/uploadfiles/")
    15. async def create_upload_files(
    16.  files: List[UploadFile] = File(description="Multiple files as UploadFile"), ):
    17.     return {"filenames": [file.filename for file in files]}
    19. @app.get("/")
    20. async def main():
    21.     content = """
    22. <body>
    23. <form action="/files/" enctype="multipart/form-data" method="post">
    24. <input name="files" type="file" multiple>
    25. <input type="submit">
    26. </form>
    27. <form action="/uploadfiles/" enctype="multipart/form-data" method="post">
    28. <input name="files" type="file" multiple>
    29. <input type="submit">
    30. </form>
    31. </body>
    32.  """
    33.     return HTMLResponse(content=content)

    小结

    本节介绍了如何用 File 把上传文件声明为（表单数据的）输入参数。

    版权声明

    本站仅做备份收录，仅供研究与教学参考之用。
    读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。

    ZONE.CI 全球网 | 安全领域涉猎者-乌云独行地带
    ZONE.CI 全球网
    安全领域涉猎者-乌云独行地带
    FastAPI开发文档教程-请求文件 编程

    FastAPI开发文档教程-请求文件

    导入 File定义 File 参数含 UploadFile 的文件参数UploadFile什么是 「表单数据」可选文件上传带有额外元数据的 UploadFile多文件上传带有额外元数据的多文件上传小结
    01-100 评论
    FastAPI开发文档教程-响应状态码 编程

    FastAPI开发文档教程-响应状态码

    关于 HTTP 状态码状态码名称快捷方式更改默认状态码与指定响应模型的方式相同，在以下任意路径操作中，可以使用 status_code 参数声明用于响应的 HTTP 状态码：@app.get()@ap
    01-100 评论
    FastAPI开发文档教程-表单数据 编程

    FastAPI开发文档教程-表单数据

    导入 Form定义 Form 参数关于 “表单字段”小结接收的不是 JSON，而是表单字段时，要使用 Form。要使用表单，需预先安装 python-multipart。例如，pip install
    01-100 评论
    ZONE.CI 全球网 | 安全领域涉猎者-乌云独行地带
    安全领域涉猎者-乌云独行地带
    ZONE.CI 全球网
    评论：0   参与：  0