示例:综合实战项目骨架
第 18 章那个博客 API 的骨架。目录、配置、数据库、迁移、Docker、测试脚手架都已就位,业务代码留了
TODO标注——照着 README 跑一遍,再按验收清单补齐,就是一次完整的从零到上线练习。
学习目标
- 能独立把一个空目录搭成可运行、可测试、可容器化的 FastAPI 工程
- 理解每个文件为什么存在,而不是照着抄
- 会用 Alembic 管理表结构、用 docker compose 一条命令起全栈
- 能用验收清单自查项目完成度
完整目录树
text
capstone/
├── README.md # 本文件:启动步骤与验收清单
├── pyproject.toml # 依赖与工具配置(uv / ruff / pytest)
├── uv.lock # 锁定依赖版本,保证 CI 与本地一致
├── .env.example # 全部环境变量的样例(含注释)
├── .gitignore # 忽略 .env / __pycache__ / .venv
├── alembic.ini # Alembic 入口配置(sqlalchemy.url 留空,由 env.py 注入)
├── Dockerfile # 多阶段构建:装依赖 → 拷代码 → fastapi run
├── docker-compose.yml # db + migrate + api 三个服务
├── migrations/
│ ├── env.py # 异步迁移环境;import 全部模型并指向 Base.metadata
│ ├── script.py.mako # 迁移文件模板
│ └── versions/
│ └── 0001_init.py # 首个迁移:users / posts / comments
├── app/
│ ├── __init__.py
│ ├── main.py # create_app():lifespan、CORS、异常处理器、include_router
│ ├── errors.py # 领域异常 → 404/403/409/422 的唯一映射点
│ ├── core/
│ │ ├── __init__.py
│ │ ├── config.py # Settings(pydantic-settings)+ get_settings()
│ │ └── security.py # pwdlib Argon2 哈希 + PyJWT 签发/校验
│ ├── db/
│ │ ├── __init__.py
│ │ ├── base.py # DeclarativeBase + TimestampMixin
│ │ └── session.py # async engine、async_sessionmaker、get_db(事务边界)
│ ├── models/
│ │ ├── __init__.py # 显式 import 全部模型,供 Alembic 扫描
│ │ ├── user.py # User:邮箱/用户名唯一、role、is_active
│ │ ├── post.py # Post:slug 唯一、ARRAY 标签、published、author_id
│ │ └── comment.py # Comment:post_id + author_id,级联删除
│ ├── schemas/
│ │ ├── __init__.py
│ │ ├── common.py # Page[T] 通用分页、ErrorOut
│ │ ├── user.py # UserCreate / UserOut / Token
│ │ ├── post.py # PostCreate / PostUpdate / PostOut
│ │ └── comment.py # CommentCreate / CommentOut
│ ├── repositories/
│ │ ├── __init__.py
│ │ ├── post.py # PostRepository:分页列表 + count、取、建、改、删
│ │ └── comment.py # CommentRepository
│ ├── services/
│ │ ├── __init__.py
│ │ ├── exceptions.py # DomainError / NotFound / PermissionDenied / Conflict
│ │ ├── user.py # 注册、认证(哈希校验)
│ │ ├── post.py # PostService:标签规范化、分页校验、属主校验
│ │ └── comment.py # CommentService
│ └── api/
│ ├── __init__.py
│ ├── deps.py # SessionDep / CurrentUser / require_role / *ServiceDep
│ └── v1/
│ ├── __init__.py
│ ├── auth.py # POST /auth/register · POST /auth/token
│ ├── users.py # GET/PATCH /users/me
│ ├── posts.py # /posts 的 CRUD + 分页 + 标签过滤
│ └── comments.py # /posts/{post_id}/comments
└── tests/
├── conftest.py # 测试库引擎、建表、dependency_overrides、AsyncClient
├── test_auth.py # 注册 / 登录 / 401
└── test_posts.py # 端到端主流程 + 403 + 409 + 分页每个文件的职责(一句话)
| 文件 | 一句话职责 |
|---|---|
app/main.py | 只做装配:create_app() 里挂 CORS、异常处理器、四个 router |
app/errors.py | 把领域异常翻译成 HTTP 状态码,全项目唯一的映射点 |
app/core/config.py | 环境变量 → Settings 对象,get_settings() 带 lru_cache |
app/core/security.py | 密码只进不出(哈希/校验),JWT 只签不猜(显式限定算法) |
app/db/base.py | DeclarativeBase 与全表共用的 created_at / updated_at |
app/db/session.py | 连接池、会话工厂与 get_db——事务边界的唯一归属地 |
app/models/__init__.py | 把三个模型 import 进来,否则 --autogenerate 会生成删表迁移 |
app/models/post.py | posts 表:slug 唯一、tags 用 ARRAY、author 用 selectin 预加载 |
app/schemas/common.py | Page[T]:所有列表接口统一的返回形状 |
app/schemas/post.py | 输入模型与输出模型分离,hashed_password 在输出侧根本不存在 |
app/repositories/post.py | 只写 SQL:select()、count()、flush(),不做业务判断 |
app/services/exceptions.py | 领域异常族,让 Service 层不依赖 fastapi |
app/services/post.py | 业务规则:标签规范化、分页边界、属主校验、slug 冲突 |
app/api/deps.py | 依赖中心:会话、当前用户、角色守卫、各 Service 的注入工厂 |
app/api/v1/posts.py | 只关心 HTTP:查询参数、状态码、response_model |
tests/conftest.py | 独立测试库 + 覆盖 get_db + ASGITransport 直连应用 |
Dockerfile | 先拷依赖清单再拷代码,让镜像层缓存生效 |
docker-compose.yml | db(健康检查)→ migrate(跑完即退)→ api 的确定启动顺序 |
.env.example 说明
ini
# ---- 应用 ----
APP_NAME=Blog API
DEBUG=true # true 时 SQLAlchemy echo=True,会打印所有 SQL
API_V1_PREFIX=/api/v1
# ---- 安全 ----
# 必须 ≥ 32 字符;生成方式:python -c "import secrets;print(secrets.token_urlsafe(48))"
SECRET_KEY=change-me-to-a-random-32-bytes-string
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
# ---- 数据库 ----
# docker compose 里要把 POSTGRES_HOST 改成 db
POSTGRES_USER=blog
POSTGRES_PASSWORD=blog
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=blog
# ---- CORS ----
# Settings 里是 list[str],所以这里必须写成 JSON 数组
CORS_ORIGINS=["http://localhost:5173"]| 变量 | 注意点 |
|---|---|
SECRET_KEY | 有 min_length=32 校验,配错会在启动时直接失败,而不是运行到登录才炸 |
CORS_ORIGINS | 是列表类型,写成 http://a,http://b 会解析失败,必须用 JSON 数组 |
POSTGRES_HOST | 本地跑用 localhost,容器内跑必须是服务名 db |
DEBUG | 生产必须 false,否则 SQL 与堆栈会进日志 |
本地启动步骤
bash
cd examples/capstone
# 1. 配置
cp .env.example .env
python -c "import secrets;print(secrets.token_urlsafe(48))" # 把结果填进 SECRET_KEY
# 2. 只起数据库
docker compose up -d db
# 3. 装依赖
uv sync
# 4. 建表
uv run alembic upgrade head
uv run alembic current # 确认已到 head
uv run alembic downgrade -1 # 可选:验证迁移能回滚,再 upgrade head 回来
# 5. 启动
uv run fastapi dev app/main.py打开 http://127.0.0.1:8000/docs ,按下面的顺序点一遍:
POST /api/v1/auth/register注册一个用户POST /api/v1/auth/token取 token,复制access_token- 点右上角 Authorize,填入用户名密码
POST /api/v1/posts发文,GET /api/v1/posts查列表
用 docker compose 启动全栈
bash
export SECRET_KEY=$(python -c "import secrets;print(secrets.token_urlsafe(48))")
docker compose up --build启动顺序由 compose 保证:db 通过 healthcheck 之后 migrate 才运行,migrate 以 service_completed_successfully 退出后 api 才启动。API 暴露在 http://127.0.0.1:8000 。
bash
docker compose logs -f api # 看日志
docker compose down # 停止(保留数据卷)
docker compose down -v # 停止并清空数据库运行测试
bash
# 需要一个独立的测试库
createdb blog_test # 或 docker compose exec db createdb -U blog blog_test
export TEST_DATABASE_URL="postgresql+asyncpg://blog:blog@localhost:5432/blog_test"
uv run pytest -q
uv run pytest -q --cov=app --cov-report=term-missing
uv run pytest tests/test_posts.py::test_full_post_lifecycle -vv # 单跑一条
uv run pytest --lf # 只跑上次失败的测试库用 PostgreSQL 而不是 SQLite:tags 是 ARRAY 类型 SQLite 不认,ON DELETE CASCADE 行为也有差异。测试库与生产库同款能省掉一整类"测试过了线上挂"的问题。
验收清单摘要
完整版见 第 18 章。这里是最关键的 12 条:
| # | 检查项 | 达标标准 |
|---|---|---|
| 1 | 目录分层 | 各层齐备,services/ 与 repositories/ 中不出现 import fastapi |
| 2 | 配置外置 | 无硬编码连接串与密钥,.env.example 可直接照抄使用 |
| 3 | 迁移双向 | upgrade head 建表、downgrade base 回滚,均无报错 |
| 4 | 密码安全 | 库中只存 Argon2 哈希;任何响应体都不含 password / hashed_password |
| 5 | 认证链路 | 注册 201、取 token 200、带 token 访问受保护端点 200 |
| 6 | 鉴权语义 | 无 token 401,越权改删 403,管理员可删任意文章 |
| 7 | 状态码 | 创建 201、删除 204、其余 200 |
| 8 | 分页 | page / size 有边界校验;total 与过滤条件一致;排序稳定 |
| 9 | 过滤 | ?tag= 与 ?author_id= 生效,标签经小写去重规范化 |
| 10 | 错误结构 | 全部错误形如 {"detail": ..., "code": ...},422 保留字段路径 |
| 11 | 测试 | 端到端用例覆盖注册/登录/发文/越权/删除/分页,行覆盖 ≥ 80% |
| 12 | 一键起栈 | docker compose up --build 自动完成迁移并暴露 8000 端口 |
对应章节
- 本项目逐节讲解 → 第 18 章:综合实战 —— 构建完整 REST API
- 分层结构设计 → 第 11 章:分层架构与 CRUD 工程化
- 认证与权限 → 第 12 章:认证与授权(OAuth2 + JWT)
- 测试体系 → 第 16 章:测试体系(pytest + httpx)
- 部署与 Docker → 第 17 章:部署与生产实践
- 写完后的规范自查 → 第 19 章:最佳实践与速查表
👉 返回课程目录