type
Post
status
Published
date
Apr 30, 2026
slug
fastapi-booking-app-claude-code
summary
用 Claude Code 从零搭建 FastAPI 约课平台后端，8 周完成全部接口与 110 个单元测试，记录架构决策、关键踩坑与 AI 协作的真实体验。
tags
开发
AI
docker
category
技术分享
icon
password
如果让 AI 当你的结对程序员，8 周能搭出什么？
这篇文章记录了我用 Claude Code 从零完成一个健身约课平台后端的全过程。项目涵盖微信小程序登录、课程预约、签到、会员卡、异步导出、数据报表等核心模块，最终交付 142 个文件、110 个单元测试全部通过、Alembic 迁移一键建库。
不是炫技，是真实的协作记录——包括走过的弯路和踩过的坑。
📝 主旨内容
项目架构与技术选型
选型越保守，AI 协作越顺畅。
技术栈刻意选用主流、文档齐全的组合：
层次 | 选型 |
Web 框架 | FastAPI + Pydantic v2 |
ORM | SQLAlchemy 2.0（ORM 模式，非 Core） |
数据库 | MySQL 8.0（生产）/ SQLite 内存（测试） |
缓存 & 锁 | Redis 7 |
异步任务 | Celery + Redis Broker |
迁移 | Alembic |
包管理 | uv（Python 3.12） |
API 按调用方分为四个路由域：
统一响应格式
R.ok(data=...) / R.fail(code=..., message=...)，所有接口 HTTP 状态码固定 200，业务错误通过 code 字段区分。关键踩坑：三条必须记住的规则
这三条坑加在一起，消耗了差不多两个下午。
坑一：MySQL CURRENT_TIMESTAMP 的正确写法
Alembic 自动生成的迁移对
server_default 处理不一致：迁移跑到一半失败、部分表已建、重新运行又报"表已存在"——最后只能 DROP DATABASE 重来。
坑二：测试里不能用 timezone-aware datetime
项目里封装了一个
now_cst() 返回带时区的北京时间，但 SQLAlchemy 存进 SQLite 的是 naive datetime。比较时：坑三：Page 模型的字段名
自定义的分页容器字段是
list，不是 items：这个在写了十几个测试之后才统一，改起来很机械但没有捷径。
Docker 本地开发环境搭建
端口冲突是最常见的"本地特有 bug"。
本机已有其他 Docker 容器占用 3306（MySQL）和 6379（Redis），所以
docker-compose.dev.yml 做了端口映射：对应
.env 同步修改：启动后三步完成初始化：
验证 API 正常：
Week 1–8 交付物一览
8 周累计完成的模块：
周次 | 模块 |
1–2 | 基础设施 / Auth / Store |
3–4 | Staff / Course / Schedule |
5–6 | CardProduct / Booking / 签到 |
7 | 会员卡服务 / Celery 异步任务 |
8 | 学员管理 / 签到记录 / 导出 / 报表 |
最终代码量：142 个文件，13,370 行，110 个单元测试（SQLite 内存，全部通过）。
🤗 总结归纳
用 AI 结对编程最大的收获不是"写得更快"，而是决策更快——遇到方案选择时不用自己查文档对比，直接给出带理由的推荐，然后开始写。踩坑的代价没有减少，但复盘和修复的速度提高了很多。前端（微信小程序 + 管理后台）还没开始，这套后端就是它们的地基——接口已全部就绪，随时可以对接。
📎 参考资料
你在用 AI 辅助开发时，最难处理的部分是什么？是测试、是架构决策、还是 debug？欢迎在评论区聊聊你的经历。
