FastAPI 学习教程 · 第3部分

路径操作配置、响应模型与状态码

💡 本部分目标：学会自定义 API 响应（如隐藏敏感字段）、设置 HTTP 状态码、为接口添加描述和分组，让你的 API 更专业、更安全、更易用。

一、为什么需要“响应模型”？

在真实项目中，你不希望把所有数据都返回给客户端。例如：

• 用户注册时，请求体包含password，但响应中绝不能返回密码
• 数据库中有created_at、updated_at等字段，但前端可能不需要

FastAPI 提供了response_model参数，让你控制返回的数据结构。

二、使用response_model控制输出

步骤 1：定义两个 Pydantic 模型

• 一个用于输入（包含密码）
• 一个用于输出（不包含密码）

frompydanticimportBaseModel# 输入模型（包含敏感信息）classUserIn(BaseModel):username:strpassword:stremail:str# 输出模型（隐藏敏感信息）classUserOut(BaseModel):username:stremail:str

步骤 2：在路由中使用response_model

fromfastapiimportFastAPI,status app=FastAPI()@app.post("/users/",response_model=UserOut)defcreate_user(user:UserIn):# 实际项目中会保存到数据库returnuser# FastAPI 自动只返回 UserOut 中的字段！

🔍 即使你返回的是UserIn对象，FastAPI 也会自动过滤，只保留UserOut中定义的字段。

✅ 测试：

• 发送请求体：

  {"username":"alice","password":"secret123","email":"alice@example.com"}

• 响应结果：

  {"username":"alice","email":"alice@example.com"}

  →密码被自动隐藏！

三、设置 HTTP 状态码

默认情况下，POST 请求返回200 OK，但 RESTful API 最佳实践是：

• 成功创建资源 → 返回201 Created
• 成功删除 → 返回204 No Content

使用status_code参数设置：

@app.post("/users/",response_model=UserOut,status_code=status.HTTP_201_CREATED)defcreate_user(user:UserIn):returnuser

💡 导入方式：from fastapi import status
这样写比直接写201更清晰、不易出错！

常见状态码：

• HTTP_200_OK→ 默认
• HTTP_201_CREATED→ 创建成功
• HTTP_204_NO_CONTENT→ 成功但无返回体
• HTTP_404_NOT_FOUND→ 资源未找到
• HTTP_400_BAD_REQUEST→ 客户端错误

四、为接口添加描述和分组（Tags）

当 API 越来越多时，需要分类管理。FastAPI 支持用tags分组。

示例：按功能分组

fromfastapiimportFastAPI app=FastAPI()@app.post("/users/",response_model=UserOut,tags=["用户管理"])defcreate_user(user:UserIn):returnuser@app.get("/items/",tags=["商品管理"])defread_items():return[{"name":"手机"}]

效果：

• 访问/docs，你会看到左侧菜单分为“用户管理”和“商品管理”两组
• 接口更清晰，团队协作更高效！

高级：添加摘要和描述

@app.post("/users/",response_model=UserOut,status_code=status.HTTP_201_CREATED,tags=["用户管理"],summary="创建新用户",description="注册一个新用户账号，密码不会返回。",response_description="成功创建用户，返回用户名和邮箱")defcreate_user(user:UserIn):""" 你也可以用 docstring 写描述（推荐）。 FastAPI 会优先使用 `description` 参数，如果没有则用 docstring。 """returnuser

五、自定义响应类（Response Class）

有时你需要返回非 JSON 内容，比如纯文本、HTML 或文件。

FastAPI 提供多种响应类：

示例：返回纯文本

fromfastapi.responsesimportPlainTextResponse@app.get("/ping",response_class=PlainTextResponse)defping():return"pong"

访问/ping将返回纯文本pong（不是 JSON）。

六、完整示例代码（推荐保存为main.py）

# main.pyfromfastapiimportFastAPI,statusfromfastapi.responsesimportPlainTextResponsefrompydanticimportBaseModel app=FastAPI(title="第3部分：响应模型与状态码")# === 用户相关模型 ===classUserIn(BaseModel):username:strpassword:stremail:strclassUserOut(BaseModel):username:stremail:str# === 商品相关模型 ===classItemCreate(BaseModel):name:strprice:floatclassItemOut(BaseModel):id:intname:strprice:float# === 路由 ===@app.post("/users/",response_model=UserOut,status_code=status.HTTP_201_CREATED,tags=["用户管理"],summary="注册新用户",description="创建一个新用户账户。密码仅用于注册，不会在响应中返回。")defcreate_user(user:UserIn):# 模拟保存到数据库（实际项目中会生成 ID 等）returnuser@app.get("/health",response_class=PlainTextResponse,tags=["系统"],summary="健康检查")defhealth_check():return"OK"@app.post("/items/",response_model=ItemOut,status_code=status.HTTP_201_CREATED,tags=["商品管理"])defcreate_item(item:ItemCreate):# 模拟生成 IDfake_id=1001return{"id":fake_id,"name":item.name,"price":item.price}

运行后，在/docs中观察：

• 接口是否按标签分组？
• POST/users/是否返回 201 状态码？
• 响应中是否没有password？

七、练习任务（动手实践）

🧠 请先自己尝试完成，再查看下方答案！

任务1：创建文章接口

• 定义ArticleIn（含title,content,author_id）
• 定义ArticleOut（只含title,author_id，不返回 content）
• 路由：POST /articles/
• 状态码：201
• 标签：["内容管理"]
• 描述：创建一篇新文章，内容不会在响应中返回

任务2：健康检查接口

• 路由：GET /ready
• 返回纯文本"ready"
• 使用PlainTextResponse

任务3（挑战）：模拟删除操作

• 路由：DELETE /users/{user_id}
• 路径参数：user_id: int
• 成功时返回204 No Content（即无响应体）
• 标签：["用户管理"]

八、练习任务参考答案

任务1 答案

classArticleIn(BaseModel):title:strcontent:strauthor_id:intclassArticleOut(BaseModel):title:strauthor_id:int@app.post("/articles/",response_model=ArticleOut,status_code=status.HTTP_201_CREATED,tags=["内容管理"],summary="创建文章",description="创建一篇新文章。出于安全考虑，内容不会在响应中返回。")defcreate_article(article:ArticleIn):returnarticle

任务2 答案

@app.get("/ready",response_class=PlainTextResponse,tags=["系统"])defready_check():return"ready"

任务3 答案

fromfastapi.responsesimportResponse@app.delete("/users/{user_id}",status_code=status.HTTP_204_NO_CONTENT,tags=["用户管理"],summary="删除用户")defdelete_user(user_id:int):# 实际项目中会从数据库删除returnResponse(status_code=status.HTTP_204_NO_CONTENT)

💡 注意：204 响应不能有响应体，所以返回Response()并指定状态码。

九、小结

在本部分，你学会了：

• 使用response_model过滤敏感字段，提升安全性
• 设置正确的HTTP 状态码（如 201、204）
• 用tags、summary、description组织和文档化 API
• 使用response_class返回非 JSON 内容