FastAPI python web开发- 响应模型 - 返回类型 (response_model) & 异常错误处理 (HTTPException) & 响应状态码 (status_code)

原创于 2026-07-14 10:44:33 发布 · 247 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

fastapi

大家好，我是Java1234_小锋老师，最近更新《2027版一天学会 FastAPI Python web开发视频教程(无废话版)》专辑，感谢大家支持。

本课程主要介绍和讲解FastAPI简介，HelloWorld实现，自动生成交互式API文档，路径参数，查询参数，请求体，参数校验，响应模型，表单数据和模型，中间件，依赖注入，集成SQLAlchemy ORM 操作数据库，集成Pydantic数据校验等

视频教程+课件+源码打包下载：

链接：https://pan.baidu.com/s/1_NzaNr0Wln6kv1rdiQnUTg
提取码：0000

响应模型 - 返回类型 (response_model) & 异常错误处理 (HTTPException) & 响应状态码 (status_code)

响应模型 - 返回类型 (response_model)

什么是响应模型 (response_model)

在 FastAPI 中，响应模型指的是你声明的、用于规定 API 接口返回数据应遵循的格式和结构的 Pydantic 模型。你可以通过在路径操作函数的返回类型注解或装饰器的 response_model 参数来声明它。

为什么使用响应模型？

使用响应模型的核心价值在于：

数据校验与安全保障：FastAPI 会自动校验返回的数据是否符合模型定义。如果数据无效（例如缺少必填字段），FastAPI 会返回服务器错误，而不是将错误数据返回给客户端。更重要的是，它会将输出数据限制并过滤为模型中所定义的内容，这可以避免意外返回敏感信息（如密码），对安全性至关重要。
自动生成 API 文档：响应模型会为你的 API 生成清晰的 JSON Schema，并自动在 Swagger UI (/docs) 等交互式文档中展示，方便前端或第三方开发者查看。
数据序列化与过滤：FastAPI 会使用 Pydantic 将你的返回数据（可以是字典、数据库对象等）自动序列化为符合模型的 JSON 格式。同时，你可以利用模型的 exclude、include 等参数精细控制哪些字段出现在最终的响应中。

我们先看一个数据验证实例：

class Item(BaseModel):
    name: str
    price: float
    # 可选字段，默认值为 None
    tax: float | None = None

# 在装饰器中通过 response_model 指定
@app.post("/create_item/", response_model=Item)
async def create_item(item: Item):
    # 假设这里进行了数据库操作，然后返回一个字典
    # FastAPI 会使用 Item 模型来校验和过滤这个字典
    return {"name": item.name, "price": item.price, "tax": item.tax}

如果我们把return里的price属性去掉，就会报错。

我们在看一个比较实用的例子，用户返回信息不带密码，重新定义一个新的用户类UserOut作为返回类型。

class UserIn(BaseModel):
    username: str
    password: str
    full_name: str | None = None


class UserOut(BaseModel):
    username: str
    full_name: str | None = None


@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
    return user

然后打开浏览器访问 http://127.0.0.1:8000/docs，进行测试

异常错误处理 (HTTPException) & 响应状态码 (status_code)

在 FastAPI 中，HTTPException 是一个内置的异常类，用于在 API 处理过程中主动抛出 HTTP 错误响应。当你的业务逻辑遇到问题（如资源不存在、权限不足、参数无效等）时，你可以抛出 HTTPException，FastAPI 会捕获它并自动将其转换为符合 HTTP 规范的 JSON 错误响应（包含状态码和详细信息）。

使用 HTTPException 的核心优势：

标准化错误响应：返回标准的 HTTP 状态码和错误信息，方便客户端处理。
自动生成文档：异常信息会出现在 OpenAPI 文档中（如果声明了 responses），提高 API 的可理解性。
与依赖注入等机制无缝集成：可以在依赖项、中间件等任何位置抛出。

我们看一个实例：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id < 1:
        # 抛出 HTTPException，状态码 400，并附带详细信息
        raise HTTPException(status_code=400, detail="ID必须大于0")
    # 模拟查询，假设只有 id=1 存在
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item项不存在")
    return {"item_id": item_id, "name": "Sample Item"}

参数说明

status_code：HTTP 状态码（如 400、404、403、500 等），可以是整数或 fastapi.status 中定义的常量（推荐使用）。
detail：错误描述信息，可以是字符串或可转为 JSON 的对象（如字典、列表）。
headers（可选）：可以添加自定义响应头。

然后打开浏览器访问 http://127.0.0.1:8000/docs，进行测试