FastAPI入门教程：响应模型配置与字段排除

欢迎来到FastAPI的世界！

如果你是Python新手，对Web开发一无所知，别担心！本教程将一步步教你如何使用FastAPI创建一个简单的API，并学习如何配置响应模型和排除不必要的字段。我们避免过多理论，侧重动手实践，用生活化类比解释概念，让你在每个步骤都能体验到成功的喜悦。

什么是响应模型和字段排除？

在FastAPI中，响应模型（Response Model）就像是餐厅的菜单——它定义了API返回给客户端的数据结构，就像菜单列出所有菜品一样。而字段排除（Field Exclusion）则类似你在点餐时只选择自己喜欢的部分，或者服务员帮你隐藏一些不必要的选项（比如过敏食材）。简单说，响应模型控制API响应的数据格式，字段排除可以让你在响应中隐藏某些敏感或不必要的信息。

准备工作：安装FastAPI

在开始之前，你需要安装FastAPI和一些依赖。打开终端或命令提示符，运行以下命令来安装：

pip install fastapi uvicorn

这就像准备烹饪工具——FastAPI是主厨（框架），uvicorn是助手（服务器），帮你快速上菜（运行API）。

创建你的第一个FastAPI应用

让我们从最简单的例子开始，建立一个信心满满的“成功时刻”。创建一个新文件，比如 main.py，并写入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI应用实例，就像开一家新餐厅

@app.get("/")  # 定义一个GET端点，类似餐厅的入口
async def read_root():
    return {"message": "你好，欢迎来到FastAPI！"}  # 返回一个简单的响应

保存文件，然后在终端运行：

uvicorn main:app --reload

打开浏览器访问 http://127.0.0.1:8000，你会看到 {"message": "你好，欢迎来到FastAPI！"}。恭喜！你刚刚创建了第一个API，响应就像菜单上的欢迎语一样简单明了。

响应模型基础：定义数据模型

现在，让我们添加一个数据模型，让响应更有条理。想象一下，你在餐厅里想点一份披萨，披萨可以有名字、大小和价格。在FastAPI中，我们使用Pydantic来定义模型。在 main.py 中添加：

from pydantic import BaseModel

# 定义一个披萨模型，就像设计披萨菜单的条目
class Pizza(BaseModel):
    name: str       # 披萨名称，比如“玛格丽特”
    size: str       # 大小，比如“大”或“小”
    price: float    # 价格，比如99.9

@app.get("/pizza/{pizza_id}")  # 添加一个端点，通过ID获取披萨信息
async def get_pizza(pizza_id: int):
    # 模拟从数据库获取披萨数据，这里我们硬编码一个示例
    pizza_data = {
        "name": "玛格丽特披萨",
        "size": "大",
        "price": 99.9,
        "secret_ingredient": "特殊酱料"  # 假设这是一个内部信息，我们可能想隐藏
    }
    return pizza_data  # 目前返回所有数据

保存并重新运行 uvicorn main:app --reload，访问 http://127.0.0.1:8000/pizza/1，你会看到完整的数据，包括 secret_ingredient。现在，我们想优化这个响应。

配置响应模型：让响应更规范

响应模型可以帮助我们确保API只返回预定义的数据。修改 get_pizza 函数，使用 response_model 参数：

@app.get("/pizza/{pizza_id}", response_model=Pizza)  # 指定响应模型为Pizza类
async def get_pizza(pizza_id: int):
    pizza_data = {
        "name": "玛格丽特披萨",
        "size": "大",
        "price": 99.9,
        "secret_ingredient": "特殊酱料"  # 这个字段不在Pizza模型中
    }
    return pizza_data  # FastAPI会自动过滤掉不在模型中的字段

访问 http://127.0.0.1:8000/pizza/1，现在响应只包含 name、size 和 price，secret_ingredient 被自动排除了！这是因为响应模型就像菜单模板——只显示预定义的菜品，隐藏额外的东西。这是你的第一个“成功时刻”：你学会了用响应模型控制输出！

字段排除：隐藏敏感信息

有时候，我们可能想从响应中排除特定字段，比如密码或内部数据。FastAPI提供了 response_model_exclude 参数来实现这一点。让我们添加一个用户模型并演示字段排除。

在 main.py 中继续添加：

# 定义一个用户模型
class User(BaseModel):
    username: str
    email: str
    password: str        # 密码是敏感信息，我们想从响应中隐藏
    age: int

@app.get("/user/{user_id}", response_model=User, response_model_exclude={"password"})  # 排除password字段
async def get_user(user_id: int):
    # 模拟用户数据
    user_data = {
        "username": "fastapi_learner",
        "email": "learner@example.com",
        "password": "secret123",   # 这个字段会被排除
        "age": 25
    }
    return user_data

保存并访问 http://127.0.0.1:8000/user/1，响应中只有 username、email 和 age，没有 password。这就像在展示用户资料时，只显示公开信息，隐藏密码保护隐私。另一个“成功时刻”：你学会了安全地排除字段！

生活化类比加深理解

• 响应模型：想象你在网上购物，产品页面只显示名称、价格和描述（模型定义的字段），而不是后台的库存代码或成本（额外字段）。
• 字段排除：就像发朋友圈时，你可以选择隐藏某些照片（字段），只分享想公开的部分。

这些类比帮助你直观理解抽象概念，让学习过程更轻松。

完整代码示例

为了巩固知识，这里是一个完整的 main.py 文件，包含所有示例：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义模型
class Pizza(BaseModel):
    name: str
    size: str
    price: float

class User(BaseModel):
    username: str
    email: str
    password: str
    age: int

# 端点定义
@app.get("/")
async def read_root():
    return {"message": "你好，欢迎来到FastAPI！"}

@app.get("/pizza/{pizza_id}", response_model=Pizza)
async def get_pizza(pizza_id: int):
    pizza_data = {
        "name": "玛格丽特披萨",
        "size": "大",
        "price": 99.9,
        "secret_ingredient": "特殊酱料"
    }
    return pizza_data

@app.get("/user/{user_id}", response_model=User, response_model_exclude={"password"})
async def get_user(user_id: int):
    user_data = {
        "username": "fastapi_learner",
        "email": "learner@example.com",
        "password": "secret123",
        "age": 25
    }
    return user_data

运行 uvicorn main:app --reload 并测试各个端点，亲身体验响应模型和字段排除的效果。

总结和下一步

通过本教程，你已经学会了：

1. 响应模型基础：用Pydantic模型定义API响应的数据结构，确保输出规范。
2. 字段排除：使用 response_model_exclude 隐藏敏感或不必要的字段，增强安全性。
3. 动手实践：从零创建FastAPI应用，通过简单示例建立信心。

继续探索FastAPI，比如添加更多端点、使用数据库或学习认证功能。记住，API开发就像烹饪——从简单菜谱开始，逐步尝试复杂料理！如果你遇到问题，参考FastAPI官方文档或社区资源。祝你学习愉快，享受编码的乐趣！