LikeC4以代码定义软件架构——从 DSL 建模、CLI 出图到可编程 API 的完整实践【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4本文以 LikeC4 仓库根目录 README.md 为主体讲解这个架构即代码Architecture as a Code项目如何用一个可扩展的建模语言描述软件架构并通过 CLI、静态站点构建和 TypeScript API 生成始终与代码同步的实时架构图。读完后你可以掌握LikeC4 DSL 的三段式结构specification / model / views、likec4 serve/likec4 build/likec4 export等核心命令的用法以及如何用LikeC4.fromWorkspace/LikeC4.fromSource以编程方式查询和遍历架构模型。LikeC4 是什么为什么叫 Like按根目录 README.md 的定义LikeC4 是一种用于描述软件架构的建模语言以及一套从模型生成架构图的工具。它的定位是可视化、协作并持续演进软件架构——通过从代码生成的、始终最新的实时图表Visualize, collaborate on, and evolve your software architecture with always up-to-date, live diagrams generated from your code。名字中的 like 有两层含义LikeC4 的设计受C4 Model与Structurizr DSL启发整体形态像C4 建模方法System / Container / Component / Code 分层但它刻意比 C4 更灵活你可以自定义或定义自己的记法notation、元素类型element types并使用任意层级的嵌套来组织架构模型而不是被固定的 C4 词汇锁死。这正是 README 中强调的 Perfectly tailored to your needs。这种可扩展 DSL的设计在源码中是直接可验证的语言解析、校验、补全由独立的 语言服务包 与 语言服务器包 承载图形布局由 layouts 包负责而模型定义与视图计算则在 core 包中完成。CLI 本身packages/likec4只是把这些能力组合起来的产物——这一点在 packages/likec4/README.md 的第一句话就有说明likec4包是语言服务、React 组件、Vite 插件与 CLI 的组合a composition of language services, react components, vite plugin and CLI。30 秒上手在本地预览架构图根 README 给出的最快上手方式是在包含 LikeC4 源码*.c4/*.likec4文件的目录下运行npx likec4 start该命令会递归搜索当前目录下的.c4源文件解析后在本地 Web 服务器中提供架构图预览任何源码修改都会触发浏览器端热更新。start是serve的别名等价写法为likec4 serve/likec4 dev见 packages/likec4/README.md。安装方式有两种前提Node.js 20# 方式一作为开发依赖安装直接写入 package.json#scripts npm install --save-dev likec4 # 方式二通过 npx 按需调用 npx likec4 [command] # 方式三全局安装后直接使用 likec4 命令 npm install --global likec4所有命令都支持--help例如likec4 build -h、likec4 codegen react -h并且会附带使用示例。仓库内置的可运行示例当前仓库自带了一个贴近真实 SaaS 场景的完整示例工程 examples/cloud-system它把一个云系统拆成了多个.c4源文件_spec.c4元素规格、model.c4模型主体、views.c4视图定义、deployment.c4部署视图、externals.c4外部系统以及cloud/子目录下的分文件建模legacy.c4/next.c4/ui.c4。在该目录下执行npx likec4 start即可复现根 README 中演示的源码 → 实时架构图效果。DSL 三段式结构specification / model / views从 examples/cloud-system 的源码可以完整还原 LikeC4 DSL 的组织方式——一个 LikeC4 工程由三类顶层块构成。1. specification定义词汇表_spec.c4 展示了如何自定义元素类型每个类型可以指定记法notation即画在图上的文字标签、默认样式shape / color / opacity / icon等。例如specification { color custom #6BD731 element actor { notation Person style { shape person } } element queue { notation Message queue style { shape queue color secondary icon aws:simple-queue-service } } relationship uses tag deprecated }几个值得注意的扩展点任意自定义元素类型示例中不仅有 C4 常见的actor/system/container还定义了mobileApp带shape mobile与icon tech:swift、gqlMutation/gqlQueryGraphQL 专用元素、lambda等完全自定义的类型——这正是 LikeC4 区别于标准 C4 的核心弹性图标体系icon aws:simple-queue-service这类写法引用的是仓库中体量庞大的图标库 packages/icons其中按aws/、azure/、gcp/、bootstrap/、tech/分类提供了数千个图标aws目录约 300 个、azure600、tech2000CLI 还提供list-icons命令辅助查询见 cli 入口tagstag deprecated等声明可在模型与视图中用于筛选和样式区分。2. model分层嵌套的架构主体model.c4 展示了模型的嵌套能力——system内嵌container元素内还可直接声明指向兄弟元素的关系model { customer actor Cloud System Customer Interacts with the system { description ## Markdown - List item | Column 1 | Column 2 | | -------- | -------- | | Row 1 | Row 1 | } cloud system Cloud System { ui container Frontends { style { shape browser } metadata { version 2.1.1 } } supportUser actor Support User { - customer helps with questions { metadata { rps 1000 } } } } customer .uses cloud uses and pays { navigateTo dynamic-view-1 } }从这份源码可以提炼出模型层的几个关键特性任意深度嵌套cloud system内部直接声明ui、legacy、next、supportUser形成树状结构引用时用点路径cloud.uiMarkdown 描述description支持多行字符串和完整 Markdown列表、代码块、表格渲染到侧边面板自定义 metadata元素与关系都可以挂任意键值如version 2.1.1、rps 1000配合仓库 config 包 中的 metadata 校验模式multi-metadata/extend等参考 examples/metadata-views、examples/multi-metadata-extend可对 metadata 结构做类型化约束关系记法多样-有向关系、 -、element .uses target引用 specification 中声明的关系类型关系上还可为点击元素后跳转哪个视图声明navigateTo实现视图间的导航联动动态视图dynamic viewmodel.c4 的views块中还定义了dynamic view dynamic-view-1用parallel { ... }描述并发调用序列适合表达请求时序类的交互。3. views同一模型多种镜头views.c4 展示了视图层如何用 include/exclude 通配符 局部样式从同一模型切出不同视角views { view cloud of cloud { title The Cloud System include *, ui.*, next.*, legacy.* exclude supportUser, ui.supportPanel, next - legacy style cloud { color sky } style cloud.* { color primary } } view view-with-custom-colors { include *, cloud - * with { color custom } } }要点include *加通配路径可批量纳入子树exclude甚至支持排除特定关系next - legacyelement - * with { ... }语法允许对特定关系的子集单独覆盖样式autoLayout TopBottom/BottomTop可指定布局方向model.c4 中有使用。视图还可用group画分组框、link挂外链、navigateTo做视图跳转。CLI 全景从预览到导出根 README 只演示了npx likec4 start这一条命令而 packages/likec4/README.md 与 CLI 源码 packages/likec4/src/cli/index.ts 揭示了完整的命令面。从源码注册顺序index.ts 第 60-83 行的pipe链可以看到 CLI 实际包含的命令serve、build、codegen、export、format、preview、publish、sync、validate、list-icons、mcp、lsp、check-update外加completion生成 shell 补全脚本。其中最常用的实战命令如下# 预览热更新 likec4 serve # 别名likec4 start / likec4 dev # 构建单页静态站点可部署到任意静态托管 likec4 build -o ./dist # 生成 React 组件用于自定义集成 likec4 codegen react --outfile ./src/likec4.generated.tsx # 导出静态图片内部启动本地服务器并用 Playwright 截图CI 中需注意 Playwright 环境 likec4 export png -o ./assets # 导出/导入 DrawIO复用现有 DrawIO 图或将 LikeC4 视图交给 DrawIO 二次编辑 likec4 export drawio -o ./diagrams likec4 import drawio diagram.drawio -o src/model.c4 # 导出到 Mermaid / Graphviz / D2 / PlantUML likec4 codegen mmd likec4 codegen mermaid likec4 codegen dot likec4 codegen d2 likec4 codegen plantuml此外README 中还介绍了 MCP Server 的启动方式让 LLM 工具链可以直接渲染 LikeC4 视图likec4 mcp # stdio 传输 likec4 mcp --http # http 传输默认端口 33335 likec4 mcp -p 1234 # 指定端口serve与build的实现分别位于 cli/serve 与 cli/export 等目录各导出器drawio / json / markdown / png / jpg则对应 packages/generators 中的独立生成模块——注意 packages/generators/src 下确实包含d2/、drawio/、mmd/、puml/、markdown/、model/等与上述 codegen 子命令一一对应的子目录这从源码结构上印证了同一模型、多目标导出的能力边界。编程 API把架构模型当数据用除了 CLIpackages/likec4/README.md 还给出了 TypeScript API 的完整用法其实现入口是 packages/likec4/src/LikeC4.tsimport { LikeC4 } from likec4 // 从工作区初始化递归搜索并解析目录下所有 .c4 / .likec4 源文件 const likec4 await LikeC4.fromWorkspace(path to workspace, opts) // 或直接从源码字符串初始化 const likec42 await LikeC4.fromSource( specification { element system element user } model { customer user Customer cloud system System } views { view index { include * } }, opts, )初始化后可以查询与遍历模型// 校验错误 console.log(likec4.getErrors()) // 遍历模型取元素 - 查入边关系 - 按 tag 过滤 - 映射出源元素 const model likec4.model() model .element(cloud.backend.api) .incoming() .filter(r r.tags.includes(http)) .map(r r.source) // 获取完成自动布局的视图可用于自渲染 const diagrams await likec4.diagrams()从 LikeC4.ts 的LikeC4Options类型定义可以读出几个关键初始化选项及其默认值选项默认值说明printErrorstrue模型非法时是否把错误打印到控制台设为false可关闭throwIfInvalidfalse设为true时初始化返回 rejected promise配合getErrors()取错误loggerconsole日志输出目标false表示静默graphvizwasm布局引擎选择wasmWebAssembly 版 dot或binary系统 dot 可执行文件watchfalse是否监听工作区变更fromSource场景下不适用logLevel-日志级别trace/debug/info/warning/error这套 API 的实际调用方在仓库内也有真实用例e2e/src/likec4-model.spec.ts 与 e2e/src/likec4-views.spec.ts 分别用fromWorkspace对 e2e/src/likec4 下的示例工程做模型与视图断言是理解 API 行为的现成参考。仓库结构速览工具链由哪些包组成从 monorepo 顶层 package.json 与各包目录可以看出LikeC4 是一条由多包拼装的工具链根版本 1.59.3包管理器 pnpm11.25.0通过 turbo 编排构建包职责packages/core模型构建builder、视图计算compute-view、手动布局、样式与几何计算packages/language-server基于 Langium 的 LSP解析、校验、补全packages/language-services语言服务封装LikeC4.fromSource/fromWorkspace的底层实现来源packages/layouts自动布局算法Graphviz dot 文件生成与布局packages/diagramReact 图表渲染组件xyflow 节点图、导航面板、overlay 等packages/generatorsdrawio / d2 / mmd / puml / markdown / react 等各目标生成器packages/iconsaws / azure / gcp / bootstrap / tech 图标库packages/mcpMCP Server 实现packages/vite-pluginVite 插件把视图嵌入 Vite 应用likec4:react虚拟模块 LikeC4View组件packages/vscodeVS Code 扩展apps/playground、apps/docs在线 Playground 与文档站源码也就是说根 README 宣传的实时图表能力是由 language-server 负责解析、layouts 负责布局、diagram 负责渲染、CLI/Vite 插件/LSP/MCP 负责不同接入形态这条链路共同支撑的。获取帮助与许可证与根 README 一致项目通过 Discord 社区与 GitHub Discussions 提供交流渠道完整贡献流程见 CONTRIBUTING.md项目以 MIT License 开源。小结LikeC4 的核心主张是架构图不是画出来的而是从代码中生成的。它以可自由扩展 notation 与嵌套层级的 DSLspecification 定词汇、model 建结构、views 切视角为骨架用 CLI 提供 serve/build/export/codegen/mcp 等命令覆盖预览、静态站点、PNG 截图、DrawIO 互转、Mermaid/D2/PlantUML 导出等场景再以LikeC4.fromWorkspace/fromSourceAPI 把模型开放为可程序化查询的数据。对需要让架构图随代码持续演进、避免图腐化的团队这是一条可落地的实践路径。【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考