FastAPI入门教程：嵌套模型与列表字段

欢迎来到FastAPI世界！

想象一下，FastAPI就像是建造一个智能邮局，它帮你快速、准确地收发数据包裹。今天，我们将学习如何用Python的FastAPI框架处理复杂数据，比如嵌套模型（就像包裹里有小包裹）和列表字段（就像一篮子多个物品）。

第一步：安装和快速启动

首先，确保您有Python基础，然后安装FastAPI。打开命令行，输入：

pip install fastapi uvicorn

创建一个新文件 main.py，添加以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

运行这个应用：

uvicorn main:app --reload

在浏览器中打开 http://127.0.0.1:8000，您会看到 {"Hello": "World"} 显示出来！

成功时刻：您的第一个FastAPI端点已经运行起来了！这是一个简单的开始，但我们已经迈出了重要一步。

第二步：引入数据模型——Pydantic

在FastAPI中，我们使用Pydantic来定义数据模型，就像创建一个表格来填写信息。假设我们要创建一个用户模型。

from pydantic import BaseModel

class User(BaseModel):
    name: str  # 名字是字符串
    age: int   # 年龄是整数

生活化类比：这就像填写一个用户注册表，有姓名和年龄两个必填项。

现在，让我们创建一个端点来处理用户数据。在 main.py 中添加：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

@app.post("/users/")
def create_user(user: User):
    return {"user": user}

重启应用（uvicorn会自动重新加载），然后用工具如Postman或curl发送POST请求到 http://127.0.0.1:8000/users/，请求体为：

{
  "name": "Alice",
  "age": 30
}

您会看到服务器返回 {"user": {"name": "Alice", "age": 30}}。

成功时刻：您已经成功地用模型验证和接收了数据！FastAPI自动检查输入是否符合模型要求，就像邮局检查包裹是否合规。

第三步：嵌套模型——包裹里有小包裹

有时候，数据更复杂，比如一个博客帖子包含作者信息。这就像一个大包裹里装了一个小包裹（作者详情）。

定义模型：

class Author(BaseModel):
    name: str
    email: str

class Post(BaseModel):
    title: str
    content: str
    author: Author  # 这里嵌套了Author模型

在 main.py 中添加端点：

@app.post("/posts/")
def create_post(post: Post):
    return {"post": post}

发送POST请求到 http://127.0.0.1:8000/posts/，请求体为：

{
  "title": "My First Post",
  "content": "Hello FastAPI!",
  "author": {
    "name": "Bob",
    "email": "bob@example.com"
  }
}

返回的结果会是完整的嵌套数据。

生活化类比：这就像订单里不仅有产品，还有送货地址——地址是一个独立的信息块，嵌套在订单中。

第四步：列表字段——一篮子多个物品

现在，假设一个订单包含多个产品，每个产品有自己的信息。我们可以用列表字段来处理。

定义模型：

from typing import List  # 为了兼容性，Python 3.9+可以直接用list[Product]

class Product(BaseModel):
    name: str
    price: float

class Order(BaseModel):
    customer: User  # 嵌套模型
    products: List[Product]  # 列表字段，表示多个产品

添加端点：

@app.post("/orders/")
def create_order(order: Order):
    return {"order": order}

发送POST请求到 http://127.0.0.1:8000/orders/，请求体为：

{
  "customer": {
    "name": "Charlie",
    "age": 25
  },
  "products": [
    {"name": "Apple", "price": 1.0},
    {"name": "Banana", "price": 0.5}
  ]
}

您会看到服务器处理了嵌套的客户信息和产品列表。

成功时刻：您已经处理了复杂的嵌套和列表数据！这就像是成功邮寄了一个装满不同物品的包裹。

第五步：完整示例——整合所有内容

让我们把上面的代码整合到一个文件中，运行一个完整的应用。

main.py 完整代码：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

class Author(BaseModel):
    name: str
    email: str

class Post(BaseModel):
    title: str
    content: str
    author: Author

class Product(BaseModel):
    name: str
    price: float

class Order(BaseModel):
    customer: User
    products: List[Product]

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.post("/users/")
def create_user(user: User):
    return {"user": user}

@app.post("/posts/")
def create_post(post: Post):
    return {"post": post}

@app.post("/orders/")
def create_order(order: Order):
    return {"order": order}

运行应用，用不同的端点测试，您会看到所有功能都正常工作。

总结和下一步

通过这个教程，您已经学会了：

• 如何用FastAPI创建简单的API端点。
• 使用Pydantic模型定义数据结构。
• 处理嵌套模型（如帖子包含作者）。
• 处理列表字段（如订单包含多个产品）。

生活化类比总结：FastAPI就像您的数据邮局，模型是邮寄规则，嵌套是包裹套包裹，列表是一箱多物。

继续探索FastAPI文档（https://fastapi.tiangolo.com/），尝试添加更多功能，如查询参数或错误处理。保持动手实践，您会很快成为Web开发高手！