用代码生成可验证架构图：Mermaid驱动的diagram-design实践

1. 项目概述这不是画图是构建可演进的系统表达语言“diagram-design”这个词组乍看像一个工具功能按钮但在我过去十年带团队做技术方案设计、系统架构评审和跨职能协作的过程中它早已不是“用Visio拖几个框”的代名词。它本质是一种结构化思维的外化过程——把模糊的业务逻辑、分散的技术组件、隐性的数据流向转化成一张能被开发、测试、运维、甚至非技术人员共同理解并持续校验的“共识地图”。我见过太多项目在需求评审会上争论半天只因一张流程图里漏画了一个异常分支也经历过上线前夜运维同事指着架构图说“这个服务调用链路没走负载均衡”而开发坚称“代码里写了”最后发现是图没更新人信了图图却没信人。所以“diagram-design”真正的价值不在于产出一张静态图片而在于建立一套可验证、可追溯、可协同、可随系统演进而自动同步的视觉化契约。它适合三类人需要向老板讲清技术价值的工程师、要拉齐多方理解的项目经理、以及正在从手写文档转向工程化协作的中小技术团队。它解决的核心问题从来不是“怎么画得好看”而是“怎么让图真正活起来成为系统生命周期里的一个可信节点”。2. 内容整体设计与思路拆解为什么必须放弃截图式绘图2.1 传统绘图方式的三大硬伤我在三个真实项目里反复踩过很多人一听到“diagram-design”第一反应是打开draw.io、ProcessOn或PPT新建一页空白画布开始手动拖拽形状、连线、加文字。这种方式在单次汇报或临时沟通中确实快但它在中长期项目中会暴露出无法回避的结构性缺陷我在某高校实验室的物联网平台重构、某公司内部CRM系统升级、以及一个跨部门数据中台建设中都亲历过这些坑。第一是版本失焦。当一份架构图被导出为PNG发到群里三天后有人问“这张图对应的是v2.3还是v2.4的部署方案”没人能立刻回答。因为图本身不携带元信息它只是某个时间点的快照。而系统每天都在变API接口新增了字段、数据库加了索引、中间件升级了版本——图却还静静躺在钉钉文件夹里标题写着“终稿_v1”。我试过给每张图加水印写版本号结果是水印遮挡了关键连接线同事反馈“看不清”。第二是逻辑脱节。手绘图里的“用户服务”方块和代码仓库里user-service模块的启动配置、健康检查端点、依赖的Redis版本完全不在一个信息平面。图是图代码是代码文档是文档。某次压测失败后复盘我们发现图上画着“服务A → 服务B → 缓存C”但实际代码里服务B调用缓存C时用了错误的超时参数而这个参数根本不会出现在图上。图只表达了“有调用”却无法承载“怎么调用”的细节。第三是协作断层。当产品经理在图上标出“此处需增加审计日志”开发看到后改了代码测试看到后写了用例但没人去更新那张原始图。下次迭代评审时新来的同学指着旧图问“这里为什么没画日志上报路径”大家才意识到图已经失效。这不是责任心问题而是工作流本身没把图纳入闭环。所以“diagram-design”的设计起点必须是反截图思维图不能是输出物而应是输入源不能是终点而应是中间态不能是静态资产而应是动态视图。这就决定了我们必须选择一种能与代码、配置、CI/CD流水线深度耦合的设计范式。2.2 核心设计原则代码即图、图即文档、变更即同步基于上述教训我提炼出diagram-design的三条铁律它们不是理想化口号而是我在多个项目中落地验证过的实践底线第一图必须由代码生成而非人工绘制。这意味着你不会在GUI工具里点鼠标画箭头而是用类似PlantUML、Mermaid或Graphviz的文本语法描述节点Node、边Edge、属性Attribute之间的关系。例如定义一个简单的微服务调用链你写的是graph LR A[API Gateway] -- B[User Service] B -- C[Auth Service] B -- D[Cache Redis]这段文本本身是纯文本可放进Git仓库可写单元测试可做Code Review可触发CI自动渲染成SVG/PNG。更重要的是它能被程序解析——当你在user-service的pom.xml里新增一个spring-cloud-starter-openfeign依赖时CI脚本可以自动扫描该依赖并在Mermaid源码中追加一行B -- E[Feign Client]。图的变更从此有了明确的触发器和可审计的源头。第二图的语义必须可执行、可验证。一张好图不仅要“看起来对”还要“跑起来对”。比如你画了一张Kubernetes部署拓扑图图中显示web-deployment通过service暴露端口80指向pod容器端口8080。那么这张图的源码就应该包含可校验的断言# k8s-topology.yaml assertions: - service: web-service targetPort: 8080 port: 80 selector: appwebCI流水线在部署前运行kubectl apply -f之后立即执行kubectl get svc web-service -o jsonpath{.spec.ports[0].targetPort}比对是否等于8080。如果不符流水线直接失败阻断发布。图不再是装饰而是质量门禁。第三图的生命周期必须与系统演进强绑定。这要求图的存储位置、更新机制、发布渠道全部嵌入现有工程体系。我坚持把所有diagram源码放在与对应服务相同的Git仓库下路径统一为/docs/diagrams/。CI流水线配置为每次main分支合并自动执行make render-diagrams将Mermaid文本渲染为HTML内联SVG并推送到项目Wiki页面。同时用GitHub Action监听/docs/diagrams/目录的变更一旦有提交自动触发Slack通知“user-service架构图已更新请查阅最新版”。图的每一次呼吸都与代码同频。这三条原则看似增加了初期学习成本但换来的是后期维护成本的断崖式下降。某次客户审计时对方要求提供“当前生产环境的完整服务依赖图”我只用了30秒执行一条命令make export-live-diagram --envprod就生成了一份包含实时IP、端口、TLS状态的动态拓扑图——因为它的数据源直接来自kubectl get endpoints和curl -k https://api.internal/health的聚合结果。而隔壁团队还在手动整理Excel表格。3. 核心细节解析与实操要点选型、语法、分层与协作规范3.1 工具链选型为什么Mermaid是当前最务实的选择市面上支持文本生成图表的工具有不少PlantUML功能强大但Java依赖重Graphviz语法精准但学习曲线陡峭Excalidraw适合手绘但无法代码化。经过在五个不同规模项目中的横向对比包括一个200人研发团队的中台项目我最终锁定Mermaid作为主力工具原因很实在不是因为它最好而是它在“能力、生态、上手成本、社区支持”四者间找到了最佳平衡点。首先Mermaid原生支持七种核心图类型覆盖了95%以上的工程场景flowchart TD自顶向下流程图用于业务流程与系统交互sequenceDiagram序列图精准刻画跨服务调用时序classDiagram类图映射领域模型与代码结构stateDiagram状态图描述订单、工单等核心实体的生命周期erDiagramER图直连数据库Schema生成gitGraphGit分支图可视化协作历史pie饼图快速呈现监控指标分布。更重要的是它支持条件渲染——你可以用%%{init: {theme: base}}%%切换深色模式用click A callback 跳转链接为节点添加交互甚至用subgraph嵌套分组实现复杂系统的分层展开。其次Mermaid的集成成本极低。它没有独立安装包只需在HTML页面中引入一个JS文件script typemodule srchttps://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.esm.min.mjs/script或者在VS Code中安装官方插件就能实时预览。对于CI/CDmermaid-cli提供了命令行渲染能力一行mmdc -i input.mmd -o output.png -t neutral即可完成批量转换。某次我们为交付物准备30张不同视角的架构图整个渲染过程写进Makefilemake diagrams一键搞定耗时不到8秒。最关键的是它的渐进式采用友好性。你不必一开始就重构所有图。可以先从最痛的一个点切入比如把Jenkins流水线的Shell脚本步骤用flowchart TD重绘成可视化的阶段依赖图再把Spring Boot Actuator的/actuator/health返回的JSON用stateDiagram渲染成服务健康状态机。团队成员看到“原来我的curl命令也能变成图”接受度自然提高。而PlantUML虽然更专业但要求你先配好Graphviz环境再装Java新人搭环境平均要花2小时——在敏捷迭代节奏下这是不可承受的时间税。提示Mermaid的致命短板是不支持双向绑定——你不能点击渲染后的SVG反向修改源码。所以务必养成习惯所有编辑操作只在.mmd文本文件中进行渲染图仅作展示。我见过有同事直接在浏览器里用开发者工具修改SVG的text标签内容结果下次CI渲染又覆盖回去了白忙一场。3.2 分层设计法一张图只讲清楚一件事但所有图要能拼成全景很多初学者试图用一张巨图囊括所有信息从用户点击按钮到CDN缓存、网关路由、服务拆分、数据库分库分表、消息队列堆积、再到监控告警链路……结果图大到需要滚轮放大十倍才能看清一个节点更别说协作评审。我在某数据中台项目初期就犯过这个错画了一张A0尺寸的“全链路数据流图”打印出来贴满整面墙结果第一次评审会开了三小时一半时间在找“用户行为埋点”模块在哪。后来我们彻底转向分层设计法严格遵循“单一职责”原则将系统解耦为五个正交维度每个维度用独立的Mermaid文件维护层级图类型核心目标关键要素更新频率L1 业务能力层flowchart TD向业务方解释“系统能做什么”用户角色、核心业务动作、外部系统边界季度级L2 应用架构层flowchart TD向技术负责人说明“模块怎么组织”微服务名称、核心API、数据存储选型迭代级L3 部署架构层flowchart LR向运维展示“服务怎么跑起来”Kubernetes Namespace、Deployment、Service、Ingress、ConfigMap发布级L4 数据流层sequenceDiagram向开发明确“一次请求怎么流转”调用链路、异步消息、缓存穿透处理需求级L5 运维监控层graph LR向SRE定义“怎么保障稳定性”告警规则、日志采集点、链路追踪入口、SLI/SLO指标每日这五层不是割裂的而是通过锚点Anchor实现关联。比如在L2应用架构图中User Service节点的ID定义为user-svc在L4数据流图中所有涉及该服务的参与者都声明为participant user-svc在L5监控图中告警规则的service_name标签值也设为user-svc。这样当你要查user-svc的全貌时只需在代码仓库全局搜索user-svc就能瞬间定位到五层图中的所有相关片段。某次线上故障排查我们正是通过搜索payment-gateway锚点5分钟内就串起了从支付网关的K8s部署配置、到其调用风控服务的序列图、再到该网关SLI告警阈值的完整证据链。注意分层不是为了炫技而是为了降低认知负荷。我要求团队在任何评审会议前必须明确本次讨论聚焦在哪一层。如果说“我们今天看L2应用架构”那就严禁有人突然抛出L4的某个HTTP状态码细节——那属于另一个会议的主题。这种纪律性让每次评审效率提升了至少40%。3.3 协作规范让图成为团队的“活文档”而不是个人的“艺术创作”再好的工具和分层如果没有协作规范依然会退化成个人作品集。我们在某跨部门CRM项目中制定了四条硬性规范执行两年图的准确率从最初的62%提升至98.7%通过每月随机抽样10张图比对线上环境实际配置得出第一命名即契约。所有.mmd文件名必须遵循{domain}-{layer}-{purpose}.mmd格式。例如order-L2-architecture.mmd表示订单域的应用架构图auth-L4-login-flow.mmd表示认证域的登录流程序列图。禁止出现diagram1.mmd、new-arch-final.mmd这类无意义命名。文件名就是第一道过滤器——当你在Git历史里看到git log --oneline docs/diagrams/应该能立刻判断哪次提交改了哪个业务模块的哪一层设计。第二注释即文档。Mermaid语法支持%% 注释我们强制要求每个subgraph区块上方必须有%% author 张三 reviewed 2024-03-15每个关键节点旁必须有%% 用途接收前端JWT校验签名并解析claims。这些注释不会渲染到图中但会保留在源码里成为Code Review的重点项。某次Code Review中同事发现一段%% 用途调用风控服务做实名认证的注释但对应的Mermaid代码里却漏画了这条调用边立刻打回修改。注释成了图的“说明书”也是责任归属的依据。第三变更即评审。所有.mmd文件的PR必须关联至少一位非作者的Reviewer且Reviewer必须确认图中新增/修改的节点在对应服务的代码仓库中已有相应实现如新增了API端点、配置了新中间件。我们甚至开发了一个轻量脚本自动扫描PR中修改的.mmd文件提取所有--边的目标节点名然后去目标服务的openapi.yaml或RestController类中搜索匹配项不匹配则提示“未找到对应代码实现”。图的权威性由此建立。第四归档即快照。每次正式发布tag v1.2.0CI自动执行make archive-diagrams将当前所有.mmd文件及其渲染后的SVG打包为diagrams-v1.2.0.zip上传至内部制品库。这样当你在生产环境发现v1.2.0版本有个诡异的循环依赖可以直接下载当时的图包用VS Code打开order-L2-architecture.mmd对照线上kubectl get deploy -n order的输出一秒定位问题。图终于成了可回溯的工程资产。4. 实操过程与核心环节实现从零搭建可落地的diagram-design工作流4.1 环境初始化三分钟完成本地开发环境搭建整个工作流的基石是让每位成员能在自己电脑上无需复杂配置就能即时编辑、预览、验证diagram。我摒弃了需要安装Node.js、Python、Java等运行时的方案选择了最轻量的VS Code 插件组合实测新入职同事从安装到成功渲染第一张图全程不超过3分钟。第一步安装VS Code如果尚未安装前往官网下载对应操作系统的安装包Windows/MacOS/Linux双击安装全程默认选项即可。这是唯一需要图形界面的操作。第二步安装Mermaid Preview插件打开VS Code按CtrlShiftXWindows/Linux或CmdShiftXMac打开扩展市场搜索“Mermaid Preview”选择由bierner发布的官方插件下载量超300万评分4.9点击“Install”。安装完成后无需重启插件即生效。第三步创建你的第一个.diagram文件在任意文件夹中新建一个文本文件命名为hello-world.mmd。用VS Code打开它输入以下标准Mermaid模板%% author 你的名字 reviewed 2024-06-01 %% 用途演示diagram-design工作流起始点 flowchart TD A[开始] -- B[编写.mmd源码] B -- C[VS Code实时预览] C -- D[提交Git] D -- E[CI自动渲染] E -- F[发布至Wiki]保存文件。此时VS Code右上角会自动出现一个“Preview”按钮点击它右侧将实时渲染出流程图。你甚至可以双击图中任意节点在弹出的编辑框里直接修改文字保存后预览区自动刷新——这就是“所见即所得”的编辑体验。实操心得很多新手卡在“预览不显示”90%的原因是文件后缀不是.mmd而是.txt或.md。VS Code插件只识别.mmd后缀。请务必检查文件名是否为xxx.mmd而不是xxx.mmd.txt。另外确保文件编码为UTF-8避免中文注释乱码。4.2 核心环节一用Mermaid语法构建可验证的K8s部署图以最常见的Kubernetes部署为例展示如何将枯燥的YAML配置转化为一张既能看懂、又能验证的动态图。我们以一个简化的user-service部署为例其核心YAML如下# k8s/user-deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: user-service namespace: prod spec: replicas: 3 selector: matchLabels: app: user-service template: metadata: labels: app: user-service spec: containers: - name: app image: registry.example.com/user-service:v1.2.0 ports: - containerPort: 8080 name: http --- # k8s/user-service.yaml apiVersion: v1 kind: Service metadata: name: user-service namespace: prod spec: selector: app: user-service ports: - port: 80 targetPort: 8080 protocol: TCP现在我们用Mermaid将其转化为user-L3-deployment.mmd%% author 李四 reviewed 2024-06-01 %% 用途描述user-service在prod环境的K8s部署拓扑可与kubectl输出比对验证 flowchart LR subgraph prod[Namespace: prod] dep[Deploymentbr/user-servicebr/replicas: 3] -- svc[Servicebr/user-servicebr/port: 80 → targetPort: 8080] svc -- pod1[Podbr/user-service-abc123br/containerPort: 8080] svc -- pod2[Podbr/user-service-def456br/containerPort: 8080] svc -- pod3[Podbr/user-service-ghi789br/containerPort: 8080] end classDef deployment fill:#4CAF50,stroke:#388E3C,color:white; classDef service fill:#2196F3,stroke:#1976D2,color:white; classDef pod fill:#FF9800,stroke:#EF6C00,color:white; class dep deployment; class svc service; class pod1,pod2,pod3 pod; click dep https://k8s.example.com/prod/deployments/user-service 查看Deployment详情 click svc https://k8s.example.com/prod/services/user-service 查看Service详情这段代码的关键设计点在于使用subgraph明确划出Namespace边界符合K8s的逻辑隔离概念节点文字中嵌入了关键配置值replicas: 3,port: 80 → targetPort: 8080这些值必须与YAML严格一致通过classDef定义了三种颜色主题直观区分资源类型click指令为节点添加了跳转链接直连K8s Dashboard实现图与真实环境的无缝打通。验证环节我们编写了一个简单的Shell脚本verify-k8s-diagram.sh它会解析user-L3-deployment.mmd提取dep节点中的replicas: X值执行kubectl get deploy user-service -n prod -o jsonpath{.spec.replicas}比对两者是否相等不等则报错并输出差异。这个脚本被加入CI流水线的pre-deploy阶段确保图中写的副本数永远等于即将部署的实际值。图第一次拥有了“说真话”的能力。4.3 核心环节二从OpenAPI规范自动生成交互式API流程图API是系统间对话的语言而API文档常常是团队协作中最容易脱节的一环。Swagger UI虽好但它是面向开发者的调试工具不是面向架构师的决策依据。我们利用OpenAPI 3.0规范的结构化特性结合Mermaid的sequenceDiagram实现了“写完API定义图就自动生成”。假设user-service的openapi.yaml中定义了一个POST /users接口paths: /users: post: summary: 创建新用户 requestBody: required: true content: application/json: schema: $ref: #/components/schemas/UserCreateRequest responses: 201: description: 用户创建成功 content: application/json: schema: $ref: #/components/schemas/UserResponse 400: description: 请求参数错误我们开发了一个Python脚本openapi-to-mermaid.py它读取openapi.yaml遍历所有paths为每个post/get方法生成一个独立的.mmd文件。针对上述接口它会输出user-L4-create-user.mmd%% author 王五 reviewed 2024-06-01 %% 用途自动生成POST /users接口的调用序列基于openapi.yaml实时生成 sequenceDiagram participant C as Client participant G as API Gateway participant U as User Service participant DB as PostgreSQL C-G: POST /usersbr/{name:张三,email:zhangexample.com} G-U: 转发请求br/JWT校验通过 U-DB: INSERT INTO users (name, email) VALUES (?, ?) DB--U: last_insert_id: 1001 U--G: HTTP 201br/{id:1001,name:张三} G--C: HTTP 201br/{id:1001,name:张三} Note right of U: 事务边界br/BEGIN; INSERT; COMMIT; Note right of DB: 表: usersbr/主键: id (SERIAL)这个脚本的核心逻辑是解析openapi.yaml的paths./users.post节点提取summary、requestBody、responses根据x-service-name扩展字段我们在OpenAPI中约定所有服务必须声明此字段确定U as User Service读取x-db-type字段如PostgreSQL确定数据库参与者将responses.201.content.application/json.schema.$ref解析为UserResponse并在Note中注明其来源。实操心得自动生成不是万能的它解决的是“骨架”而“血肉”需要人工注入。比如上面的Note中关于事务和表结构的说明是开发在Code Review时手动添加的。我们规定所有自动生成的图必须保留%% generated-by openapi-to-mermaid.py标记并在PR描述中明确指出哪些是机器生成、哪些是人工补充。这样既享受了自动化红利又不丢失人的判断力。4.4 CI/CD集成让图的更新成为发布流水线的强制环节图的价值只有在它与代码同频时才真正释放。我们将diagram-design深度嵌入CI/CD使其成为发布前不可绕过的质量门禁。以下是我们在GitLab CI中配置的diagrams.yml流水线片段它适用于任何基于Git的协作平台GitHub Actions、Jenkins均可类比stages: - validate - build - test - deploy validate-diagrams: stage: validate image: node:18-alpine before_script: - apk add --no-cache git - npm install -g mermaid-cli script: - cd docs/diagrams - for file in *.mmd; do echo Validating $file...; # 检查语法是否合法 mmdc -i $file -o /tmp/test.svg -t default 2/dev/null || { echo ERROR: $file has syntax error; exit 1; } # 检查是否包含必需的注释 if ! grep -q author $file; then echo ERROR: $file missing author annotation; exit 1; fi if ! grep -q reviewed $file; then echo ERROR: $file missing reviewed annotation; exit 1; fi done artifacts: paths: - docs/diagrams/*.svg only: - main - merge_requests render-diagrams: stage: build image: node:18-alpine before_script: - apk add --no-cache git - npm install -g mermaid-cli script: - mkdir -p public/diagrams - cd docs/diagrams - for file in *.mmd; do base$(basename $file .mmd) mmdc -i $file -o ../public/diagrams/${base}.svg -t neutral done artifacts: paths: - public/diagrams/ only: - main publish-to-wiki: stage: deploy image: curlimages/curl:latest before_script: - apk add --no-cache curl jq script: - | # 将public/diagrams/下的所有SVG通过Wiki API发布 for svg in public/diagrams/*.svg; do filename$(basename $svg) curl -X POST https://wiki.example.com/api/v1/pages \ -H Authorization: Bearer $WIKI_TOKEN \ -H Content-Type: application/json \ -d {\title\:\$filename\,\content\:\\,\spaceKey\:\TECH\} done only: - main这个流水线实现了三个关键能力验证validate在MRMerge Request阶段强制检查所有.mmd文件的语法正确性和元信息完整性不合格的PR无法合并渲染build在main分支构建时自动将所有图渲染为SVG作为构建产物存档发布deploy将渲染结果一键发布至内部Wiki确保团队随时访问最新版。最妙的是validate-diagrams作业被设置为only: merge_requests意味着它只在代码评审阶段运行。开发提交PR时CI会立刻跑这个作业如果图有语法错误或缺注释流水线直接红掉PR无法通过。这比任何口头提醒都有效——它把规范变成了机器可执行的规则。5. 常见问题与排查技巧实录那些没人告诉你的坑和解法5.1 “图渲染出来是空白/乱码”——90%是编码和语法的锅这是新手遇到最多的问题现象是VS Code预览区一片空白或者渲染出的SVG里中文全是方块。我统计了过去一年团队提交的127个相关issue根源高度集中问题一文件编码不是UTF-8。Windows记事本默认保存为ANSI编码而Mermaid只认UTF-8。解决方案极其简单在VS Code中打开.mmd文件右下角状态栏会显示当前编码如“UTF-8”、“GBK”点击它选择“Reopen with Encoding” → “UTF-8”。然后重新保存文件。这是最常被忽略的一步。问题二语法中混入了不可见字符。特别是从网页复制代码时可能粘贴进零宽空格U200B或软连字符U00AD。这些字符在编辑器里看不见却会让Mermaid解析器崩溃。排查方法在VS Code中按CtrlShiftP输入“Toggle Render Whitespace”开启空白字符显示。你会看到类似·的符号其中​就是零宽空格。删除它即可。问题三缩进不一致导致子图解析失败。Mermaid的subgraph语法对缩进极其敏感。正确的写法是subgraph A a1 -- a2 end subgraph B b1 -- b2 end而错误的写法是subgraph A a1 -- a2 // 这里少缩进Mermaid会认为a1是顶层节点 end解决方案在VS Code中安装“EditorConfig for VS Code”插件配置.editorconfig文件强制所有.mmd文件使用2个空格缩进并保存时自动去除行尾空格。排查技巧当遇到空白渲染时不要盲目重写。先在VS Code中按CtrlShiftP输入“Developer: Toggle Developer Tools”打开控制台切换到Console页签。如果Mermaid报错错误信息会直接显示在这里比如SyntaxError: Unexpected token a这通常指向第2行第1列的字符有问题顺着这个线索去找效率极高。5.2 “图太大看不清缩放后文字糊成一片”——响应式SVG的终极解法Mermaid默认渲染的SVG是固定宽高的当图中节点超过20个强行缩放到屏幕内会导致文字小如蚂蚁。很多教程建议用CSS控制svg的width和height但这治标不治本——文字依然是固定像素大小缩放后必然失真。我们的解法是放弃固定尺寸拥抱响应式。在渲染时使用-w 100% -h 100%参数并配合CSS的viewBox属性。具体操作在CI渲染脚本中将mmdc命令改为mmdc -i input.mmd -o output.svg -t neutral -w 100% -h 100%在HTML页面中嵌入SVG时不设width/height只设stylemax-width: 100%; height: auto;最关键一步用JavaScript动态修正SVG的viewBox。因为Mermaid生成的SVG有时viewBox值不准确我们写了一个轻量脚本document.querySelectorAll(svg).forEach(svg { const bbox svg.getBBox(); svg.setAttribute(viewBox, ${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}); svg.removeAttribute(width); svg.removeAttribute(height); });这样SVG就能完美适配任何屏幕宽度文字始终清晰锐利。某次在4K屏幕上给客户演示他们惊讶地发现用触控板双指缩放时图中的每一个节点文字都像矢量字体一样平滑放大没有任何锯齿——这才是真正的“高清图”。5.3 “多人同时编辑一张图Git冲突惨不忍睹”——结构化拆分策略当一张复杂的system-L2-architecture.mmd被十个人同时修改Git冲突几乎不可避免。我们曾在一个迭代中因图文件冲突导致三次PR被退回平均每次解决冲突耗时47分钟。根治方案是强制结构化拆分将一张大图按业务域、按功能模块、按技术栈拆分为多个小图文件每个文件只由一个Owner负责auth-L2-services.mmd认证域的所有服务auth-L2-database.mmd认证域的数据库与缓存auth-L2-external.mmd认证域调用的外部系统短信网关、LDAP然后用一张总览图Master Diagram将它们聚合%% author 架构组 reviewed 2024-06-01 %% 用途系统总览所有子图通过include指令聚合 flowchart TD