TypeScript脚本批量生成20+企业架构图

当一位 CTO 需要为一家拥有 350 人、运行着 15 个系统且零现有图表的企业提供架构文档时，时间线很少允许花几周来做 Visio 工作。传统手动方式在截止日期前最多只能产出五张图，而且墨迹未干就已过时。

批量生成方案：将系统定义为代码，以编程方式渲染图表，通过自动化检查迭代视觉质量。同样的定义在手动绘制一张图的时间内即可生成 20 张或更多图表。

一个 TypeScript 脚本生成 20+ 企业架构图表为 Draw.io XML 格式：ERD、网络拓扑、CI/CD 流水线、集成图、安全模型。每张图导出为 SVG 并嵌入 Azure 图标。所有图表在发布前都通过自动化质量门（网格对齐、配色方案、边线路由）和视觉 QA 审核循环。整批生成仅需几分钟。

运行示例：Cascade Dynamics

Cascade Dynamics 是贯穿多篇文章使用的典型 az365 虚构公司。其架构设计足够可信且完整，能够覆盖每一种图表类型，同时完全采用虚构形式。这些内容均不针对任何特定真实项目。

背景设定：一家 350 人的公司正在对其案例管理平台进行现代化改造。该虚构环境继承了一个已运行 15 年的 Oracle 19c 数据库，并在过渡期间保持传统系统运行的同时，在 Azure 和 Power Platform 上构建混合平台。

传统系统：Oracle 19c 本地部署、SFTP 批量数据馈送、Windows Server 虚拟机

Azure：AKS、App Services、Cosmos DB、Azure SQL、API Management、Service Bus、Azure OpenAI

Power Platform：Dataverse 用于案例管理、Power Automate 用于审批、Power BI 用于仪表盘

安全：Entra ID + 条件访问、Key Vault、Sentinel

这类环境中，架构文档不是可选项，而是合规要求。也是这类环境中，没人有时间手动绘制图表。

如何从代码生成 20+ 张图表？

模式很简单。一个 TypeScript 脚本包含常用图表元素的辅助函数（图标、矩形、容器、边线）和一个规范数组，其中每个图表是一个返回 Draw.io XML 的函数。

// Helper: Azure icon with label
function iconBlock(x, y, iconPath, label) {
  const id = addIcon(x, y, iconPath);
  addLabel(x - 20, y + 60, 90, 20, label);
  return id;
}

// One diagram = one function
{ name: 'cascade-cicd-pipeline', fn: () => {
  const ado = iconBlock(30, 70, 'devops/Azure_DevOps.svg', 'Azure DevOps');
  const build = step(140, 80, 140, 55, 'Build', 'Compile + unit tests', blue);
  const test = step(320, 80, 140, 55, 'Test', 'Integration + security', amber);
  addEdge(ado, build, 'push');
  addEdge(build, test);
  // ...
}}

运行脚本。它生成 20+ 个 .drawio 文件，将每张图导出为 SVG（嵌入 Azure 图标、透明背景），并根据质量门进行验证。整批完成仅需几分钟。

每个企业架构都需要这 5 类图表

每个复杂系统至少需要以下五类图表。跳过任何一个都会留下盲点，在事件响应、审计或新员工入职时浪费时间。

数据架构：ERD、流程、事件和状态机

这永远是图表 #1。在任何人写一行代码之前，他们需要看到数据模型。Cascade Dynamics 的 Dataverse 架构有 3 个领域跨 6 个核心表：临床（蓝色）、提供者（绿色）和行政（琥珀色/紫色/灰色）。

Cascade Dynamics 的核心 ERD。按领域配色：临床（蓝色）、提供者（绿色）、调度（琥珀色）、文档（紫色）、审计（灰色）。所有关系均标注了基数。

这张 ERD 有价值之处：列级细节（不仅是表名）、按领域配色，以及每条边上的关系基数。Document 表上的 ai_summary 列立即表明 AI 处理发生在数据层。

若要深入了解如何从 Dataverse 架构生成漂亮的 ERD，请参阅《5 分钟生成漂亮的 Dataverse ERD》。

数据摄取流水线

Oracle 到 Azure 的迁移通过 SFTP 运行夜间批量数据馈送。此图显示了从传统系统到云端的流程，将结构化数据分流到 Azure SQL，文档分流到 Cosmos DB。

从传统 Oracle 的夜间数据摄取。SFTP 批量上传到 Blob Storage 触发 Data Factory，后者将结构化数据路由到 SQL，文档路由到 Cosmos。

事件驱动架构

Service Bus 处理异步事件分发。三个主题类别（案例事件、文档事件、审计事件）馈送到 Function App 消费者。这是骨干系统。系统中每个状态变更都流经此处。

Service Bus 拓扑，3 个主题类别和 4 个 Function 消费者。每个消费者只有一个职责：通知、AI 处理、搜索索引或合规日志记录。

案例生命周期状态机

案例经过 7 个状态和决策网关流转。拒绝循环（返回草稿）是导致最多 bug 的那个。向后回退的状态转换在 Power Automate 中需要仔细处理。

案例生命周期状态机。'Returned' 状态循环回到 Draft。这种向后转换是大多数工作流 bug 所在之处。

基础设施 + 安全：网络、Zero Trust、身份和可观测性

Hub-spoke VNet 设计。Hub 承载防火墙、bastion 和 DNS。应用和数据 spoke 连接到 Hub 对等连接。本地 Oracle 通过 VPN/ExpressRoute 连接。这是网络团队和审计人员首先要求的图表。

Hub-spoke 网络拓扑。Hub VNet（10.0.0.0/16）与应用和数据 spoke 对等连接。本地连接通过 VPN/ExpressRoute 到传统 Oracle 环境。

Zero Trust 安全模型

Entra ID 居中，四个支柱向外辐射：条件访问（MFA）、Key Vault（托管标识）、Sentinel（SIEM）和 NSG 规则（微分段）。每个支柱映射到其下方的一个具体实现。

Zero Trust 安全模型。每个组件从原则（条件访问）映射到实现（所有用户、所有应用均需 MFA）。

身份架构

端到端认证流程。用户通过 Entra ID 认证，通过条件访问（MFA + 设备合规），接收 JWT，访问 API Management，然后被路由到适当的后端 API。这是交给渗透测试团队的图表。

端到端身份流。每个请求在到达后端服务前经过 4 个检查点。

监控和可观测性

三个遥测源（App Services、AKS、Functions）馈送到 Application Insights 和 Log Analytics，汇聚到 Azure Monitor。从那里，安全事件发送到 Sentinel，运营指标发送到仪表盘。这就是团队回答"凌晨 3 点哪里坏了"的方式。

可观测性堆栈。三个遥测源汇聚到 Azure Monitor，后者将安全告警路由到 Sentinel，运营指标路由到 Power BI 仪表盘。

DevOps + 部署：CI/CD、拓扑、IaC 和容器

Azure DevOps 运行该流水线。代码推送触发构建和单元测试，然后是集成测试和安全测试，再经过审批门，最后是带有蓝绿部署的 staging 环境，最后进入生产环境。ACR（Container Registry）存储镜像。

CI/CD 流水线包含 5 个阶段。测试与 staging 之间的审批门是大多数部署停下来等待人工审核的关键节点。

三个环境，每个环境都有相同的资源集。Dev（蓝色）、Test/UAT（琥珀色）、Production（绿色）。promote/approve 边显示了单向流动。没有任何东西从 prod 往回流向 dev。

部署拓扑。每个环境都有相同的资源类型（App Service、SQL、Cosmos），环境之间有 promotion 门控。

Infrastructure as Code

Bicep 模板托管在 git 中，提交到 Azure DevOps 流水线，运行 ARM what-if 验证，然后部署到资源组。Azure Policy 在每次部署时验证合规性。不允许手动在门户中点击操作。

Infrastructure as Code 流水线。Bicep 模板是唯一的事实来源。Azure Policy 在每次部署时根据合规规则进行验证。

Container Architecture

AKS 集群承载 4 个工作负载：Clinical API、Document API、Event Processor 和一个 Auth Sidecar（DaemonSet）。ACR 提供容器镜像，Application Gateway 处理入口流量，Key Vault 通过 auth sidecar 提供密钥。

AKS 集群架构。Auth Sidecar（DaemonSet）负责从 Key Vault 轮换密钥，因此应用 Pod 从不直接接触密钥。

Integration + AI: APIs, Document Processing, RAG, and Migration

Enterprise Integration Map

API Management 处于中心位置。左侧：消费系统（Power Platform、Power Pages 门户、移动端应用）。右侧：后端服务（App Services、Functions）。下方：遗留 Oracle 和 Dataverse。每个系统间的调用都经过 APIM 路由。

企业集成地图。APIM 是所有系统间通信的单一网关。遗留 Oracle 适配器（虚线）处理 SFTP/CDC 桥接。

AI Document Processing Pipeline

文档流经 6 个步骤：上传、blob 存储、AI Document Intelligence（表单提取）、Azure OpenAI（摘要）、Cosmos DB（存储）和 Power App（展示）。审核员上传一份扫描表单，即可在案例管理应用中获取结构化摘要。

AI 文档处理流水线。文档在几秒内从 PDF 变为结构化摘要。Doc Intelligence 提取字段，OpenAI 生成摘要，Cosmos 存储结果。

The Retrieval-Augmented Generation pattern. A user asks a question, Azure OpenAI sends a vector search to AI Search, which fetches relevant documents from Cosmos DB. The documents flow back to OpenAI as context for a grounded response with citations.

RAG 架构。反馈循环（OpenAI → Search → Cosmos → OpenAI）确保每个回复都基于真实文档，而非 hallucinate。

Legacy Modernization Path

从 Oracle 迁移到 Azure 是一个 6 个月的项目。Data Migration Service 处理 schema 和数据传输，结构化记录进入 Azure SQL，文档进入 Cosmos DB。并行运行阶段验证数据一致性，然后才执行 Oracle 切替。

遗留系统现代化路径。6 个月的并行运行对于受监管系统是硬性要求。在下线任何系统之前验证数据一致性。

Power Platform + Governance: Landscape, Approvals, Environments, and CoE

Power Platform Footprint

完整的 Power Platform 地图。Dataverse 是引力中心。Power Apps 驱动案例管理 UI，Power Automate 处理工作流，Power BI 驱动仪表板，Copilot Studio 提供 AI 助手。API Management 将 Power Platform 连接到 Azure 后端服务。

Power Platform 全景。Dataverse 是引力中心。每个平台组件都从同一个数据层读写。

Approval Flow Architecture

案例需要 3 个审批步骤：经理审核、专家审核和合规检查。Power Automate 编排多步骤审批，每个阶段有并行通知。

多步骤审批流程。三个顺序门控，每个门控有不同的审核者和标准。末尾的合规检查是唯一能捕获政策违规的环节。

The standard Dev to Test/UAT to Production promotion path. Solutions export as unmanaged from Dev, import as managed into Test, and deploy to Production only after approval. Connection references and environment variables handle the per-environment configuration.

环境晋升策略。Dev 是非托管的（自由实验），Test 导入托管解决方案，Production 仅接受托管解决方案。

The Center of Excellence toolkit sits at the middle. DLP policies block risky connectors, CoE Starter Kit provides inventory and compliance tracking, and Environment Groups handle routing rules. Below: Solution Checker gates code quality, Approval Gates control prod promotion, and Azure Policy enforces infrastructure compliance.

治理模型。三大支柱（DLP、CoE、Environment Groups）各自映射到具体的执行机制。Azure Policy 将治理扩展到基础设施层。

Why Not Use Visio, Lucidchart, or Miro?

The table below contrasts a typical manual Visio workflow against the script-based approach. Times are illustrative, not measured benchmarks.

真正的优势不是速度。这些图表是代码，这才是关键。当架构发生变化时，修改脚本然后重新生成即可。图表始终保持最新，因为更新它们的成本为零。

The Visual QA Loop That Catches What Code Reviews Miss

自动化质量门检查结构：网格对齐、颜色调色板合规性、边路由、图标使用。这些检查能捕获机械性错误。但它们会遗漏使图表混乱的美学问题：路由纠缠、标签被截断、间距糟糕、边线交叉。

修复方法：将每张图导出为 PNG，可视化地审视、批评、修改、重新生成。PNG 审查能捕获结构检查无法发现的问题。两种检查一起才能实现完整覆盖。

对于本文中的每张图，流水线是：

从 TypeScript 规格生成 .drawio XML

运行质量门禁（网格、调色板、边、图标），必须通过

导出为 2x 比例的 PNG

对 PNG 进行视觉检查，查看美观问题

修复脚本中的坐标问题

重新生成并重新验证

导出最终 SVG，背景透明并嵌入图标

结果：20+ 张图表，结构正确且视觉整洁。无乱成一团的箭头。无被裁剪的文字。无交叉的边。

更多关于图表流水线的信息，请参阅 Architecture Diagrams with Draw.io MCP and Claude Code。关于让文档在 git 中保持活力的更广泛论述，请参阅 Living Documentation in Git。

推荐的起点

从 5 张图开始，而非 20 张。每个企业至少需要：一张 ERD、一张网络拓扑图、一张集成图、一条 CI/CD 流水线，以及一张环境策略图。这五张覆盖了 80% 利益相关者会问的问题。

增量构建脚本。一次添加一张图，验证外观正确后提交。避免试图一次设计全部 20 张。

从第一天起就使用视觉 QA 循环。图表出现图标损坏、背景过暗、箭头缠绕的情况相当频繁，以至于导出到 PNG 并查看这一步是强制性的。每一次都是。

目标不是完美的图表。目标是让图表存在、准确，且在架构变化时能够更新。如果文档策略要求有人手动更新 Visio 文件，文档下周就会过时。

代码生成的图表是活的文档。这才是全部意义所在。

想要构建能保持最新的架构文档？可以了解 AI 智能体开发在实际中如何运作，以及 Draw.io MCP 的完整图表流水线。

本文最初发表于 az365.ai。我是 Alex Pechenizkiy，Azure 和 Power Platform 解决方案架构师，撰写关于 Microsoft AI 堆栈的诚实、供应商中立的分析。更多内容请访问 az365.ai。

如需进一步行动，你可以考虑屏蔽此人和/或举报滥用行为。