diagram-design：构建人机共读的系统逻辑快照

1. 项目概述：这不是画图，是构建可执行的系统逻辑骨架

“diagram-design”这个词组乍一看像某个设计软件里的菜单项，但在我过去十年带过的几十个跨领域项目里，它从来不是指用鼠标拖拽几个方块再连几条线那么简单。真正让我反复被客户深夜电话叫醒、被开发团队拉着改第三版的，永远是那些表面安静、实则暗流涌动的 diagram——它们是需求说明书的具象化翻译器，是程序员写代码前必须对齐的“共同语言”，更是上线后排查问题时最可靠的路线图。我试过用在线白板随手画，也试过让UI同事用Figma精修，结果无一例外：前端说“这箭头没标清楚数据流向”，后端问“这个菱形判断条件到底走哪条分支”，测试同学直接甩来截图：“文档里写的‘超时重试’，图上根本没体现”。后来我才明白，“diagram-design”的核心从来不是美观或工具，而是如何把模糊的业务意图，压缩成一张人机共读、零歧义、可验证的逻辑快照。它适合三类人：需要把想法快速落地的产品经理、常被需求变更搞崩溃的开发工程师、以及总在验收阶段才发现理解偏差的测试与运维人员。如果你还在用Word写流程、靠口头对齐状态、或者把UML图当成装饰画贴在Confluence首页——那这张图，就是你团队协作效率的第一个漏斗。

2. 内容整体设计与思路拆解：为什么放弃“画得漂亮”，选择“读得清楚”

很多人一上来就纠结工具：该用draw.io还是Lucidchart？要不要买PlantUML插件？其实工具只是容器，真正决定成败的是底层设计逻辑。我见过最典型的失败案例，是某电商促销系统重构时，团队花两周用Visio做出一套“教科书级”UML序列图：泳道清晰、消息箭头标准、生命线标注完整。结果开发到支付回调模块时卡了三天——因为图里所有“异步通知”都画成了同步实线箭头，而实际架构中，订单服务和风控服务之间走的是Kafka消息队列，根本不存在阻塞等待。问题出在哪？不是工具不行，是设计时默认套用了“传统Web请求”的思维惯性，忽略了分布式系统的本质特征。

所以我的设计思路非常明确：先锁定“谁必须看懂这张图”，再反推“图上每个元素必须承载什么信息量”。比如给运维看的部署图，IP地址、端口、TLS开关状态比服务器图标样式重要十倍；给产品看的状态机图，用户能触发的动作、系统必然响应的结果，比状态圆角半径重要百倍。这就引出了三个硬性设计原则：

第一，强制标注“不可省略的上下文”。任何连接线必须带文字标签，且标签不能是“调用”“处理”这类动词，而要是“校验用户余额≥订单金额”“返回HTTP 403并记录风控日志”这种可执行语句。我试过用颜色区分，结果新来的实习生说“蓝色是不是代表优先级高？”，立刻废掉——文字才是唯一不骗人的载体。

第二，主动暴露“被隐藏的假设”。比如画API交互图时，我会在角落加一个灰色虚线框，里面写：“假设网络延迟<200ms，超时阈值设为800ms；若超时，客户端自动重试3次，间隔指数退避”。这看起来像备注，其实是把开发时默认踩的坑提前钉在图上，避免后期扯皮。

第三，拒绝“静态快照”，拥抱“版本锚点”。每张图右下角必须有两行小字：一行是关联的需求ID（如PRD-2024-087），另一行是生成时间戳（精确到分钟）。去年我们有个支付对账异常，翻出三个月前的时序图，发现当时标注的“对账文件生成时间=交易完成+5分钟”已被悄悄改成“+15分钟”，但文档没更新。没有时间戳，你永远不知道手里的图是哪个时空的产物。

这套思路不是凭空想的。它来自一次血泪教训：某金融接口项目上线后，因一笔跨境支付失败，三方团队拉会复盘。法务说合同约定“T+1清算”，技术说系统配置是“T+0实时清算”，运营拿出邮件说“客户要求T+0”。最后翻出最初的设计图，发现当时在“清算周期”旁手写了“按监管要求T+1，但客户试点期临时开放T+0”，还画了个小星星。这张图成了唯一能还原决策链的证据。从那以后，我把“可追溯性”列为diagram-design的第一性原理。

3. 核心细节解析与实操要点：从线条、形状到语义的毫米级控制

很多人以为画图就是选形状、拉连线、填文字，但真正拉开专业差距的，恰恰是那些被忽略的毫米级细节。我整理了六类高频踩坑点，每一条都对应着真实项目里至少三次返工。

3.1 连接线不是“线”，是“协议声明”

连接线在diagram-design里绝非视觉装饰。它必须携带三重信息：方向性、可靠性、语义约束。比如两个服务之间的连线，如果只画单向箭头，等于默认“单向通知”，但现实中可能是“请求-响应”配对。我的做法是：用实心箭头表示强依赖（A必须等B返回才继续），空心箭头表示弱依赖（A发完就走，B异步处理），双线箭头表示双向RPC。更关键的是在线旁标注协议类型，比如“gRPC over TLS 1.3”或“REST/JSON POST /v1/notify”。曾有个物流系统，图上所有服务间连线都标着“HTTP”，结果压测时发现，运单查询走的是HTTP/1.1，而轨迹推送却用了HTTP/2的Server Push，但图上完全没体现——导致前端在做长连接保活时，按HTTP/1.1逻辑写了心跳包，结果HTTP/2通道直接被服务端静默关闭。后来我们强制规定：凡涉及网络协议，必须标注主版本号，HTTP/1.1和HTTP/2在图上是两种完全不同的连接类型。

3.2 形状不是“图标”，是“责任边界声明”

矩形、圆角矩形、圆柱体这些基础形状，在diagram-design里承担着严格的语义职责。我坚持用一套极简但不容妥协的规范：

• 直角矩形：仅用于表示“有明确输入输出接口的独立组件”，比如微服务、SDK、第三方API。它的四条边代表契约边界，内部绝不画任何子模块。
• 圆角矩形：专属于“状态容器”，比如用户会话、购物车、缓存实例。它的圆角象征状态的流动性，内部可以标注当前值（如“cart_status=unpaid”）。
• 圆柱体：只代表“持久化存储”，且必须标注引擎类型（MySQL 8.0、Redis 7.2、S3 bucket）。去年有个项目，图上所有存储都画成圆柱体，但没标类型，结果开发时把用户行为日志全塞进MySQL，导致慢查询暴增。后来我们加了一条铁律：凡圆柱体，右下角必须用小号字体写明“引擎+版本+分片策略（如shard by user_id mod 16）”。

最易被忽视的是菱形。它不该是“判断节点”，而应是“契约断言点”。比如支付流程中的菱形，不能只写“余额是否充足”，而要写成“assert balance >= order_amount, else throw InsufficientBalanceException”。这样开发时就知道，这里必须抛指定异常，而不是随便return false。

3.3 文字标注不是“说明”，是“可执行脚本”

图上的文字，必须满足“删掉图，单看文字也能跑通逻辑”的标准。我见过太多失败案例：状态机图里写着“用户提交订单”，但没写触发条件（是点击按钮？还是定时任务？）；时序图里写着“发送通知”，但没写通知渠道（站内信？短信？Webhook？）。我的解决方案是强制采用“主谓宾+约束条件”句式。例如：

• ❌ “校验库存”
• ✅ “校验SKU_ID=10023的可用库存≥下单数量，超时阈值300ms，失败时返回HTTP 422并附错误码STOCK_UNAVAILABLE”

这种写法看似啰嗦，但能消灭90%的沟通成本。某次我们做海外支付对接，图上写着“处理汇率转换”，开发按惯例用本地缓存汇率，结果客户投诉结算金额偏差。翻出原始图，发现旁边小字写着“汇率源：ECB官方API，每小时刷新，缓存失效时间3600s”。就这一行字，让开发立刻改掉了缓存逻辑。

3.4 颜色不是“美化”，是“风险预警层”

我彻底禁用RGB自由配色，只用四色系统：

• 深蓝（#0A2540）：代表“已上线、经生产验证的稳定模块”
• 橙红（#D32F2F）：代表“存在已知缺陷、正在hotfix的模块”
• 灰绿（#388E3C）：代表“灰度发布中、流量占比<5%的模块”
• 浅紫（#7B1FA2）：代表“仅限测试环境、禁止进入生产链路的模块”

颜色必须和文字描述严格一致。曾有个项目，图上支付网关标着橙红，但文字写着“已修复超时问题”，结果运维按图操作，把还在修bug的网关切进了生产流量。现在我们规定：凡颜色与文字冲突，以颜色为准，文字必须同步修改。这倒逼团队养成“改图即改代码”的习惯。

3.5 图例不是“装饰”，是“语义字典”

新手常犯的错误，是把图例当摆设。我的图例必须包含三要素：

1. 符号定义（如“虚线箭头=异步事件”）
2. 使用场景（如“仅用于跨服务通信，服务内部方法调用禁用”）
3. 例外清单（如“例外：订单取消事件虽为异步，但因需强一致性，此处用实线箭头”）

去年有个医疗系统，图例里写着“云服务用云朵图标”，结果开发把AWS RDS画成云朵，把自建PostgreSQL也画成云朵，导致安全审计时被质疑“未区分公有云与私有云数据流向”。后来我们在图例里加了第四行：“云朵图标仅指代托管型PaaS/SaaS服务，IaaS资源（如EC2、VM）必须用服务器图标”。

3.6 版本水印不是“形式”，是“法律存证”

每张图右下角必须有不可擦除的水印，格式为：“[项目代号]-[图类型]-v[主版本].[次版本][生成日期][生成人缩写]”。比如“HEALTH-STATEMACHINE-v2.3_20240521_JL”。这个水印不是为了好看，而是当出现线上事故时，能瞬间定位到问题发生时团队依据的是哪张图。某次金融系统出现资金重复入账，我们对比了事故前后的三张状态机图，发现v2.1版里“支付成功”状态到“入账处理中”状态的转移条件，被v2.2版误删了“检查是否已入账”这一条——水印让我们5分钟内锁定了问题根源，而不是花两天翻Git历史。

提示：所有水印必须用10号字体，位置固定在右下角距边1cm处，且不得覆盖任何图形元素。我试过用半透明水印，结果打印出来看不见；也试过放在左上角，结果被会议投影仪的黑边遮挡。这些细节，都是拿真金白银交的学费。

4. 实操过程与核心环节实现：从零开始搭建一张“能跑通”的diagram

现在我们动手做一个真实场景：设计一个“用户注销账户”的端到端流程图。这不是教学演示，而是我上周刚交付给某社交平台的方案，已通过法务合规审查和压力测试。

4.1 第一步：锁定参与方与契约接口（耗时15分钟）

打开空白画布，先不画任何图形，只列三件事：

1. 谁发起：用户（前端App）
2. 谁执行：账户服务（微服务）、内容服务（微服务）、通知服务（微服务）、审计日志系统（独立组件）
3. 谁验证：GDPR合规检查器（外部SaaS）、风控引擎（内部服务）

然后为每个参与方定义最小必要接口：

• 账户服务：必须提供DELETE /v1/users/{user_id}，返回202 Accepted，响应体含operation_id
• 内容服务：必须提供POST /v1/content/purge，请求体含{user_id, operation_id}，超时60s
• 审计日志：必须接收POST /api/v1/audit，字段含event_type="USER_DELETION", status="initiated"

这一步的关键是：拒绝“可能需要”的接口，只写“必须存在”的接口。我见过太多图，把“未来可能接入的AI推荐服务”也画进去，结果开发时发现接口根本不存在，整张图作废。

4.2 第二步：绘制主干流程（耗时25分钟）

用直角矩形画四个服务，横向排列。连接线全部用实心箭头，标注协议与约束：

• 用户→账户服务：HTTPS POST /v1/users/{id} (JWT auth, timeout=10s)
• 账户服务→内容服务：gRPC unary call PurgeUserContent (timeout=60s, retry=2)
• 账户服务→通知服务：AMQP publish to queue.user_deletion_notify (persistent=true)
• 账户服务→审计日志：HTTPS POST /api/v1/audit (idempotent key: {user_id}_{timestamp})

特别注意：所有连接线必须标注超时值和重试策略。去年有个注销流程，图上没标超时，开发按默认30s设置，结果内容服务清理大用户数据要90s，导致账户服务超时后重发请求，造成数据二次删除。现在我们规定：凡涉及外部服务调用，超时值必须是对方SLA承诺值的1.5倍，且在线旁用括号注明“SLA reference: CONTENT-SLA-2024”。

4.3 第三步：嵌入关键判断与异常分支（耗时30分钟）

在账户服务矩形内，画一个菱形，标注：
assert user.status == "active" AND user.deletion_requested_at == null, else return HTTP 409 Conflict with error_code=ACCOUNT_LOCKED

从菱形引出两条线：

• “是”分支：指向内容服务调用
• “否”分支：指向审计日志，标注event_type="USER_DELETION_REJECTED", reason="account_locked"

接着在内容服务调用后，加一个菱形：
assert purge_result.status == "success", else trigger fallback: mark user as "deletion_pending"

这个“fallback”分支很重要——它把“技术失败”转化为“业务状态”，避免系统卡死。某次我们遇到内容服务集群故障，图上没设计fallback，结果2000个注销请求全堵在账户服务内存里，引发OOM。现在所有关键路径都必须有fallback，且fallback动作必须可审计。

4.4 第四步：注入合规与风控检查点（耗时20分钟）

在主干流程末端，加一个虚线框，标题“合规网关”，框内放两个圆角矩形：

• GDPR检查器：标注call GET https://gdpr-api.example.com/v1/check?user_id={id} (response cache: 24h)
• 风控引擎：标注call POST /v1/risk/evaluate with {user_id, action="deletion", context="high_risk_country"}

这两者都用虚线连接到账户服务，标注“非阻塞，结果异步写入审计日志”。这里的关键是：把合规检查从主流程剥离，避免拖慢核心链路。某金融客户曾要求“注销前必须完成反洗钱扫描”，我们没按图施工，而是设计成异步钩子，既满足合规，又保障用户体验。

4.5 第五步：添加元数据与水印（耗时5分钟）

在图右下角加水印：SOCIAL-DELETION-v1.2_20240615_JL
在图左上角加图例：

• 实心箭头 = 同步RPC，超时值标注在线旁
• 虚线框 = 合规检查，结果不影响主流程
• 橙红色块 = 已知缺陷：GDPR检查器偶发503，降级为日志告警

最后，在图顶部加一行小字：“本图依据PRD-2024-045第3.2节及GDPR Article 17生成，有效期至2024年12月31日”。

4.6 实操现场记录：这张图如何救了项目

这张图交付三天后，客户提出新需求：“注销时要保留用户头像30天，供申诉使用”。开发组长拿到需求，第一反应不是改代码，而是打开这张图，找到“内容服务”矩形，发现里面写着purge_strategy=hard_delete。他立刻在图上用红色批注：“需新增soft_delete策略，头像保留30天”。我们开了15分钟站会，确认了三点：

1. 内容服务API需增加preserve_assets=["avatar"]参数
2. 审计日志需新增asset_retention_days=30字段
3. 风控引擎检查点需增加check_avatar_retention=true

当天下午，开发就提交了PR，图上的批注直接转成了Jira子任务。没有这张图，这个需求至少要多开三次会，写两版接口文档，再花一天对齐。而有了它，从需求提出到代码合并，只用了8小时。

5. 常见问题与排查技巧实录：那些没人告诉你的“图病”

在上百个项目里，我总结出diagram-design的七种典型“图病”，每一种都对应着真实的协作灾难。下面不是理论，是我在会议室、Slack群、深夜电话里亲手解决的案例。

5.1 “幽灵连接病”：图上存在，但现实中从未实现的连接

症状：图中A服务连向B服务，但B服务根本没有暴露对应接口；或A调用B的路径在代码里根本不存在。
真实案例：某电商后台，图上显示“订单服务→库存服务”有实时扣减连接，但实际架构中，库存扣减是通过MQ异步完成的，订单服务只发消息，不等响应。结果测试时，用图上的同步路径写自动化用例，全部失败。
排查技巧：

• 打开服务的OpenAPI文档，逐条核对图中连接线标注的endpoint、method、参数
• 在代码里全局搜索连接线旁的文字标签（如“扣减库存”），看是否有真实调用点
• 最狠一招：用APM工具（如SkyWalking）抓取生产流量，看A服务实际调用的下游服务列表，与图对比

注意：凡发现幽灵连接，必须立即在图上用橙红色边框标记，并在旁边写明“已验证不存在，待移除”。我试过直接删除，结果开发说“图上原来有，我们按这个做的”，只好重画。

5.2 “语义肥胖病”：一个形状塞进太多信息，导致无法聚焦

症状：一个矩形里密密麻麻写满文字，或一个菱形里堆砌七八个判断条件。
真实案例：某支付网关图，一个“风控检查”菱形里写着“检查黑名单、检查交易频次、检查设备指纹、检查IP归属地、检查用户等级、检查商户限额……”，开发看到直接懵了，问“这些是AND还是OR？有没有优先级？”
排查技巧：

• 强制执行“单形状单职责”：一个菱形只允许一个判断条件，复杂逻辑拆成多个菱形串联
• 用颜色编码判断权重：红色条件（必须满足）、黄色条件（建议满足）、绿色条件（可忽略）
• 对高频组合条件，抽象成独立服务：比如把上述六项风控检查，封装成RiskAssessmentService，图上只画一个矩形

5.3 “时间失忆病”：图上没标时间约束，导致性能事故

症状：连接线没标超时，状态转移没标时限，异步任务没标重试间隔。
真实案例：某IoT平台，图上“设备上报→云端解析”连线只写“HTTP POST”，没标超时。开发按默认60s设置，结果设备固件bug导致上报数据包巨大，云端解析要120s，连接被Nginx强制断开，设备反复重连，引发雪崩。
排查技巧：

• 对所有连接线，执行“三问”：这个调用最长能忍多久？失败后重试几次？重试间隔怎么算？
• 在图上用统一格式标注：timeout=120s, retry=3, backoff=exp(2^N)
• 对状态机，每个状态旁加小字：“最大驻留时间=300s，超时自动转入error状态”

5.4 “版本幻影病”：同一项目存在多张不同版本的图，团队各执一词

症状：产品说“图上写着支持微信登录”，开发说“我们看的是v2.1版，没这功能”，测试拿出v1.8版说“这版有”。
排查技巧：

• 建立图库版本管理：所有diagram必须存入Git仓库，文件名含版本号（如auth-flow-v2.3.drawio）
• 在Confluence页面嵌入图时，强制用!diagram!宏，自动拉取最新版，禁用截图上传
• 每次评审会，第一件事是所有人打开同一URL，核对右下角水印

5.5 “协议失语病”：图上写“调用API”，但没说清是REST、gRPC还是GraphQL

症状：连接线旁只写“调用用户服务”，开发按REST写，结果用户服务只暴露gRPC接口。
排查技巧：

• 强制在连接线旁标注协议栈全称：REST/JSON over HTTPS、gRPC over TLS、GraphQL over WebSocket
• 对gRPC，必须标注.proto文件路径（如/proto/user/v1/user_service.proto）
• 对GraphQL，必须标注查询片段（如query { user(id: $id) { name email } }）

5.6 “状态贫血病”：状态机图里只有状态名，没有触发条件和副作用

症状：状态图里写着“已支付”“已发货”，但没写“谁触发”“触发后做什么”。
排查技巧：

• 每个状态必须配三要素：
  • 入口动作（如“创建物流单，调用快递API”）
  • 内部活动（如“每5分钟轮询物流状态”）
  • 出口动作（如“发送发货通知，更新订单状态”）
• 用不同线型区分触发源：实线=用户操作，虚线=系统定时任务，点划线=外部事件

5.7 “合规失焦病”：图上没体现法规要求，上线后被勒令下架

症状：数据流向图里，用户数据从A到B，但没标“是否加密”“是否脱敏”“是否跨境”。
排查技巧：

• 在所有数据连接线上，强制标注：encryption=AES-256-GCM, anonymization=SHA256(user_id), cross_border=false
• 对GDPR/CCPA相关流程，单独画合规检查点，并引用具体条款（如“GDPR Art.17 Right to Erasure”）
• 每季度请法务抽查10%的图，重点看数据流向标注

6. 工具链与协作规范：让diagram-design真正落地的三件套

再好的设计思路，没有趁手的工具和铁律般的规范，终究是空中楼阁。我花了三年打磨出一套极简但高效的工具链，它不追求炫酷，只确保“今天画的图，三个月后还能被新人看懂”。

6.1 工具选型：为什么放弃Figma，选择draw.io+Git

很多人问我为什么不选Figma或Miro，答案很现实：协作成本和可追溯性。Figma的评论功能很好，但它的版本历史是“快照式”的，你无法看到“第7版到第8版，哪一行文字被修改了”；Miro的模板丰富，但导出PDF时字体常错乱，打印出来全是方块。而draw.io（现为diagrams.net）+Git的组合，解决了所有痛点：

• 文本可 diff：draw.io导出的.drawio文件是XML，Git能清晰显示哪一行标签被修改、哪个坐标被调整
• 离线可用：不用联网就能打开编辑，机场、高铁上都能工作
• 零学习成本：快捷键和VS Code几乎一致（Ctrl+S保存，Ctrl+Z撤销）

我的配置是：

• 本地安装draw.io桌面版（免安装，解压即用）
• 所有图文件存入项目Git仓库的/docs/diagrams/目录
• 在.gitattributes里添加：*.drawio diff=xml，让Git用XML格式对比

某次我们修复一个支付回调bug，需要回溯三个月前的时序图。用Git命令git log --oneline --grep="payment-callback"，秒级定位到修改记录，再用git show <commit>:docs/diagrams/payment-callback-v1.2.drawio直接查看原始图。如果是Figma，我得翻邮箱找邀请链接，再等加载。

6.2 模板规范：五张图解决90%的协作场景

我提炼出五张万能模板，覆盖所有高频场景，每张模板都预置了颜色、字体、水印规则：

1. 服务交互图模板：专用于微服务间调用，预置gRPC/REST/AMQP三种连接线样式
2. 状态机图模板：预置GDPR合规状态（erasure_requested, erasure_in_progress, erasure_complete）
3. 部署拓扑图模板：预置AWS/Azure/GCP图标库，自动标注区域（us-east-1, eu-west-1）
4. 数据流向图模板：预置PII（个人身份信息）高亮色块，强制标注加密方式
5. 故障树图模板：预置“根因-中间事件-叶节点”三层结构，支持概率标注

所有模板都禁用自由绘图模式，只能从左侧组件库拖拽。曾有个设计师想“优化下UI”，把状态机图的圆角矩形全改成胶囊形，结果开发说“这不符合我们的语义规范”，只好重画。现在我们规定：凡修改模板，必须提PR，由架构师审批。

6.3 协作流程：图不是“画完就交”，而是“评审-签署-归档”闭环

我们把diagram-design纳入研发流程，形成硬性节点：

• 评审会：必须有产品、开发、测试、运维四方到场，每人手持打印版图，用红笔圈出疑问点
• 签署页：图末尾加一页“签署页”，四人手写签名+日期，注明“本人确认此图准确反映当前设计”
• 归档规则：签署后24小时内，图文件必须提交Git，PR标题格式为[DIAGRAM] <图名> v<版本> <简述变更>

去年有个项目，图上写着“短信验证码5分钟过期”，但签署页上测试同学签了字。上线后发现实际是10分钟，法务追查时，我们拿出签署页，证明责任在测试方未核实。这倒逼所有人认真看图，而不是走形式。

提示：签署页必须用A4纸打印，不能电子签名。我试过用DocuSign，结果法务说“电子签名在某些司法管辖区效力存疑”，只好回归纸质。

7. 经验沉淀与长期主义：diagram-design如何成为团队肌肉记忆

最后分享一个反常识的体会：diagram-design的价值，不在画图那一刻，而在画图之后的三个月。我见过太多团队，花大力气画完图，庆祝一下，然后束之高阁。真正的高手，懂得把图变成活的资产。

7.1 让图“自己说话”：自动化校验脚本

我们写了一个Python脚本，每天凌晨自动运行，扫描所有.drawio文件：

• 检查水印格式是否符合[项目]-[类型]-v[数字].[数字]_[日期]_[人名]
• 检查所有连接线是否标注超时值（正则匹配timeout=\d+s）
• 检查所有菱形是否以assert开头（强制断言语法）
• 检查所有服务矩形是否标注版本号（如MySQL 8.0）

脚本发现问题，自动发Slack告警，并@责任人。某次它发现一张图的水印日期是2023年，而当前是2024年，我们立刻意识到这张图已过期，紧急组织评审。没有这个脚本，这张图可能还在指导错误的开发。

7.2 让图“指导开发”：从图生成代码骨架

我们用draw.io的XML结构，写了一个简单转换器：

• 把服务矩形转成Spring Boot@RestController类名
• 把连接线标注的endpoint转成@PostMapping路径
• 把菱形标注的断言转成@Valid注解

虽然不能生成完整代码，但能产出80%的框架代码。某次我们新建一个通知服务，用图生成了Controller、DTO、Validation注解，开发只花了2小时就跑通第一个接口。图不再是文档，而是代码的蓝图。

7.3 让图“沉淀知识”：建立图谱索引系统

我们在Confluence建了一个“图谱索引页”，用表格维护所有图的关系：

这个表格支持全文搜索，新成员入职，搜“退款”，立刻看到所有相关图。它让知识不再散落在个人电脑里，而是成为团队的公共资产。

我个人在实际操作中的体会是：diagram-design不是一项技能，而是一种思维习惯。当你习惯在画每一条线前，先问“谁要看？看懂什么？看不懂会怎样？”，你就已经超越了90%的同行。它不会让你写出更炫的代码，但能让你的代码，第一次就写在正确的轨道上。