Skip to content

示例:综合实战项目骨架 ​

第 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.pyDeclarativeBase 与全表共用的 created_at / updated_at
app/db/session.py连接池、会话工厂与 get_db——事务边界的唯一归属地
app/models/__init__.py把三个模型 import 进来,否则 --autogenerate 会生成删表迁移
app/models/post.pyposts 表:slug 唯一、tags 用 ARRAY、author 用 selectin 预加载
app/schemas/common.pyPage[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.ymldb(健康检查)→ 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 ,按下面的顺序点一遍:

  1. POST /api/v1/auth/register 注册一个用户
  2. POST /api/v1/auth/token 取 token,复制 access_token
  3. 点右上角 Authorize,填入用户名密码
  4. 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 端口

对应章节 ​


👉 返回课程目录

本文阅读--次|全站访问--次|访客--人