# 用 LikeC4 实现架构即代码：从代码库自动生成并维护实时更新的软件架构图 > 本文深入探讨如何利用 LikeC4 这一基于 DSL 的架构描述工具，实现软件架构图的自动化生成与同步更新。通过 CLI 与 GitHub Actions 的配合，构建一套可持续交付的架构文档流水线。 ## 元数据 - 路径: /posts/2026/02/07/likec4-software-architecture-diagrams-code-generation/ - 发布时间: 2026-02-07T02:17:15+08:00 - 分类: [systems](/categories/systems/) - 站点: https://blog.hotdry.top ## 正文 在软件开发过程中，架构图往往是团队沟通和文档维护的核心资产之一。然而，传统的手工绘制方式存在诸多痛点：图表更新滞后于代码演进、不同成员绘制的风格难以统一、版本管理困难、难以与 CI/CD 流程集成。随着代码库规模的扩大，这些问题会被显著放大，导致文档逐渐失去参考价值。LikeC4 作为一个新兴的架构建模工具，提供了另一种思路：它允许开发者使用代码（更准确地说，是一种专门的领域特定语言）来描述系统架构，并自动生成、更新可视化图表。这种「架构即代码」的方法，天然解决了传统文档的同步问题，并能将架构设计纳入版本控制和工作流自动化体系中。本文将详细介绍 LikeC4 的核心概念、实施路径以及如何将其集成到工程实践中。 ## LikeC4 核心概念与设计哲学 LikeC4 的命名来源于 C4 模型（C4 Model），这是由 Simon Brown 提出的一种用于可视化软件架构的标准化方法。与 C4 模型一致，LikeC4 鼓励从 Context（上下文）、Container（容器）、Component（组件）和 Deployment（部署）等多个层次描述系统。但在核心设计上，LikeC4 并不强制要求使用某种固定的符号系统或嵌套层级，而是提供了极高的灵活性，允许团队根据自身需求定制元素类型、关系类型和可视化样式。这种灵活性使其能够适配从初创公司到大型企业的不同规模团队。 从技术实现角度看，LikeC4 包含两个核心组成部分：一套用于描述架构的领域特定语言（DSL），以及一套用于解析该语言并生成图表的工具链。DSL 的设计目标是简洁、可读，并且对大型语言模型（LLM）友好。这意味着开发者可以用极低的上手成本开始编写架构描述，而 AI 助手也能理解并补全这些描述。工具链则提供了从本地预览到 CI/CD 集成的全套能力，支持生成静态网站、导出 PNG/Mermaid/Dot/D2 等多种格式，并提供 React 组件和 Web Components 的代码生成功能。 在实际使用中，一个典型的 LikeC4 工作流始于对系统术语和规范的定义。开发者可以在 `specification` 块中声明系统中使用的元素类型（如 Actor、System、Component）以及它们之间的关系类型（如同步、异步、依赖）。随后，在 `model` 块中定义具体的系统实例，描述各个组件的属性（如技术栈、描述信息）以及它们之间的交互关系。最后，在 `views` 块中声明需要渲染哪些图表，指定包含和排除哪些元素，以及应用哪些样式规则。这种分层结构使得架构描述既具有声明式的清晰性，又保留了足够的表达能力来描述复杂的系统拓扑。 ## DSL 语法与模型定义要点 LikeC4 的 DSL 语法设计强调简洁性和表现力的平衡。以一个典型的 SaaS 系统为例，其架构描述通常包含三个主要区块：specification、model 和 views。在 specification 中，开发者定义「类型」而非具体实例。例如，可以声明 `element actor` 表示参与者，`element system` 表示系统，`element component` 表示组件。还可以为这些类型指定默认的可视化样式，如 `style { shape person }` 用于将所有 Actor 渲染为人物图标。关系类型同样可以在此定义，如 `relationship async` 用于表示异步通信。 在 model 区块中，开发者定义具体的架构元素实例及其关系。这通常是一个层次化的声明过程：从高层系统开始，逐步细化到各个子组件。例如，一个 `cloud` 系统可能包含 `backend` 和 `ui` 两个组件，它们之间通过 `ui -[async]-> backend 'requests via HTTPS'` 的语法建立异步关系。每个元素都可以附加丰富的属性，如技术栈图标（`icon tech:graphql`）、描述文本（`description 'Implements business logic'`）以及自定义样式。这种声明式的方式使得架构逻辑清晰可见，也便于代码审查。 views 区块负责控制最终生成的可视化输出。通过 `include` 和 `exclude` 谓词，开发者可以精确控制每个视图包含哪些元素。例如，`include *, cloud.*` 会显示所有顶级元素以及 `cloud` 系统的所有子元素。样式规则同样可以在视图级别覆盖，如 `style cloud.* { color green }` 为 `cloud` 系统下的所有元素设置绿色。这种机制使得同一个模型可以生成多种不同侧重点的图表，从系统上下文图到详细组件图，无需重复描述。 从可落地参数的角度，团队在定义规范时应遵循以下原则：保持术语的一致性，避免在同一模型中混用同义词；为每个关键组件添加描述性文本，便于后续维护者理解其职责；合理使用嵌套结构，避免单层包含过多元素导致视图混乱；利用 `icon` 属性标注技术栈，提高图表的信息密度。 ## CLI 与本地开发工作流 LikeC4 提供了功能完备的命令行工具 `@likec4/cli`，支持在本地环境中进行架构图的开发、预览和构建。对于 npm 项目，可以将其作为开发依赖安装：`npm i -D @likec4/cli`，然后在 `package.json` 的 scripts 中添加 `"dev": "likec4 dev"` 这样的命令。CLI 会递归搜索当前目录下的 `*.c4` 和 `*.likec4` 文件，解析并启动一个本地服务器。开发者可以在浏览器中实时查看图表效果，任何对源文件的修改都会触发热更新，实现所见即所得的开发体验。 在工程实践中，本地开发工作流的核心是预览功能。`likec4 dev`（或 `serve`、`start` 别名）命令会启动热更新服务器，非常适合在编写架构描述时进行即时反馈。CLI 还提供了 `likec4 validate` 命令，用于检查模型是否存在语法错误或布局漂移（即手动布局与自动计算不一致的情况）。该命令在发现错误时会返回非零退出码，非常适合用于在提交前进行自动化检查。团队可以将此命令集成到 Git Hooks（如 pre-commit）中，确保提交到仓库的架构描述始终是有效的。 对于需要生成可交付物的场景，CLI 的 build 和 export 子命令是关键。`likec4 build --output dist` 会将所有图表打包成一个静态网站，适合部署到内部文档站点或 GitHub Pages。输出目录、基础 URL、标题等参数都可以通过命令行选项或项目配置文件进行控制。`likec4 export png -o ./assets` 则会使用 Playwright 截取各个图表的 PNG 截图，适用于需要将架构图嵌入到非 Web 环境的场景。如果需要集成 PlantUML 或 Mermaid 等其他格式的图表，可以使用 `likec4 gen mermaid` 等子命令生成对应的文本描述。 值得注意的是，CLI 的导出功能在 CI 环境中使用时需要注意 Playwright 的配置。根据官方文档，在 CI 中导出 PNG 需要预先安装 Playwright 浏览器依赖，或者使用 `use-dot-bin` 参数调用本地的 Graphviz `dot` 二进制文件以获得更稳定的布局效果。这些细节在设置自动化流水线时需要特别留意。 ## GitHub Actions 与 CI/CD 流水线集成 LikeC4 的真正价值在于其与持续集成/持续交付（CI/CD）流程的无缝集成。通过官方维护的 GitHub Action `likec4/actions@v1`，团队可以在每次代码推送时自动验证架构模型、生成图表并发布更新。这种自动化机制确保了架构图始终反映系统的最新状态，消除了手工维护带来的同步延迟和人为错误。 一个典型的 GitHub Actions 工作流包含以下步骤：首先使用 `actions/checkout@v4` 检出代码，然后使用 LikeC4 Action 执行构建或导出操作。对于需要将架构文档部署到 GitHub Pages 的场景，工作流配置相对简单：Action 会将 LikeC4 模型编译为静态网站（通过 `action: build`），输出到 `dist` 目录；随后使用 `actions/upload-artifact@v3` 上传构建产物，并结合 Pages 部署操作完成发布。这个过程在每次 main 分支有推送时自动触发，确保在线文档始终是最新的。 除了构建网站，Action 还支持直接导出图表到 PNG 或生成代码工件。对于需要在 Pull Request 中展示架构变更的场景，团队可以配置两个并行任务：一个使用 `codegen: react` 生成 React 组件供预览页面使用，另一个使用 `export: png` 导出静态图片并作为 Artifact 上传。更高级的用法是利用 `likec4 validate` 作为 CI 门禁的一部分，如果架构描述存在语法错误或布局问题，就阻止合并，保证主分支的持续可用性。 从部署策略角度，建议团队采用「渐进式部署」策略来降低风险。首先在 feature 分支进行开发测试，确认无误后合并到 develop 分支进行集成验证，最后推送到 main 分支触发生产发布。对于关键系统，可以考虑保留历史版本的快照，以便回溯查看特定时刻的架构状态。此外，由于 LikeC4 生成的内容全部是静态文件，部署过程不需要后端服务支持，可以充分利用 CDN 加速访问，提高文档站点的性能和可用性。 ## 代码生成与扩展能力 LikeC4 不仅能生成可视化图表，还提供了从模型到代码的逆向能力。通过 `likec4 gen react` 等命令，可以从架构模型生成 React 组件、Web Components 或 TypeScript 类型定义。这在构建内部开发者门户或架构仪表盘时非常有用：开发者可以使用统一的架构模型，同时获得可直接复用的 UI 组件，保持可视化展示与底层模型的同步更新。 API 层面的集成同样值得关注。LikeC4 提供了 Model API，允许在运行时读取和操作架构模型。这使得开发者可以在 IDE 插件或其他工具中实时查询系统的拓扑结构，例如在编写代码时自动提示某个组件的依赖关系，或者在单元测试中验证架构约束。官方还提供了 MCP（Model Context Protocol）服务器实现，使 AI 助手能够在对话中访问架构上下文，这对于利用 AI 进行代码审查或架构建议具有重要意义。 从扩展性角度看，LikeC4 支持通过配置文件和插件机制进行定制。团队可以定义自己的元素类型、关系类型和可视化样式，以适配特定领域的术语。例如，微服务团队可以将 `service` 定义为一级元素类型；数据库团队可以添加 `table` 和 `column` 的可视化符号。这种可扩展性确保了 LikeC4 能够适应不同组织的技术栈和沟通习惯，而不是强制推行一套统一的「标准」。 ## 实施建议与工程化参数 成功引入 LikeC4 需要团队在工具、文化和流程三个层面做好准备。在工具层面，建议首先在 `package.json` 中添加 LikeC4 相关依赖，并配置好本地开发脚本。安装方式推荐使用本地依赖（`npm i -D @likec4/cli`）而非全局安装，以确保所有开发者使用相同版本的工具，减少因环境差异导致的问题。同时，为 VS Code 用户安装官方扩展（`likec4.likec4-vscode`），获得语法高亮、自动补全和实时预览功能，这些特性显著降低了学习成本。 在工程化参数方面，以下配置值可作为团队实践的起点：文件组织上，建议将所有 `.likec4` 文件集中放在 `src/architecture` 或 `docs/architecture` 目录下，保持与业务代码的清晰分离；命名约定上，采用功能域+视图类型的命名方式，如 `payment-system.c4` 或 `payment-views.c4`，便于后续维护和检索；自动化触发上，在 `pre-commit` 钩子中运行 `likec4 validate`，在 `on: push` 事件中触发 GitHub Actions 构建，在 `on: pull_request` 时可选运行 `likec4 export png` 生成变更对比图。 文化层面同样关键。LikeC4 的最大价值在于它使架构决策成为可追踪、可审查的代码变更。团队应当建立「架构即代码」的共识，将架构描述文件的修改视作与业务代码同等重要的工程实践。在 Code Review 中，架构图的变更是必要的审查项之一；新成员入职时，架构模型应当是首先阅读的文档之一。通过这种方式，架构知识得以沉淀和传承，避免因核心人员离职而导致的知识断层。 风险控制方面，团队应当意识到 DSL 学习曲线的存在。建议从简单模型开始，逐步增加复杂度；优先使用官方提供的模板仓库（`likec4/template`）作为起点，其中包含了推荐的目录结构和最佳实践。对于已有大量遗留文档的团队，不必追求一次性迁移，而是采用「新增使用 LikeC4，存量逐步替换」的策略，平滑过渡到新工具链。 ## 总结与资料来源 LikeC4 代表了软件架构文档管理的现代范式：它通过领域特定语言和自动化工具链，将架构图从静态文档转变为动态资产。在实际应用中，团队可以充分利用其 DSL 的表达能力描述系统拓扑，通过 CLI 实现本地开发和预览，借助 GitHub Actions 实现自动化构建和部署，并利用代码生成能力构建更丰富的架构感知工具。这套工作流不仅提升了文档的时效性和准确性，也促进了团队对架构决策的理解和共识。 如需深入了解，建议参考以下官方资源：项目仓库位于 [GitHub - likec4/likec4](https://github.com/likec4/likec4)，CLI 使用说明见 [LikeC4 CLI 文档](https://likec4.dev/tooling/cli/)，GitHub Actions 集成指南见 [LikeC4 GitHub Actions 文档](https://likec4.dev/tooling/github/)。 ## 同分类近期文章 ### [好奇号火星车遍历可视化引擎：Web 端地形渲染与坐标映射实战](/posts/2026/04/09/curiosity-rover-traverse-visualization/) - 日期: 2026-04-09T02:50:12+08:00 - 分类: [systems](/categories/systems/) - 摘要: 基于好奇号2012年至今的原始Telemetry数据，解析交互式火星地形遍历可视化引擎的坐标转换、地形加载与交互控制技术实现。 ### [卡尔曼滤波器雷达状态估计：预测与更新的数学详解](/posts/2026/04/09/kalman-filter-radar-state-estimation/) - 日期: 2026-04-09T02:25:29+08:00 - 分类: [systems](/categories/systems/) - 摘要: 通过一维雷达跟踪飞机的实例，详细剖析卡尔曼滤波器的状态预测与测量更新数学过程，掌握传感器融合中的最优估计方法。 ### [数字存算一体架构加速NFA评估：1.27 fJ_B_transition 的硬件设计解析](/posts/2026/04/09/digital-cim-architecture-nfa-evaluation/) - 日期: 2026-04-09T02:02:48+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析GLVLSI 2025论文中的数字存算一体架构如何以1.27 fJ/B/transition的超低能耗加速非确定有限状态机评估，并给出工程落地的关键参数与监控要点。 ### [Darwin内核移植Wii硬件：PowerPC架构适配与驱动开发实战](/posts/2026/04/09/darwin-wii-kernel-porting/) - 日期: 2026-04-09T00:50:44+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析将macOS Darwin内核移植到Nintendo Wii的技术挑战，涵盖PowerPC 750CL适配、自定义引导加载器编写及IOKit驱动兼容性实现。 ### [Go-Bt 极简行为树库设计解析：节点组合、状态机与游戏 AI 工程实践](/posts/2026/04/09/go-bt-behavior-trees-minimalist-design/) - 日期: 2026-04-09T00:03:02+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析 go-bt 库的四大核心设计原则，探讨行为树与状态机在游戏 AI 中的工程化选择。