AWS 风格架构图
概述
生成遵循 AWS 参考架构图 约定的图表：准确的服务名称、带标签的账户/区域/VPC 边界、简短的数据流标签，以及简洁的画布。“AWS 风格”描述的是这些约定；它本身并不要求使用官方 AWS 图标或 Graphviz。
Mermaid 和 Graphviz DOT 是同级的创作格式。Mermaid 通常适合内联、受主题影响、可文本审查的文档；DOT 则适合精确的本地 AWS 图标资产、可控的构图和可用于演示的 SVG/PNG。当一种格式能完全满足交付合同要求时使用它，当不同的受众或产物使得额外的维护成本值得时，两种都使用。
何时使用
将此技能用于基于证据的 AWS 架构、拓扑、系统上下文或数据流图。不要将其用于非 AWS 的可视化，或者当表格本身就能更清晰地传达所请求的事实。
常见误区
- “AWS 风格意味着 DOT”忽略了那些能够满足实际合同的 Mermaid 渲染器。
- “两种格式更安全”在没有两个指定消费者的情况下会带来同步成本。
- “这个服务可能连接到这里”不足以作为绘制边的证据。
危险信号
在绘制或查询实时基础设施之前，如果遇到不受支持的资源或关系、模糊的目标渲染器、缺失的图标权限或资产、冲突的源证据，或者请求的区域超出授权范围，请停止并解决这些问题。
超越美学的规则
只绘制来源所建立的内容。 每个节点、边、边界、区域和协议都必须追溯到真实存在的东西——Terraform、CloudFormation、CDK、已部署的配置，或所有者的书面声明。图表是一个恰好是可视化的证据制品。
永远不要因为图片看起来不平衡就添加服务、连接、可用区、VPC 或区域。如果来源没有建立某个边界，就忽略它；一个诚实的稀疏图表胜过一个装饰性的完整图表。当某些组件已部署但被禁用时，在节点上说明（WEB_PUSH_ENABLED=false，“已部署，发布禁用”），而不是将其绘制为活跃状态，并标记为其他团队所有，这样读者就不会认为你控制它。
在图表本身中注明来源——一个副标题，命名来源，例如 “追踪至 <iac-dir>/*.tf，版本 <revision>” 或 “只读实时清单，<date>” ——并在 DOT 源文件的头部注释中重复。
命名资源，而不仅仅是服务
仅凭服务图标无法识别任何东西。一个品红色的 DynamoDB 标记，标签为“Operations”，可能代表一个表、一个流或一个索引，读者无法在控制台中找到它。每个节点应陈述三个事实：
- 在 AWS 中的真实名称。 实际部署的名称——
acme-orders-events，而不是像“Orders”这样的友好别名。将账户 ID 写为<account>而不是数字；绝不要将秘密、令牌或端点放在图表中。 - 它是什么类型的资源。 用灰色字体写在名称下方：“DynamoDB 表”、“S3 存储桶”、“Lambda 函数”、“API Gateway HTTP API”、“WAFv2 Web ACL”、“SES v2 电子邮件身份”。
- 它有什么用途。 一行文字，仅在读者无法推断出用途时添加。
对于 Graphviz 输出，如果 AWS 发布了资源图标，则使用它——Res_Amazon-DynamoDB_Table、Res_Amazon-Simple-Storage-Service_Bucket、Res_AWS-Lambda_Lambda-Function——其他情况则使用服务 (Arch_) 图标。图标增强了标识，但它绝不应是唯一承载标识的东西，因为图标在灰度、缩略图尺寸或屏幕阅读器中都是不可读的。
根据需求选择格式
没有全局优胜者和默认格式。如果明确请求了某种源格式，则予以尊重，除非它与另一个验收标准冲突。否则，比较实际的交付需求：
| 需求 | Mermaid 通常更适合 | Graphviz DOT 通常更适合 |
|---|---|---|
| 仓库审查 | 内联 Markdown 渲染，紧凑的文本差异 | 可审查的文本源，加上单独渲染的产物 |
| 图表类型 | 序列图、流程图、状态图、依赖图和简单的架构视图 | 密集拓扑、嵌套边界和需要精心规划边缘路由的图 |
| AWS 视觉效果 | AWS 风格名称、边界、颜色，或渲染器提供的图标包 | 仓库本地的 AWS 发布图标资产 |
| 布局 | 渲染器管理的响应式布局和主题适配 | 精确的排名、端口、集群、间距和固定构图 |
| 交付 | 应该在编写处渲染的文档 | 用于演示文稿、文档和展示面的受控 SVG/PNG |
| 工具链 | 目标渲染器已支持所需的 Mermaid 语法和版本 | Graphviz 和所需的本地资产在构建或创作环境中可用 |
如果请求的内容实际上是表格，请使用 Markdown 表格，而不是将其转化为图片。对于有序的参与者交互，Mermaid sequenceDiagram 通常是自然的选择；这是图表类型的优势，而不是对 Mermaid 的普遍偏好。
Mermaid 支持架构图和可配置的图标包，但不能假设托管渲染器会提供仓库本地的 AWS 资产、自定义包注册，或与受控本地渲染器相同的 Mermaid 版本。Graphviz 可以直接加载本地图片资产，因此当精确的图标资产和固定的导出构图是验收标准时，它是可靠的选择，而不仅仅是因为请求说“AWS 风格”。
权衡双方的代价。Mermaid 可能因渲染器版本、可用的图标包和主机主题而异。DOT 增加了渲染步骤和生成的产物，这些产物必须与可编辑的源保持同步。选择代价与仓库和目标相匹配的格式，而不是将任何一种工具的优势视为普遍适用。
如果渲染器支持、图标保真度、固定构图或预期的输出文件会实质性地改变结果，并且请求不明确，请澄清交付合同。否则，选择能够以最少的项目特定机制满足已知需求的格式。
当选择 Mermaid 时，保留上述关于证据、来源、资源命名和可访问性的规则，在目标渲染器中验证源文件，并在下面的 Graphviz 特定工作流程之前停止。
何时两种格式都有理由使用
当 Mermaid 和 DOT 能够满足不同的实际需求时，例如内联仓库审查加上精确 AWS 图标的演示输出，则同时生成它们。双重交付并不自动更好：只有当两个产物都有指定的消费者或验收标准时，它才是合理的。
默认情况下，两种源都不是权威的。两者都从相同的已验证资源和关系清单派生，携带相同的来源信息，并检查节点、边、边界、区域、所有权和不确定性是否一致。格式可以添加特定于演示的结构，而不会改变其所声称的架构。只有当用户或仓库策略明确指定了权威格式时，才将一种格式命名为权威。
对于需要精确 AWS 图标、固定构图或端口级连接器放置的异常密集的完整系统地图，DOT 及其 SVG 和 PNG 可以作为演示和 AWS 图标产物。当也需要时，Mermaid 渲染可以作为可维护、可内联审查的伴生产物。对于没有这些 DOT 特定需求的焦点流，仅 Mermaid 就可能满足合同。这些是基于需求的选择，而不是为每个图表都生成两种格式的理由。
Mermaid 工作流程
1. 选择 Mermaid 图表类型
使用 architecture-beta 或流程图来表示架构和拓扑，使用 sequenceDiagram 表示有序交互，并且仅在实际状态转换时使用状态图。确认目标渲染器支持选定的语法和任何图标包；不要假设 GitHub、文档站点和本地 Mermaid CLI 运行相同的版本或配置。使用 Iconify 符号时，请在文本中保留完整的 AWS 资源名称和类型；图标绝不能是唯一的资源标识符。
2. 编码已验证的清单
仅当证据建立了 AWS 账户、区域、VPC、可用区、子网和所有权边界时，才表示它们。使用完整的资源名称和类型、简短的有标签边，以及用于允许或推断关系的可见注释。将来源信息保存在附近的 Markdown 中，并在语法允许时保存在源注释中。
3. 在目标环境中渲染并检查
使用仓库固定的 Mermaid 命令或文档构建工具。验证将实际交付的精确围栏代码块或 .mmd 源文件，然后在其预期的宽度和主题下检查渲染结果。检查裁剪的标签、重叠的边、不支持的图标或语法、不可访问的对比度以及与已验证清单的语义偏差。修复可编辑源文件并重新渲染，直到其可读。
显式注册非内置的图标包。对于 Mermaid CLI，可重现的 AWS 符号渲染可以使用：
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
将 ? 回退标记视为渲染失败，而不是外观降级。图标包支持可能因 Mermaid 版本和布局渲染器而异；验证实际输出的视觉和结构。如果一个受支持的渲染器丢失了注册的图标，请使用另一个保留了它们的受支持渲染器，并记录布局权衡。不要声称内联可移植性，除非目标主机也注册了所需的包。
4. 交付所需的产物
当这是仓库合同时，将 Mermaid 保持内联。当需要独立的 SVG 或 PNG 输出时，使用仓库固定的 Mermaid 版本以确定性的方式进行渲染，并记录重现命令。
Graphviz 工作流程
1. 从源建立架构
在绘制任何内容之前，读取 IaC 并盘点实际存在的资源。找到该项目用于存放 IaC 的目录——infra/、terraform/、deploy/、CDK 应用程序——而不是假设布局：
iac_dir=infra # 无论该仓库实际使用什么
然后提取出使边变为真实连接以及使节点带上名称的具体细节：函数名、表名、存储桶名、事件规则及其计划、S3 通知、授权程序，以及任何跨账户或跨栈的授权。通过变量和本地变量将名称解析为实际部署的值。注意实际设置区域的变量，而不是根据假设。
1b. 当没有 IaC，或者 IaC 只是资产的一部分时
有时需要绘制图表的对象是一个没有人拥有 Terraform 的正在运行的账户，或者 Terraform 只涵盖了已部署资源的一小部分。那么，来源就是实时的只读账户，并且图表必须明确说明这一点。
从标签谓词开始，而不是逐个服务地扫描，因为这是界定“哪些资源属于这个系统”的唯一方法：
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<key>,Values=<v1>,<v2>'
可能需要多个标签键，每个键一个请求，之后按 ARN 合并——在一个请求中传递两个键会应用 AND 操作，静默地丢弃所有只携带其中一个键的资源。记录结果计数和日期；这是一个快照，而不是事实。
标签 API 不会返回所有资源类型，标签也不代表所有权。因此，标签查询提供了节点集，而关系来自实际对它们进行建模的 API：
| 要建立的关系 | 读取 |
|---|---|
| 入站连接 | elbv2 describe-load-balancers、describe-target-groups |
| 允许的路径 | ec2 describe-security-groups、describe-vpcs |
| 计算层可能调用的 | iam get-instance-profile，然后 get-policy-version |
| 数据层形状和副本 | rds describe-db-instances、elasticache describe-* |
| 异步连接 | 队列重定向策略、S3 通知、事件规则 |
在绘制之前，将找到的每个 CIDR 解析为命名的 VPC；未解析的 10.16.0.0/16 对读者毫无意义。
1c. 说明每条边所依据的证据类型
这在读取实时账户时最为重要，因为很容易因为两个资源共享一个命名前缀就画一条线。在视觉上区分这些类别，并在图表及其文字说明中定义它们：
- AWS 自己报告的连接——目标组的目标、副本的源。最强的类别；AWS 正在为你建模这种关系。
- 某物允许的路径——安全组规则、存储桶策略。这建立了调用可能发生，而不是确实发生。当规则是 CIDR 范围而不是安全组范围时，请注意：它授权了整个范围，而不是你绘制箭头的那个特定工作负载。
- 身份拥有的授权——IAM 策略语句。同样的注意事项，而且直到 SCP、权限边界和资源策略被评估之前，该授权都不是有效权限。
- 从命名或标签推断——用虚线绘制，用不确定性标记，或者完全省略。永远不要用实线。
不存在也是一种值得绘制的发现。当一个“显然”要与队列通信的角色实际上不持有任何 sqs:* 操作时，一个说明此情况的节点比一个缺失的箭头更有用，因为它排除了错误的假设，而不是让其悬而未决。
…
[余下内容已截断]