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

数据存在哪儿

本合集目录
本章目录

单册说明:本文件是卷 6 的第 1 章,可独立阅读。前置:卷 5 第 8 章(联调收口)。本章不教语法,只回答一个问题——你的数据放在哪,那个位置还能撑多久,什么时候必须换。最后动手把卷 5 的 JSON 存储换成 SQLite。

项 内容
所属卷 卷 6 · 数据与状态(第 1 / 8 章)
前置章节 5.8 联调收口
本章产出 一张存储选型对照表 · 一份"该换库了"的判断清单 · 一次 JSON → SQLite 的迁移
对应代码 app/db.py、app/migrations/001_init.sql、scripts/import_json.py
配图 无(后续统一制图)
读完的判定 能说出你现在的存储由谁负责并发、持久化、备份,并指出哪一项它不管

6.1.1 一句话结论:存储的差别不在"能不能存",在"谁替你管三件事"

内存、JSON 文件、SQLite、服务式数据库,四个东西都能"存住数据"。真正的差别是三件事分别由谁负责:并发(两个人同时写会不会互相覆盖)、持久化(断电后还在不在)、备份(坏了能不能回到昨天)。

先说一个真实场景。你用卷 5 的 JSON 存储跑了三天,攒了四十多条摘录。第四天早上打开页面:

500 Internal Server Error

后端日志里是这一行:

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

data/notes.json 变成了 0 字节。原因不复杂:保存时用的是"打开文件 → 清空 → 重新写"这套流程,写到一半进程被 Ctrl+C 或系统更新重启打断,文件就停在"已清空、还没写回"的状态。.bak 你没做,四十条摘录全没了。

这不是运气差,是这个存储方案从来没有承诺过"写一半崩了怎么办"。选存储,本质是选"哪些麻烦交给别人"。

6.1.2 原理与方法

四层对照:谁在管什么

内存(dict / list) JSON 文件 SQLite 服务式数据库
谁管并发 没有人,靠 Python 的 GIL 侥幸活着 没有人,后写的覆盖先写的 数据库自己,用库级写锁 数据库自己,行级锁 + MVCC
谁管持久化 没有人,进程一停就没 你自己,open + write + flush 数据库自己,事务提交才落盘 数据库自己,还有副本
谁管备份 没有人 你自己 cp,且要停写 你发一条命令,它保证一致 它自己定时做,还能回滚到某个时刻
能不能按条件查 要自己写循环筛 全读进内存再筛 SQL,可以走索引 SQL
两人同时写 一个覆盖一个 文件直接损坏或丢更新 排队,第二个等锁 排队,粒度更细
十万条数据 内存吃紧 每次请求全量解析,几十毫秒起 毫秒级,走索引更快 毫秒级
典型失效 重启即失 半截文件、编码错乱 锁等待、单机上限 网络、连接池、账单

这张表只说明一件事:你少管的每一件事,都要有人管;没人管,就在最坏的时刻爆发。

什么时候该换:五条判断

不要因为"SQLite 听起来低级"就换,也不要因为"JSON 还能跑"就不换。逐条问自己:

# 问题 答"是"意味着
1 数据丢了,用户会不会真的生气? 需要事务与备份,JSON 出局
2 有没有"两条记录必须一起改"的操作? 需要事务,文件存储做不到
3 数据量会不会超过"一次全读进内存"的舒适区(约几万条)? 需要索引与分页查询
4 会不会有第二个写者(另一个进程、另一个部署实例)? 需要真正的并发控制
5 会不会有人问"上个月这条记录是什么样"? 需要备份与时间点恢复

前三条任意一条答"是",就该从 JSON 换到 SQLite。第 4、5 条答"是",SQLite 也要打问号。

SQLite 的适用与不适用

SQLite 不是"玩具数据库",它是嵌入式数据库:没有独立进程,你的程序直接读写一个文件。手机、浏览器、飞机娱乐系统里都有它。

场景 合适吗 原因
个人站点、单机部署、读多写少 很合适 零运维,备份就是一个文件
一次请求写几条、并发几十 合适 写锁是毫秒级持有,排队感知不到
数据分析、本地脚本、测试 很合适 不用起服务,sqlite3 标准库直接开
多台机器同时写同一个库 不行 锁依赖本地文件系统,网络盘上不可靠
每秒几百次写 不合适 全局只有一个写者,写会排队
需要按用户分配数据库权限 不合适 库是文件,权限就是文件权限

所以本书的部署形态是"一台服务器 + 一个进程",SQLite 正好。等到需要多机,换的是数据库,不是"SQLite 不好"。

那什么时候轮得到服务式数据库(PostgreSQL、MySQL 这类要单独起进程、单独连端口的)?三个信号:写入量到了每秒几百次以上;需要多台机器同时写同一份数据;需要按表、按列授权给不同的人。除此之外,它给你的是更多能力,也给你更多要维护的东西:连接池、用户与权限、版本升级、备份策略、监控。单机项目上它不解决任何你现有的问题,只是把"运维一个文件"换成"运维一个服务"。

迁移成本为什么主要不在 SQL

很多人以为换库的难点是"SQL 方言不一样"。实际做一次就知道,SQL 那部分占不到两成:

环节 工作量感受 具体是什么
SQL 方言 小 AUTOINCREMENT、strftime 这类函数各库写法不同
连接管理 中 文件存储没有"连接"概念,改成库之后要决定何时开、何时关、谁来关
事务边界 大 原来的代码是"一行行写文件",现在要回答"哪几条必须一起成功"
查询方式 大 原来是"全读出来再 for 循环筛",现在要写成 WHERE,还要考虑分页
数据迁移 小 一次性脚本,跑完就删
并发假设 中 原来假设"只有一个请求在写",现在要假设"随时可能有第二个"

结论:如果你的代码里到处是 open() 和 json.dump(),换库等于重写业务逻辑。 这正是第 4 章要分层的理由——把这些"到处"收进一个 storage 层,下次换库才只改一层。

6.1.3 动手:把 JSON 存储改成 sqlite3,先能读写

目标不大:能建表、能插入、能按用户列出来。接口层不动。

第一步:建表语句单独放一个文件

-- app/migrations/001_init.sql
CREATE TABLE users (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    email         TEXT    NOT NULL UNIQUE,
    password_hash TEXT    NOT NULL,
    created_at    TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
);

CREATE TABLE notes (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id    INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title      TEXT    NOT NULL,
    content    TEXT    NOT NULL,
    source_url TEXT,
    created_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
);

这两个表本章够用。tags 与 note_tags 第 2 章再加。

时间字段为什么用 TEXT 而不是 DATETIME:SQLite 没有真正的日期类型,存成 2026-11-17T09:12:03Z 这种固定格式的字符串,排序就是字典序,跨语言也不会解析失败。

第二步:一个文件管住所有连接

# app/db.py(本章版本,第 5 章再补事务与迁移)
import sqlite3
from pathlib import Path

DB_PATH = Path(__file__).resolve().parent.parent / "data" / "dudao.db"


def connect() -> sqlite3.Connection:
    con = sqlite3.connect(
        DB_PATH,
        timeout=5.0,            # 等锁最多 5 秒
        isolation_level=None,   # 关掉隐式事务,后面自己发 BEGIN
    )
    con.row_factory = sqlite3.Row
    con.execute("PRAGMA foreign_keys = ON")
    con.execute("PRAGMA journal_mode = WAL")
    return con

三个参数各有原因,第 3、5 章会逐个拆开讲。现在只需要记住:整个项目里只有这个文件出现 sqlite3.connect。

第三步:读写各一个函数

# 本章先放在 db.py 末尾,第 4 章会搬到 storage/notes.py
def list_notes(con, user_id: int) -> list[dict]:
    rows = con.execute(
        "SELECT id, title, content, source_url, created_at "
        "FROM notes WHERE user_id = ? ORDER BY id DESC",
        (user_id,),
    ).fetchall()
    return [dict(r) for r in rows]


def insert_note(con, user_id: int, title: str, content: str, source_url: str | None) -> int:
    cur = con.execute(
        "INSERT INTO notes(user_id, title, content, source_url) VALUES (?,?,?,?)",
        (user_id, title, content, source_url),
    )
    con.commit()
    return cur.lastrowid

注意 ? 和后面的元组:值永远走参数,不拼字符串。这一条在第 3 章会用一个"删库现场"证明它有多重要。

第四步:把老数据搬进来

# scripts/import_json.py(节选)
raw = json.loads(Path("data/notes.json").read_text(encoding="utf-8"))
items = raw["notes"] if isinstance(raw, dict) else raw
owner = con.execute("SELECT id FROM users WHERE email = ?", (OWNER_EMAIL,)).fetchone()
for item in items:
    note_id = store.insert_note(con, owner["id"], item["title"], item["content"], item.get("source_url"))
    store.set_tags(con, owner["id"], note_id, item.get("tags", []))

真实跑一次的输出:

导入 3 条,该账号现在共 3 条
(1, 1, 'SQLite 的事务', 1)
(2, 1, 'Python 的 with', 1)
(3, 1, '读书笔记', 2)

最后一行是 LEFT JOIN note_tags 数出来的标签个数,证明多对多的关系也搬过来了。

迁移的铁律:旧文件不要删。改名成 notes.json.bak 放一周,确认线上数据对得上再删。迁移脚本跑第二遍会插重复数据,所以它只能跑一次——要么加个"已导入"标记,要么跑完就把脚本从流水线里摘掉。

第五步:验证"重启后还在"

不重启验证等于没验证。内存存储在同一个进程里也"读得到"。所以要做的动作是:

  1. Ctrl+C 停掉服务,再 uvicorn app.main:app 起来;
  2. 刷新列表页,条数不变;
  3. 换一个终端,确认文件真的在磁盘上:
python -m sqlite3 data/dudao.db "SELECT COUNT(*) FROM notes"

Windows 上没有 sqlite3 命令也能用这条(python -m sqlite3 是标准库自带的极简命令行)。三行都对上,才叫"换成功了"。第 3 章会把这条命令的用法讲全。

6.1.4 三个坑

坑一:数据库文件"自己变空了",其实是你读错了文件

症状:迁移明明成功,重启服务后列表全空。data/ 下出现两个 dudao.db,一个 60KB 一个有内容,另一个 0 字节。

成因:连接用的是相对路径 sqlite3.connect("data/dudao.db")。相对路径相对于进程的当前工作目录。你在 backend/ 下启动是 backend/data/dudao.db,在仓库根目录用 uvicorn backend.app.main:app 启动就变成 ./data/dudao.db——新目录、新空库,SQLite 会很乐意帮你建一个。

修法:路径一律由 Path(__file__).resolve().parent 推出来,写成绝对路径。这也是 db.py 里那行的意义:配置的基准是文件位置,不是你在哪儿敲命令。

坑二:插入了,但另一个连接看不到

症状:脚本里 INSERT 成功,SELECT 也查得到;用另一个终端打开数据库,一条都没有。进程退出后再看,数据又没了。

成因:Python 的 sqlite3 默认 isolation_level="",会替你隐式开事务,close() 遇到未提交的事务是回滚而不是提交。少写一句 commit(),数据就停在事务里等着被丢弃。

修法:要么显式 con.commit(),要么用第 5 章的 with transaction(con)。本书统一选后者:把"提交"写成一个只能用对的形状,而不是靠每次记得。

坑三:把库文件放进同步盘/网络盘,锁开始随机失灵

症状:本地一切正常,部署到挂载的网络盘(或某网盘同步目录)后,偶发 sqlite3.OperationalError: database is locked,重试又好,过一会儿再犯。

成因:SQLite 的锁依赖操作系统的文件锁语义。网络文件系统(NFS、SMB)对 fcntl 锁的实现不完整,两个客户端可能都以为自己拿到了锁。SQLite 官方文档对此的措辞是"不要这么做"。

修法:库文件放本地磁盘。需要多机共享数据,答案是换成服务式数据库,不是"把 SQLite 放网上"。备份文件可以同步,正在使用的库文件不行。

本章验收

  • 能画出四种存储在"并发 / 持久化 / 备份"上的责任划分
  • 能用五条判断说出自己项目现在该不该换库,并给出理由
  • data/ 下只有一个 dudao.db,且服务重启后数据还在
  • 老 JSON 的数据全部导入,条数与标签数对得上
  • 能在代码里指出"哪一行决定了数据库文件的位置"

自测

Q1:为什么"用 json.dump 保存"会在断电时把整个文件弄坏,而 SQLite 不会?

看答案 `json.dump` 的写法通常是先截断文件再写入,写入过程没有任何保护:断电时文件可能停在"已清空、写了一半"的中间态,而且旧内容已经被覆盖,回不去。SQLite 修改数据时先写日志(WAL 或 rollback journal),提交那一刻才把改动落到主文件;中途崩溃,下次打开会自动用日志回滚到"上一次完整提交"的状态。它保证的不是"不丢最后一次写",而是"不会留下一个自相矛盾的文件"。

Q2:一个人用的小站,一天几十次写入,用 SQLite 有什么风险?

看答案 几乎没有风险,这个量级 SQLite 完全够用。要注意的是三件事:库文件必须在本地盘;只能有一个进程写(多 worker 部署要谨慎,虽然能跑,但锁竞争会变多);备份要按第 8 章的方法做,不能直接 `cp` 正在写的库文件。真正的风险来自"以后想多机部署",那是换库的信号,不是 SQLite 的缺陷。

Q3:为什么说"迁移成本主要在代码结构,不在 SQL"?

看答案 因为 SQL 语句的数量是有限的,改写它们是一次性工作,半天到两天能完成。真正贵的是散落在业务代码里的假设:数据在内存里可以直接 `.append`、文件读写不需要事务、只有一个请求在写、查询就是 `for` 循环过滤。这些假设没有写在任何地方,却决定了每一处代码怎么写。把它们收进一层(第 4 章),换库才是一次替换而不是一次重写。

下一步

存储选好了,接下来得会跟它说话。下一章从"表为什么这么设计"开始,把四张表建出来,再用六条查询把数据问出来。

→ 卷6-02-表与SQL基础.md