我本来只想给博客换个皮肤。
结果 15 天后，我有了一个 enterprise 级博客、29 份架构决策文档，和一颗想回到“只改改样式”那天的心。

---

🤯 开场：这博客到底经历了什么

事情是这样的——我有个基于 WordPress 的老博客，跑着一个叫 Argon 的主题。它很好，但我手痒了。

于是我决定“重构”一下。就是那种“我就改改样式”的重构。

15 天之后：

• 前端的 WordPress 主题没了，变成了 Astro 7 + React 19 的 headless 架构
• 项目名字从一开始就是 Maltose（麦芽糖）——没什么宏大叙事，就是觉得可爱又好听，以后我养的猫也要叫这个名字
• 包管理器从 npm 换成了 pnpm（npm 的 node_modules 像盘根错节的树根）
• 代码没写几行，架构决策文档先写了 29 份

29 份是什么概念？就是你还没开始写 Hello World，已经写了一篇硕士论文的“研究背景”。

但这套“先立字据再动手”的 ADR（Architecture Decision Record，架构决策记录）工作流，后来救了我不止一次。这个系列就是想把这 15 天的坑、顿悟和翻车现场，全部交代一遍。

今天是第 1 篇：为什么要重构、ADR 文化怎么形成的、以及第一个大坑——浏览量计数。

---

🐒 踩坑 01：浏览量计数——当你的计数器和数据库各说各话

先说第一个大坑，因为它直接决定了后面整个缓存架构的走向。

老博客的浏览量用的是 WP-PostViews 插件——经典的老牌插件，能用，但有个问题：它和主题深度耦合，而且它的数据格式（存在 postmeta 里）有点像“文档说 1.0，代码用 1.1”的祖传协议。

我的需求很简单：浏览量要实时（刷新就要最新），要能自己控制（不想被插件绑架）。

于是第一版方案（记录在 ADR-0002/0003）：

1. 在 Maltose 主题里注册 WPGraphQL 字段 viewCount，自己读写 postmeta（WP 的文章附属数据，相当于文章的便签墙）
2. 为了“兼容老数据”，刻意复用 WP-PostViews 的 views 键——这样老文章的浏览量不会清零

结果第一个坑就来了：

// 主题里注册 viewCount 字段
register_graphql_field('Post', 'viewCount', [
    'type' => 'Int',
    'resolve' => function ($post) {
        // 这里的 $post 是 WPGraphQL 的 Model 对象，不是原生 WP_Post！
        // 我第一次直接当 WP_Post 用，喜提 500 错误
        $views = get_post_meta($post->databaseId, 'views', true);
        return (int) $views;
    },
]);

报错现场是这样的：

Cannot return null for non-nullable field "Post.databaseId"

翻译成人话：你给我的对象不对，我拿不到它的身份证。

WPGraphQL 的 Post 类型解析器要求的是 WPGraphQL\Model\Post（它的模型对象），不是 WordPress 原生的 WP_Post。这俩长得像，但不是一个人——就像你给前台递了张身份证复印件，她只认原件。

修复其实一行的事（用 array_map 包一层 Model），但教训很深刻：

GraphQL 字段的 resolve 函数，签名里的“Post”未必是你以为的那个 Post。

这个坑后来在第 2 篇的“WPGraphQL 静默 100 条上限”那里又升级了——GraphQL 不仅对象会骗你，连数量都会骗你。

---

💡 灵光 01：ADR 工作流是怎么长出来的

很多人问：写个博客而已，为什么要整 ADR 这种“大厂流程”？

答案：因为我踩的坑，80% 都是“上次改的时候没想到”。

拿浏览量的例子来说。第一版方案里，我为了让浏览量实时，设计了三层缓存 + 主动失效：

浏览器 → nginx → Astro SSR（Apollo InMemoryCache + cache-first）
              ↘ WordPress（postmeta 实时读写）

保存文章时 → WP save_post 钩子 → 签名 POST → Astro 清缓存

这个方案（ADR-0003）当时觉得天衣无缝。结果一周内被自己打了三次脸：

• 评论编辑后浏览量不刷新（缓存清的是文章，不是评论）
• 前端多了一个“渐进更新”的 Provider，每次首页加载多一次请求
• 排查陈旧数据时，签名代理 + Apollo 缓存 + WP transient 三层叠加，头都大了

最后干脆推倒重来：全局 network-only（每次真实打 WP），缓存什么的不要了。

那一刻我悟了：

与其设计一个“聪明的缓存失效机制”，不如想清楚谁才配拥有缓存。

这套“设计 → 翻车 → 推翻 → 再设计”的过程，如果每次都用脑子记，第 5 个坑就记混了。所以从第 2 天起，每个决策我都写成 ADR：背景、决策、备选方案、为什么没选备选。

29 份 ADR 就是这么攒出来的。它不是什么流程合规，它是我给自己留的防失忆保险。

---

🐒 踩坑 02：安全审查四连——你以为没人看你博客，但坏人会

重构的第 3 天，我做了一次“如果我是坏人，我会怎么打这个博客”的头脑风暴。收获很丰富，都是血泪：

坑 A：CORS 开的是 *

// 重构前的“豪放”写法
const headers = {
  "Access-Control-Allow-Origin": "*", // 任何网站都能调我的 API
};

* 意味着：任何恶意网站都能在浏览器里向你的 API 发请求。等于你家大门没锁，还挂了块“欢迎光临”的牌子。

修复：白名单 + 只对允许的来源回 CORS 头。

坑 B：评论内容 XSS——让用户的浏览器替你打工

评论是 dangerouslySetInnerHTML（React 直接插 HTML 的方式）渲染的，如果不消毒，用户发一条 <script>偷cookie</script> 的评论，全站访客的 cookie 就没了。

修复：DOMPurify 消毒（HTML 消毒库，等于给用户输入装了个安检机）。

坑 C：JWT 里的用户 ID，是字符串还是数字？

鉴权 JWT（JSON Web Token）里存了用户 ID。判断“这条评论是不是我发的”时，1 === "1" 是 false（严格相等），导致你自己发的评论，系统不认账——一个类型不对就让你连自己都删不掉自己的评论。

修复：统一 String() 归一化。类型要严谨，不然生活（和评论权限）会教做人。

坑 D：信任了浏览器的 User-Agent

记录评论来源时，我直接用了请求头的 User-Agent（浏览器自报家门的字符串）。但 UA 是客户端随便填的——坏人可以伪装成任何设备。

修复：服务端解析 + 只存“设备类型”这种低敏信息，不存原始 UA。

这四连的教训浓缩成一句话：

你的博客可能没多少人看，但一定有坏人扫描。安全审查不是 KPI，是底线。

---

🎉 中场：评论系统的“8 连击马拉松”

主体架构搞定后，我花了一整天打磨评论系统——不是功能，是UI 细节的 8 个 commit：

1. 气泡样式对齐 shadcn 的 Message 架构
2. 头像顶部对齐（评论气泡和头像谁高谁低，强迫症大战）
3. 配色映射到主题色板
4. 头像加载失败的回退
5. 嵌套回复的弹窗导航
6. 提及（@）颜色可读性
7. 提及自动注入到第一条评论
8. ……以及记不清的第 8 个

为什么这么较真？因为评论区是一个博客最像“社区”的地方。技术上它只是 CRUD（增删改查），体验上它是你的“客厅”。

没有人因为评论框圆角多 2px 而关注你，但所有人会因为评论框用着别扭而离开。

（这 8 个 commit 的恩怨情仇，如果反响好我考虑单开一篇。）

---

🔮 下篇预告

第 1 篇到这里。今天讲了：为什么重构、ADR 文化怎么来的、浏览量的坑、安全四连、评论马拉松。

但真正的重头戏还没开始——下一篇，我要给博客装一个“会自我修复的缓存大脑”（LruLink），然后让三个 feature 分支像三条龙一样并行开发、合并——还失败了一次。

缓存这东西，你以为是帮手，其实是前任：你以为ta走了，其实ta一直住在你家客厅，还把你的现任吓跑了。

下一篇：《我的缓存会自我修复：LruLink 与三条并行分支的合并舞步》