02 第2周D10 FastAPI与API设计
D10 FastAPI + API 设计
D10 FastAPI + API 设计
精讲（必讲）。公司后端核心框架（core-api-v2、sub2api 等），也是第 4 周项目后端模块（A/B）的骨架。
教学目标（学完能做什么）
- 能写一个带路由/请求校验/依赖注入/鉴权的 FastAPI 服务
- 会看自动生成的 Swagger 文档并测试接口
- 知道 REST API 设计规范（URL、方法、状态码、幂等）
- 理解 API Key / Bearer 认证在公司业务里的用法
前置要求
- D3（HTTP/状态码/Header）、D9（Python）
本模块在业务中的位置
- 公司的一切后端都是"API 生意"：网关给客户 API、后端给前端 API。本模块教你"把 Python 变成一个能对外服务的 API"，第 4 周项目 A（代理服务）与 B（计费引擎）直接用到。
内容分段
1. FastAPI 为什么是公司的选择
- 自动生成 Swagger 文档（/docs）、类型标注即校验、异步支持、性能好。
- 公司例子：
api.akria.net（core-api-v2）。
2. 最小应用
# main.py
from fastapi import FastAPI
app = FastAPI(title="我的 API")
@app.get("/health")
def health():
return {"status": "ok"}uvicorn main:app --reload --port 8000
# 打开 http://127.0.0.1:8000/docs 自动 Swagger！3. 路径参数、查询参数、请求体
from pydantic import BaseModel
class ChatRequest(BaseModel): # 请求体模型（校验自动做）
model: str
messages: list[dict]
stream: bool = False
@app.get("/users/{uid}") # 路径参数
def get_user(uid: int):
return {"uid": uid}
@app.post("/chat")
def chat(req: ChatRequest):
return {"model": req.model, "n_messages": len(req.messages)}- 类型标注即校验：
uid: int传入非数字自动 422。
4. 鉴权：API Key / Bearer
from fastapi import Depends, HTTPException, Header
def verify_key(x_api_key: str = Header(...)):
if x_api_key != "sk-secret": # 真实场景查数据库/缓存
raise HTTPException(401, "invalid key")
return x_api_key
@app.post("/chat", dependencies=[Depends(verify_key)])
def chat(req: ChatRequest):
return {"ok": True}- 回顾 D3：LLM 业务用
Authorization: Bearer或x-api-key。 - 401 vs 403：key 错/没传 → 401；key 有效但无权访问该模型 → 403。
5. REST 设计规范
| 原则 | 说明 | 反例 |
|---|---|---|
| 资源用名词 | /users、/orders | /getUser（动词） |
| 方法表达动作 | GET 读 / POST 建 / PUT 改 / DELETE 删 | 全部 GET 带参数 |
| 复数资源 | /users/{uid} | /user/{uid} |
| 状态码语义正确 | 201 创建、404 没有、429 限流 | 一律 200 |
| 幂等 | 重复 GET/PUT/DELETE 结果一致 | POST 用来干 GET 的活 |
- 写接口先想"这是资源还是动作"：资源用名词路径，动作（如"扣费"）用一个明确的 POST 子路径。
6. 错误处理与日志
@app.exception_handler(Exception)
async def catch_all(request, exc):
return JSONResponse(status_code=500, content={"detail": str(exc)})- 原则：对外返回干净的结构化错误（
{"detail": "..."}），详细原因进日志，不暴露内部细节给客户。 - 公司风格：日志用 logging 中文说明。
讲解节奏建议（约 90 分钟）
| 时段 | 内容 |
|---|---|
| 09:00-09:10 | 引入：公司一切后端都是 API，FastAPI 是骨架 |
| 09:10-09:35 | 最小应用 + Swagger（现场跑起来） |
| 09:35-10:00 | 路径/查询/请求体 + 类型校验 |
| 10:00-10:25 | 鉴权（API Key/Bearer，串起 D3 的 401/403） |
| 10:25-10:45 | REST 设计规范（讲反例最有效） |
| 10:45-11:30 | 学员实操：写 mini CRUD API（对应作业） |
| 11:30-11:50 | 常见误区 + 小结 |
| 11:50-12:00 | 布置作业 |
常见误区汇总
| 误区 | 正确理解 |
|---|---|
| URL 用动词 | 资源用名词，动词交给方法 |
| 所有接口都返回 200 | 状态码表达语义（401/403/404/429） |
| key 校验写在每个函数里 | 用依赖注入 Depends 统一做 |
| 鉴权失败返回 403 | 认证失败是 401，授权不足才是 403 |
| 把内部异常细节直接返回给客户 | 对外干净结构，细节进日志 |
| 不写类型标注 | FastAPI 的校验与文档全靠它，必须写 |