分层重构
本合集目录
本章目录
单册说明:本文件是卷 6 的第 4 章,可独立阅读。前置:第 3 章(sqlite3 与注入)。本章把卷 5 那个单文件后端拆成 router / service / storage 三层,并用同一组 curl 证明"接口行为一点没变"。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 6 · 数据与状态(第 4 / 8 章) |
| 前置章节 | 6.3 SQLite 实战与注入 |
| 本章产出 | 一棵完整目录树 · 三层职责清单 · 一份 11 条 curl 回归记录 |
| 对应代码 | app/main.py、app/routers/*.py、app/services/*.py、app/storage/*.py、app/deps.py、app/models.py |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能指着一个改动说出它该落在哪一层,并说出另外两层为什么不该碰它 |
6.4.1 一句话结论:分层的唯一目的是"改一处只动一层"
分层不是为了好看,是为了让同一个规则只写一遍。规则写五遍,就一定会漏一遍。
看一个真实后果。卷 5 的单文件里,"只能看自己的摘录"这件事写在五个地方:列表、详情、修改、删除、标签统计。某天加"删除"接口,作者照着"详情"抄,抄漏了 user_id:
con.execute("DELETE FROM notes WHERE id = ?", (note_id,))
不报错,不警告,返回 204。任何人只要知道 id,就能删掉别人的摘录。同一天写的"详情"接口是对的:
con.execute("SELECT ... FROM notes WHERE id = ? AND user_id = ?", (note_id, uid))
两个接口,一条规则,两种写法。 这不是粗心,是结构问题:当你把"归属"这件事交给每个 handler 自己记得,它迟早会被忘在某一个分支里。
分层的做法是:把"归属"写进 storage 层的每一条 SQL,让上层根本没有"不带 user_id 的查询"可用。规则从"要求每个人记得"变成"想违反都难"。
6.4.2 原理与方法
三层各自管什么
| 层 | 只做 | 明确禁止 | 违反后的症状 |
|---|---|---|---|
router(routers/) |
解析 HTTP:路径参数、查询参数、请求体、状态码、响应模型 | 写 SQL;写事务;做业务判断 | 换个前端就要改后端;同一业务在两处实现不一致 |
service(services/) |
业务规则:归属校验、事务边界、字段白名单、跨表流程 | 拼 SQL;碰 Request/Response |
规则散落,改一处漏一处(就是上面那个 204) |
storage(storage/) |
只做数据存取:SQL、行转字典、lastrowid |
判断"能不能做";抛 HTTP 错误 | 数据库细节往上渗透,换库要改全项目 |
调用方向是单向的:
HTTP 请求
▼
router 收参数、定状态码 routers/notes.py
▼
service 判归属、开事务 services/notes.py
▼
storage 发 SQL storage/notes.py
▼
SQLite
反过来不行:storage 不能 import service,service 不能 import router。这条规则的价值在于依赖是单向的,改下层不会引发上层连锁反应。
分层的收益,在"改需求"的那一刻才看得见:
| 需求变了 | 该改哪一层 | 实际动几个文件 |
|---|---|---|
| 摘录增加"收藏"字段 | storage(SQL)+ models(出入参)+ migration | 3 个,且都是加,不改逻辑 |
| 标题上限从 200 改到 120 | models | 1 个 |
| 搜索要支持"只在标题里搜" | service(条件拼装)+ storage(SQL) | 2 个 |
| 从 SQLite 换到 PostgreSQL | storage + db.py | 2 个,service 与 router 不动 |
| 404 要改成"返回空对象" | service + 统一错误处理 | 2 个,storage 不动 |
对照一下单文件时代:上面每一行都要在同一个 800 行文件里找五个地方,还要祈祷没有第六个。
依赖注入:连接从上面传下来
不要在每个函数里 connect(),也不要搞一个全局连接。两种做法的坏处:
| 做法 | 问题 |
|---|---|
每个函数自己 connect() |
一次请求开五个连接,事务跨不过去,忘了关就泄漏 |
| 全局一个连接 | 多线程共用,SQLite 连接默认不允许跨线程;一个请求的事务会影响另一个 |
FastAPI 的写法是一个"产出连接"的函数:
def get_db():
con = connect()
try:
yield con
finally:
con.close()
路由函数声明 con: sqlite3.Connection = Depends(get_db),框架负责在请求开始时调它、请求结束时执行 finally。一个请求一条连接,用完必关——这正是第 5 章事务能成立的前提:事务的"开始"和"结束"落在同一条连接上。
Depends 有个容易误解的点:同一次请求里多处 Depends(get_db),FastAPI 默认复用同一个返回值(依赖缓存),所以 router 和 current_user 拿到的是同一条连接。这一点在写测试时很有用,在生产里意味着"不要在依赖里改连接的全局状态"。
入参与出参:两个模型,不是同一个
入参 NoteIn |
出参 NoteOut |
|
|---|---|---|
| 从哪来 | 请求体 JSON | 数据库行 |
| 校验什么 | 长度、格式、必填 | 不校验,只保证形状 |
| 有哪些字段 | title, content, source_url, tags |
id, title, content, source_url, tags, created_at |
| 缺字段时 | 422,拒绝请求 | 由代码补默认值 |
| 谁会改它 | 前端需求变 | 表结构变 |
把两者合成一个类的代价很具体:id 和 created_at 出现在入参模型里,客户端就能试着传 id: 999;user_id 出现在出参里,等于把内部字段名暴露给前端,将来改名就是破坏性变更。入参是契约的"输入",出参是契约的"输出",它们的变更理由不同,就该是两个类。
目录结构
backend/
├─ app/
│ ├─ __init__.py
│ ├─ main.py # 建 app、挂中间件、注册异常处理、include_router
│ ├─ config.py # 路径、cookie 名、有效期,全部集中
│ ├─ db.py # connect / get_db / transaction / migrate
│ ├─ deps.py # current_user 依赖
│ ├─ errors.py # AppError / NotFound / Unauthorized / Conflict
│ ├─ models.py # Pydantic 入参与出参
│ ├─ security.py # scrypt 哈希、token 生成
│ ├─ migrations/
│ │ ├─ 001_init.sql
│ │ └─ 002_sessions.sql
│ ├─ routers/
│ │ ├─ notes.py
│ │ ├─ tags.py
│ │ └─ auth.py
│ ├─ services/
│ │ ├─ notes.py
│ │ └─ auth.py
│ └─ storage/
│ ├─ notes.py
│ └─ users.py
├─ data/dudao.db
├─ scripts/import_json.py
└─ requirements.txt
判断一个文件该放哪,只问一句:它里面出现的东西,换掉数据库之后还需不需要存在? 需要 → 上层;不需要 → storage。
有人会问:为什么不用 ORM,让框架自动生成 SQL?三个理由。一是这一卷的目标是让你看懂 SQL,ORM 会把 SQL 藏起来,出错时你只能猜;二是本项目的查询都很简单,五个表、十来个查询,手写比配模型短;三是 ORM 不消除分层,它只是把 storage 层换成了模型类,该想清楚的"归属条件在哪写"一样要想。等你把 SQL 写熟、项目大到"手写 JOIN 太累"时再上,那时你能判断它替你做了什么。
800 行怎么拆:按"动词"而不是按"文件长度"
不要按行号切("前 300 行一个文件"),那样切出来的是五个互不相干的碎片。按功能切,一次一条链路:
| 步 | 动作 | 完成标志 |
|---|---|---|
| 1 | 把 connect() 抽到 db.py,所有地方改调它 |
全项目只有一处 sqlite3.connect |
| 2 | 把 Pydantic 模型抽到 models.py |
路由函数签名里不再出现匿名 dict |
| 3 | 每条链路抽一个 storage 函数,只搬 SQL,不改逻辑 | 原文件里的 SQL 全部消失 |
| 4 | 每条链路抽一个 service 函数,把"判断 + 事务"搬进来 | storage 里不再出现 raise HTTPException |
| 5 | 路由只剩参数声明和返回值 | 单个 handler 不超过 15 行 |
| 6 | 按资源拆 router 文件,main.py 只负责组装 |
main.py 不超过 60 行 |
每做完一步就跑一遍回归(本章末尾那 11 条),确认行为没变。不要六步一起做完再测——出了问题你不知道是哪一步引入的。
6.4.3 动手:拆完的三层长什么样
第 1 层:router 只谈 HTTP
# app/routers/notes.py
@router.get("/notes", response_model=NoteList)
def list_notes(
tag: str | None = None,
q: str | None = None,
limit: int = Query(default=20, ge=1, le=100),
offset: int = Query(default=0, ge=0),
con: sqlite3.Connection = Depends(get_db),
user: dict = Depends(current_user),
):
items, total = service.list_notes(con, user["id"], tag, q, limit, offset)
return {"items": items, "total": total}
@router.delete("/notes/{note_id}", status_code=204)
def delete_note(note_id: int, con=Depends(get_db), user=Depends(current_user)):
service.delete_note(con, user["id"], note_id)
return Response(status_code=204)
整个文件没有一行 SQL,也没有一次 if 不是你的。它只做三件事:声明参数、调 service、定状态码。
第 2 层:service 只谈规则
# app/services/notes.py
def get_note(con, user_id: int, note_id: int) -> dict:
note = store.get_note(con, user_id, note_id)
if note is None:
# 不区分"不存在"和"不是你的"
raise NotFound("摘录不存在")
return note
def create_note(con, user_id: int, data) -> dict:
with transaction(con):
note_id = store.insert_note(con, user_id, data.title, data.content, data.source_url)
store.set_tags(con, user_id, note_id, data.tags)
return store.get_note(con, user_id, note_id)
两个细节值得停一下。第一,get_note 把"查不到"翻译成 NotFound,于是修改、删除都能复用它,规则只有一份。第二,create_note 的"插摘录 + 挂标签"包在一个事务里——插完摘录、挂标签时崩了,会一起回滚,不会留下一条没有标签的半成品(第 5 章细讲)。
第 3 层:storage 只谈 SQL
# app/storage/notes.py
def get_note(con, user_id: int, note_id: int) -> dict | None:
row = con.execute(
"SELECT n.id, n.title, n.content, n.source_url, n.created_at "
"FROM notes n WHERE n.id = ? AND n.user_id = ?",
(note_id, user_id),
).fetchone()
if row is None:
return None
return _rows_with_tags(con, [row])[0]
注意 AND n.user_id = ? 是这条 SQL 的一部分,不是上层补的判断。这意味着:任何人想"只按 id 查询",得先绕过这个函数自己写 SQL——成本高到不会顺手发生。防越权最有效的办法不是加检查,是让危险写法不存在。
组装:main.py 只做四件事
app = FastAPI(title="读到 API", version="1.0.0")
app.add_middleware(CORSMiddleware, ...) # 1 跨源
app.add_exception_handler(AppError, handle_app_error) # 2 统一错误
app.include_router(auth.router) # 3 挂路由
app.include_router(notes.router)
app.include_router(tags.router)
自己定义的 AppError 之所以要分 NotFound / Unauthorized / Conflict 三个子类,是为了让 service 能表达"错在哪一类",而不用知道状态码。NotFound 内在携带 404,Conflict 携带 409——状态码是"这一类错误"的属性,不是每个调用点的自由选择,否则同一个"邮箱已注册"在注册接口是 409、在登录接口变成 400,前端又要写分支。
回归:同一组命令,行为必须一致
重构有个铁律:先建分支,按步提交。六步六次提交,任何一步回归失败就 git checkout 回上一步,而不是在烂摊子上继续改。这也是卷 3 那些 Git 命令第一次真正派上用场的地方——重构是"没有新功能、但随时可能改坏"的典型场景。
拆之前跑一遍记录结果,拆之后再跑一遍对比。这 11 条就是本章的验收脚本(Windows 的 Git Bash 里直接跑,$B 换成你的地址):
| # | 命令 | 期望 | 实测 |
|---|---|---|---|
| 1 | 注册 [email protected] |
201 | 201 |
| 2 | 登录并 -c ck.txt 存 cookie |
200 | 200 |
| 3 | 不带 cookie 拉列表 | 401 | 401 |
| 4 | 带 cookie 新建一条 | 201 + 完整 JSON | 201 |
| 5 | 拉列表 | total: 1 |
total: 1 |
| 6 | 拉详情 /api/notes/1 |
200 | 200 |
| 7 | PATCH 改标题 |
200,标题已变 | 200 |
| 8 | 查 /api/notes/999 |
404 | 404 |
| 9 | DELETE /api/notes/1 |
204 | 204 |
| 10 | 再查 /api/notes/1 |
404 | 404 |
| 11 | 建空标题 | 422 | 422 |
第 4 条的实际响应:
{"id":1,"title":"事务","content":"BEGIN IMMEDIATE","source_url":null,
"tags":["sqlite"],"created_at":"2026-11-16T18:28:26Z"}
字段名、顺序、null 的出现位置都和卷 5 一样。这就是"接口行为不变"的可验证定义:不是"我觉得没变",是同一组请求返回同一组响应。
6.4.4 三个坑
坑一:service 里又写起了 SQL
症状:重构完很满意,三个月后要加一个"按标签过滤",打开 services/notes.py 发现里面躺着三条 con.execute("SELECT ...")。换库时你改了 storage/,一测全是 500。
成因:写 SQL 是"最快把功能做出来"的路径,尤其在 service 里已经拿到了 con。分层不是编译器强制的,它靠约定。
修法:定一条可检查的机械规则——services/ 目录里不许出现 SELECT、INSERT、UPDATE、DELETE 这四个词。用 grep -rn "SELECT\|INSERT" app/services/ 就能查。规则越机械,越容易守住。
坑二:在 router 里自己 connect(),事务就散了
症状:service 里明明包了事务,实际却没回滚;或者压测时出现 sqlite3.ProgrammingError: SQLite objects created in a thread can only be used in that same thread。
成因:router 里写了 con = connect(),service 内部又 connect() 了一次。两条连接各自开事务,一个提交了、另一个回滚了,看起来"有时候生效有时候不生效"。线程报错则是把一个连接传给了另一个线程。
修法:连接只从 Depends(get_db) 来,一层层往下传,谁都不许自己开。要验证也简单:全项目 grep -rn "connect(" app/ 应该只命中 db.py。
坑三:422 走的还是 FastAPI 默认形状
症状:前端统一按 error.code 处理错误,401、404、409 都对,唯独表单校验失败时 error 是 undefined,页面弹出一句"未知错误"。
成因:AppError 的处理器只接住了你自己抛的错。Pydantic 校验失败抛的是 RequestValidationError,FastAPI 有它自己的默认处理器,返回的是 {"detail": [...]},形状完全不同:
{"detail":[{"type":"string_too_short","loc":["body","title"],
"msg":"String should have at least 1 character","input":""}]}
修法:给 RequestValidationError 也注册一个处理器,把它翻译成同一个形状:
@app.exception_handler(RequestValidationError)
def handle_validation(request: Request, exc: RequestValidationError):
first = exc.errors()[0]
field = ".".join(str(x) for x in first["loc"][1:]) or "body"
return JSONResponse(status_code=422, content={
"error": {"code": "validation_error", "message": f"{field}: {first['msg']}"}})
改完第 11 条回归的响应变成:
{"error":{"code":"validation_error","message":"title: String should have at least 1 character"}}
契约的价值在于"没有例外"。 只要有一条路径不遵守,前端就得写两套解析。
本章验收
- 全项目
grep -rn "sqlite3.connect" app/只命中db.py -
grep -rn "SELECT" app/services/ app/routers/无结果 - 11 条 curl 回归全部通过,响应体与拆之前一致
- 能说出
NoteIn与NoteOut各缺一个字段时会怎样 -
main.py不超过 60 行,单个 handler 不超过 15 行
自测
Q1:为什么"归属校验"要写进 storage 的 SQL,而不是在 service 里 if note["user_id"] != user_id: raise?
看答案
两种写法在"这一个接口"上都对。差别在复制成本:service 里的判断需要每个接口都记得写一次,新增接口时最容易漏,而漏了不报错。写进 SQL 之后,危险写法(不带 user_id 的查询)在代码里根本不存在,新接口想复用只能调到安全的那一个。另外,先查出来再判断还有个隐患——数据已经读到内存里了,一旦后面有人加日志、加缓存,别人的内容就跟着流出去了。Q2:为什么不让 storage 层直接抛 HTTPException(404)?
看答案
因为 storage 是"数据存取",它不该知道有 HTTP 这回事。一旦它 import 了 `fastapi`,你就没法在脚本、定时任务、测试里复用它——那些场景没有 HTTP 响应可返回。正确做法是 storage 返回 `None` 表示"没有这条记录",由 service 翻译成 `NotFound`,再由统一处理器变成 404。分层的第一条纪律就是"下层不知道上层的存在"。Q3:重构时为什么要"每步一测",而不是全部拆完再测?
看答案
因为回归失败时,你需要知道是哪一步引入的。六步一起做完,失败点可能在任何一层,排查范围是全部代码;每步都跑一遍同一组请求,失败就锁定在刚才那一步的改动里。这也是为什么回归要用"固定的 11 条命令"而不是"随便点两下"——命令是可重复的,点击不是。下一步
结构清爽了,接下来处理"一组操作必须一起成功"这件事。下一章用一次会中途失败的转账演示回滚,再解决 database is locked 和"表结构要改怎么办"。