likec4 部署关系双向语法-与-[kind]-完全指南从 DSL 解析到视图计算【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4本文基于 likec4 仓库.changeset/deployment-bidirectional-relations.md变更记录展开该变更v1.59.3 起为部署块deployment {}中的关系引入了-与-[kind]-双向声明语法并同步打通了语言服务器解析、模型构建、指纹去重与视图关系表达式。读完本文你将掌握双向关系的 DSL 写法、语法规则、底层实现原理以及如何在视图谓词中用-/-精确筛选双向关系并了解对应的源码与测试证据。一、变更背景一次面向部署关系的语法增强在 likec4 中关系relationship默认是有向的用-表示n1 - n2表示从n1流向n2的关系。然而在部署模型deployment {}中很多连接天然是双向的——例如两个节点之间的同步sync、副本之间的数据复制、对等组件之间的握手协议。若逐一书写两条反向关系既冗余又容易在视图里画成两条平行箭头。该变更见 .changeset/deployment-bidirectional-relations.md正是在这一背景下落地部署关系支持 v1.59.3 引入的-与-[kind]-双向语法。变更涉及三个包的 patch 级更新变更包影响面likec4/corepatch关系类型新增isBidirectional标志视图计算按双向语义处理likec4/language-serverpatchDSL 语法解析、模型构建与校验支持双向连接符likec4/generatorspatch生成器如 React/views-data-ts输出中保留双向语义仓库根CHANGELOG.md对应 packages/language-server/CHANGELOG.md对同版本更早引入的模型层能力做了更完整描述允许模型关系使用文档化的-和-[kind]-语法并通过样式与关系扩展relationship extension保留双向语义同时在视图关系表达式中可从任一端点 include/exclude 它们。二、双向关系语法两种写法一处语义在部署块中声明双向关系有两种等价写法写法一无类型双向关系deployment { node n1 node n2 n1 - n2 }写法二带关系类型kind的双向关系specification { deploymentNode node relationship sync } deployment { node n1 node n2 n1 -[sync]- n2 }-[kind]-中kind引用的是specification {}里用relationship关键字声明的关系类型RelationshipKind与有向写法-[kind]-保持一致的引用规则。语法规则细节完整的语法验证用例位于 packages/language-server/src/tests/deployment.spec.ts其中两个.valid测试确认了以上两种写法都能通过解析与校验。双向关系同样支持标题、描述、技术标签等后缀deployment { node n1 node n2 n1 - n2 syncs 同步主备状态 }三、底层实现Langium 语法中的双向连接符语法层面的支持定义在语言服务器使用的 Langium 文法文件 packages/language-server/src/like-c4.langium 中。模型关系与部署关系共用同一个连接符片段fragmentfragment RelationConnector: dotKindRelationKindDotRef | -[ kind[RelationshipKind] (isBidirectional?]- | ]-) | isBidirectional?- | - ;对应 like-c4.langium。可以看到isBidirectional?-可选的双向标记解析成功后会在 AST 上置位isBidirectional-[ kind... (isBidirectional?]- | ]-)带 kind 的双向写法被拆解为-[kind]-其中]-使isBidirectional置位而]-维持有向语义。视图关系表达式view predicate中也提供了独立的双向支持同文件 like-c4.langiumOutgoingRelationExpr: fromFqnExpr (isBidirectional?- | dotKindRelationKindDotRef | - | -[ kind[RelationshipKind:Id] ]-) ;即视图过滤里也可直接书写a - b来表达取 a 与 b 之间的双向关系或a - b表达有向关系。模型构建后的数据结构部署关系解析后构建为带isBidirectional: true标志的关系对象。deployment.spec.ts中的构建断言deployment.spec.ts验证了{ source: { deployment: n1 }, target: { deployment: n2 }, title: syncs, isBidirectional: true, tail: normal, }注意tail: normal——双向关系可以同时携带箭头样式tail arrow说明在渲染上它拥有独立的尾部箭头表达能力而不是简单退化为单向。四、指纹去重双向关系的规范化由于双向关系本质上是一条关系而非两条反向关系的叠加其关系 ID指纹必须与方向无关。实现在 packages/language-server/src/model/relationFingerprint.tsif (isBidirectional targetKey sourceKey) { const normalizedSource targetKey targetKey sourceKey sourceKey normalizedSource } return stringHash( extend-relation, sourceKey, targetKey, kind ?? default, title ?? , isBidirectional ? bidirectional : directed, )关键点端点排序规范化当isBidirectional为真时source/target按字典序交换保证n1 - n2与n2 - n1得到同一个 ID语义标签参与哈希哈希串末尾显式区分bidirectional与directed避免双向关系与同端点、同 kind、同 title 的有向关系发生 ID 冲突该函数同时服务于模型关系与部署关系FqnRef.flatten统一处理两类端点因此关系扩展extend、样式继承等机制可以稳定地命中同一条双向关系。五、视图计算双向关系从两端都可入图双向关系在视图中的行为由likec4/core的视图计算负责。专项测试 packages/core/src/compute-view/deployment-view/test/relation.bidirectional.spec.ts 用rel(prod.n1, prod.n2, { title: syncs, isBidirectional: true })构造了模型并验证了四个关键行为测试场景视图谓词断言结果从声明终点入图include(prod.n1)include(- prod.n2)得到边prod.n1 - prod.n2从声明起点入图include(prod.n2)include(- prod.n1)同样得到边prod.n1 - prod.n2单向关系保持入向语义对单向关系prod.n1 - prod.n3从 n3 写include(- prod.n1)不产生边从声明起点排除exclude(- prod.n1)双向关系被排除结论很明确双向关系在视图谓词里无论从声明的哪一端书写-入向表达式都能命中同一条边而单向关系依然只认自己的入向。这与双向关系本质是一条无向语义边的模型完全一致。六、关联的生成器与样式语义由于本变更同时作用于likec4/generators生成链路如把视图数据导出为 React/TS 数据或 DrawIO会原样携带isBidirectional标志绘图侧见 packages/generators/src/drawio/parse-drawio.ts 等对 bidirectional 的处理可据此绘制双向箭头。样式规则也能通过关系扩展命中同一条双向关系从而保证声明一次样式、过滤、渲染处处一致。在仓库示例与端到端测试中可找到可直接运行的双向关系场景例如 examples/cloud-system/deployment.c4 与 e2e/src/likec4/deployment.c4可作为学习或回归验证的素材。七、从 v1.59.3 迁移与使用建议适用版本本能力随 v1.59.3 发布升级likec4/core、likec4/language-server、likec4/generators至该版本及以上即可使用使用场景部署节点之间的对等同步、复制、心跳、对等协议等无方向差异的连接优先用-避免维护两条互为反向的重复关系视图筛选入向表达式- x会自动命中双向关系的两端无需为每条双向关系额外维护两条谓词与样式/扩展的配合双向关系通过规范化指纹保持稳定 ID关系扩展relationship extend与样式规则可直接作用于它无需区分声明方向。八、总结-与-[kind]-是 likec4 部署模型表达无方向连接的规范语法Langium 文法在解析层置位isBidirectional标志like-c4.langium模型构建产出带tail: normal的双向关系对象deployment.spec.ts指纹层按端点字典序规范化保证方向无关的稳定 IDrelationFingerprint.ts视图计算层从任一端入向均可命中relation.bidirectional.spec.ts。这套从 DSL 到渲染的全链路支持让部署关系表达更简洁、语义更准确也让视图与样式维护成本随之降低。【免费下载链接】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），仅供参考