Maltose：15 天重构博客，先写了 29 份 ADR 才敢写代码
内容提要
作者用15天将博客从WordPress重构为Astro+React架构，并撰写了29份ADR文档。过程中遇到浏览量计数因WPGraphQL对象类型错误导致500、安全审查发现CORS全开、XSS漏洞及JWT类型不严谨等问题，评论系统经过8次提交打磨。核心经验是ADR工作流有助于记录决策和避免重复错误，安全审查是底线。
延伸解读
ADR 的价值：防失忆的决策记录
作者在重构中踩坑后，发现 80% 的问题源于“上次改的时候没想到”。因此从第 2 天起，每个决策都写成 ADR，记录背景、决策、备选方案及未选原因。29 份 ADR 并非流程合规，而是给自己留的防失忆保险，帮助避免重复错误，并在复杂架构中保持清晰思路。
GraphQL 的隐藏陷阱：类型与对象模型
在 WPGraphQL 中注册字段时，resolve 函数的参数是 WPGraphQL 的 Model 对象，而非原生 WP_Post，直接使用会导致 500 错误。这提醒开发者：GraphQL 字段的签名可能与你预期不同，需仔细阅读文档或调试，避免因对象类型不匹配而踩坑。
安全审查：博客虽小，风险不小
作者通过模拟攻击发现多个漏洞：CORS 全开、评论 XSS、JWT 类型不严谨、信任 User-Agent。这些看似小问题，却可能被恶意利用。安全审查不是 KPI，而是底线。即使博客访问量低，也应重视基础安全，如白名单、消毒、类型归一化、服务端解析等。
缓存设计的反思：简单优于复杂
作者最初设计了三层缓存与主动失效机制，但一周内多次被自己打脸，最终推倒重来，改用全局 network-only。这启示：复杂的缓存失效机制可能带来更多维护成本，不如想清楚谁才配拥有缓存，有时简单直接的方式更可靠。
Q&A
作者为什么在重构博客时写了29份ADR文档？
作者在重构博客过程中踩了很多坑，其中80%都是因为“上次改的时候没想到”。为了记录决策、避免重复犯错，从第2天起每个决策都写成ADR，包括背景、决策、备选方案及未选原因。29份ADR是给自己留的防失忆保险。
博客重构中浏览量计数遇到了什么坑？如何解决的？
浏览量计数最初通过WPGraphQL注册viewCount字段，但resolve函数中误将WPGraphQL的Model对象当作WP_Post使用，导致500错误。修复方法是使用array_map包装一层Model。后来因缓存失效复杂，最终放弃缓存，改为全局network-only策略。
安全审查中发现了哪些漏洞？分别如何修复？
发现四个漏洞：1) CORS配置为*，修复为白名单；2) 评论内容XSS，使用DOMPurify消毒；3) JWT中用户ID类型不严谨，统一用String()归一化；4) 信任浏览器User-Agent，改为服务端解析并只存设备类型。
评论系统打磨了哪些细节？
评论系统经过8次提交打磨，包括气泡样式对齐shadcn的Message架构、头像顶部对齐、配色映射到主题色板、头像加载失败回退、嵌套回复弹窗导航、提及颜色可读性、提及自动注入到第一条评论等。
博客重构后的技术架构是什么？
博客从WordPress重构为Astro 7 + React 19的headless架构，包管理器从npm换成pnpm，项目名为Maltose。
作者从这次重构中总结的核心经验是什么？
核心经验是ADR工作流有助于记录决策和避免重复错误，安全审查是底线。此外，与其设计复杂的缓存失效机制，不如想清楚谁才配拥有缓存。
