Mahiro-Blog 二开实战（二）：数据流与 JSON 管道设计

做二开最怕的不是“现在能不能显示”，而是“半年后还能不能改”。

数据结构设计就是这个问题的核心。

1. 先画出你的数据流

建议你把数据来源按 3 类拆开：

1. 内容数据：src/content/blog/*
2. 配置数据：mahiro.config.yaml
3. 展示数据：src/data/*.json

这样定位问题时会快很多：是内容错、配置错，还是 JSON 错。

2. JSON 管理的基本约束

建议统一执行：

• 文件命名语义化
• 字段尽量稳定
• 可选字段必须有兜底逻辑

你后续的自动审核、页面筛选、迁移脚本都会因此受益。

3. 一个可扩展字段策略

字段建议分三类：

• 必填字段：保证页面可渲染
• 可选字段：增强展示能力
• 衍生字段：运行时计算，不入库

这个策略可以显著降低 schema 变更成本。

4. 数据改造时的“兼容优先”原则

新增字段时不要破坏旧数据：

• 新字段默认可选
• 组件使用时判空
• 旧数据无该字段也能正常渲染

这能避免“一次升级，全站报错”。

5. 常见坑位

5.1 同名字段语义不一致

例如多个 JSON 都有 type，但含义不同，后续很容易混乱。

5.2 页面直接依赖原始 JSON

建议先经过映射层再渲染，便于后续 schema 变更。

5.3 没有兜底值

空字段直出到 UI，最容易导致页面断裂。

6. 二开建议

• 把“数据规范”写进文档
• 把“字段校验”写进 CI（后续可加）
• 每次 schema 变更附带迁移说明

你做的是“系统”，不是一次性页面。

系列导航（二开实战）

二开总览入口