FastAPI进阶：Form参数在API设计中的最佳实践

在FastAPI中，当你想要从form-data（通常在HTML表单中使用）中获取数据时，你需要使用Form类来声明这些参数。这告诉FastAPI，这些参数应该从请求的表单数据中获取，而不是从查询参数或请求体（JSON）中获取。

以下是一个使用Form从表单数据中获取参数的示例：

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/")
async def create_item(name: str = Form(...), description: str = Form(None), price: float = Form(...), tax: float = Form(None)):
    item = Item(name=name, description=description, price=price, tax=tax)
    return item

在这个例子中，我们定义了一个Item模型，它包含几个字段，其中一些字段是可选的。我们创建了一个POST路由/items/，它接受来自表单的参数。我们使用Form来声明name、description、price和tax参数，这样FastAPI就知道这些参数应该从表单数据中获取。

如果你想使用HTML表单发送请求到这个端点，你的HTML代码可能看起来像这样：

<form action="http://localhost:8000/items/" method="post">
    <input type="text" name="name" placeholder="Name">
    <input type="text" name="description" placeholder="Description">
    <input type="number" name="price" placeholder="Price">
    <input type="number" name="tax" placeholder="Tax">
    <button type="submit">Create Item</button>
</form>

当用户填写表单并提交时，表单数据将作为form-data发送到服务器，FastAPI将解析这些数据并使用Form声明的参数来填充Item模型。

请注意，如果你使用Form但客户端请求没有包含表单数据，FastAPI将返回一个错误。因此，确保客户端请求与你的端点期望的参数类型相匹配。

在FastAPI中，使用Form声明与接收POST JSON值的主要区别在于数据的来源和期望的请求内容类型。以下是详细说明：

重点使用Form声明

1. 数据来源：当你使用Form声明参数时，你期望从form-data中获取数据。这种数据通常通过multipart/form-data编码的POST请求发送，这在提交HTML表单时非常常见。

2. 请求内容类型：使用Form时，FastAPI期望客户端发送multipart/form-data内容类型的请求。这种类型的请求可以包含文件上传和其他表单字段。

3. 参数声明：使用Form时，你需要在函数参数前加上Form来明确指出该参数应该从表单数据中获取。例如：

   name: str = Form(...)
   

4. 使用场景：Form参数通常用于处理文件上传、接收用户提交的表单数据等场景。

原来使用的POST JSON值

1. 数据来源：接收POST JSON值意味着你期望从请求体中的JSON数据中获取参数。这种数据通常通过application/json编码的POST请求发送。

2. 请求内容类型：当客户端发送JSON数据时，请求的内容类型是application/json。

3. 参数声明：对于JSON请求体，你不需要使用Form。FastAPI会自动将JSON请求体解析为Pydantic模型或直接作为参数传递给路由函数。例如：

   name: str
   

4. 使用场景：JSON请求体通常用于API接口，其中客户端（如前端应用、移动应用或其他服务）发送结构化的JSON数据。

着重说明Form

• 表单数据解析：Form用于告诉FastAPI从form-data中解析数据。这对于处理文件上传和表单字段非常有用。

• 非JSON数据：Form允许你接收非JSON格式的数据，这在处理二进制文件（如图片、文档等）或简单的键值对数据时非常有用。

• 字段验证：即使使用Form，FastAPI仍然可以利用Pydantic进行字段验证，确保接收到的数据符合预期的类型和格式。

• 示例：

  @app.post("/upload/")
  async def upload_file(file: UploadFile = File(...), token: str = Form(...)):
      # 处理文件上传和表单字段
      return {"filename": file.filename, "token": token}
  

在这个示例中，file参数用于接收上传的文件，而token参数则使用Form来从表单数据中获取。

Form在FastAPI中用于明确指出某些参数应该从multipart/form-data编码的表单数据中获取，这与从JSON请求体中获取参数有明显区别。使用Form时，你需要确保客户端发送的是适当编码的表单数据。

使用Form来声明表单字段是FastAPI中处理特定类型请求的一种方式，它不会影响前后端分离的设计模式，而是为这种模式提供了一种处理表单数据的选项。

使用Form时，数据通常以multipart/form-data格式发送，这适用于文件上传或提交包含文件的表单数据。而前后端分离的模式中，前端可以通过JavaScript库（如Axios、Fetch API等）来构造这种类型的请求。