【Python】 fastapi 文件上传：file: UploadFile = File(...)展开解释与分析

file: UploadFile = File(...) 是 FastAPI 中用于处理文件上传的关键代码。它定义了一个文件上传的接口参数，允许客户端通过 HTTP 请求上传文件。以下是对这段代码的详细解释与分析：

---

1. UploadFile 类型

UploadFile 是 FastAPI 提供的一个专门用于处理文件上传的类。它封装了上传文件的相关信息和方法，包括文件名、文件内容、文件类型等。它的主要属性和方法包括：

• filename: 上传文件的文件名（字符串）。
• content_type: 文件的 MIME 类型（如 image/png、application/zip 等）。
• file: 一个文件对象，可以直接读取文件内容。
• size: 文件的大小（以字节为单位）。
• headers: 文件的 HTTP 头信息。
• read(size: int): 读取文件内容，可以指定读取的字节数。
• write(data: bytes): 向文件写入数据（通常用于保存文件）。
• seek(offset: int): 移动文件指针到指定位置。
• close(): 关闭文件。

---

2. File(...) 函数

File(...) 是 FastAPI 提供的一个函数，用于声明一个文件上传的表单字段。它的作用是告诉 FastAPI，客户端需要通过表单字段上传文件。它的主要参数包括：

• default: 默认值（通常为 ...，表示该字段是必填的）。
• alias: 字段的别名（如果客户端使用的字段名与参数名不同）。
• description: 字段的描述信息（用于 API 文档）。
• media_type: 文件的 MIME 类型（用于 API 文档）。
• max_size: 文件的最大大小（以字节为单位）。
• regex: 文件名的正则表达式验证。

例如：

file: UploadFile = File(..., description="Upload a file", max_size=10_000_000)  # 限制文件大小为 10MB

---

3. file: UploadFile = File(...) 的作用

这段代码的作用是：

• 声明一个文件上传的表单字段，字段名为 file。
• 客户端需要通过表单字段 file 上传文件。
• 上传的文件会被封装为 UploadFile 对象，可以通过该对象访问文件的内容和元数据。

---

4. 代码示例与分析

一个完整的 FastAPI 文件上传接口示例：

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

app = FastAPI()

@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    # 打印文件信息
    print(f"Filename: {file.filename}")
    print(f"Content type: {file.content_type}")
    print(f"File size: {file.size} bytes")

    # 读取文件内容
    content = await file.read()
    print(f"File content (first 100 bytes): {content[:100]}")

    # 返回响应
    return JSONResponse(content={"filename": file.filename, "message": "File uploaded successfully"})

代码分析：

1. 文件上传：

   • 客户端通过表单字段 file 上传文件。
   • FastAPI 将上传的文件封装为 UploadFile 对象。

2. 文件信息：

   • 通过 file.filename 获取文件名。
   • 通过 file.content_type 获取文件的 MIME 类型。
   • 通过 file.size 获取文件大小。

3. 文件内容：

   • 使用 await file.read() 读取文件内容。
   • 文件内容以字节形式返回（bytes 类型）。

4. 响应：

   • 返回一个 JSON 响应，包含文件名和成功消息。

---

5. 客户端上传文件的示例

客户端可以通过以下方式上传文件：

使用 curl：

curl -X POST "http://127.0.0.1:8000/upload/" \
     -H "accept: application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@yourfile.zip"

使用 Python requests：

import requests

url = "http://127.0.0.1:8000/upload/"
files = {"file": open("yourfile.zip", "rb")}
response = requests.post(url, files=files)

print(response.json())

---

6. 常见问题与注意事项

1. 文件大小限制：

   • FastAPI 默认的文件上传大小限制是 1MB。如果需要上传更大的文件，可以通过 max_size 参数调整：

     file: UploadFile = File(..., max_size=100_000_000)  # 限制文件大小为 100MB
     

2. 文件类型限制：

   • 如果需要限制上传的文件类型，可以在接口中添加验证逻辑：

     allowed_types = {"image/png", "image/jpeg"}
     if file.content_type not in allowed_types:
         raise HTTPException(status_code=400, detail="Invalid file type")
     

3. 文件保存：

   • 上传的文件通常需要保存到服务器。可以使用以下代码保存文件：

     with open(file.filename, "wb") as buffer:
         buffer.write(await file.read())
     

4. 文件名冲突：

   • 如果上传的文件名已存在，新文件会覆盖旧文件。可以根据需要处理文件名冲突（如重命名文件）。

5. 性能优化：

   • 对于大文件上传，建议使用流式读取和写入，避免内存占用过高：

     with open(file.filename, "wb") as buffer:
         while chunk := await file.read(1024 * 1024):  # 每次读取 1MB
             buffer.write(chunk)
     

---

7. 总结

file: UploadFile = File(...) 是 FastAPI 中处理文件上传的核心代码。它通过 UploadFile 类封装了上传文件的相关信息和方法，使得文件上传变得非常简单和灵活。通过结合 File(...) 函数的参数，可以实现对文件大小、类型等的限制。