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 來源的標頭註解中重複此資訊。
命名資源，而非僅命名服務
單獨的服務圖示無法識別任何東西。一個標示為「Operations」的洋紅色 DynamoDB 符號可能是資料表、串流或索引，而讀者無法在控制台中找到它。每個節點應陳述三件事實：
- 它在 AWS 中的名稱。 實際部署的名稱——例如
acme-orders-events，而不是像是「Orders」的友好別名。將帳戶 ID 寫成<帳戶>而不是實際數字；切勿將密碼、權杖或端點放入圖表中。 - 它是何種資源類型。 以灰色字體寫在名稱下方：「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、可用區域、子網和擁有權邊界。使用完整的資源名稱和類型、簡短的標籤邊緣，以及用於允許或推斷關係的 Visible 註解。將出處保留在附近的 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 # 無論此儲存庫實際使用什麼
grep -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
然後提取使邊緣真實存在的具體細節，以及節點上的名稱：函數名稱、資料表名稱、儲存桶名稱、事件規則及其排程、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:* 動作時，一個說明此情況的節點比一個缺失的箭頭更有用，因為它能排除錯誤的假設，而不是讓它懸而未決。
（由於原文已在該處截斷，此處無法提供更多內容。完整的原始技能檔案請參考上游來源。）