Monorepo中UML图的存放位置约定及最佳实践咨询

一、通用的文件夹命名约定 #

在Monorepo里存放UML图，有不少被广泛认可的命名习惯，分两种场景来看：

1. 根目录级存放（全局架构图） #

如果是覆盖整个Monorepo的全局架构UML图，常用的根目录文件夹名称包括：

• docs/diagrams：将图归类到文档目录的子文件夹，和其他项目文档统一管理，是非常普遍的做法
• diagrams：直接在根目录创建该文件夹，专门存放所有架构图、UML图，直观清晰
• architecture/diagrams：突出图的架构属性，适合以整体架构设计为核心的仓库

2. 包/工作区级存放（组件/模块专属图） #

如果是某个子项目/工作区的专属UML图，通常放在对应包的内部：

• <package-root>/docs/diagrams：和该包的本地文档放在一起，方便维护时关联查看
• <package-root>/uml：直接在包内创建UML文件夹，指向性明确
• <package-root>/assets/diagrams：若将UML图视为静态资源类文件，也会放在assets的子文件夹中

很多团队还会在这些文件夹下进一步细分，比如按图的类型（class、sequence、architecture）或状态（draft、final）建立子文件夹，方便管理不同阶段和类型的图。

二、在代码库中存放架构UML图是否属于良好实践？ #

答案是肯定的，这是非常值得推荐的实践，原因如下：

• 同步迭代：和代码存放在同一仓库，架构图能随代码更新及时调整，避免出现图与实际代码脱节的情况
• 便捷查阅：开发人员查看代码时可直接找到对应架构图，快速理解模块设计逻辑
• 版本追溯：借助Git等版本控制工具，能追踪架构图的变更历史，清晰了解系统设计的演进过程
• 认知统一：团队成员都能通过代码库获取最新架构图，确保对系统设计的认知保持一致

实践中需要注意几个细节：

• 优先使用可编辑的文本格式UML（比如PlantUML），而非仅存图片格式，方便后续修改维护
• 定期清理过时的草稿图，避免仓库冗余
• 给图起清晰的命名，比如user-service-class-diagram-final.puml，便于快速识别用途

内容的提问来源于stack exchange，提问作者Raul