路径操作配置、响应模型与状态码
💡 本部分目标：学会自定义 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 提供多种响应类：
| 响应类 | 用途 |
|---|---|
JSONResponse | 默认（通常不用显式写） |
PlainTextResponse | 返回纯文本 |
HTMLResponse | 返回 HTML 页面 |
FileResponse | 返回文件（如图片、PDF） |
示例：返回纯文本
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 内容
