Python 全栈后端工程实践：FastAPI + SQLAlchemy 2.0 打造事项看板 API（pytest 全绿 + 真实压测）

Python 全栈后端工程实践FastAPI SQLAlchemy 2.0 打造事项看板 APIpytest 全绿 真实压测Python Web 后端怎么学才不虚一套能跑测试、能出压测数据的完整工程比十篇语法笔记有用。本文把一个 FastAPI SQLAlchemy 2.0 SQLite 的事项看板 API 从建模到压测完整走一遍pytest 14/14 全绿、20 线程并发写入零丢失、真实 uvicorn 压测四场景零错误。完整工程源码见文章末尾引用块。一、技术栈与工程结构python-fullstack-kit/ ├── src/app.py # 全部后端代码单文件注释完整 ├── tests/test_app.py # 14 个测试用例 ├── bench/bench.py # 真实 uvicorn 压测脚本 └── bench/results.json # 机器生成的压测结果选型理由FastAPI 的 Pydantic v2 做入口校验天然严格SQLAlchemy 2.0 的Mapped/mapped_column类型化写法告别遗留 Query APISQLite 零部署成本专注把工程范式讲清楚。二、数据建模SQLAlchemy 2.0 风格classTask(Base):__tablename__tasksid:Mapped[int]mapped_column(Integer,primary_keyTrue,autoincrementTrue)title:Mapped[str]mapped_column(String(120),indexTrue)status:Mapped[str]mapped_column(String(16),indexTrue,defaulttodo)priority:Mapped[int]mapped_column(Integer,default0)created_at:Mapped[datetime]mapped_column(DateTime,default...)入口校验交给 Pydantictitle限 1~120 字、status用 pattern 锁定 todo/doing/done、priority0~9越界直接 422。三、接口设计七个端点方法路径要点POST/api/tasks201 校验失败 422GET/api/tasks分页 status 过滤 priority 降序GET/api/tasks/{id}404 统一错误体{code, msg}PATCH/api/tasks/{id}exclude_unset局部更新未传字段不覆盖DELETE/api/tasks/{id}204/404GET/api/stats按状态分组统计GET/api/health健康检查一个容易踩的坑PATCH 必须用model_dump(exclude_unsetTrue)否则未传字段会被 None 覆盖——测试里专门有一条验证「改 status 不动 priority」。四、并发写入SQLite 单写者的正确姿势SQLite 同一时刻只允许一个写者多线程下直接写会报database is locked。工程里的做法连接串加check_same_threadFalse允许多线程复用连接池进程内threading.Lock把写路径串行化测试用 ThreadPoolExecutor 开20 线程并发创建 100 条断言 100 个 201 且统计计数一致——实测零丢失。五、真实压测数据32 并发 × 6 秒场景RPSp50p95p99错误POST 写入228.385.8ms105.8ms118.3ms0GET 列表308.763.4ms92.0ms117.7ms0GET 详情488.540.5ms46.4ms63.1ms0混合读写373.744.7ms154.8ms249.1ms0写入比读取慢是 SQLite 单写者的固有代价锁串行化数据如实呈现这个权衡——这也是什么时候该换 PostgreSQL 的判断依据。六、复现步骤pipinstallfastapi uvicorn sqlalchemy httpx pytest uvicorn src.app:app--port8000# 起服务文档在 /docspython-mpytest tests/-q# 14 passedpython bench/bench.py# 压测四场景配套完整工程已整理上传Python全栈开发资源包FastAPISQLAlchemy轻量后端工程pytest 14项全绿真实压测含全部源码、测试与压测结果