从 0 到 1 搭建 API：FastAPI 实战教程（含数据库、部署与安全）

目录

• 1. 引言
• 2. 什么是 API
  • 2.1 生活中的类比
  • 2.2 API 的核心组成
• 3. 搭建前的准备工作
  • 3.1 技术选型
  • 3.2 环境准备
  • 3.3 需求分析
• 4. 第一个 API 接口
  • 4.1 创建主文件
  • 4.2 启动服务
  • 4.3 测试接口
• 5. 设计数据模型
  • 5.1 定义模型
  • 5.2 模型说明
• 6. 实现增删改查
  • 6.1 内存数据存储
  • 6.2 创建待办事项
  • 6.3 查询待办事项列表
  • 6.4 查询单个待办事项
  • 6.5 更新待办事项
  • 6.6 删除待办事项
  • 6.7 全局异常处理
  • 6.8 数据库集成
• 7. 接口测试与调试
  • 7.1 使用 Swagger 文档测试
  • 7.2 使用 curl 命令测试
  • 7.3 使用 Python requests 调用
  • 7.4 使用 JavaScript fetch 调用
  • 7.5 使用 Postman / Apifox 图形化工具
  • 7.6 常见问题排查
  • 7.7 接口性能对比
  • 7.8 实战测试：完整流程演练
• 8. 部署上线
  • 8.1 使用 Docker 部署
  • 8.2 部署到云平台
  • 8.3 部署后的监控
• 9. API 安全
  • 9.1 身份认证
  • 9.2 授权（RBAC）
  • 9.3 输入校验与安全防护
  • 9.4 限流与防暴力破解
  • 9.5 安全最佳实践清单
  • 9.6 HTTPS 与 CORS 安全配置
• 10. 总结与进阶方向

1. 引言

在当今的软件开发中，API（Application Programming Interface，应用程序编程接口）已经成为连接不同系统、服务和数据的关键桥梁。无论是构建 Web 应用、移动端 App，还是实现微服务架构，API 都扮演着不可或缺的角色。

然而，对于许多初学者来说，API 似乎是一个既熟悉又陌生的概念——每天都在使用别人提供的 API，却不知道如何从零开始设计和搭建一个属于自己的 API。本文将从最基础的概念出发，一步步带你完成一个 API 从设计、开发、测试到部署上线的完整流程。

2. 什么是 API

API 本质上是一组定义了软件组件之间如何交互的规则和协议。它允许不同的软件系统之间进行通信和数据交换，而无需了解对方内部的具体实现细节。

2.1 生活中的类比

可以把 API 想象成餐厅里的服务员：

• 你（客户端）向服务员（API）点菜（发送请求）
• 服务员将你的需求传达给厨房（服务器）
• 厨房做好菜后，服务员再将菜品（响应数据）端到你面前

在这个过程中，你不需要知道厨房内部如何运作，只需要按照菜单（API 文档）点菜即可。

2.2 API 的核心组成

一个典型的 Web API 通常包含以下要素：

• 端点（Endpoint）：API 的访问地址，如 https://api.example.com/users
• 方法（Method）：HTTP 动词，如 GET、POST、PUT、DELETE
• 参数（Parameters）：请求中携带的数据，可以是路径参数、查询参数或请求体
• 响应（Response）：服务器返回的数据，通常为 JSON 或 XML 格式
• 状态码（Status Code）：表示请求结果的数字代码，如 200 表示成功、404 表示资源不存在

3. 搭建前的准备工作

在开始编写代码之前，我们需要先做好环境准备和需求分析。

3.1 技术选型

本文以 Python 的 FastAPI 框架为例进行演示，因为它具有以下优势：

• 性能优异，基于 Starlette 和 Pydantic
• 自动生成交互式 API 文档
• 类型提示友好，代码可读性强
• 支持异步编程

当然，你也可以选择其他技术栈，如 Node.js 的 Express、Java 的 Spring Boot 等，核心思路是相通的。

3.2 环境准备

首先，确保你的电脑上安装了 Python 3.8 及以上版本，然后创建虚拟环境并安装依赖：

# 创建项目目录
mkdir my-api
cd my-api

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（Windows）
venv\\Scripts\\activate

# 激活虚拟环境（macOS/Linux）
source venv/bin/activate

# 安装 FastAPI 和 Uvicorn
pip install fastapi uvicorn

3.3 需求分析

在动手写代码之前，先明确我们的 API 要解决什么问题。本文以一个简单的「待办事项管理」API 为例，需要实现以下功能：

• 创建待办事项
• 查询待办事项列表
• 查询单个待办事项详情
• 更新待办事项
• 删除待办事项

4. 第一个 API 接口

现在，让我们从最简单的接口开始，感受一下 FastAPI 的开发体验。

4.1 创建主文件

在项目目录下创建 main.py 文件：

from fastapi import FastAPI

# 创建 FastAPI 实例
app = FastAPI(title="待办事项 API", version="1.0.0")

@app.get("/")
def read_root():
return {"message": "欢迎使用待办事项 API"}

4.2 启动服务

在终端中运行以下命令启动开发服务器：

uvicorn main:app –reload

启动成功后，你会看到类似如下的输出：

INFO: Uvicorn running on http://127.0.0.1:8000
INFO: Application startup complete.

4.3 测试接口

打开浏览器访问 http://127.0.0.1:8000，你会看到返回的 JSON 数据：

{
"message": "欢迎使用待办事项 API"
}

同时，FastAPI 还自动生成了交互式 API 文档，访问 http://127.0.0.1:8000/docs 即可查看和在线调试所有接口。

5. 设计数据模型

接下来，我们使用 Pydantic 定义待办事项的数据模型。Pydantic 是 FastAPI 的数据验证核心，可以自动完成请求数据的类型校验和序列化。

5.1 定义模型

在 main.py 中新增数据模型：

from typing import Optional
from pydantic import BaseModel
from datetime import datetime

class TodoItem(BaseModel):
"""待办事项数据模型"""
id: Optional[int] = None
title: str
description: Optional[str] = None
completed: bool = False
created_at: datetime = datetime.now()

5.2 模型说明

• id：待办事项的唯一标识，创建时自动生成
• title：标题，必填字段
• description：详细描述，可选字段
• completed：是否已完成，默认为 False
• created_at：创建时间，默认为当前时间

6. 实现增删改查

现在，我们来实现完整的 CRUD（Create、Read、Update、Delete）接口。

6.1 内存数据存储

为了简化演示，我们先使用内存列表存储数据。在实际项目中，你会使用数据库（如 PostgreSQL、MySQL）来持久化数据。

# 内存数据存储
todos = []
todo_id_counter = 1

6.2 创建待办事项

from fastapi import HTTPException

@app.post("/todos", status_code=201)
def create_todo(todo: TodoItem):
"""创建新的待办事项"""
global todo_id_counter
todo.id = todo_id_counter
todo_id_counter += 1
todos.append(todo)
return todo

6.3 查询待办事项列表

@app.get("/todos")
def list_todos(completed: Optional[bool] = None):
"""获取待办事项列表，可按完成状态筛选"""
if completed is None:
return todos
return [todo for todo in todos if todo.completed == completed]

6.4 查询单个待办事项

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
"""根据 ID 获取单个待办事项"""
for todo in todos:
if todo.id == todo_id:
return todo
raise HTTPException(status_code=404, detail="待办事项不存在")

6.5 更新待办事项

@app.put("/todos/{todo_id}")
def update_todo(todo_id: int, todo_update: TodoItem):
"""更新指定 ID 的待办事项"""
for index, todo in enumerate(todos):
if todo.id == todo_id:
# 保留原 ID 和创建时间
todo_update.id = todo.id
todo_update.created_at = todo.created_at
todos[index] = todo_update
return todo_update
raise HTTPException(status_code=404, detail="待办事项不存在")

6.6 删除待办事项

@app.delete("/todos/{todo_id}", status_code=204)
def delete_todo(todo_id: int):
"""删除指定 ID 的待办事项"""
for index, todo in enumerate(todos):
if todo.id == todo_id:
todos.pop(index)
return
raise HTTPException(status_code=404, detail="待办事项不存在")

删除成功后返回 204 No Content，表示操作成功且无返回内容。如果待办事项不存在，则返回 404 错误。

6.7 全局异常处理

6.8 数据库集成

前面我们使用内存列表存储数据，服务重启后数据就会丢失。下面我们使用 SQLAlchemy 连接 SQLite 数据库，实现数据的持久化存储。

6.8.1 安装依赖

pip install sqlalchemy

6.8.2 配置数据库

在 main.py 中新增数据库配置和模型：

from sqlalchemy import create_engine, Column, Integer, String, Boolean, DateTime
from sqlalchemy.orm import declarative_base, sessionmaker
from datetime import datetime

# 数据库配置（使用 SQLite，实际项目可替换为 PostgreSQL/MySQL）
DATABASE_URL = "sqlite:///./todos.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class TodoDB(Base):
"""数据库中的待办事项表"""
__tablename__ = "todos"

id = Column(Integer, primary_key=True, index=True)
title = Column(String, nullable=False)
description = Column(String, nullable=True)
completed = Column(Boolean, default=False)
created_at = Column(DateTime, default=datetime.now)

# 创建数据表
Base.metadata.create_all(bind=engine)

6.8.3 改造 CRUD 接口

将原来的内存操作替换为数据库操作：

from fastapi import Depends
from sqlalchemy.orm import Session

def get_db():
"""获取数据库会话"""
db = SessionLocal()
try:
yield db
finally:
db.close()

@app.post("/todos", status_code=201)
def create_todo(todo: TodoItem, db: Session = Depends(get_db)):
"""创建新的待办事项（写入数据库）"""
db_todo = TodoDB(
title=todo.title,
description=todo.description,
completed=todo.completed,
)
db.add(db_todo)
db.commit()
db.refresh(db_todo)
return db_todo

@app.get("/todos")
def list_todos(completed: Optional[bool] = None, db: Session = Depends(get_db)):
"""获取待办事项列表（从数据库读取）"""
query = db.query(TodoDB)
if completed is not None:
query = query.filter(TodoDB.completed == completed)
return query.all()

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int, db: Session = Depends(get_db)):
"""根据 ID 获取单个待办事项"""
todo = db.query(TodoDB).filter(TodoDB.id == todo_id).first()
if not todo:
raise HTTPException(status_code=404, detail="待办事项不存在")
return todo

@app.put("/todos/{todo_id}")
def update_todo(todo_id: int, todo_update: TodoItem, db: Session = Depends(get_db)):
"""更新指定 ID 的待办事项"""
todo = db.query(TodoDB).filter(TodoDB.id == todo_id).first()
if not todo:
raise HTTPException(status_code=404, detail="待办事项不存在")
todo.title = todo_update.title
todo.description = todo_update.description
todo.completed = todo_update.completed
db.commit()
db.refresh(todo)
return todo

@app.delete("/todos/{todo_id}", status_code=204)
def delete_todo(todo_id: int, db: Session = Depends(get_db)):
"""删除指定 ID 的待办事项"""
todo = db.query(TodoDB).filter(TodoDB.id == todo_id).first()
if not todo:
raise HTTPException(status_code=404, detail="待办事项不存在")
db.delete(todo)
db.commit()

改造完成后，重启服务，数据就会持久化保存到 todos.db 文件中，即使服务重启数据也不会丢失。

为了让 API 在出错时返回统一、友好的错误信息，我们添加一个全局异常处理器。这样无论是参数校验失败、资源不存在，还是服务器内部错误，客户端都能收到结构一致的 JSON 响应。

from fastapi import Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
"""统一处理 HTTP 异常，返回 JSON 格式的错误信息"""
return JSONResponse(
status_code=exc.status_code,
content={"code": exc.status_code, "message": exc.detail, "data": None},
)

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
"""统一处理请求参数校验失败，返回字段级别的错误详情"""
errors = exc.errors()
detail = []
for error in errors:
field = ".".join(str(loc) for loc in error["loc"] if loc != "body")
detail.append({"field": field, "message": error["msg"]})
return JSONResponse(
status_code=422,
content={"code": 422, "message": "请求参数校验失败", "data": detail},
)

@app.exception_handler(Exception)
async def unhandled_exception_handler(request: Request, exc: Exception):
"""兜底捕获未处理的异常，避免向客户端泄露堆栈信息"""
return JSONResponse(
status_code=500,
content={"code": 500, "message": "服务器内部错误，请稍后重试", "data": None},
)

添加后，所有接口的错误响应都会统一为 {"code": …, "message": …, "data": …} 的结构，前端解析起来更加方便。

@app.delete("/todos/{todo_id}", status_code=204)
def delete_todo(todo_id: int):
"""删除指定 ID 的待办事项"""
for index, todo in enumerate(todos):
if todo.id == todo_id:
todos.pop(index)
return
raise HTTPException(status_code=404, detail="待办事项不存在")

7. 接口测试与调试

接口写完后，我们需要进行充分的测试，确保每个接口都能正常工作。除了 Swagger 和 curl，API 还支持多种调用方式，下面逐一介绍。

7.1 使用 Swagger 文档测试

FastAPI 自动生成的 /docs 页面提供了可视化的接口测试工具。你可以：

7.2 使用 curl 命令测试

在终端中也可以直接使用 curl 进行测试：

# 创建待办事项
curl -X POST "http://127.0.0.1:8000/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "完成 API 开发教程"}'

# 查询列表
curl "http://127.0.0.1:8000/todos"

# 查询单个
curl "http://127.0.0.1:8000/todos/1"

# 更新
curl -X PUT "http://127.0.0.1:8000/todos/1" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "已完成", "completed": true}'

# 删除
curl -X DELETE "http://127.0.0.1:8000/todos/1"

7.3 使用 Python requests 调用

在 Python 脚本或 Jupyter Notebook 中，可以使用 requests 库调用 API：

import requests

BASE_URL = "http://127.0.0.1:8000"

# 创建待办事项
resp = requests.post(
f"{BASE_URL}/todos",
json={"title": "学习 FastAPI", "description": "完成 API 开发教程"},
)
print(resp.status_code, resp.json())

# 查询列表
resp = requests.get(f"{BASE_URL}/todos")
print(resp.status_code, resp.json())

# 查询单个
resp = requests.get(f"{BASE_URL}/todos/1")
print(resp.status_code, resp.json())

# 更新
resp = requests.put(
f"{BASE_URL}/todos/1",
json={"title": "学习 FastAPI", "description": "已完成", "completed": True},
)
print(resp.status_code, resp.json())

# 删除
resp = requests.delete(f"{BASE_URL}/todos/1")
print(resp.status_code)

7.4 使用 JavaScript fetch 调用

在前端浏览器或 Node.js 环境中，可以使用 fetch 调用 API：

const BASE_URL = "http://127.0.0.1:8000";

// 创建待办事项
const createResp = await fetch(`${BASE_URL}/todos`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
title: "学习 FastAPI",
description: "完成 API 开发教程",
}),
});
console.log(createResp.status, await createResp.json());

// 查询列表
const listResp = await fetch(`${BASE_URL}/todos`);
console.log(listResp.status, await listResp.json());

// 查询单个
const getResp = await fetch(`${BASE_URL}/todos/1`);
console.log(getResp.status, await getResp.json());

// 更新
const updateResp = await fetch(`${BASE_URL}/todos/1`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
title: "学习 FastAPI",
description: "已完成",
completed: true,
}),
});
console.log(updateResp.status, await updateResp.json());

// 删除
const deleteResp = await fetch(`${BASE_URL}/todos/1`, { method: "DELETE" });
console.log(deleteResp.status);

7.5 使用 Postman / Apifox 图形化工具

Postman 和 Apifox 是流行的图形化 API 调试工具，适合团队协作和接口文档管理：

调用方式选择建议：日常调试用 Swagger 或 Postman；脚本自动化用 Python requests；前端联调用 fetch 或 axios；命令行快速验证用 curl。

接口写完后，我们需要进行充分的测试，确保每个接口都能正常工作。

7.1 使用 Swagger 文档测试

FastAPI 自动生成的 /docs 页面提供了可视化的接口测试工具。你可以：

7.2 使用 curl 命令测试

在终端中也可以直接使用 curl 进行测试：

# 创建待办事项
curl -X POST "http://127.0.0.1:8000/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "完成 API 开发教程"}'

# 查询列表
curl "http://127.0.0.1:8000/todos"

# 查询单个
curl "http://127.0.0.1:8000/todos/1"

# 更新
curl -X PUT "http://127.0.0.1:8000/todos/1" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "已完成", "completed": true}'

# 删除
curl -X DELETE "http://127.0.0.1:8000/todos/1"

7.3 常见问题排查

在开发和测试过程中，你可能会遇到一些常见问题。下面按错误类型给出排查思路和解决方案。

7.3.1 404 错误：资源不存在

现象：请求返回 404 Not Found。

可能原因与解决方案：

• URL 路径写错：检查路径是否与路由定义完全一致，注意大小写和末尾斜杠
• 资源 ID 不存在：确认查询的 ID 是否在数据库中存在，可先调用列表接口确认
• 路由顺序问题：如果定义了 /todos/{todo_id} 和 /todos/me 这类路由，注意静态路径要放在动态路径之前

7.3.2 422 错误：参数校验失败

现象：请求返回 422 Unprocessable Entity，响应体中包含字段级别的错误详情。

可能原因与解决方案：

• 缺少必填字段：如创建待办事项时未传 title，检查请求体是否完整
• 字段类型错误：如 completed 传了字符串 "true" 而不是布尔值 true，检查 JSON 中的类型
• 路径参数类型错误：如 /todos/abc 中 abc 无法转换为 int，确认路径参数类型

7.3.3 500 错误：服务器内部异常

现象：请求返回 500 Internal Server Error。

可能原因与解决方案：

• 数据库连接失败：检查数据库服务是否启动、连接串是否正确
• 代码逻辑异常：查看终端日志中的堆栈信息，定位具体报错行
• 依赖缺失：确认所有依赖都已安装，可执行 pip list 检查

7.3.4 服务无法启动

现象：运行 uvicorn main:app –reload 时报错退出。

可能原因与解决方案：

• 端口被占用：换一个端口启动，如 uvicorn main:app –port 8001
• 导入错误：检查 main.py 中是否有语法错误或未安装的依赖
• 虚拟环境未激活：确认当前终端使用的是项目虚拟环境

7.3.5 数据不持久化

现象：服务重启后，之前创建的数据丢失。

可能原因与解决方案：

• 仍在使用内存存储：确认是否已按第 6.8 节改造为数据库存储
• 数据库文件路径问题：检查 DATABASE_URL 中的路径是否正确，SQLite 文件是否生成
• 未执行建表：确认 Base.metadata.create_all(bind=engine) 已执行

排查技巧：遇到问题时，先看终端日志中的堆栈信息，再结合响应体中的 code 和 message 字段定位问题，通常能快速找到根因。

7.4 接口性能对比

为了直观展示不同实现方式的性能差异，下面用一张对比图说明内存存储与数据库存储、同步与异步接口、有无缓存等场景下的响应耗时情况。

#mermaid-svg-iJbumWrc2scx5FVY{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-iJbumWrc2scx5FVY .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-iJbumWrc2scx5FVY .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-iJbumWrc2scx5FVY .error-icon{fill:#552222;}#mermaid-svg-iJbumWrc2scx5FVY .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-iJbumWrc2scx5FVY .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-iJbumWrc2scx5FVY .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-iJbumWrc2scx5FVY .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-iJbumWrc2scx5FVY .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-iJbumWrc2scx5FVY .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-iJbumWrc2scx5FVY .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-iJbumWrc2scx5FVY .marker{fill:#333333;stroke:#333333;}#mermaid-svg-iJbumWrc2scx5FVY .marker.cross{stroke:#333333;}#mermaid-svg-iJbumWrc2scx5FVY svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-iJbumWrc2scx5FVY p{margin:0;}#mermaid-svg-iJbumWrc2scx5FVY .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-iJbumWrc2scx5FVY .cluster-label text{fill:#333;}#mermaid-svg-iJbumWrc2scx5FVY .cluster-label span{color:#333;}#mermaid-svg-iJbumWrc2scx5FVY .cluster-label span p{background-color:transparent;}#mermaid-svg-iJbumWrc2scx5FVY .label text,#mermaid-svg-iJbumWrc2scx5FVY span{fill:#333;color:#333;}#mermaid-svg-iJbumWrc2scx5FVY .node rect,#mermaid-svg-iJbumWrc2scx5FVY .node circle,#mermaid-svg-iJbumWrc2scx5FVY .node ellipse,#mermaid-svg-iJbumWrc2scx5FVY .node polygon,#mermaid-svg-iJbumWrc2scx5FVY .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-iJbumWrc2scx5FVY .rough-node .label text,#mermaid-svg-iJbumWrc2scx5FVY .node .label text,#mermaid-svg-iJbumWrc2scx5FVY .image-shape .label,#mermaid-svg-iJbumWrc2scx5FVY .icon-shape .label{text-anchor:middle;}#mermaid-svg-iJbumWrc2scx5FVY .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-iJbumWrc2scx5FVY .rough-node .label,#mermaid-svg-iJbumWrc2scx5FVY .node .label,#mermaid-svg-iJbumWrc2scx5FVY .image-shape .label,#mermaid-svg-iJbumWrc2scx5FVY .icon-shape .label{text-align:center;}#mermaid-svg-iJbumWrc2scx5FVY .node.clickable{cursor:pointer;}#mermaid-svg-iJbumWrc2scx5FVY .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-iJbumWrc2scx5FVY .arrowheadPath{fill:#333333;}#mermaid-svg-iJbumWrc2scx5FVY .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-iJbumWrc2scx5FVY .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-iJbumWrc2scx5FVY .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-iJbumWrc2scx5FVY .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-iJbumWrc2scx5FVY .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-iJbumWrc2scx5FVY .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-iJbumWrc2scx5FVY .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-iJbumWrc2scx5FVY .cluster text{fill:#333;}#mermaid-svg-iJbumWrc2scx5FVY .cluster span{color:#333;}#mermaid-svg-iJbumWrc2scx5FVY div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-iJbumWrc2scx5FVY .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-iJbumWrc2scx5FVY rect.text{fill:none;stroke-width:0;}#mermaid-svg-iJbumWrc2scx5FVY .icon-shape,#mermaid-svg-iJbumWrc2scx5FVY .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-iJbumWrc2scx5FVY .icon-shape p,#mermaid-svg-iJbumWrc2scx5FVY .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-iJbumWrc2scx5FVY .icon-shape .label rect,#mermaid-svg-iJbumWrc2scx5FVY .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-iJbumWrc2scx5FVY .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-iJbumWrc2scx5FVY .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-iJbumWrc2scx5FVY :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

适用场景

缓存命中率

平均响应耗时

接口实现方式

内存存储（无 I/O）

SQLite 存储（本地磁盘 I/O）

PostgreSQL 存储（网络 I/O）

SQLite + Redis 缓存（缓存命中）

异步 PostgreSQL（asyncpg）

0.1ms – 0.5ms

1ms – 5ms

5ms – 20ms

0.2ms – 1ms

3ms – 10ms

100%（无缓存）

0%（无缓存）

0%（无缓存）

90% – 99%

0%（无缓存）

缓存 / 临时数据

中小型应用 / 开发环境

生产环境 / 高并发

高频读取 / 低频更新

高并发写入 / 大数据量

从图中可以看出：

• 内存存储：响应最快，但数据无法持久化，适合缓存或临时数据
• SQLite 存储：本地磁盘 I/O，速度尚可，适合中小型应用和开发环境
• PostgreSQL 存储：网络 I/O 开销较大，但支持并发、事务和水平扩展，适合生产环境
• SQLite + Redis 缓存：缓存命中时响应接近内存速度，适合高频读取、低频更新的数据
• 异步 PostgreSQL：通过异步驱动减少线程阻塞，在高并发下吞吐量显著提升

读多写少场景：优先考虑加缓存；写多读少场景：优先考虑异步驱动和连接池；高并发场景：两者结合效果最佳。

7.4.1 性能对比数据表

为了更直观地对比不同实现方式的性能差异，下面给出一个参考数据表（基于 1000 次请求的平均值）：

缓存命中率说明：缓存命中率越高，实际响应越接近内存速度。当缓存命中率低于 80% 时，建议检查缓存淘汰策略或调整过期时间，避免缓存穿透和雪崩。

7.5 实战测试：完整流程演练

下面通过一个完整的实战演练，把前面学到的接口串起来跑一遍，验证 CRUD 全流程的正确性。

7.5.1 准备测试数据

先创建两条待办事项作为测试数据：

# 创建第一条待办事项
curl -X POST "http://127.0.0.1:8000/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "完成 API 开发教程"}'

# 创建第二条待办事项
curl -X POST "http://127.0.0.1:8000/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "编写单元测试", "description": "为 CRUD 接口补充测试用例"}'

7.5.2 验证查询功能

# 查询列表，应返回 2 条记录
curl "http://127.0.0.1:8000/todos"

# 按完成状态筛选
curl "http://127.0.0.1:8000/todos?completed=false"

# 查询单个
curl "http://127.0.0.1:8000/todos/1"

7.5.3 验证更新功能

# 将第一条待办事项标记为已完成
curl -X PUT "http://127.0.0.1:8000/todos/1" \\
-H "Content-Type: application/json" \\
-d '{"title": "学习 FastAPI", "description": "完成 API 开发教程", "completed": true}'

7.5.4 验证删除功能

# 删除第二条待办事项
curl -X DELETE "http://127.0.0.1:8000/todos/2"

# 再次查询列表，应只剩 1 条记录
curl "http://127.0.0.1:8000/todos"

7.5.5 验证错误处理

# 查询不存在的 ID，应返回 404
curl "http://127.0.0.1:8000/todos/999"

# 缺少必填字段，应返回 422
curl -X POST "http://127.0.0.1:8000/todos" \\
-H "Content-Type: application/json" \\
-d '{"description": "缺少 title 字段"}'

7.5.6 使用 Python 脚本自动化测试

手动测试只能验证单个接口，下面用 Python 脚本把整个流程自动化跑一遍，并断言每个步骤的返回结果：

import requests

BASE_URL = "http://127.0.0.1:8000"

def test_create_todo():
"""测试创建待办事项"""
resp = requests.post(
f"{BASE_URL}/todos",
json={"title": "学习 FastAPI", "description": "完成 API 开发教程"},
)
assert resp.status_code == 201, f"创建失败: {resp.status_code}"
data = resp.json()
assert data["title"] == "学习 FastAPI"
print(f"✅ 创建成功: id={data['id']}")
return data["id"]

def test_list_todos():
"""测试查询列表"""
resp = requests.get(f"{BASE_URL}/todos")
assert resp.status_code == 200
assert isinstance(resp.json(), list)
print(f"✅ 查询列表成功: 共 {len(resp.json())} 条")

def test_get_todo(todo_id: int):
"""测试查询单个"""
resp = requests.get(f"{BASE_URL}/todos/{todo_id}")
assert resp.status_code == 200
assert resp.json()["id"] == todo_id
print(f"✅ 查询单个成功: id={todo_id}")

def test_update_todo(todo_id: int):
"""测试更新"""
resp = requests.put(
f"{BASE_URL}/todos/{todo_id}",
json={"title": "学习 FastAPI", "description": "已完成", "completed": True},
)
assert resp.status_code == 200
assert resp.json()["completed"] is True
print(f"✅ 更新成功: id={todo_id}")

def test_delete_todo(todo_id: int):
"""测试删除"""
resp = requests.delete(f"{BASE_URL}/todos/{todo_id}")
assert resp.status_code == 204
print(f"✅ 删除成功: id={todo_id}")

def test_not_found():
"""测试 404 错误处理"""
resp = requests.get(f"{BASE_URL}/todos/99999")
assert resp.status_code == 404
assert resp.json()["code"] == 404
print("✅ 404 错误处理正确")

def test_validation_error():
"""测试 422 参数校验错误"""
resp = requests.post(f"{BASE_URL}/todos", json={"description": "缺少 title"})
assert resp.status_code == 422
assert resp.json()["code"] == 422
print("✅ 422 参数校验错误处理正确")

if __name__ == "__main__":
print("开始自动化测试…\\n")
todo_id = test_create_todo()
test_list_todos()
test_get_todo(todo_id)
test_update_todo(todo_id)
test_delete_todo(todo_id)
test_not_found()
test_validation_error()
print("\\n🎉 全部测试通过！")

运行脚本：

python test_api.py

预期输出：

开始自动化测试…

✅ 创建成功: id=1
✅ 查询列表成功: 共 1 条
✅ 查询单个成功: id=1
✅ 更新成功: id=1
✅ 删除成功: id=1
✅ 404 错误处理正确
✅ 422 参数校验错误处理正确

🎉 全部测试通过！

测试要点：自动化测试脚本应覆盖正常流程（增删改查）和异常流程（404、422），并断言状态码和关键字段。实际项目中可结合 pytest 编写更完整的测试套件，并接入 CI/CD 流水线。

7.5.7 使用 pytest 编写自动化测试

除了手动调用脚本，更推荐使用 pytest 编写可重复执行的自动化测试。这样每次修改代码后，只需运行一条命令即可验证所有接口是否正常。

首先安装 pytest 和 httpx（FastAPI 的测试客户端依赖）：

pip install pytest httpx

然后创建 test_main.py 测试文件：

import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_todo():
"""测试创建待办事项"""
resp = client.post("/todos", json={
"title": "学习 pytest",
"description": "编写自动化测试",
})
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "学习 pytest"
assert data["completed"] is False
assert "id" in data

def test_list_todos():
"""测试查询待办事项列表"""
# 先创建一条数据
client.post("/todos", json={"title": "测试列表"})

resp = client.get("/todos")
assert resp.status_code == 200
assert isinstance(resp.json(), list)
assert len(resp.json()) >= 1

def test_get_todo_not_found():
"""测试查询不存在的待办事项返回 404"""
resp = client.get("/todos/99999")
assert resp.status_code == 404
assert resp.json()["code"] == 404

def test_update_todo():
"""测试更新待办事项"""
# 先创建一条数据
create_resp = client.post("/todos", json={"title": "待更新"})
todo_id = create_resp.json()["id"]

resp = client.put(f"/todos/{todo_id}", json={
"title": "已更新",
"completed": True,
})
assert resp.status_code == 200
assert resp.json()["title"] == "已更新"
assert resp.json()["completed"] is True

def test_delete_todo():
"""测试删除待办事项"""
# 先创建一条数据
create_resp = client.post("/todos", json={"title": "待删除"})
todo_id = create_resp.json()["id"]

resp = client.delete(f"/todos/{todo_id}")
assert resp.status_code == 204

# 再次查询应返回 404
resp = client.get(f"/todos/{todo_id}")
assert resp.status_code == 404

def test_validation_error():
"""测试参数校验失败返回 422"""
resp = client.post("/todos", json={"title": ""})
assert resp.status_code == 422
assert resp.json()["code"] == 422

运行测试：

pytest test_main.py -v

输出示例：

============================= test session starts =============================
collected 6 items

test_main.py::test_create_todo PASSED
test_main.py::test_list_todos PASSED
test_main.py::test_get_todo_not_found PASSED
test_main.py::test_update_todo PASSED
test_main.py::test_delete_todo PASSED
test_main.py::test_validation_error PASSED

============================== 6 passed in 0.35s ==============================

测试要点：使用 TestClient 无需启动真实服务器即可模拟请求；每个测试用例相互独立，建议在测试前清空数据库或使用独立测试库；断言时同时检查状态码和响应体，确保接口行为符合预期。

7.5.8 使用 pytest 测试数据库集成

在完成数据库改造后，我们需要验证 CRUD 接口与 SQLite 的集成是否正常。下面是一个针对数据库版本的 pytest 测试脚本：

# test_db_integration.py
import os
import tempfile
import pytest
from fastapi.testclient import TestClient

# 使用临时数据库，避免污染开发数据
os.environ["DATABASE_URL"] = f"sqlite:///{tempfile.mkdtemp()}/test.db"

from main import app, Base, engine, SessionLocal, TodoDB

# 创建测试表
Base.metadata.create_all(bind=engine)

client = TestClient(app)

@pytest.fixture(autouse=True)
def clean_db():
"""每个测试用例前清空数据库"""
db = SessionLocal()
db.query(TodoDB).delete()
db.commit()
db.close()
yield

def test_create_todo_persists_to_db():
"""创建待办事项后，数据应写入数据库"""
resp = client.post("/todos", json={"title": "数据库测试", "description": "验证持久化"})
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "数据库测试"

# 直接从数据库验证
db = SessionLocal()
todo = db.query(TodoDB).filter(TodoDB.id == data["id"]).first()
assert todo is not None
assert todo.title == "数据库测试"
db.close()

def test_list_todos_reads_from_db():
"""列表接口应返回数据库中的数据"""
# 先创建一条数据
client.post("/todos", json={"title": "待查询事项"})

resp = client.get("/todos")
assert resp.status_code == 200
assert len(resp.json()) == 1
assert resp.json()[0]["title"] == "待查询事项"

def test_update_todo_syncs_to_db():
"""更新接口应同步修改数据库记录"""
create_resp = client.post("/todos", json={"title": "原始标题"})
todo_id = create_resp.json()["id"]

update_resp = client.put(
f"/todos/{todo_id}",
json={"title": "更新后的标题", "completed": True},
)
assert update_resp.status_code == 200
assert update_resp.json()["title"] == "更新后的标题"

# 验证数据库中的记录已更新
db = SessionLocal()
todo = db.query(TodoDB).filter(TodoDB.id == todo_id).first()
assert todo.title == "更新后的标题"
assert todo.completed is True
db.close()

def test_delete_todo_removes_from_db():
"""删除接口应移除数据库记录"""
create_resp = client.post("/todos", json={"title": "待删除事项"})
todo_id = create_resp.json()["id"]

delete_resp = client.delete(f"/todos/{todo_id}")
assert delete_resp.status_code == 204

# 验证数据库中的记录已删除
db = SessionLocal()
todo = db.query(TodoDB).filter(TodoDB.id == todo_id).first()
assert todo is None
db.close()

运行测试：

pytest test_db_integration.py -v

测试要点：使用 TestClient 模拟真实 HTTP 请求，无需启动服务器；通过 autouse fixture 在每个用例前清空数据库，保证测试隔离；测试结束后临时数据库自动清理，不影响开发数据。

7.5.9 使用 pytest 测试部署后的接口

部署完成后，我们同样可以使用 pytest 对线上接口进行冒烟测试，确保服务在云平台上正常运行。下面是一个针对部署环境的测试脚本：

# test_deployed_api.py
"""
部署环境冒烟测试
验证线上 API 的核心功能是否正常
"""
import os
import requests
import pytest

# 从环境变量读取线上地址，本地测试时使用默认值
BASE_URL = os.getenv("DEPLOYED_API_URL", "https://your-app.railway.app")

@pytest.fixture(scope="module")
def base_url():
"""返回线上 API 地址"""
return BASE_URL

def test_health_check(base_url):
"""健康检查接口应返回 200"""
resp = requests.get(f"{base_url}/health", timeout=10)
assert resp.status_code == 200
data = resp.json()
assert data["status"] == "ok"

def test_create_todo(base_url):
"""线上创建待办事项"""
resp = requests.post(
f"{base_url}/todos",
json={"title": "部署冒烟测试", "description": "验证线上创建功能"},
timeout=10,
)
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "部署冒烟测试"
return data["id"]

def test_list_todos(base_url):
"""线上查询列表"""
resp = requests.get(f"{base_url}/todos", timeout=10)
assert resp.status_code == 200
assert isinstance(resp.json(), list)

def test_get_todo(base_url):
"""线上查询单个待办事项"""
# 先创建一个
create_resp = requests.post(
f"{base_url}/todos",
json={"title": "查询测试"},
timeout=10,
)
todo_id = create_resp.json()["id"]

resp = requests.get(f"{base_url}/todos/{todo_id}", timeout=10)
assert resp.status_code == 200
assert resp.json()["id"] == todo_id

def test_update_todo(base_url):
"""线上更新待办事项"""
create_resp = requests.post(
f"{base_url}/todos",
json={"title": "更新前", "completed": False},
timeout=10,
)
todo_id = create_resp.json()["id"]

resp = requests.put(
f"{base_url}/todos/{todo_id}",
json={"title": "更新后", "completed": True},
timeout=10,
)
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "更新后"
assert data["completed"] is True

def test_delete_todo(base_url):
"""线上删除待办事项"""
create_resp = requests.post(
f"{base_url}/todos",
json={"title": "待删除"},
timeout=10,
)
todo_id = create_resp.json()["id"]

resp = requests.delete(f"{base_url}/todos/{todo_id}", timeout=10)
assert resp.status_code == 204

def test_404_for_missing_todo(base_url):
"""查询不存在的待办事项应返回 404"""
resp = requests.get(f"{base_url}/todos/999999", timeout=10)
assert resp.status_code == 404
data = resp.json()
assert data["code"] == 404

运行方式：

# 本地测试
pytest test_deployed_api.py -v

# 指定线上地址测试
DEPLOYED_API_URL="https://your-app.railway.app" pytest test_deployed_api.py -v

部署测试要点：冒烟测试覆盖健康检查与核心 CRUD 流程，确保线上服务可用；通过环境变量注入线上地址，避免把测试地址硬编码；建议在 CI/CD 流水线中部署完成后自动执行冒烟测试，快速发现回归问题。

7.5.10 使用 curl 脚本进行端到端冒烟测试

除了使用 pytest 编写单元测试，我们还可以编写一个轻量级的 shell 脚本，对部署后的 API 进行快速的端到端冒烟测试。这种方式非常适合在 CI/CD 流水线中作为部署后的健康检查步骤。

#!/usr/bin/env bash
# smoke_test.sh – API 冒烟测试脚本
# 用法: ./smoke_test.sh [BASE_URL]
# 示例: ./smoke_test.sh http://127.0.0.1:8000

set -e # 任何命令失败则立即退出

BASE_URL="${1:-http://127.0.0.1:8000}"
PASS=0
FAIL=0

# 辅助函数：检查 HTTP 状态码
check_status() {
local expected="$1"
local actual="$2"
local description="$3"

if [ "$expected" -eq "$actual" ]; then
echo "✅ PASS: $description (HTTP $actual)"
PASS=$((PASS + 1))
else
echo "❌ FAIL: $description (期望 HTTP $expected, 实际 HTTP $actual)"
FAIL=$((FAIL + 1))
fi
}

echo "========================================"
echo "开始 API 冒烟测试: $BASE_URL"
echo "========================================"

# 1. 健康检查
echo ""
echo "— 1. 健康检查 —"
HEALTH_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/health")
check_status 200 "$HEALTH_CODE" "健康检查接口"

# 2. 创建待办事项
echo ""
echo "— 2. 创建待办事项 —"
CREATE_RESP=$(curl -s -X POST "$BASE_URL/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "冒烟测试任务", "description": "由脚本自动创建"}')
CREATE_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$BASE_URL/todos" \\
-H "Content-Type: application/json" \\
-d '{"title": "冒烟测试任务", "description": "由脚本自动创建"}')
check_status 201 "$CREATE_CODE" "创建待办事项"

# 提取新创建的 ID（使用 Python 解析 JSON）
TODO_ID=$(echo "$CREATE_RESP" | python3 -c "import sys, json; print(json.load(sys.stdin)['id'])" 2>/dev/null || echo "1")
echo " 创建成功，新 ID = $TODO_ID"

# 3. 查询列表
echo ""
echo "— 3. 查询待办事项列表 —"
LIST_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/todos")
check_status 200 "$LIST_CODE" "查询待办事项列表"

# 4. 查询单个
echo ""
echo "— 4. 查询单个待办事项 —"
GET_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/todos/$TODO_ID")
check_status 200 "$GET_CODE" "查询单个待办事项 (ID=$TODO_ID)"

# 5. 更新待办事项
echo ""
echo "— 5. 更新待办事项 —"
UPDATE_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X PUT "$BASE_URL/todos/$TODO_ID" \\
-H "Content-Type: application/json" \\
-d '{"title": "冒烟测试任务（已更新）", "completed": true}')
check_status 200 "$UPDATE_CODE" "更新待办事项 (ID=$TODO_ID)"

# 6. 删除待办事项
echo ""
echo "— 6. 删除待办事项 —"
DELETE_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "$BASE_URL/todos/$TODO_ID")
check_status 204 "$DELETE_CODE" "删除待办事项 (ID=$TODO_ID)"

# 7. 验证删除后返回 404
echo ""
echo "— 7. 验证删除后返回 404 —"
NOT_FOUND_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/todos/$TODO_ID")
check_status 404 "$NOT_FOUND_CODE" "删除后查询应返回 404"

echo ""
echo "========================================"
echo "测试完成: 通过 $PASS 项, 失败 $FAIL 项"
echo "========================================"

# 如果有失败项，以非零状态码退出（供 CI 判断）
if [ "$FAIL" -gt 0 ]; then
exit 1
fi

运行方式：

# 给脚本添加执行权限
chmod +x smoke_test.sh

# 本地测试
./smoke_test.sh http://127.0.0.1:8000

# 测试部署后的线上环境
./smoke_test.sh https://my-api.onrender.com

冒烟测试要点：脚本覆盖了 CRUD 全流程和健康检查，任何一步失败都会以非零状态码退出；set -e 确保中间步骤失败时立即终止，避免误报；建议将该脚本接入 CI/CD 流水线，在每次部署后自动执行，快速发现回归问题。

7.5.11 使用 pytest 测试完整 CRUD 流程

除了针对单个接口的测试，我们还可以编写一个覆盖完整 CRUD 流程的端到端测试，验证「创建 → 查询 → 更新 → 删除」全链路是否正常。下面给出一个完整的测试脚本：

# test_crud_flow.py
"""
完整 CRUD 流程测试
覆盖创建、查询、更新、删除的端到端验证
"""
import requests
import pytest

BASE_URL = "http://127.0.0.1:8000"

@pytest.fixture()
def created_todo():
"""创建一条待办事项，测试结束后自动清理"""
resp = requests.post(
f"{BASE_URL}/todos",
json={"title": "端到端测试任务", "description": "验证完整 CRUD 流程"},
)
assert resp.status_code == 201
todo = resp.json()
yield todo

# 清理：删除测试数据
requests.delete(f"{BASE_URL}/todos/{todo['id']}")

def test_create_todo():
"""创建待办事项应返回 201 和完整数据"""
resp = requests.post(
f"{BASE_URL}/todos",
json={"title": "学习 pytest", "description": "编写自动化测试"},
)
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "学习 pytest"
assert data["description"] == "编写自动化测试"
assert data["completed"] is False
assert data["id"] is not None
assert "created_at" in data

def test_get_todo_list():
"""查询列表应返回数组且包含刚创建的数据"""
resp = requests.get(f"{BASE_URL}/todos")
assert resp.status_code == 200
data = resp.json()
assert isinstance(data, list)
assert len(data) > 0

def test_get_single_todo(created_todo):
"""按 ID 查询单个待办事项"""
todo_id = created_todo["id"]
resp = requests.get(f"{BASE_URL}/todos/{todo_id}")
assert resp.status_code == 200
data = resp.json()
assert data["id"] == todo_id
assert data["title"] == "端到端测试任务"

def test_update_todo(created_todo):
"""更新待办事项应返回更新后的数据"""
todo_id = created_todo["id"]
resp = requests.put(
f"{BASE_URL}/todos/{todo_id}",
json={
"title": "已更新的任务",
"description": "更新描述",
"completed": True,
},
)
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "已更新的任务"
assert data["completed"] is True

def test_delete_todo(created_todo):
"""删除待办事项应返回 204"""
todo_id = created_todo["id"]
resp = requests.delete(f"{BASE_URL}/todos/{todo_id}")
assert resp.status_code == 204

# 删除后再次查询应返回 404
resp = requests.get(f"{BASE_URL}/todos/{todo_id}")
assert resp.status_code == 404

def test_get_nonexistent_todo():
"""查询不存在的 ID 应返回 404"""
resp = requests.get(f"{BASE_URL}/todos/999999")
assert resp.status_code == 404
data = resp.json()
assert data["code"] == 404

运行方式：

pytest test_crud_flow.py -v

测试要点：使用 fixture 自动创建和清理测试数据，避免测试之间相互干扰；每个测试只验证一个核心行为，失败时能快速定位问题；建议将 CRUD 流程测试与安全测试、部署测试一起纳入 CI/CD 流水线，形成完整的自动化测试体系。

7.5.12 使用 pytest 测试完整 CRUD 流程（数据库版

7.5.13 使用 pytest 测试完整 CRUD 流程（数据库版，完整可运行）

下面给出一个完整、可直接运行的 pytest 测试脚本，覆盖数据库版 CRUD 的全部接口。它使用 FastAPI 的 TestClient 和临时 SQLite 数据库，确保测试之间互不干扰：

# test_todo_db.py
"""
数据库版 CRUD 完整测试
运行方式：pytest test_todo_db.py -v
"""
import os
import tempfile
import pytest
from fastapi.testclient import TestClient

# 使用临时数据库，避免污染开发数据
TEMP_DB = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
os.environ["DATABASE_URL"] = f"sqlite:///{TEMP_DB.name}"

# 注意：必须在导入 main 之前设置好环境变量
from main import app, Base, engine, SessionLocal # noqa: E402

# 重建表结构
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)

client = TestClient(app)

@pytest.fixture(autouse=True)
def clean_db():
"""每个测试用例前清空数据表，保证用例独立"""
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)
yield
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)

def test_create_todo():
"""测试创建待办事项"""
resp = client.post("/todos", json={"title": "学习 FastAPI", "description": "完成教程"})
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "学习 FastAPI"
assert data["completed"] is False
assert data["id"] == 1

def test_list_todos_empty():
"""测试空列表"""
resp = client.get("/todos")
assert resp.status_code == 200
assert resp.json() == []

def test_list_todos_with_filter():
"""测试按完成状态筛选"""
client.post("/todos", json={"title": "任务A", "completed": False})
client.post("/todos", json={"title": "任务B", "completed": True})

resp = client.get("/todos", params={"completed": True})
assert resp.status_code == 200
data = resp.json()
assert len(data) == 1
assert data[0]["title"] == "任务B"

def test_get_todo_success():
"""测试查询单个待办事项"""
created = client.post("/todos", json={"title": "任务A"}).json()
resp = client.get(f"/todos/{created['id']}")
assert resp.status_code == 200
assert resp.json()["title"] == "任务A"

def test_get_todo_not_found():
"""测试查询不存在的待办事项"""
resp = client.get("/todos/999")
assert resp.status_code == 404
assert resp.json()["code"] == 404

def test_update_todo():
"""测试更新待办事项"""
created = client.post("/todos", json={"title": "任务A"}).json()
resp = client.put(
f"/todos/{created['id']}",
json={"title": "任务A（已更新）", "description": "新描述", "completed": True},
)
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "任务A（已更新）"
assert data["completed"] is True

def test_update_todo_not_found():
"""测试更新不存在的待办事项"""
resp = client.put("/todos/999", json={"title": "不存在"})
assert resp.status_code == 404

def test_delete_todo():
"""测试删除待办事项"""
created = client.post("/todos", json={"title": "待删除"}).json()
resp = client.delete(f"/todos/{created['id']}")
assert resp.status_code == 204

# 删除后再次查询应返回 404
resp = client.get(f"/todos/{created['id']}")
assert resp.status_code == 404

def test_delete_todo_not_found():
"""测试删除不存在的待办事项"""
resp = client.delete("/todos/999")
assert resp.status_code == 404

def test_validation_error():
"""测试缺少必填字段时返回 422"""
resp = client.post("/todos", json={"description": "缺少 title"})
assert resp.status_code == 422
data = resp.json()
assert data["code"] == 422
assert data["data"][0]["field"] == "title"

def test_full_crud_flow():
"""测试完整 CRUD 流程"""
# 1. 创建
resp = client.post("/todos", json={"title": "完整流程", "description": "测试"})
assert resp.status_code == 201
todo_id = resp.json()["id"]

# 2. 查询列表
resp = client.get("/todos")
assert resp.status_code == 200
assert len(resp.json()) == 1

# 3. 查询单个
resp = client.get(f"/todos/{todo_id}")
assert resp.status_code == 200

# 4. 更新
resp = client.put(f"/todos/{todo_id}", json={"title": "完整流程（完成）", "completed": True})
assert resp.status_code == 200
assert resp.json()["completed"] is True

# 5. 删除
resp = client.delete(f"/todos/{todo_id}")
assert resp.status_code == 204

# 6. 确认已删除
resp = client.get(f"/todos/{todo_id}")
assert resp.status_code == 404

运行方式：

# 安装测试依赖
pip install pytest httpx

# 运行全部测试
pytest test_todo_db.py -v

测试要点：每个用例通过 clean_db fixture 重建数据表，保证用例之间完全隔离；TestClient 直接调用应用，无需启动真实服务器；覆盖了成功、失败、参数校验、完整流程等 12 个典型场景，可作为回归测试长期保留。

）

前面我们分别测试了内存版和数据库版的接口。下面给出一个针对数据库版 CRUD 的完整 pytest 测试脚本，覆盖创建、查询、更新、删除全流程，并验证数据确实持久化到 SQLite：

# test_crud_db.py
"""
数据库版 CRUD 完整测试
覆盖：创建、查询列表、查询单个、更新、删除、持久化验证
"""
import os
import pytest
from fastapi.testclient import TestClient

# 使用临时数据库，避免污染开发数据
os.environ["DATABASE_URL"] = "sqlite:///./test_todos.db"

from main import app, Base, engine, SessionLocal, TodoDB

client = TestClient(app)

@pytest.fixture(scope="module", autouse=True)
def setup_database():
"""每个测试模块开始时重建数据库表"""
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)
yield
# 测试结束后清理临时数据库文件
Base.metadata.drop_all(bind=engine)
if os.path.exists("./test_todos.db"):
os.remove("./test_todos.db")

def test_create_todo():
"""创建待办事项应返回 201 和完整数据"""
resp = client.post("/todos", json={
"title": "学习 FastAPI",
"description": "完成数据库版 CRUD 测试",
})
assert resp.status_code == 201
data = resp.json()
assert data["title"] == "学习 FastAPI"
assert data["completed"] is False
assert data["id"] == 1
return data

def test_list_todos():
"""查询列表应包含刚创建的数据"""
resp = client.get("/todos")
assert resp.status_code == 200
data = resp.json()
assert len(data) >= 1
assert any(t["title"] == "学习 FastAPI" for t in data)

def test_get_single_todo():
"""按 ID 查询单个待办事项"""
resp = client.get("/todos/1")
assert resp.status_code == 200
data = resp.json()
assert data["id"] == 1
assert data["title"] == "学习 FastAPI"

def test_get_nonexistent_todo():
"""查询不存在的 ID 应返回 404"""
resp = client.get("/todos/999")
assert resp.status_code == 404
assert resp.json()["code"] == 404

def test_update_todo():
"""更新待办事项应返回更新后的数据"""
resp = client.put("/todos/1", json={
"title": "学习 FastAPI（已完成）",
"description": "数据库版 CRUD 测试通过",
"completed": True,
})
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "学习 FastAPI（已完成）"
assert data["completed"] is True

def test_delete_todo():
"""删除待办事项应返回 204"""
resp = client.delete("/todos/1")
assert resp.status_code == 204

def test_delete_nonexistent_todo():
"""删除不存在的 ID 应返回 404"""
resp = client.delete("/todos/999")
assert resp.status_code == 404

def test_data_persisted_in_db():
"""验证数据确实写入 SQLite 数据库文件"""
# 直接查询数据库，绕过 API
db = SessionLocal()
try:
# 先创建一条数据
client.post("/todos", json={"title": "持久化验证", "description": "直接查库"})
# 从数据库读取
todo = db.query(TodoDB).filter(TodoDB.title == "持久化验证").first()
assert todo is not None
assert todo.description == "直接查库"
finally:
db.close()

运行方式：

pytest test_crud_db.py -v

数据库版测试要点：使用 TestClient 模拟真实 HTTP 请求，无需启动服务器；通过 Base.metadata.drop_all/create_all 在测试前后重建表，保证测试隔离；最后一条用例直接查询数据库，验证数据确实落盘，而不仅仅是内存操作。

7.5.14 使用 pytest 测试完整 CRUD 流程（数据库版，含错误场景

7.5.15 使用 pytest 测试完整 CRUD 流程（数据库版，含错误场景）

在 7.5.14 的基础上，补充一个完整的端到端测试脚本，覆盖数据库版 CRUD 的全部成功与错误场景，并加入并发与边界测试，确保接口在生产环境下的健壮性。

# test_todo_e2e.py
"""
待办事项 API 端到端测试（数据库版）
覆盖：CRUD 成功路径、404/422 错误路径、并发写入、边界值、数据持久化
"""
import threading
import time
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool

from main import app, Base, get_db, TodoDB

# 使用独立的内存数据库，避免污染开发数据
engine = create_engine(
"sqlite://",
connect_args={"check_same_thread": False},
poolclass=StaticPool,
)
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def override_get_db():
db = TestingSessionLocal()
try:
yield db
finally:
db.close()

app.dependency_overrides[get_db] = override_get_db
client = TestClient(app)

@pytest.fixture(autouse=True)
def setup_db():
"""每个测试前重建数据表，保证用例相互独立"""
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)
yield

def create_todo(title="学习 FastAPI", description="完成教程", completed=False):
"""辅助函数：创建待办事项"""
return client.post(
"/todos",
json={"title": title, "description": description, "completed": completed},
)

# ========== 创建接口测试 ==========
def test_create_todo_success():
"""正常创建返回 201 且包含自增 ID"""
resp = create_todo()
assert resp.status_code == 201
data = resp.json()
assert data["id"] == 1
assert data["title"] == "学习 FastAPI"
assert data["completed"] is False
assert "created_at" in data

def test_create_todo_missing_title():
"""缺少必填字段 title 返回 422"""
resp = client.post("/todos", json={"description": "没有标题"})
assert resp.status_code == 422
body = resp.json()
assert body["code"] == 422
assert "title" in str(body["data"])

def test_create_todo_wrong_type():
"""title 类型错误返回 422"""
resp = client.post("/todos", json={"title": 12345})
assert resp.status_code == 422

def test_create_todo_empty_title():
"""空字符串 title 返回 422（可结合 Pydantic 校验器）"""
resp = client.post("/todos", json={"title": ""})
assert resp.status_code in (201, 422) # 取决于是否配置 min_length

# ========== 查询接口测试 ==========
def test_list_todos_empty():
"""空数据库返回空列表"""
resp = client.get("/todos")
assert resp.status_code == 200
assert resp.json() == []

def test_list_todos_with_filter():
"""按 completed 筛选"""
create_todo("任务A", completed=False)
create_todo("任务B", completed=True)

resp = client.get("/todos", params={"completed": True})
assert resp.status_code == 200
data = resp.json()
assert len(data) == 1
assert data[0]["title"] == "任务B"

def test_get_todo_success():
"""查询单个待办事项"""
created = create_todo().json()
resp = client.get(f"/todos/{created['id']}")
assert resp.status_code == 200
assert resp.json()["title"] == "学习 FastAPI"

def test_get_todo_not_found():
"""查询不存在的 ID 返回 404"""
resp = client.get("/todos/999")
assert resp.status_code == 404
assert resp.json()["code"] == 404

def test_get_todo_invalid_id():
"""非数字 ID 返回 422"""
resp = client.get("/todos/abc")
assert resp.status_code == 422

# ========== 更新接口测试 ==========
def test_update_todo_success():
"""正常更新字段"""
created = create_todo().json()
resp = client.put(
f"/todos/{created['id']}",
json={"title": "已更新", "description": "新描述", "completed": True},
)
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "已更新"
assert data["completed"] is True
assert data["id"] == created["id"] # ID 不变

def test_update_todo_not_found():
"""更新不存在的 ID 返回 404"""
resp = client.put(
"/todos/999",
json={"title": "不存在", "description": "", "completed": False},
)
assert resp.status_code == 404

def test_update_todo_partial_fields():
"""只更新部分字段（description 为 None 时保留原值）"""
created = create_todo(description="原始描述").json()
resp = client.put(
f"/todos/{created['id']}",
json={"title": "只改标题", "description": None, "completed": False},
)
assert resp.status_code == 200
assert resp.json()["title"] == "只改标题"

# ========== 删除接口测试 ==========
def test_delete_todo_success():
"""正常删除返回 204"""
created = create_todo().json()
resp = client.delete(f"/todos/{created['id']}")
assert resp.status_code == 204

def test_delete_todo_not_found():
"""删除不存在的 ID 返回 404"""
resp = client.delete("/todos/999")
assert resp.status_code == 404

def test_delete_then_get_returns_404():
"""删除后再查询返回 404"""
created = create_todo().json()
client.delete(f"/todos/{created['id']}")
resp = client.get(f"/todos/{created['id']}")
assert resp.status_code == 404

# ========== 边界与并发测试 ==========
def test_create_many_todos():
"""批量创建 100 条，验证 ID 自增与列表长度"""
for i in range(100):
resp = create_todo(title=f"任务{i}")
assert resp.status_code == 201

resp = client.get("/todos")
assert len(resp.json()) == 100
assert resp.json()[0]["id"] == 1
assert resp.json()[–1]["id"] == 100

def test_concurrent_create():
"""并发创建 20 条，验证无 ID 冲突"""
results = []

def worker(n):
resp = create_todo(title=f"并发任务{n}")
results.append(resp.status_code)

threads = [threading.Thread(target=worker, args=(i,)) for i in range(20)]
for t in threads:
t.start()
for t in threads:
t.join()

assert all(code == 201 for code in results)
resp = client.get("/todos")
assert len(resp.json()) == 20

def test_data_persisted_in_db():
"""创建后数据确实写入数据库"""
create_todo(title="持久化验证")
db = TestingSessionLocal()
todo = db.query(TodoDB).filter(TodoDB.title == "持久化验证").first()
db.close()
assert todo is not None
assert todo.completed is False

运行方式：

# 安装依赖
pip install fastapi uvicorn sqlalchemy pytest httpx

# 运行端到端测试
pytest test_todo_e2e.py -v

测试要点：覆盖创建（成功/缺字段/类型错误/空标题）、查询（空列表/筛选/成功/404/422）、更新（成功/404/部分字段）、删除（成功/404/删除后查询）、边界（批量 100 条/并发 20 线程/数据库持久化）共 5 大类 18 个用例；每个用例独立重建内存数据库，互不干扰；并发测试验证了 SQLite 在 check_same_thread=False 配置下的写入安全性。

）

在 7.5.13 的基础上，补充覆盖错误场景的测试用例，包括：资源不存在（404）、参数校验失败（422）、重复创建、非法 ID 等，确保接口在异常情况下也能返回正确的状态码和错误信息。

# test_crud_errors.py
"""
数据库版 CRUD 错误场景测试
覆盖：404 资源不存在、422 参数校验失败、非法 ID、重复创建等
"""
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool

from main import app, Base, get_db, TodoDB

# 使用内存数据库，每个测试独立重建
engine = create_engine(
"sqlite://",
connect_args={"check_same_thread": False},
poolclass=StaticPool,
)
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def override_get_db():
"""测试用数据库会话"""
db = TestingSessionLocal()
try:
yield db
finally:
db.close()

app.dependency_overrides[get_db] = override_get_db
client = TestClient(app)

@pytest.fixture(autouse=True)
def setup_db():
"""每个测试前重建数据表"""
Base.metadata.drop_all(bind=engine)
Base.metadata.create_all(bind=engine)
yield

def create_todo(title="测试待办", description="测试描述"):
"""辅助函数：创建一条待办"""
return client.post(
"/todos",
json={"title": title, "description": description},
)

# ========== 404 资源不存在 ==========
def test_get_nonexistent_todo():
"""查询不存在的待办返回 404"""
resp = client.get("/todos/999")
assert resp.status_code == 404
assert resp.json()["detail"] == "待办事项不存在"

def test_update_nonexistent_todo():
"""更新不存在的待办返回 404"""
resp = client.put(
"/todos/999",
json={"title": "不存在", "description": "无", "completed": False},
)
assert resp.status_code == 404

def test_delete_nonexistent_todo():
"""删除不存在的待办返回 404"""
resp = client.delete("/todos/999")
assert resp.status_code == 404

# ========== 422 参数校验失败 ==========
def test_create_missing_title():
"""缺少必填字段 title 返回 422"""
resp = client.post("/todos", json={"description": "缺少标题"})
assert resp.status_code == 422
data = resp.json()
assert data["code"] == 422
assert "title" in str(data["data"])

def test_create_wrong_type():
"""completed 传字符串而非布尔值返回 422"""
resp = client.post(
"/todos",
json={"title": "类型错误", "completed": "true"},
)
assert resp.status_code == 422

def test_get_invalid_id_type():
"""路径参数非整数返回 422"""
resp = client.get("/todos/abc")
assert resp.status_code == 422

# ========== 正常流程 + 边界 ==========
def test_create_and_get_flow():
"""创建后能正确查询到"""
create_resp = create_todo("边界测试")
assert create_resp.status_code == 201
todo_id = create_resp.json()["id"]

get_resp = client.get(f"/todos/{todo_id}")
assert get_resp.status_code == 200
assert get_resp.json()["title"] == "边界测试"

def test_create_multiple_todos():
"""连续创建多条，ID 自增且互不干扰"""
ids = []
for i in range(3):
resp = create_todo(f"待办 {i}")
assert resp.status_code == 201
ids.append(resp.json()["id"])

assert ids == [1, 2, 3]

list_resp = client.get("/todos")
assert len(list_resp.json()) == 3

def test_filter_by_completed():
"""按完成状态筛选"""
create_todo("未完成")
resp = client.post(
"/todos",
json={"title": "已完成", "completed": True},
)
assert resp.status_code == 201

pending = client.get("/todos?completed=false")
done = client.get("/todos?completed=true")

assert len(pending.json()) == 1
assert len(done.json()) == 1
assert done.json()[0]["title"] == "已完成"

def test_update_preserves_id_and_created_at():
"""更新后 ID 和创建时间保持不变"""
create_resp = create_todo("原始标题")
todo_id = create_resp.json()["id"]
original_created_at = create_resp.json()["created_at"]

update_resp = client.put(
f"/todos/{todo_id}",
json={"title": "新标题", "description": "新描述", "completed": True},
)
assert update_resp.status_code == 200
data = update_resp.json()
assert data["id"] == todo_id
assert data["created_at"] == original_created_at
assert data["title"] == "新标题"
assert data["completed"] is True

def test_delete_then_get_returns_404():
"""删除后再查询返回 404"""
create_resp = create_todo("待删除")
todo_id = create_resp.json()["id"]

delete_resp = client.delete(f"/todos/{todo_id}")
assert delete_resp.status_code == 204

get_resp = client.get(f"/todos/{todo_id}")
assert get_resp.status_code == 404

def test_empty_list():
"""空数据库返回空列表"""
resp = client.get("/todos")
assert resp.status_code == 200
assert resp.json() == []

运行方式：

# 安装测试依赖
pip install pytest httpx

# 运行错误场景测试
pytest test_crud_errors.py -v

测试要点：覆盖 404（查询/更新/删除不存在资源）、422（缺字段/类型错误/非法路径参数）、正常流程（创建查询、批量创建、状态筛选、更新保留 ID 与创建时间、删除后 404）、空列表共 4 大类 12 个用例；每个用例独立重建内存数据库，互不干扰；app.dependency_overrides 将数据库会话替换为测试内存库，无需真实 SQLite 文件。

7.5.16 使用 pytest 测试内存版 CRUD 接口（完整可运行）

下面提供一个针对内存版 CRUD 接口的完整 pytest 测试脚本。它使用 FastAPI 自带的 TestClient，无需启动真实服务器即可运行，适合在开发阶段快速验证接口逻辑。

# test_todo_memory.py
"""
内存版 CRUD 接口测试
覆盖：创建、列表、查询单个、更新、删除、错误处理
"""
import pytest
from fastapi.testclient import TestClient

# 假设内存版接口定义在 main_memory.py 中
from main_memory import app

client = TestClient(app)

@pytest.fixture(autouse=True)
def reset_todos():
"""每个测试前重置内存数据"""
from main_memory import todos, todo_id_counter
todos.clear()
todo_id_counter = 1
yield

def create_todo(title="学习 FastAPI", description="完成 API 开发教程"):
"""辅助函数：创建待办事项"""
return client.post("/todos", json={"title": title, "description": description})

# ========== 创建 ==========
def test_create_todo_success():
"""正常创建返回 201 和待办事项"""
resp = create_todo()
assert resp.status_code == 201
data = resp.json()
assert data["id"] == 1
assert data["title"] == "学习 FastAPI"
assert data["completed"] is False

def test_create_todo_missing_title():
"""缺少必填字段 title 返回 422"""
resp = client.post("/todos", json={"description": "没有标题"})
assert resp.status_code == 422

def test_create_todo_auto_increment_id():
"""连续创建 ID 自动递增"""
create_todo("任务一")
resp = create_todo("任务二")
assert resp.json()["id"] == 2

# ========== 查询列表 ==========
def test_list_todos_empty():
"""空列表返回 []"""
resp = client.get("/todos")
assert resp.status_code == 200
assert resp.json() == []

def test_list_todos_with_data():
"""有数据时返回全部"""
create_todo("任务一")
create_todo("任务二")
resp = client.get("/todos")
assert resp.status_code == 200
assert len(resp.json()) == 2

def test_list_todos_filter_completed():
"""按完成状态筛选"""
create_todo("未完成")
resp = client.post("/todos", json={"title": "已完成", "completed": True})
assert resp.status_code == 201

resp = client.get("/todos", params={"completed": True})
data = resp.json()
assert len(data) == 1
assert data[0]["title"] == "已完成"

# ========== 查询单个 ==========
def test_get_todo_success():
"""查询存在的待办事项"""
create_todo()
resp = client.get("/todos/1")
assert resp.status_code == 200
assert resp.json()["title"] == "学习 FastAPI"

def test_get_todo_not_found():
"""查询不存在的 ID 返回 404"""
resp = client.get("/todos/999")
assert resp.status_code == 404
assert resp.json()["detail"] == "待办事项不存在"

# ========== 更新 ==========
def test_update_todo_success():
"""正常更新返回更新后的数据"""
create_todo()
resp = client.put(
"/todos/1",
json={"title": "学习 FastAPI", "description": "已完成", "completed": True},
)
assert resp.status_code == 200
data = resp.json()
assert data["completed"] is True
assert data["description"] == "已完成"

def test_update_todo_not_found():
"""更新不存在的 ID 返回 404"""
resp = client.put(
"/todos/999",
json={"title": "不存在", "description": "", "completed": False},
)
assert resp.status_code == 404

# ========== 删除 ==========
def test_delete_todo_success():
"""正常删除返回 204"""
create_todo()
resp = client.delete("/todos/1")
assert resp.status_code == 204

def test_delete_todo_not_found():
"""删除不存在的 ID 返回 404"""
resp = client.delete("/todos/999")
assert resp.status_code == 404

def test_delete_todo_removes_data():
"""删除后列表不再包含该数据"""
create_todo()
client.delete("/todos/1")
resp = client.get("/todos")
assert resp.json() == []

运行方式：

# 安装测试依赖
pip install pytest httpx

# 运行测试
pytest test_todo_memory.py -v

测试要点：覆盖创建（成功/缺字段/ID 自增）、列表（空/有数据/筛选）、查询单个（成功/404）、更新（成功/404）、删除（成功/404/数据移除）共 5 大类 13 个用例；每个用例通过 fixture 重置内存数据，保证用例之间相互独立；TestClient 直接调用应用，无需启动真实端口，测试速度更快。

题

8. 部署上线

接口开发、测试完成后，下一步就是把它部署到公网，让其他用户能够访问。本章介绍从 Docker 容器化到云平台部署的完整流程。

8.1 使用 Docker 部署

Docker 可以将应用及其依赖打包成镜像，实现「一次构建，到处运行」。首先创建 Dockerfile：

# 使用 Python 3.11 作为基础镜像
FROM python:3.11-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install –no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "main:app", "–host", "0.0.0.0", "–port", "8000"]

创建 requirements.txt：

fastapi==0.115.0
uvicorn[standard]==0.30.0
sqlalchemy==2.0.30
pydantic==2.7.0