开源项目中的架构演进如何记录？

本文目录导读：

1. 核心原则
2. 主要记录方法
3. 实用工具与模板
4. 一个推荐的记录框架

在开源项目中,记录架构演进是维护项目可理解性、吸引贡献者、降低后期维护成本的关键，这不仅仅是写文档，更是一种工程实践和文化。

以下是记录架构演进的几种主流方法、最佳实践以及针对不同项目阶段的建议。

核心原则

1. 渐进式记录：不要试图一次性写“完美架构”，而是随着演变持续更新。
2. 决策驱动：记录为什么这么做（上下文、权衡），比记录做了什么更重要。
3. 低门槛、可追溯：让新贡献者能快速理解过去，让老贡献者能轻松找到依据。
4. 与代码协同：文档和代码应该保持同步，否则文档会迅速过时。

主要记录方法

架构决策记录（ADR，Architecture Decision Record）—— 最推荐

这是目前最流行、最有效的记录架构演进的方法，它把每一次重大的架构决策都记录成一个独立的、结构化的文件。

• 核心思想：每个ADR记录一个决策及其上下文和后果。

• 文件结构（通常是Markdown文件，存放在 docs/adr/ 目录下）：

  • 0001-使用微服务架构拆分单体应用.md（带序号，方便排序）
  • 状态：提案 -> 已接受 -> 已废弃/已取代
  • 上下文：当时面临什么问题？有什么限制？有哪些备选方案？（这是最重要的部分）
  • 决策：最终选择了哪个方案？
  • 理由：为什么选这个？对备选方案的分析（优点、缺点、权衡）。
  • 后果：这个决策将带来哪些正面和负面的影响？需要做哪些后续工作？
  • 关联：是否替代了之前的某个ADR？是否与另一个ADR有关？

• 优点：

  • 时间线清晰：按序号排列，就是一部完整的演进史。
  • 上下文完整：避免“为什么当初要这么设计”的困惑。
  • 可参与：贡献者可以通过提案ADR来参与架构讨论。

• 缺点：

  • 需要社区成员养成记录的习惯。
  • 适合中等以上粒度的决策,太细的决策（如函数命名）不适合。

示例：Kubernetes、React、Rails等许多大型项目都使用ADR。

架构文档（Architecture Documentation）—— 传统但有效

指项目根目录下的 ARCHITECTURE.md、docs/architecture/ 等，它需要随着架构演进定期更新。

• 核心思想：定期更新一份“当前架构概览”文档。

• • 总体架构图（用工具如PlantUML、Mermaid、Draw.io生成）。
  • 核心模块及职责。
  • 数据流（关键的数据流向、API调用链）。
  • 关注点分离（如分层、模块化、微服务边界）。
  • 关键架构决策（可以链接到ADR）。
  • “为什么如此设计”：解释架构背后的思想。

• 优点：能给新贡献者一个快速的上手图谱。

• 缺点：容易过时（维护成本高），难以展现“演进”过程。

代码注释与提交信息（Quick & Dirty）—— 最低成本

当团队精力有限时,将关键的架构决策直接写在代码中或详细的Git提交信息中。

• 代码注释：

  • 在复杂模块的包名、类名、接口名前加注释，说明为何这样设计。
  • 在关键优化、重构代码周围加 // Note: 或 // TODO: 记录上下文。

• Git提交信息：

  • 约定： 详细描述为什么做这个变更（问题、动机）。
  • feat: 引入事件溯源模式以解决订单历史追踪问题
    • 背景： 旧方案基于MySQL快照，无法还原历史状态。
    • 决策： 引入EventStore作为事件持久化层。
    • 影响： 查询性能略有下降（需聚合事件），但获得完整的审计能力。

• 优点：与代码紧密结合，几乎零额外成本。

• 缺点：不能替代完整的架构文档，且Git历史对于大型查询不友好。

Wiki / 社区博客 / 发布说明 —— 辅助手段

• Wiki（如GitHub Wiki）：适合存放非结构化的演进故事、设计讨论、长文分析。
• 发布说明：每次发布新版本时，可以简要列出本版本中发生的架构变化，并链接到ADR或Issue。
• 社区博客：当有重大重构或里程碑时，写一篇博客解释当时为什么需要改变，这对吸引贡献者和用户非常有帮助。

1. 小型项目（1-3人维护，月更新<10次）：

   • 方法：代码注释 + 详细的Git提交信息。
   • 建议：在 README.md 中放一个“架构概览”段落，描述核心模块和大致数据流，关键决策用注释说明。

2. 中型项目（3-15人维护，社区活跃）：

   • 方法：ADR（首选）+ 定期更新的 ARCHITECTURE.md。
   • 建议：在 docs/ 下建立 adr/ 目录，每次合并重大Pull Request（PR）时，要求贡献者同时更新相关ADR或在 ARCHITECTURE.md 中添加一段说明。

3. 大型成熟项目（有专门架构组，社区庞大）：

   • 方法：ADR + 完整的架构文档（可能包含多种视图）+ 公开的RFC（Request for Comments）流程。
   • 建议：所有重大变更先经过RFC讨论（结果归档），架构文档由专人维护，定期评审，发布说明中记录架构变化。

实用工具与模板

• ADR模板：GitHub上有成熟的模板，
  • adr-tools 命令行工具。
  • https://github.com/joelparkerhenderson/architecture-decision-record 提供了Markdown模板、状态管理、编号规则等。
• 图表工具：
  • Mermaid（GitHub原生支持）：docs/ 内嵌 ```mermaid 代码块，渲染出架构图。
  • PlantUML：功能更强大，但需要插件。
  • Draw.io / diagrams.net：导出为SVG/PNG并提交到仓库。
• RFC流程：很多项目（如React、Rust、Kubernetes）使用 rfcs/ 目录来管理提案，这本身就是一种架构演进的记录。

一个推荐的记录框架

1. 初始化：在项目创建时，写一个简单的 ARCHITECTURE.md 描述初版设计。
2. 每次决策：遇到重大的架构决定（模块拆分、引入新技术、数据模型大改），创建新的ADR文件。
3. 定期回顾：每3-6个月，或每次大版本发布前，评审一次 ARCHITECTURE.md，确保其与当前代码和ADR状态一致。
4. 让贡献者参与：在 CONTRIBUTING.md 中说明：欢迎针对架构改进提出ADR提案。

最终的目标是：无论项目规模如何，任何新贡献者都能在半小时内，通过阅读一系列ADR和一份架构文档，清晰地理解项目为什么以现在的方式演进到现在。