多路径写入一致性：从一次 Debug 到系统性防御

写在前面

这不是一篇通用的技术教程，而是一次真实 Debug 的完整复盘。

问题本身很简单------"博客分类筛选不工作"------但往下挖了四层才发现，表象各异的四个 Bug 其实指向同一个设计缺陷。这个缺陷从项目的第一行代码就埋下了，后续每次加功能都在上面打补丁，直到补丁本身变成了问题的一部分。

我想通过这个案例说清楚三件事：

数据一致性不是靠修 Bug 修出来的，是设计阶段决定的
多路径写入不一致有一个很简单的判断方法，可以在代码生成之前就发现
AI 编程中这个问题尤其容易被放大，但也有对应的解决手段

一、先理解架构：数据是怎么流转的

1.1 文章和分类的关系

在动手之前，先看清项目的三个核心数据实体和它们的存储方式：

scss 复制代码

Tag（标签）                      Category（分类）
─────────────────────────────    ─────────────────────────────
Tag 表（独立实体，从第一天就在）    Article.category（字符串字段）
  ↑                                ↑
_get_or_create_tags()             后来需要侧边栏展示 →
  ↑                                SiteSetting.blog_categories（新开一个存储）
article_tags（关联表）             再后来需要多入口编辑 →
                                     没有重构，继续打补丁

关键对比：

标签：一张表、一个写入函数、一个关联表 → 从不出问题
分类：一个字符串字段 + 一个平行列表 + 两个写入入口 → 到处出问题

这不是巧合。

1.2 什么是"多路径写入不一致"

同一个语义数据存在两条以上写入路径，各路径指向不同存储位置，最终数据漂移。

scss 复制代码

正常情况（单路径）：
  编辑器 → _get_or_create_tags() → Tag 表 → 所有读取方
                                       ↑ 唯一来源，永不漂移

问题情况（多路径）：
  编辑器 → Article.category（字符串字段）
  管理台 → SiteSetting.blog_categories（平行列表）
               ↑ 两个写入目标，天然不一致

二、Debug 过程：四层下钻

问题从表面到底层一共四层。每一层发现一个不同的 Bug，但最终都指向同一个根因。

第一层：为什么标签链接点了没反应？

现象：点击博客页的标签链接，URL 不变，页面刷新。

排查：打开浏览器开发者工具 → Elements → 查看标签 <a> 的 href。

ini 复制代码

<a href="">#AI</a>
          ↑ 空的！

原因：Jinja2 模板中有一行代码：

jinja 复制代码

{% set tag_url = '/blog?tag=' + tag_info.name + ('&category=' + current_category if current_category else '') %}

问题出在运算符优先级。Jinja2 的条件表达式优先级低于 +，实际解析为：

bash 复制代码

('/blog?tag=' + tag_info.name + '&category=' + current_category)  if  current_category  else  ''

当 current_category 为空（默认情况），tag_url = ''。空 href 等于"刷新当前页"。

修复：拆成两行，不用行内条件表达式。

jinja 复制代码

{% set tag_url = '/blog?tag=' + tag_info.name %}
{% if current_category %}
  {% set tag_url = tag_url + '&category=' + current_category %}
{% endif %}

这一层的本质：模板表达式求值 Bug。与数据一致性无关，但为后续排查开了个头。

第二层：为什么新建的分类不出现？

现象：创建文章时选了一个新分类名（比如"深度学习"），保存后博客侧边栏找不到这个分类。

排查：分别追踪"写"和"读"两条链路。

bash 复制代码

写入链路：
  文章编辑器 → POST /api/articles → Article.category = "深度学习"
  
读取链路：
  博客侧边栏 → _get_category_list(db) → SiteSetting.blog_categories
                                      → ["AI", "Python后端", ...]
                                      ↑ 没有"深度学习"！

问题是两端的存储位置不同 。文章写了 Article.category，但侧边栏从 SiteSetting.blog_categories 读。新分类名从未被注册到列表中。

css 复制代码

文章保存：  Article.category（字段 A）
博客展示：  SiteSetting.blog_categories（列表 B）
                ↑ 链路在此断裂

对应到架构图：

arduino 复制代码

标签的工作方式（正确）：
  输入 "Python" → _get_or_create_tags() → Tag 表 → 所有读取方可见 ✅

分类的工作方式（错误）：
  输入 "深度学习" → Article.category = "深度学习"
                    → SiteSetting.blog_categories 不知道这件事 ❌

修复：添加 _ensure_category_in_list()，每次保存文章时将新分类名注册到列表中。

python 复制代码

def _ensure_category_in_list(db, category):
    if not category: 
        return
    cats = _get_category_list(db)
    if category not in cats:
        cats.append(category)
        _save_category_list(db, cats)

手动埋了个"事后同步"函数。

这一层的本质：这是设计阶段留下的坑。分类从一开始就是字符串字段，后来为了展示侧边栏加了平行列表，但文章编辑器不知道这个列表的存在。两处存储之间没有同步机制。

第三层：为什么编辑已有文章的分类不生效？

现象：进入文章编辑页，修改分类，保存。回到博客页，文章还在旧分类下。

排查：抓 API 请求，看数据流。

前端发出的请求：

json 复制代码

PUT /api/articles/5
{"category": "AI", "title": "...", "content": "..."}

后端接收的模型：

python 复制代码

class ArticleUpdate(BaseModel):
    title: Optional[str] = None
    content: Optional[str] = None
    summary: Optional[str] = None
    cover_image: Optional[str] = None
    is_published: Optional[bool] = None
    # ❌ category 在哪里？

ArticleUpdate 没有定义 category 字段。 FastAPI/Pydantic 收到 {"category": "AI"} 后直接丢弃，update_article 中的 if "category" in update_data 永远为 False。

这个字段从项目一开始就缺失------因为创建文章用的是 ArticleCreate（继承自 ArticleBase，有 category），但更新文章用的是独立的 ArticleUpdate，只是当时没人记得加上去。

修复：加一行 category: Optional[str] = None。

这一层的本质：代码的"写"端也有断点。文章编辑器发了数据，但 API 层根本没接收。

第四层：为什么首页文章数不对？

现象：首页侧边栏显示"文章：6"，实际有十几篇。

排查：追踪模板变量来源。

jinja 复制代码

{{ articles|length }}  ← 这个值只有 6

追踪到路由：

python 复制代码

articles = query.order_by(...).limit(PAGE_SIZE).all()  # 默认 PAGE_SIZE = 9
total = query.count()  # 真正的总数被计算了

return _ctx(request,
    articles=articles[:6],  # 传到模板的只有 6 篇
    # total=total  ← 被计算但没传递！
)

total 被计算了但没传到模板。模板只能退而求其次用 articles|length，显示第一页的篇数。

修复：把 total 传过去。

这一层的本质：服务端与模板之间的参数传递断链。不是 Bug，是遗漏。

四个 Bug 的共同点

复制代码

第一层：模板表达式 Bug          ← 代码写错了
第二层：新建分类不注册到列表     ← 两处存储没同步
第三层：ArticleUpdate 缺字段     ← 代码少写了
第四层：total 没传模板           ← 参数漏传了

前两个影响功能，后两个表面不影响------但它们指向同一个方向：这个项目的分类功能从设计到实现都缺乏对"数据完整链路"的把控。每一步都是独立加上去的，没有人完整地追踪过一篇文章的分类从输入到展示走过了哪些环节。

三、追根溯源：问题是怎么一步步积累的

从 Git 历史看这个功能的时间线：

javascript 复制代码

第 1 天：Article.category = Column(String)
        需求：文章需要一个分类字段。
        选择：字符串字段，因为简单。
        问题判断：❌ 没有预判"分类"未来会被复用

第 N 天：SiteSetting.blog_categories
        需求：博客页需要侧边栏展示分类列表。
        选择：在 SiteSetting 新建一个 JSON 列表。
        问题判断：⚠️ 应该重构 Article.category 为独立表，但选择了"再加一个存储"

第 N+M 天：文章编辑器自由输入分类
        需求：用户可以在写文章时新建分类。
        选择：<input> 加 <datalist>，不限制输入。
        问题判断：❌ 没有建立任何"分类注册"机制

第 N+M+K 天：管理台分类管理
        需求：需要独立管理分类的地方。
        选择：新建分类 CRUD API，操作 SiteSetting.blog_categories。
        问题判断：❌ 第三个入口，第三个存储操作，依然没有归一化

每一个决策在当下都是合理的。字符串字段简单，平行列表快速，自由输入灵活，管理 CRUD 必要。但累积起来，就形成了一个"每个入口各写各的"的架构。

这就是典型的补丁式演进------每一次都在上一层的补丁上再打补丁，直到补丁本身变成问题。

四、修复方案：从打补丁到重构

4.1 短期修复：修 Bug

四个 Bug 各自修复，耗时约 15 分钟。

4.2 中期方案：写后同步

添加 _ensure_category_in_list()，在文章保存时将新分类注册到列表中。解决了"数据不出现"的问题，但未解决"两处存储"的结构问题。

4.3 长期方案：归一化

真正的修复是让分类和标签走完全相同的模式：

python 复制代码

# 新增 Category 表（与 Tag 表完全对应）
class Category(Base):
    __tablename__ = "categories"
    id = Column(Integer, primary_key=True)
    name = Column(String(50), unique=True, nullable=False)

# Article 新增 FK
class Article(Base):
    category_id = Column(Integer, ForeignKey("categories.id"))
    category_rel = relationship("Category", back_populates="articles")

# 与 _get_or_create_tags 完全一致的写入函数
def _get_or_create_category(db, name):
    if not name:
        return None
    cat = db.query(Category).filter(Category.name == name.strip()).first()
    if not cat:
        cat = Category(name=name.strip())
        db.add(cat)
        db.flush()
    return cat.id

然后删除所有旧代码：

删除 _get_category_list()、_save_category_list()、CATEGORIES_KEY
删除 _ensure_category_in_list()
博客侧边栏改为直接从 Category 表查询
管理台分类 CRUD 改为操作 Category 表
启动时自动迁移旧数据

修复后，分类的数据流变成了：

scss 复制代码

写入：
  文章编辑器 → _get_or_create_category() → Category 表（唯一存储）
  管理台     → CRUD API → Category 表（唯一存储）

读取：
  博客侧边栏 → Category 表查询
  文章详情   → Article.category_rel
  管理台列表 → Category 表查询

所有路径指向同一个位置。不再需要同步函数，不再有平行列表。

五、从这次经历中提炼的设计原则

原则一：SSOT 判定------在写第一行代码前决定存储方式

一个字段应该用字符串还是独立表？判断标准不是"现在需要多少功能"，而是"未来可能被怎么用"。

arduino 复制代码

这个问题只要有一个"是"，就应该用独立表：
  □ 会被多条记录复用吗？
  □ 会被作为筛选条件吗？
  □ 需要在侧边栏/导航中展示吗？
  □ 用户需要统一重命名或删除吗？

案例对比：

字段	判断	选择	结果
`Article.tags`	复用 + 筛选 + 管理	`Tag` 独立表 ✅	从不出问题
`Article.category`	复用 + 筛选 + 管理	字符串字段 ❌	四处打补丁
`Article.cover_image`	只展示	字符串字段 ✅	从不出问题

原则二：数据链路审计------列出所有入口和出口

每新增一个数据实体，强制做一次链路审计：

css 复制代码

写入口 ①：A 功能 → 写到哪里？
写入口 ②：B 功能 → 写到哪里？
读出口 ①：C 页面 → 从哪里读？
读出口 ②：D 页面 → 从哪里读？

→ 所有写的指向同一个存储？
→ 所有读的指向同一个存储？
→ 读写指向同一个存储？

如果任一答案是"否"，链路在这里断裂。

原则三：警惕"事后同步"函数

代码中出现以下函数名时，是强烈的设计警告：

python 复制代码

_ensure_xxx_in_list()      # "确保 xxx 在列表中"------为什么不在写的时候就放进去？
sync_xxx_from_articles()   # "从文章同步 xxx"------为什么要事后同步？
migrate_xxx_data()         # "迁移 xxx 数据"------为什么要等数据先错再修？

如果一个字段需要事后同步函数来保持一致性，说明设计已经出了问题。 正确的设计不需要同步函数------因为所有路径在写入时就放在了正确的位置。

原则四：补丁式演进是数据一致性的最大敌人

复制代码

错误的决策 + 不重构 = 必然的技术债
正确的决策 + 不重构 = 正常的代码演化
错误的决策 + 及时重构 = 可以被接受的弯路

问题不是"第一次选错了存储方式"，而是"发现错了之后没有重构，而是继续在错误的基础上加补丁"。

六、AI 编程中如何系统性避免这类问题

6.1 问题本质：AI 倾向于走"最小路径"

当人类说"给文章加个分类功能"时，AI 最自然的输出是：

python 复制代码

class Article(Base):
    category = Column(String(50), default="")  # 最小改动，最快完成

这不是 AI 的错------它被训练成优先理解并满足当前请求，而不是预测六个月后的需求。AI 缺少两个能力：

预判：不知道"分类"未来会被怎样复用
全局审计：不知道项目中有没有类似 Tag 的模式可以参考

6.2 解决方法一：在需求描述中注入设计约束

与其说"加分类功能"，不如说：

scss 复制代码

给文章加分类功能。
设计要求：
1. 分类必须用独立表，不要字符串字段（参考已有的 Tag 表模式）
2. 提供 _get_or_create_category() 函数（参考 _get_or_create_tags()）
3. 列出所有写入和读取分类的路径

为什么有效：AI 其实知道应该怎么做------你给了明确的约束，它就能输出正确的结果。问题在于你不说它就不做。

6.3 解决方法二：让 AI 做负向推演

在 AI 输出方案后，追问：

复制代码

这个设计有什么数据一致性风险？
列出所有可能写入这个字段的代码路径。
这些路径是否都指向同一个存储？

为什么有效：AI 能识别风险，但它不会主动说出来。你需要一个提问来触发它做安全检查。就像代码审查中问"这个函数有什么边界情况"一样。

6.4 解决方法三：在项目记忆中固化设计规则

在项目的 CLAUDE.md 或记忆系统中加入：

markdown 复制代码

## 数据一致性规则

- 共享实体（分类、标签、状态等）必须使用独立表 + FK 关联
- 禁止使用字符串字段 + 平行列表的模式
- 添加新数据实体时，必须列出所有写入/读取路径
- 参考 Tag 表的 _get_or_create_tags 模式

为什么有效：AI 在每次交互时会加载这些规则。它不需要你每次都说一遍。

6.5 解决方法四：对 AI 的输出做"模式识别审查"

人工审查时，快速扫描 AI 生成的代码：

scss 复制代码

✅ 好信号（安全）：
  category_id = Column(Integer, ForeignKey("categories.id"))
  _get_or_create_category()  # 原子创建
  db.query(Category).all()   # 从唯一表读取

❌ 危险信号（需要追问）：
  category = Column(String(50))           # 字符串字段 → 将来可能被复用？
  settings.xxx                             # 平行配置 → 有没有主存储？
  _ensure_xxx() / _sync_xxx()             # 事后同步 → 为什么不在写入时解决？
  xxx_list / xxx_cache / xxx_backup       # 冗余存储 → 有没有一致性保障？

为什么有效：这些模式在代码中非常明显，一眼就能看出来。你不需要深入理解业务逻辑。

6.6 一个完整的交互示例

差的交互：

bash 复制代码

我：给文章加个分类功能。
AI：好的，在 Article 表加一个 category 字段。
我：......
# 六个月后数据开始漂移，开始打补丁

好的交互：

scss 复制代码

我：给文章加分类功能。
   设计要求：独立表 + FK 关联，参考 Tag 的实现。

AI：创建 Category 表，Article 加 category_id FK，提供 _get_or_create_category()。
   写入路径：① 文章编辑器 → POST/PUT /api/articles → _get_or_create_category()
            ② 管理台 → POST /api/categories → 直接写 Category 表
   读取路径：① 博客侧边栏 → 查询 Category 表
            ② 文章详情 → Article.category_rel
   所有路径指向同一存储。没有平行列表，不需要事后同步。

区别不在于 AI 的能力------同一套 AI 模型在前者输出错误方案，在后者输出正确方案。区别在于你给了多少约束。

七、检查清单

7.1 新功能开发自检

SSOT 判定：这个数据需要独立表吗？
数据链路已列出：所有写入口指向同一存储，所有读出口从同一存储读取
级联操作已定义：删除/重命名时关联数据如何处理
多表操作在同一事务中

7.2 代码审查中识别危险信号

有没有 Column(String) 字段未来可能变成独立实体？
有没有独立于主存储的"列表"或"缓存"？
有没有"同步"、"修复"、"确保"类函数？
GET 请求有没有写操作副作用？
定时任务和用户操作是否写同一资源？

7.3 AI 编程约束

需求描述中注明了设计约束（独立表 / 链路审计 / 参考模式）
对 AI 的输出做了模式识别审查（好信号 ✅ / 危险信号 ❌）
追问了"有哪些数据一致性风险"
项目中固化了数据一致性规则（CLAUDE.md 或记忆系统）