跳到正文
零到全栈 · 卷 6 · 数据与状态

分层重构

本合集目录
本章目录

单册说明:本文件是卷 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 和"表结构要改怎么办"。

→ 卷6-05-事务并发与迁移.md