多方法写入一致性：从一次 Debug 到程序性防御

写在前面

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

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

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

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

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

文章和分类的关系

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

Tag Category
───────────────────────────── ─────────────────────────────
Tag 表 Article.category
↑ ↑ _get_or_create_tags
后来需要侧边栏展示 → ↑
SiteSetting.blog_categories article_tags
再后来需要多入口编辑 → 没有重构，继续打补丁

关键对比：

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

使用者痛点：开发者经常因为「看似小改动」而引入多个隐藏的数据入口，导致后期排查成本指数级上升。

什么是“多方法写入不一致”

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

正常情况：
编辑器 → _get_or_create_tags → Tag 表 → 所有读取方
↑ 唯一来源，永不漂移
再看问题情况。编辑器 → Article.category
管理台 → SiteSetting.blog_categories
↑ 两个写入目标，天然不一致

二、Debug 过程：四层下钻

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

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

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

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

 ↑ 空的！话说回来，

原因：Kinja2 模板中运算符优先级错误导致空 。

修复：

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

第二层这方面，为什么新建的分类不出现？

现象：创建文章时选了新分类名，保存后博客侧边栏找不到该分类。

排查：

• 写入链路： 文章编辑器 → POST /api/articles → Article.category = "深度学习"
• 读取链路： 博客侧边栏 → → SiteSetting.blog_categories →

根因：两端存储位置不同——A=Article.category ,B=SiteSetting.blog_categories . 新分类从未同步到列表 B。

修复： 添加事后同步函数 .

def _ensure_category_in_list:
if not category:
return
cats = _get_category_list
if category not in cats:
cats.append
_save_category_list

第三层的观点是，为什么编辑已有文章的分类不生效？其实，

现象： 修改文章分类后刷新页面仍显示旧分类。

排查： 查看 API 接收模型。

class ArticleUpdate:
至于title，Optional = None
content: Optional = None
summary: Optional = None
cover_image: Optional = None
is_published: Optional = None
# ❌ category 在哪里？

Pydantic 丢弃未声明字段，导致更新逻辑永远不会触发。

修复： 为模型添加 `category: Optional = None`.

至于第四层，为什么首页文章数不对？

现象： 侧边栏显示“文章：”，实际数量远大于显示值。不过，

排查: 模板变量仅使用 {{ articles|length }}。而后台已经计算出完整总数却未传递。

articles = query.order_by.limit.all
total = query.count # 已计算
return _ctx(request。articles=articles,# total=total ← 漏传！)

Fix: 将 total 作为上下文变量传递给模板即可。

四个 Bug 的共同点

: 前两类直接影响功能可用性。后两类虽表面无害，却都源自同一根本设计缺陷——缺乏对「数据完整链路」的把控。

• 模板表达式错误 – 代码书写失误
• 分类未注册到统一列表 – 多处存储不同步
• API 更新模型缺失字段 – 写端断链
• 模板参数漏传 – 读取端断链

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

从 Git 历史看功能演进时间线：

第1天：Article.category = Column // 简单字符串字段
再看第N天。SiteSetting.blog_categories // 为侧边栏新增平行 JSON 列表
至于第N+M天，文章编辑器自由输入分类 // 未建立制
第N+M+K天：管理台 分类 CRUD //
操作平行列表，无归一化

每一次决策在当时都合理，却在累计后形成「每个入口各自为政」 的架构。

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

从短期修复来看，逐个 Bug 修复

• 模板表达式
• 新增 _ensure_category_in_list 并在保存时调用
• 为 ArticleUpdate 添加 category 字段
• 将 total 参数传递至模板

中期方案这方面。写后同步统一列表

通过 _ensure_category_in_list 实现「事后同步」，暂时消除「新建分类不出现」的问题，但仍保留双重存储结构。

说到长期方案，归一化存储

# 新增 Category 表
class Category:
__tablename__ = "categories"
id = Column
name = Column,unique=True,nullable=False)
# Article 改为外键引用
class Article:
category_id = Column)
category_rel = relationship
def _get_or_create_category:
if not name:
return None
cat = db.query.filter).first
if not cat:
cat = Category)
db.add
db.flush
return cat.id

• 删除旧的平行列表相关代码。_save_category_list,etc.)
• 所有读写统一指向 Category 表，无需同步函数
• 迁移脚本负责把历史字符串字段迁入新表

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

至于原则一，SSOT 判定 —— 写第一行代码前决定存储方式

• 会被多记录复用？✔︎ 用独立表
• 会作为筛选条件？按理说，✔︎ 用独立表
• 会在导航/侧边栏展示？✔︎ 用独立表
• 需要统一重命名或删除？✔︎ 用独立表 如果任意答案为「是」，就不要使用字符串字段。

字段	判断	选择	结果
/article.tags/	> 复用 + 筛选 + 管理	/Tag/	✓ 从不出错
/article.category/	> 复用 + 筛选 + 管理	/String/	× 四处补丁
/article.cover_image/	> 仅展示	/String/	✓ 正常使用

原则二这方面，数据链路审计 —— 列出所有入口和出口并统一指向同一存储

• 写入口 A/B/C …话说回来，是否全部指向同一 DB 表？读出口 X/Y/Z ，是否全部从同一 DB 表读取？若任意答案否，则出现链路断裂风险。

至于原则三，警惕 “事后同步” 函数 这些函数往往是“不完整设计”的信号。正确做法是在写入阶段直接落库，而非事后补齐。

原则四的观点是。补丁式演进是数据一致性的最大敌人 错误决策 + 不重构 ⇒ 技术债累积 正确决策 + 不重构 ⇒ 正常演进 错误决策 + 即时重构 ⇒ 可接受弯路 关键不是第一次选错，而是发现错之后是否及时回滚并统一实现。

六、AI 编程中如何程序性避免这类问题  🧠​ ​​​​​​​​​‍​​‍​​‍​​​​​​​ ​‍​​‍​​‍​​​‍‌‌‌‌‌‌‌‌‌‏‏‏‏‏‎‎‎‎⁠⁠⁠⁠⁠⁠⁠⁠‌‎‌‎ ️ ​

Problem Essence : 🟢  **Missing foresight** – AI doesn’t predict that a “category” will later become a filterable entity. 🟢  **No global audit** – AI isn’t aware of existing patterns like `Tag` that could be reused. ​

✅ Solution 1️⃣ – Embed design constraints in requirement

Add article categories. Design constraints: · Must use an independent table . · Provide `_get_or_create_category` helper. · List all write/read paths.

Why it works: Once you spell out constraints,model generates correct schema instead of a quick‑and‑dirty string field.

✅ Solution 2️⃣ – Ask AI for risk assessment

What consistency risks does this design have?List every possible write path to “category” field. Do y all point to same storage?

Result: AI will enumerate risks enabling you to catch m early.

✅ Solution 3️⃣ – Store design rules in project memory

Create a CONSISTENCY_GUIDELINES.md:

• Shared entities must use separate tables with FK links. • Prohibit plain‑string fields plus parallel list caches. • Every new entity requires a write‑path & read‑path audit. • Follow Tag’s `_get_or_create_*` pattern.

When model loads this file each session it automatically respects those rules.

✅ Solution 4️⃣ – Pattern‑recognition review checklist

When reviewing generated snippets scan for:

✅ Good signals: categoryid = Column) _getorcreatecategory db.query.all

❌ Warning signals: category = Column) settings.xxxlist / xxxcache ensurexxx / syncxxx

If any warning appears。ask follow‑up questions before committing code.

Interaction Example

Bad prompt: I need a category field for articles. AI: adds category = Column). Six months later you face drift.

Good prompt:

Add a category feature. Design must: · Use an independent table with FK. · Provide `_get_or_create_category` helper. · Enumerate all read/write paths.

AI: creates Category table,foreign key category_id,unified read/write routes—no hidden drift.

Takeaway: The model’s capability is unchanged;success depends on how much structural guidance you give it.

七、检查清单 ✅

新功能开发自检

• SSOT 判定：该数据是否必须独立表？✔︎  ✔︎  ✔︎ ✔︎ ✔︎                                                                                                                                                                     

 



// No furr lines needed

---