系統架構設計指引
企業標準技術白皮書|版本 v2.0|2026-10-07
適用範圍:以 Java / Spring Boot 為後端、以 Web 前端為使用介面,部署在容器平台(Kubernetes)的企業應用系統,涵蓋架構治理、品質屬性、架構風格、整合、API、資料、效能、韌性、安全、可觀測性、部署平台與交付流程。
v2.0 全面改寫 v1.x:依 ISO/IEC/IEEE 42010:2022、ISO/IEC 25010:2023、OWASP Top 10:2025、NIST SP 800-207 等國際標準重新組織內容;每條規則都附有範例與「驗證方式」,每節結尾都有「🔍 審查與驗證」,讓審查者能判斷 AI 或同事產出的架構設計是否正確。範例均經工具實測(見 附錄 E)。
目錄
- 0. 文件資訊
- 1. 架構治理與國際標準
- 2. 品質屬性與非功能需求
- 3. 架構風格與系統拆分
- 4. 整合與通訊
- 5. API 設計
- 6. 前端架構
- 7. 後端分層架構
- 8. 資料架構
- 9. 效能與擴展性
- 10. 韌性、高可用與災難復原
- 11. 安全架構
- 12. 可觀測性
- 13. 容器與部署平台
- 14. 持續整合與交付
- 15. 微服務治理
- 16. AI 輔助架構設計與審查
- 附錄 A 規則總表
- 附錄 B 架構審查檢核表
- 附錄 C 範本
- 附錄 D 參考標準與資源
- 附錄 E 修訂紀錄與查證紀錄
- 結語
0. 文件資訊
0.1 文件目的與讀者
本指引定義企業應用系統的架構決策標準:哪些事情必須這樣做、為什麼、做到什麼程度才算合格,以及如何驗證。它回答的是「系統應該長什麼樣子」,而不是「某一行程式碼怎麼寫」。程式碼層級的規範請見 程式寫作指引。
| 讀者 | 主要用途 | 建議閱讀章節 |
|---|---|---|
| 架構師、技術主管 | 制定與審查架構決策、主持架構審查會議 | 全部,特別是第 1、2、16 章與附錄 B |
| 後端/前端工程師 | 依規則實作,理解每條規則背後的理由 | 第 3–9 章、第 15 章 |
| SRE、平台工程師 | 部署、韌性、可觀測性與平台設定 | 第 10、12、13、14 章 |
| 資安人員 | 安全架構審查、威脅建模 | 第 11 章、附錄 C.4 |
| 使用 AI 產生設計的人 | 撰寫提示、審查 AI 產出 | 第 16 章,以及各節的「🔍 審查與驗證」 |
0.2 技術基準版本
本指引的範例與規則以下列版本為準(查證日期 2026-10-07)。版本更新時,以各專案的相依管理檔為準,但不得低於「最低版本」欄。
| 類別 | 技術 | 基準版本 | 最低版本 | 備註 |
|---|---|---|---|---|
| 語言 | Java(OpenJDK) | 25 LTS | 21 LTS | 25 起 Virtual Threads 不再因 synchronized 釘住載體執行緒(JEP 491,Java 24) |
| 框架 | Spring Boot | 4.1.1 | 3.5.x | 3.5 的開源支援至 2026-06 結束,新專案一律用 4.x |
| 框架 | Spring Framework | 7.0.9 | 6.2.x | 7.0 起內建 @Retryable、@ConcurrencyLimit |
| 框架 | Spring Cloud | 2025.1.3 | 2025.0.x | 對應 Boot 4.0/4.1 |
| 框架 | Spring Modulith | 2.1.1 | 1.4.x | 模組化單體的邊界驗證 |
| 韌性 | Resilience4j | 2.4.0 | 2.3.0 | Boot 4 使用 resilience4j-spring-boot4 |
| 測試 | ArchUnit | 1.5.1 | 1.3.x | 架構規則自動化測試 |
| 資料庫遷移 | Flyway | 13.9 | 10.x | |
| 容器平台 | Kubernetes | 1.37.1 | 1.35 | 1.37 的 API 版本見第 13 章 |
| 網路 | Gateway API | 1.6.3 | 1.2 | 取代 Ingress 的新一代 API |
| 服務網格 | Istio | 1.31.1 | 1.29 | Ambient 模式已 GA |
| 可觀測性 | OpenTelemetry Collector | 0.162.0 | — | Java Agent 2.32.0 |
| 監控 | Prometheus | 3.15.0 | 3.13 LTS | |
| API 規格 | OpenAPI | 3.1.1(撰寫)/3.2.1(已發布) | 3.0.3 | 工具鏈支援 3.2 前仍以 3.1 撰寫,見 5.1 |
| 事件規格 | AsyncAPI/CloudEvents | 3.1.0/1.0.2 | 3.0/1.0 | |
| 安全標準 | OWASP Top 10/ASVS | 2025/5.0.0 | — | |
| 供應鏈 | SLSA | 1.2 | 1.0 | 1.2 新增 Source Track |
0.3 規範等級與規則格式
本文規則採用 RFC 2119 與 RFC 8174 的語意:
| 等級 | 英文 | 意義 | 架構審查處理 |
|---|---|---|---|
| 必須 | MUST | 不遵守會造成重大風險(資安、資料遺失、無法維運) | 不通過審查;如需例外必須走 0.6 豁免流程 |
| 應該 | SHOULD | 業界共識的最佳實務,除非有充分理由 | 不遵守時必須在 ADR 中記錄理由 |
| 可以 | MAY | 建議做法,依系統規模與情境選用 | 不阻擋 |
| 不應該 | SHOULD NOT | 通常是錯誤的做法,除非有充分理由 | 採用時必須在 ADR 中記錄理由 |
每條規則都有編號,格式為 <領域>-<三位數序號>,方便在架構審查、ADR 與豁免單中引用。編號一經發布不會重編,新增規則使用該領域尚未使用的號碼。
| 前綴 | 領域 | 章 | 前綴 | 領域 | 章 |
|---|---|---|---|---|---|
GOV | 架構治理 | 1 | PERF | 效能與擴展性 | 9 |
NFR | 品質屬性與非功能需求 | 2 | RES | 韌性與災難復原 | 10 |
STY | 架構風格與拆分 | 3 | SEC | 安全架構 | 11 |
INT | 整合與通訊 | 4 | OBS | 可觀測性 | 12 |
API | API 設計 | 5 | PLT | 容器與部署平台 | 13 |
FE | 前端架構 | 6 | CICD | 持續整合與交付 | 14 |
BE | 後端分層架構 | 7 | MS | 微服務治理 | 15 |
DATA | 資料架構 | 8 | AI | AI 輔助架構設計 | 16 |
驗證方式欄位: 每張規則表的最後一欄說明「怎麼確認設計符合這條規則」。審查者應先看這一欄,再決定要花多少心力人工檢查。
| 圖示 | 意義 | 範例 | 審查者該做什麼 |
|---|---|---|---|
| 🤖 | 工具可自動檢查 | 🤖 ArchUnit、🤖 kubeconform、🤖 Spectral | 確認 CI 有執行該工具且沒有被停用或略過 |
| 🧪 | 需要以測試或演練證明 | 🧪 Testcontainers 整合測試、🧪 故障演練 | 確認有對應的測試或演練紀錄,而且規則被違反時測試會失敗 |
| 👁 | 只能由人判斷 | 👁 架構審查 | 依該節「🔍 審查與驗證」的問題逐項確認 |
範例標記: 範例中以 ✅ <規則編號> 標示符合規則的寫法,以 ❌ <規則編號> 標示違規寫法。所有規則都至少出現在一個範例中(統計見 附錄 A)。
0.4 與其他指引的關係
本指引處理「系統層級」的決策。下列主題另有專門指引,本文只列出與架構相關的要求並連結過去:
| 主題 | 指引 | 本文的分工 |
|---|---|---|
| 程式碼寫法、命名、例外處理 | 程式寫作指引 | 本文只定義分層與模組邊界,第 7 章 |
| 系統設計文件、物件導向設計 | 系統設計指引 | 本文提供架構決策的規則與檢核 |
| 安全程式碼 | 安全程式碼指引 | 本文處理安全架構,第 11 章 |
| 資料庫實體設計 | 資料庫設計指引 | 本文處理資料架構,第 8 章 |
| 測試方法 | 測試與品質保證指引 | 本文只定義架構測試與測試分層,第 7、14 章 |
| 開發流程與文件範本 | 軟體開發標準程序教學手冊 | 本文的 ADR/SAD 範本與該手冊的範本共用,附錄 C |
0.5 如何閱讀本指引
每一節都依相同的結構撰寫,閱讀與審查時可以直接跳到需要的部分:
- 概念說明:為什麼需要這個設計、有哪些選項。
- 規則表:編號、等級、規則內容、驗證方式。
- 範例:✅ 正確寫法與 ❌ 常見錯誤,範例中標註規則編號。
- 🔍 審查與驗證:自動檢查指令、人工審查問題、AI 常見錯誤。
第一次導入時,建議依下列順序進行:
flowchart LR
A["第 1 章<br/>建立 ADR 與審查流程"] --> B["第 2 章<br/>寫下可量測的品質目標"]
B --> C["第 3 章<br/>選擇架構風格"]
C --> D["第 4–9 章<br/>逐項設計"]
D --> E["第 10–14 章<br/>韌性、安全、維運"]
E --> F["附錄 B<br/>架構審查檢核"]0.6 例外與豁免流程
規則不可能涵蓋所有情境。專案無法遵守某條「必須」規則時,依下列流程申請豁免,不得直接忽略:
- 撰寫一份 ADR(格式見 1.4),標題寫明豁免的規則編號,說明原因、替代控制措施與到期日。
- 由架構審查委員會(或指定的架構師)核准,並記錄核准人與日期。
- 到期前重新評估;到期未處理的豁免,在下一次架構審查視為不通過。
# ADR-0042 豁免 RES-006:報表服務以單一副本執行
- 狀態:accepted(有效至 2027-03-31)
- 豁免規則:RES-006(正式環境線上服務至少 3 個副本並跨 AZ)
- 原因:報表服務為單一副本的批次工作,夜間執行,白天不提供服務。
- 替代控制:批次工作可重跑(冪等),失敗時由排程系統告警並自動重試。
- 核准:架構審查委員會,2026-10-071. 架構治理與國際標準
架構治理的目的不是產生文件,而是讓「重要的決策」被看見、被討論、被記錄、被驗證。本章定義企業採用的國際標準、架構原則、決策紀錄方式,以及如何用自動化測試守住架構。
1.1 國際標準與參考框架
本指引參考下列標準與框架。它們的定位不同,不需要「全部導入」,但團隊應該知道每一項解決什麼問題:
| 標準/框架 | 版本 | 解決的問題 | 本指引的對應 |
|---|---|---|---|
| ISO/IEC/IEEE 42010 | 2022 | 架構描述(Architecture Description)應包含哪些元素 | 1.5 架構文件 |
| ISO/IEC/IEEE 42020 | 2019 | 架構相關流程(治理、管理、概念化、評估、精化) | 1.6 架構審查流程 |
| ISO/IEC/IEEE 42030 | 2019 | 架構評估的框架 | 1.6、2.3 |
| ISO/IEC 25010 | 2023 | 產品品質模型(9 項品質特性) | 第 2 章 |
| TOGAF Standard | 第 10 版 | 企業架構方法(ADM)與架構內容框架 | 企業層級;本指引聚焦解決方案架構 |
| AWS Well-Architected | 2026 更新 | 雲端工作負載的 6 大支柱(卓越營運、安全、可靠性、效能效率、成本最佳化、永續性) | 附錄 B 檢核表 |
| Azure Well-Architected | 持續更新 | 5 大支柱(可靠性、安全、成本最佳化、卓越營運、效能效率) | 附錄 B 檢核表 |
| SEI ATAM | — | 以品質屬性情境評估架構取捨 | 2.3 |
| arc42 | 第 9 版範本 | 架構文件的 12 個章節結構 | 1.5 |
| C4 Model | — | 以 4 個抽象層級繪製架構圖 | 1.5 |
| MADR | 4.0.0 | ADR 的 Markdown 格式 | 1.4 |
ISO/IEC/IEEE 42010:2022 的幾個核心名詞是後續各節的共同語言,第一次接觸時請先理解:
| 名詞 | 英文 | 意義 | 例子 |
|---|---|---|---|
| 利害關係人 | Stakeholder | 對系統有利益或關注的人或組織 | 業務單位、維運團隊、資安稽核 |
| 關注點 | Concern | 利害關係人在意的事情 | 「尖峰時段下單不能超過 1 秒」 |
| 觀點 | Viewpoint | 描述「用什麼方式看系統」的規約 | 部署觀點:節點、網路、區域 |
| 視圖 | View | 依某個觀點畫出的實際描述 | 正式環境的部署圖 |
| 對應關係 | Correspondence | 不同視圖元素之間的關聯 | 「訂單容器」部署在「AZ-a 的 Node Pool」 |
| 決策理由 | Rationale | 為什麼這樣設計 | ADR 的內容 |
42010 不規定用哪一種圖或工具,它規定的是「架構描述要能追溯到利害關係人的關注點」。因此審查架構文件時,第一個問題永遠是:這張圖回答了誰的什麼問題?
1.2 架構原則
架構原則是團隊做取捨時的共同依據。下表是本企業採用的架構原則,每項原則都附上「如何判斷有沒有做到」,避免原則淪為口號:
| 原則 | 說明 | 如何判斷有沒有做到 |
|---|---|---|
| 業務能力導向 | 模組與服務依業務能力(Bounded Context)切分,而非依技術層切分 | 服務名稱是業務名詞(訂單、付款),而不是技術名詞(db-service、common-service) |
| 高內聚、低耦合 | 一起變更的東西放在一起;跨邊界只透過明確的介面 | 一個需求變更平均只需要修改 1 個服務;跨服務 PR 比例低於 10% |
| 依賴指向穩定方 | 不穩定的模組依賴穩定的模組;業務核心不依賴框架 | ArchUnit 測試證明 domain 套件沒有依賴 Spring 或 JPA(7.2) |
| 為失敗而設計 | 任何遠端呼叫都會失敗,設計時就要決定失敗時的行為 | 每個對外呼叫都有逾時、重試或降級設定(第 10 章) |
| 預設安全 | 安全是預設值,而不是額外選項 | 未經設定的端點預設拒絕存取;機密不出現在版本庫(第 11 章) |
| 可觀測 | 系統行為可以從外部觀察,不需要登入主機查看 | 每個請求都能用 Trace ID 串起跨服務的呼叫(第 12 章) |
| 自動化優先 | 能自動化的檢查不靠人工 | 架構規則、API 規格、部署設定都在 CI 檢查(1.7、第 14 章) |
| 演進式設計 | 只為已知的需求設計,保留未來調整的空間,不預先過度設計 | 每個複雜機制(分片、CQRS、Service Mesh)都有對應的 ADR 說明當下需要它的理由 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-001 | 必須 | 每項架構原則都必須附上「如何判斷有沒有做到」的可觀察標準;不接受只有口號的原則 | 👁 架構審查 |
GOV-002 | 應該 | 引入複雜機制(分散式交易、分片、CQRS、Service Mesh、多區域部署)前,必須以 ADR 說明當下的需求與更簡單的替代方案為何不足 | 👁 架構審查:比對架構元件清單與 ADR 清單 |
<!-- ❌ GOV-001 原則只有口號,沒有人能判斷有沒有做到 -->
- 系統要有高擴展性
- 系統要安全
<!-- ✅ GOV-001 原則附上可觀察的判斷標準 -->
- 水平擴展:訂單服務在 CPU 70% 時自動增加副本,壓測 3 倍流量時 p99 < 800 ms
- 預設安全:所有端點預設需要 JWT,例外端點列在 SecurityConfig 白名單並經資安審查
<!-- ❌ GOV-002 沒有 ADR 就引入 Kafka + CQRS,只因為「以後可能會用到」 -->
<!-- ✅ GOV-002 ADR-0007 說明:日訂單 30 萬筆、報表查詢拖慢交易庫,讀寫分離不足,因此導入 CQRS -->🔍 1.2 審查與驗證
人工審查問題:
- 架構文件列出的每項原則,是否都能指出一個可觀察的證據(測試、指標、設定)?(
GOV-001) - 架構圖中的每個「複雜元件」(訊息佇列、快取叢集、Service Mesh、讀寫分離)是否都有對應的 ADR?(
GOV-002)
AI 常見錯誤: AI 產生的架構原則常常是一串形容詞(高可用、高效能、高安全),沒有任何可驗證的標準;也常常在需求只有幾百位使用者時,就提出微服務、Kafka、Redis Cluster 與 Service Mesh 的「標準架構」(GOV-001、GOV-002)。
1.3 技術選型與技術雷達
技術選型的目標是「選擇團隊能長期維運的技術」,而不是選擇最新或最熱門的技術。企業以技術雷達管理允許使用的技術:
| 環 | 意義 | 使用條件 |
|---|---|---|
| Adopt(採用) | 已在多個正式系統驗證,有維運經驗 | 可直接使用 |
| Trial(試用) | 已通過評估,適合在低風險的正式系統試用 | 需架構師同意,並在 ADR 記錄 |
| Assess(評估) | 值得研究,但尚未有正式系統使用 | 只能用於 PoC |
| Hold(暫緩) | 不建議新專案使用,或已停止維護 | 新專案不得使用;既有系統需有汰換計畫 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-003 | 必須 | 新專案只能使用技術雷達 Adopt 或 Trial 環的技術;使用 Trial 環技術必須有 ADR | 👁 架構審查:比對相依清單(SBOM)與技術雷達 |
GOV-004 | 必須 | 不得使用已結束支援(EOL)或在 12 個月內 EOL 而沒有升級計畫的版本 | 🤖 依 endoflife.date API 或 SBOM 掃描工具比對 |
GOV-005 | 應該 | 技術選型以加權評估矩陣比較至少兩個方案,評估項目包含團隊能力、社群活躍度、授權、支援期限與總持有成本 | 👁 ADR 審查 |
技術雷達以 YAML 維護在架構版本庫,方便 CI 自動比對:
# tech-radar.yaml(✅ GOV-003 技術雷達以檔案管理,CI 可比對 SBOM)
- name: Spring Boot
quadrant: frameworks
ring: adopt
versions: ">=4.0"
- name: Spring Modulith
quadrant: frameworks
ring: trial
adr: ADR-0012
- name: Istio Ambient Mode
quadrant: platforms
ring: assess
- name: Spring Cloud Netflix Hystrix
quadrant: frameworks
ring: hold # 2018 年起停止維護,改用 Resilience4j 或 Spring Framework 7 內建韌性功能
replacement: Resilience4j選型評估矩陣(GOV-005)。權重總和為 100,每個方案以 1–5 分評分:
<!-- ✅ GOV-005 至少比較兩個方案,評估項目涵蓋團隊能力與總持有成本 -->
| 評估項目 | 權重 | Kafka | RabbitMQ | 雲端代管佇列 |
| --- | --- | --- | --- | --- |
| 符合需求(事件重播、保留 7 天) | 30 | 5 | 2 | 3 |
| 團隊能力與維運經驗 | 25 | 3 | 4 | 4 |
| 總持有成本(3 年) | 20 | 2 | 4 | 4 |
| 支援期限與社群活躍度 | 15 | 5 | 4 | 4 |
| 授權與合規 | 10 | 5 | 5 | 3 |
| **加權總分** | 100 | **3.90** | **3.50** | **3.60** |加權總分 = Σ(權重 × 分數) ÷ 100。以 Kafka 為例:(30×5 + 25×3 + 20×2 + 15×5 + 10×5) ÷ 100 = (150 + 75 + 40 + 75 + 50) ÷ 100 = 3.90。審查評估矩陣時,請自行重算每一個總分,並確認權重總和為 100;總分算錯或與各項分數不一致,是 AI 產生的評估矩陣最常見、也最容易抓到的錯誤。
評估矩陣只是輔助。總分接近時(差距小於 0.3),決策應回到「最重要的那一兩個驅動因素」,並在 ADR 中說明。
<!-- ❌ GOV-004 選用已 EOL 的版本 -->
- 框架:Spring Boot 2.7(開源支援已於 2023-11 結束)
- 執行環境:Java 11
<!-- ✅ GOV-004 選用支援中的版本,並記錄支援期限 -->
- 框架:Spring Boot 4.1.x(開源支援至 2027-06)
- 執行環境:Java 25 LTS🔍 1.3 審查與驗證
自動檢查: 在 CI 產生 SBOM(第 11.8 節),再以腳本比對技術雷達的 hold 清單與 endoflife.date 的支援期限(GOV-003、GOV-004)。
人工審查問題:
- 相依清單中是否有 Hold 環或已 EOL 的技術?(
GOV-003、GOV-004) - 評估矩陣的權重總和是否為 100?每個方案的加權總分是否算對?(
GOV-005) - 評估項目是否包含「團隊能力」與「總持有成本」,而不只是功能比較?(
GOV-005)
AI 常見錯誤: AI 推薦的版本常是訓練資料當時的版本(例如 Spring Boot 3.2、Java 17),也常推薦已停止維護的元件(Hystrix、Ribbon、Zuul 1);評估矩陣的加權總分算錯的情形也很常見(GOV-004、GOV-005)。
1.4 架構決策紀錄 (ADR)
架構決策紀錄(Architecture Decision Record,ADR)記錄一個重要決策的背景、考慮過的選項、最後的選擇與後果。它解決的問題是:半年後沒有人記得「為什麼當初這樣設計」。
什麼樣的決策需要 ADR? 符合下列任一條件即需要:
- 會影響品質屬性(效能、可用性、安全)的決策。
- 難以反悔或反悔成本高的決策(資料庫選型、服務拆分、對外 API 格式)。
- 偏離本指引規則的決策(豁免,見 0.6)。
- 引入新技術或新的外部相依。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-006 | 必須 | 符合上述條件的決策必須以 ADR 記錄,存放於系統版本庫的 docs/adr/,以 PR 審查 | 🤖 CI 檢查 docs/adr/ 的檔名格式與必要章節 |
GOV-007 | 必須 | ADR 採用 MADR 4.0 格式,至少包含:狀態、日期、決策者、背景與問題、考慮的選項(至少兩個)、決策結果與後果、確認方式 | 🤖 CI 檢查必要標題 |
GOV-008 | 必須 | 已接受(accepted)的 ADR 不得修改決策內容;決策改變時新增一份 ADR,並將舊 ADR 狀態改為 superseded by ADR-NNNN | 🤖 CI 比對已接受 ADR 的內容變更;👁 PR 審查 |
GOV-009 | 應該 | ADR 的「確認方式」(Confirmation)必須指出可以驗證此決策被落實的方法,例如 ArchUnit 測試、CI 檢查或指標 | 👁 ADR 審查 |
MADR 4.0 格式的 ADR 範例:
---
status: accepted
date: 2026-09-15
decision-makers: 架構師 王大明、訂單組組長 李小華
consulted: 資安組、SRE 組
informed: 全體開發團隊
---
# ADR-0012 訂單系統採用模組化單體,而非微服務
<!-- ✅ GOV-006 存放於 docs/adr/0012-modular-monolith-for-order.md -->
<!-- ✅ GOV-007 包含 MADR 4.0 的必要章節 -->
## Context and Problem Statement
訂單系統預計上線第一年有 5,000 位使用者、尖峰 50 TPS,開發團隊 6 人。
需要決定系統要以微服務或單體方式建置。
## Decision Drivers
- 團隊人數少,無專職平台工程師
- 業務邊界仍在調整,預計第一年會有大量跨模組變更
- 未來可能拆分付款模組給其他團隊維護
## Considered Options
- 微服務(訂單、庫存、付款各自部署)
- 模組化單體(Spring Modulith,單一部署單元)
- 傳統分層單體
## Decision Outcome
選擇「模組化單體」,因為它在團隊規模與業務不確定性下維運成本最低,
同時以模組邊界保留未來拆分付款模組的彈性。
### Consequences
- 好處:單一部署、單一資料庫交易,維運簡單
- 壞處:所有模組共用發布週期;需要以測試守住模組邊界,否則會退化為大泥球
### Confirmation
<!-- ✅ GOV-009 確認方式指向可自動驗證的測試 -->
`ModularityTests` 執行 `ApplicationModules.verify()`,模組間出現循環依賴或
存取其他模組的內部套件時,CI 失敗(見 7.4)。
## Pros and Cons of the Options
### 微服務
- 好處:可獨立部署與擴展
- 壞處:6 人團隊需維運多個部署單元、分散式交易與服務網路,成本過高
### 傳統分層單體
- 好處:最簡單
- 壞處:沒有模組邊界,無法支援未來拆分付款模組決策改變時的正確做法(GOV-008):
<!-- ❌ GOV-008 直接修改已接受的 ADR-0012,把「模組化單體」改成「微服務」,歷史消失 -->
<!-- ✅ GOV-008 新增 ADR-0031,並更新 ADR-0012 的狀態 -->
---
status: superseded by ADR-0031
date: 2026-09-15
---
# ADR-0012 訂單系統採用模組化單體,而非微服務CI 可以用簡單的腳本檢查 ADR 格式(GOV-006、GOV-007):
#!/usr/bin/env bash
# check-adr.sh — ✅ GOV-006 / GOV-007 檢查 ADR 檔名與必要章節
set -euo pipefail
status=0
for f in docs/adr/[0-9][0-9][0-9][0-9]-*.md; do
for section in "## Context and Problem Statement" "## Considered Options" \
"## Decision Outcome" "### Confirmation"; do
if ! grep -qF "$section" "$f"; then
echo "::error file=$f::缺少必要章節:$section"
status=1
fi
done
grep -qE '^status: (proposed|accepted|rejected|deprecated|superseded by ADR-[0-9]{4})$' "$f" \
|| { echo "::error file=$f::status 欄位格式錯誤"; status=1; }
done
exit "$status"🔍 1.4 審查與驗證
自動檢查: CI 執行 check-adr.sh,檢查檔名、必要章節與狀態值(GOV-006、GOV-007)。
人工審查問題:
- 「考慮的選項」是否至少有兩個真正可行的方案,而不是一個稻草人方案?(
GOV-007) - 「後果」是否同時列出好處與壞處?只有好處的 ADR 通常是事後補寫的。(
GOV-007) - 「確認方式」是否能被驗證?「團隊會注意」不算確認方式。(
GOV-009) - 這份 PR 是否修改了已接受 ADR 的決策內容?(
GOV-008)
AI 常見錯誤: AI 寫的 ADR 常常只有一個選項,或把「不採用的選項」寫得明顯不合理;「後果」只列好處;status 寫成 MADR 不認得的值(例如 approved、done)(GOV-007)。
1.5 架構文件:arc42 與 C4 模型
架構文件採用 arc42 的章節結構,架構圖採用 C4 模型的抽象層級。兩者搭配使用:arc42 決定「寫什麼」,C4 決定「圖怎麼畫」。
arc42 的 12 個章節與必要程度:
| 章節 | 內容 | 必要程度 | 對應本指引 |
|---|---|---|---|
| 1. Introduction and Goals | 需求概要、品質目標(前 3–5 項)、利害關係人 | 必須 | 第 2 章 |
| 2. Architecture Constraints | 技術、組織、法規限制 | 必須 | 1.3 |
| 3. Context and Scope | 系統邊界、外部系統與介面(C4 Level 1) | 必須 | 1.5 |
| 4. Solution Strategy | 關鍵技術決策與架構風格摘要 | 必須 | 第 3 章 |
| 5. Building Block View | 容器與元件分解(C4 Level 2、3) | 必須 | 第 3、7 章 |
| 6. Runtime View | 重要情境的執行流程(循序圖) | 應該 | 第 4 章 |
| 7. Deployment View | 部署拓撲、環境、網路 | 必須 | 第 13 章 |
| 8. Cross-cutting Concepts | 安全、日誌、錯誤處理、交易等跨領域機制 | 必須 | 第 10–12 章 |
| 9. Architecture Decisions | ADR 清單(連結到 docs/adr/) | 必須 | 1.4 |
| 10. Quality Requirements | 品質樹與品質情境 | 必須 | 2.3 |
| 11. Risks and Technical Debts | 已知風險與技術債 | 應該 | 1.6 |
| 12. Glossary | 業務與技術名詞 | 應該 | 3.3 通用語言 |
C4 模型的四個層級:
| 層級 | 名稱 | 回答的問題 | 讀者 | 必要程度 |
|---|---|---|---|---|
| 1 | System Context | 系統和誰互動? | 所有人,包括非技術人員 | 必須 |
| 2 | Container | 系統由哪些可部署/可執行的單元組成?用什麼技術?如何通訊? | 開發、維運、資安 | 必須 |
| 3 | Component | 一個容器內部由哪些元件組成? | 開發 | 選用(複雜容器才畫) |
| 4 | Code | 類別層級的結構 | 開發 | 不建議手繪,由 IDE 產生 |
C4 的「Container」指的是可獨立執行或部署的單元(應用程式、資料庫、佇列),不是 Docker 容器。這是最常見的誤解。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-010 | 必須 | 每個系統必須有依 arc42 結構撰寫的架構文件,至少包含上表「必須」的章節,存放在系統版本庫(docs-as-code) | 🤖 CI 檢查 docs/architecture/ 的章節標題;👁 架構審查 |
GOV-011 | 必須 | 架構文件必須有 C4 Level 1(System Context)與 Level 2(Container)圖;每個容器標示技術與通訊協定 | 👁 架構審查 |
GOV-012 | 應該 | 架構圖以文字描述(Mermaid、PlantUML 或 Structurizr DSL)產生並納入版本控制,不使用無法比對差異的二進位圖檔 | 🤖 CI 檢查 docs/ 下沒有 .vsdx、.drawio.png 等檔案 |
GOV-013 | 應該 | 每張圖都要有標題、圖例,以及每條連線的說明(做什麼、用什麼協定、同步或非同步) | 👁 架構審查 |
C4 Level 1(System Context)範例,以 Mermaid flowchart 繪製:
flowchart TB
%% ✅ GOV-011 C4 Level 1:系統與外部的互動;GOV-013 每條連線都說明用途
customer["👤 消費者<br/>[Person]<br/>透過網頁下單、查詢訂單"]
staff["👤 客服人員<br/>[Person]<br/>處理退貨與客訴"]
order["🟦 線上訂單系統<br/>[Software System]<br/>接受訂單、處理付款與出貨"]
payment["⬜ 金流閘道<br/>[External System]<br/>信用卡授權與請款"]
logistics["⬜ 物流系統<br/>[External System]<br/>建立出貨單、回報配送狀態"]
idp["⬜ 企業身分提供者<br/>[External System]<br/>OIDC 登入"]
customer -- "下單、查詢<br/>HTTPS" --> order
staff -- "處理退貨<br/>HTTPS" --> order
order -- "授權、請款<br/>HTTPS / REST,同步" --> payment
order -- "建立出貨單<br/>HTTPS / REST,非同步回呼" --> logistics
order -- "驗證身分<br/>OIDC" --> idpC4 Level 2(Container)範例。若團隊使用 Structurizr,建議以 DSL 維護模型,一份模型可以產生所有層級的圖,避免多張圖不一致:
workspace "線上訂單系統" {
// ✅ GOV-012 以 Structurizr DSL 描述模型,納入版本控制
model {
customer = person "消費者"
payment = softwareSystem "金流閘道" "信用卡授權與請款" "External"
orderSystem = softwareSystem "線上訂單系統" {
spa = container "Web 前端" "下單與查詢介面" "Vue 3 / TypeScript"
api = container "訂單 API" "訂單、庫存、付款模組" "Java 25 / Spring Boot 4.1"
db = container "訂單資料庫" "訂單與庫存資料" "PostgreSQL 18" "Database"
broker = container "事件代理" "領域事件" "Apache Kafka 4.3" "Queue"
}
// ✅ GOV-011 每個容器標示技術;GOV-013 每條關係說明用途與協定
customer -> spa "下單、查詢" "HTTPS"
spa -> api "呼叫 API" "HTTPS / JSON"
api -> db "讀寫訂單" "JDBC"
api -> broker "發布 OrderPlaced 事件" "Kafka,非同步"
api -> payment "授權付款" "HTTPS / REST,同步,逾時 3 秒"
}
views {
systemContext orderSystem "Context" { include * autolayout lr }
container orderSystem "Containers" { include * autolayout lr }
}
}<!-- ❌ GOV-011 / GOV-013 一張圖混合了所有層級,連線沒有說明 -->
[使用者] → [Nginx] → [Docker] → [Spring] → [OrderService.java] → [MySQL]
<!-- 問題:
1. 「Docker」不是 C4 的 Container,而是部署技術,應出現在部署圖
2. OrderService.java 是 Level 4(Code),不應出現在 Container 圖
3. 連線沒有說明協定與同步/非同步 -->CI 檢查 arc42 的必要章節是否存在(GOV-010):
#!/usr/bin/env bash
# check-arc42.sh — ✅ GOV-010 架構文件放在版本庫,必要章節缺一即失敗
set -euo pipefail
required=(01-introduction-and-goals 02-architecture-constraints 03-context-and-scope
04-solution-strategy 05-building-block-view 07-deployment-view
08-crosscutting-concepts 09-architecture-decisions 10-quality-requirements)
missing=0
for name in "${required[@]}"; do
if [[ ! -s "docs/architecture/${name}.md" ]]; then
echo "::error::缺少 arc42 必要章節 docs/architecture/${name}.md"
missing=1
fi
done
exit "$missing"🔍 1.5 審查與驗證
自動檢查: CI 檢查 docs/architecture/ 是否包含 arc42 的必要章節標題,並拒絕二進位圖檔(GOV-010、GOV-012)。Mermaid 圖可用 @mermaid-js/mermaid-cli(mmdc)在 CI 渲染,語法錯誤時失敗。
人工審查問題:
- Context 圖是否列出所有外部系統與使用者角色?是否漏掉身分提供者、監控、批次排程等「看不見」的相依?(
GOV-011) - Container 圖的每個方塊是否都是可獨立執行/部署的單元?是否混入了類別或部署技術?(
GOV-011) - 每條連線是否標示了協定與同步/非同步?(
GOV-013) - 圖與 ADR、部署設定是否一致?例如圖上畫了 Kafka,部署設定是否真的有?(
GOV-010)
AI 常見錯誤: AI 畫的「架構圖」常把 Nginx、Docker、Kubernetes 和業務服務畫在同一層;連線沒有任何說明;或使用 Mermaid 的 C4Context 語法(仍為實驗性功能,各版本渲染結果不一致),建議改用 flowchart 或 Structurizr(GOV-011、GOV-013)。
1.6 架構審查流程
架構審查依 ISO/IEC/IEEE 42020 的「架構評估」流程,在專案的關鍵時間點檢查架構是否滿足品質目標。審查的重點是風險,不是文件格式。
flowchart LR
A["概念審查<br/>(需求確認後)"] --> B["設計審查<br/>(開發開始前)"]
B --> C["實作審查<br/>(每個 Sprint,抽查)"]
C --> D["上線審查<br/>(Go-Live 前)"]
D --> E["定期審查<br/>(每年或重大變更)"]| 審查時機 | 輸入 | 重點 | 輸出 |
|---|---|---|---|
| 概念審查 | 需求、品質目標草案 | 架構風格是否合適、品質目標是否可量測 | 審查紀錄、需補充的 ADR |
| 設計審查 | arc42 文件、ADR、C4 圖 | 品質情境是否都有對應設計(2.3)、風險清單 | 通過/有條件通過/不通過 |
| 實作審查 | 程式碼、架構測試結果 | 實作是否偏離設計、架構測試是否持續通過 | 偏差清單 |
| 上線審查 | 壓測、故障演練、資安掃描報告 | 品質目標是否被證明達成 | 上線許可 |
| 定期審查 | 維運指標、事件報告、技術債清單 | 架構是否仍符合現況 | 技術債與改善計畫 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-014 | 必須 | 設計審查與上線審查必須留下書面紀錄,包含審查人、結論、風險清單與待辦事項的負責人與期限 | 👁 審查紀錄存放於 docs/reviews/ |
GOV-015 | 必須 | 上線審查必須以證據判斷品質目標是否達成(壓測報告、故障演練紀錄、弱點掃描報告),不接受「預期可以達成」 | 👁 上線審查 |
GOV-016 | 應該 | 審查發現的風險以「風險、影響的品質屬性、可能性、衝擊、緩解措施」記錄於 arc42 第 11 章 | 👁 架構審查 |
<!-- ✅ GOV-014 / GOV-016 審查紀錄:結論、風險、負責人與期限 -->
# 設計審查紀錄:線上訂單系統 v1.0(2026-10-01)
- 審查人:架構師 王大明、SRE 陳志明、資安 林美玲
- 結論:**有條件通過**(R-02 需於開發第 2 個 Sprint 結束前解決)
| 編號 | 風險 | 品質屬性 | 可能性 | 衝擊 | 緩解措施 | 負責人 | 期限 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| R-01 | 金流閘道逾時造成執行緒耗盡 | 可用性 | 中 | 高 | 逾時 3 秒+熔斷(RES-001) | 李小華 | 2026-10-20 |
| R-02 | 報表查詢與交易共用資料庫 | 效能 | 高 | 中 | 報表改讀唯讀副本(DATA-008) | 張家豪 | 2026-10-31 |
<!-- ❌ GOV-015 上線審查只寫「已完成壓測,效能符合預期」,沒有附上報告與數據 -->🔍 1.6 審查與驗證
人工審查問題:
- 審查紀錄是否有明確的結論(通過/有條件通過/不通過),以及每項待辦的負責人與期限?(
GOV-014) - 上線審查是否附上壓測報告、故障演練紀錄與弱點掃描結果?數據是否與第 2 章的品質目標逐項對照?(
GOV-015) - 風險是否標示影響的品質屬性與緩解措施?(
GOV-016)
AI 常見錯誤: AI 產生的審查紀錄常常每一項都是「通過」,沒有任何風險;或把「預期效能良好」當成證據(GOV-015)。
1.7 架構適應度函數 (Fitness Functions)
架構適應度函數(Architecture Fitness Function)是「可以自動執行、用來判斷架構是否仍符合某個特性」的檢查。它把架構規則從文件變成 CI 中會失敗的測試,避免架構隨時間退化。
| 類型 | 檢查的特性 | 工具範例 | 執行時機 |
|---|---|---|---|
| 結構 | 分層、模組邊界、循環依賴 | ArchUnit、Spring Modulith | 每次建置 |
| 契約 | API 規格相容性 | Spectral、oasdiff、Pact | 每次 PR |
| 效能 | 回應時間、吞吐量 | k6、Gatling 的門檻(thresholds) | 每日或發布前 |
| 安全 | 相依弱點、設定錯誤 | Trivy、OWASP Dependency-Check、kubeconform | 每次建置 |
| 韌性 | 故障時的行為 | Chaos Mesh、Litmus、故障注入測試 | 定期演練 |
| 維運 | 部署設定符合標準 | Kyverno、OPA Gatekeeper 政策 | 部署時(Admission) |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
GOV-017 | 必須 | 本指引中標示 🤖 的「必須」規則,必須在 CI 中以適應度函數自動檢查,檢查失敗時阻擋合併 | 🤖 CI 設定審查 |
GOV-018 | 應該 | 每個 ADR 的「確認方式」若可自動化,必須實作為適應度函數,並在測試名稱或註解中引用 ADR 編號 | 👁 ADR 審查 |
以 ArchUnit 實作 ADR-0012 的確認方式(模組間不得有循環依賴)。完整的分層測試見 7.2:
package com.example.shop.architecture;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;
// ✅ GOV-017 架構規則以測試實作,CI 中失敗即阻擋合併
// ✅ GOV-018 測試註明對應的 ADR
@AnalyzeClasses(packages = "com.example.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class ModuleCycleArchTest {
/** ADR-0012:模組(com.example.shop 下一層套件)之間不得有循環依賴。 */
@ArchTest
static final ArchRule modules_should_be_free_of_cycles =
slices().matching("com.example.shop.(*)..").should().beFreeOfCycles();
}# ❌ GOV-017 架構測試存在,但 CI 以 -DskipTests 跳過,等於沒有檢查
- name: Build
run: ./mvnw -B package -DskipTests🔍 1.7 審查與驗證
自動檢查: 確認 CI 的建置步驟有執行測試,且架構測試類別(*ArchTest、ModularityTests)有出現在測試報告中(GOV-017)。
人工審查問題:
- CI 是否有
-DskipTests、--no-verify、continue-on-error: true等繞過檢查的設定?(GOV-017) - 架構測試是否曾經真的失敗過?可以故意加入一個違規的依賴,確認測試會變紅。(
GOV-017) - ADR 的確認方式是否都已實作?(
GOV-018)
AI 常見錯誤: AI 產生的 ArchUnit 測試常常寫錯套件名稱(例如 ..service.. 但專案用 application),導致規則永遠不會匹配任何類別而「永遠通過」。ArchUnit 1.x 預設在規則沒有匹配任何類別時失敗(archRule.failOnEmptyShould=true),不要為了讓測試通過而把它關掉(GOV-017)。
2. 品質屬性與非功能需求
功能需求決定系統「做什麼」,品質屬性決定系統「做得多好」。架構的大部分決策(拆不拆服務、要不要快取、部署幾個區域)都是為了滿足品質屬性,因此品質屬性必須先被寫清楚、可以量測,架構才有判斷的依據。
2.1 ISO/IEC 25010:2023 品質模型
ISO/IEC 25010:2023 將產品品質分為 9 項特性。和 2011 版相比,2023 版新增「安全性(Safety)」與「彈性(Flexibility)」,並把「可用性(Usability)」改名為「互動能力(Interaction capability)」、「可攜性(Portability)」併入「彈性」。
| 品質特性 | 子特性 | 常見的架構手段 | 本指引章節 |
|---|---|---|---|
| 功能適合性 Functional suitability | 功能完整性、功能正確性、功能適當性 | 領域模型、驗收測試 | 第 3 章 |
| 效能效率 Performance efficiency | 時間行為、資源使用率、容量 | 快取、非同步、水平擴展、資料分割 | 第 9 章 |
| 相容性 Compatibility | 共存性、互通性 | 標準協定、API 版本管理、契約測試 | 第 4、5 章 |
| 互動能力 Interaction capability | 可辨識性、易學性、可操作性、使用者錯誤防護、使用者參與度、包容性、使用者協助、自我描述性 | 設計系統、無障礙(WCAG 2.2)、i18n | 第 6 章 |
| 可靠性 Reliability | 無缺陷性、可用性、容錯性、可恢復性 | 冗餘、熔斷、重試、備份與災難復原 | 第 10 章 |
| 資訊安全 Security | 機密性、完整性、不可否認性、可歸責性、真實性、抗攻擊性 | 零信任、加密、稽核日誌、威脅建模 | 第 11 章 |
| 可維護性 Maintainability | 模組化、可重用性、可分析性、可修改性、可測試性 | 分層架構、模組邊界、架構測試、可觀測性 | 第 7、12 章 |
| 彈性 Flexibility | 適應性、擴展性、可安裝性、可替換性 | 容器化、組態外部化、Ports & Adapters | 第 7、13 章 |
| 安全性 Safety | 運作限制、風險識別、失效安全、危害警示、安全整合 | 失效安全預設值、限流、人工確認關卡 | 第 10 章 |
中文的「安全」同時對應 Security(資訊安全,防止惡意攻擊)與 Safety(安全性,防止系統對人或環境造成危害)。本指引以「資訊安全」與「安全性」區分。一般企業應用系統以 Security 為主;控制實體設備、醫療或金融交易的系統則必須同時評估 Safety。
2.2 非功能需求的量化
「系統要快」「系統要穩定」不是需求,因為沒有人能判斷它有沒有被滿足。品質需求必須寫成品質屬性情境(Quality Attribute Scenario),這是 SEI 提出、ATAM 評估方法使用的六段式格式:
| 段落 | 意義 | 範例 |
|---|---|---|
| 來源(Source) | 誰或什麼觸發 | 消費者 |
| 刺激(Stimulus) | 發生了什麼 | 送出訂單 |
| 環境(Environment) | 在什麼條件下 | 雙 11 尖峰,每秒 500 筆訂單 |
| 標的(Artifact) | 影響系統的哪個部分 | 訂單 API |
| 回應(Response) | 系統怎麼反應 | 建立訂單並回傳訂單編號 |
| 回應量測(Response measure) | 怎麼判斷做得夠好 | p99 回應時間 ≤ 800 ms,錯誤率 ≤ 0.1% |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
NFR-001 | 必須 | 每項品質需求都要寫成六段式品質屬性情境,回應量測必須是可量測的數字與條件 | 👁 需求審查 |
NFR-002 | 必須 | 回應時間以百分位數(p95、p99)表示,並註明負載條件;不得只用平均值 | 👁 需求審查;🧪 壓測報告必須輸出百分位數 |
NFR-003 | 必須 | 系統的品質目標必須排序,前 3–5 項寫入 arc42 第 1 章,作為架構取捨的依據 | 👁 架構審查 |
NFR-004 | 必須 | 法規與合規要求(個人資料保護法、資通安全管理法、產業規範)必須列為品質需求,並指出對應的控制措施 | 👁 架構審查;👁 資安審查 |
<!-- ❌ NFR-001 / NFR-002 無法驗證的需求 -->
- 系統回應要快,平均回應時間 200 ms 以內
- 系統要高可用
- 系統要能支援大量使用者
<!-- ✅ NFR-001 六段式情境;NFR-002 以百分位數表示,並註明負載條件 -->
| 編號 | 來源 | 刺激 | 環境 | 標的 | 回應 | 回應量測 |
| --- | --- | --- | --- | --- | --- | --- |
| QS-01 | 消費者 | 送出訂單 | 尖峰 500 TPS,持續 30 分鐘 | 訂單 API | 建立訂單並回傳編號 | p99 ≤ 800 ms,錯誤率 ≤ 0.1% |
| QS-02 | 金流閘道 | 連續逾時 | 正常負載 | 付款模組 | 熔斷並回傳「付款處理中」 | 10 秒內熔斷,其他 API 的 p99 不受影響 |
| QS-03 | 維運人員 | 一個 AZ 失效 | 正常負載 | 整體系統 | 流量自動轉到其他 AZ | 5 分鐘內恢復,不遺失已確認的訂單 |
| QS-04 | 開發人員 | 新增一種付款方式 | 開發期間 | 付款模組 | 只修改付款模組 | 2 人週內完成,其他模組不需修改 |為什麼不能只用平均值?假設 100 個請求中,99 個是 100 ms、1 個是 10 秒,平均值是 199 ms,看起來「符合 200 ms 的需求」,但每 100 位使用者就有 1 位等了 10 秒。百分位數 p99 = 10 秒,才會暴露這個問題。
<!-- ✅ NFR-003 品質目標排序,寫入 arc42 第 1 章 -->
## 1.2 品質目標
| 優先 | 品質目標 | 情境 | 理由 |
| --- | --- | --- | --- |
| 1 | 可靠性:不遺失已確認的訂單 | QS-03 | 遺失訂單造成直接營收損失與客訴 |
| 2 | 效能:尖峰下單不超過 800 ms | QS-01 | 行銷活動尖峰流量為平日 10 倍 |
| 3 | 可修改性:新增付款方式 2 人週內完成 | QS-04 | 每季新增 1–2 種付款方式 |
<!-- ✅ NFR-004 法規需求列為品質需求,並指出控制措施 -->
| 編號 | 法規要求 | 控制措施 | 章節 |
| --- | --- | --- | --- |
| CMP-01 | 個資法:個人資料蒐集需告知目的,並可依請求刪除 | 個資欄位分級、刪除 API、稽核日誌 | 8.6、11.6 |
| CMP-02 | 資通安全管理法及其子法:依防護基準留存並保護系統日誌(保存期限依主管機關與內部政策,本例訂為 180 天) | 日誌集中保存 180 天以上,不可竄改 | 12.3 |🔍 2.2 審查與驗證
人工審查問題:
- 每一項品質需求是否都有「回應量測」欄,而且是數字?(
NFR-001) - 回應時間是否用百分位數表示,並註明負載條件與持續時間?(
NFR-002) - 品質目標是否有排序?當「效能」與「資訊安全」衝突時,團隊是否知道哪一個優先?(
NFR-003) - 系統處理個人資料或屬於關鍵基礎設施時,是否列出對應的法規需求?(
NFR-004)
AI 常見錯誤: AI 常把 v1.x 這類「API 平均回應 < 200ms」「CPU 使用率 < 80%」直接當成品質需求;後者是維運指標,不是使用者感受到的品質,而且沒有負載條件就無法驗證(NFR-001、NFR-002)。
2.3 品質情境與取捨分析
品質屬性之間經常衝突:加密提升資訊安全但增加延遲;多區域部署提升可用性但增加成本與資料一致性的困難。ATAM(Architecture Tradeoff Analysis Method)以**效用樹(Utility Tree)**排序品質情境,再逐一分析架構決策對它們的影響。
flowchart LR
%% ✅ NFR-005 效用樹:每個情境標示(業務重要性, 實作難度)
U["效用<br/>Utility"] --> P["效能"]
U --> R["可靠性"]
U --> M["可修改性"]
P --> QS01["QS-01 尖峰下單 p99 ≤ 800 ms<br/>(H, M)"]
R --> QS02["QS-02 金流逾時 10 秒內熔斷<br/>(H, M)"]
R --> QS03["QS-03 AZ 失效 5 分鐘內恢復<br/>(H, H)"]
M --> QS04["QS-04 新增付款方式 2 人週<br/>(M, L)"]括號內第一個字母是業務重要性,第二個是實作難度(H/M/L)。(H, H)的情境是架構風險最高、最需要投入設計的地方。
分析時,對每個高優先的情境找出:
| 名詞 | 意義 | 範例 |
|---|---|---|
| 敏感點(Sensitivity point) | 對某個品質屬性影響很大的設計參數 | 連線池大小直接影響 QS-01 |
| 取捨點(Tradeoff point) | 同時影響多個品質屬性、而且方向相反的設計參數 | 同步複寫到第二個區域:提升 QS-03,但增加 QS-01 的延遲 |
| 風險(Risk) | 可能讓品質目標無法達成的決策 | 付款與訂單共用連線池,金流變慢會拖垮下單 |
| 非風險(Non-risk) | 已確認沒有問題的決策 | 唯讀查詢走快取,命中率 95% 已由壓測證明 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
NFR-005 | 應該 | 以效用樹標示每個品質情境的業務重要性與實作難度,(H, H)的情境必須有對應的 ADR 與驗證計畫 | 👁 架構審查 |
NFR-006 | 必須 | 每個品質情境必須能追溯到「架構決策」與「驗證方式」(測試、壓測、演練或監控指標);沒有驗證方式的情境視為未完成 | 👁 架構審查:檢查追溯表 |
<!-- ✅ NFR-006 品質情境 → 架構決策 → 驗證方式的追溯表 -->
| 情境 | 架構決策 | 取捨點 | 驗證方式 |
| --- | --- | --- | --- |
| QS-01 | 商品資料快取(ADR-0015)、HPA 自動擴展 | 快取一致性 vs. 回應時間 | k6 壓測 500 TPS,門檻 p(99)<800 |
| QS-02 | Resilience4j 熔斷 + 獨立隔艙(ADR-0018) | 降級時無法即時確認付款 | 故障注入測試:金流 mock 延遲 30 秒 |
| QS-03 | 跨 3 個 AZ 部署、資料庫同步複寫(ADR-0020) | 寫入延遲 +2 ms | 每季 AZ 失效演練 |
| QS-04 | 付款模組以 Port & Adapter 設計(ADR-0016) | 多一層抽象 | ArchUnit 測試:其他模組不得依賴付款實作 |
<!-- ❌ NFR-006 有情境、有設計,但沒有驗證方式;上線後才發現達不到 -->
| QS-01 | 加快取 | — | — |🔍 2.3 審查與驗證
人工審查問題:
- 是否每個(H, H)情境都有 ADR 與驗證計畫?(
NFR-005) - 追溯表中的每個情境是否都有驗證方式?驗證方式是否會在上線前執行?(
NFR-006) - 是否明確寫出取捨點,而不是假裝所有品質屬性都能同時最佳化?(
NFR-006)
AI 常見錯誤: AI 常宣稱某個設計「同時提升效能、安全與可用性」,沒有任何取捨;或把驗證方式寫成「上線後監控」,等於沒有事前驗證(NFR-006)。
2.4 SLI、SLO 與錯誤預算
可用性與可靠性目標以 Google SRE 的 SLI/SLO 方法定義:
| 名詞 | 意義 | 範例 |
|---|---|---|
| SLI(Service Level Indicator) | 量測服務品質的指標,通常是「好事件 ÷ 全部事件」 | 回應碼非 5xx 且 800 ms 內完成的請求比例 |
| SLO(Service Level Objective) | SLI 在一段期間內的目標值 | 28 天內 99.9% |
| SLA(Service Level Agreement) | 對客戶的合約承諾,違反有罰則 | 每月 99.5%,未達成退費 10% |
| 錯誤預算(Error budget) | 1 − SLO,允許失敗的額度 | 28 天 × 0.1% ≈ 40 分鐘 |
可用性目標與允許的停機時間(以平均每月 30.44 天計算):
| 可用性 | 每月允許停機 | 每年允許停機 | 典型架構要求 |
|---|---|---|---|
| 99% | 7.31 小時 | 3.65 天 | 單一實例+自動重啟 |
| 99.5% | 3.65 小時 | 1.83 天 | 多實例,單一 AZ |
| 99.9% | 43.8 分鐘 | 8.77 小時 | 多 AZ、自動容錯移轉、無停機部署 |
| 99.95% | 21.9 分鐘 | 4.38 小時 | 多 AZ、資料庫自動容錯移轉、完整的自動化 |
| 99.99% | 4.38 分鐘 | 52.6 分鐘 | 多區域主動—主動、人工介入不足以應變 |
串聯可用性: 一個請求依序經過多個相依元件時,整體可用性是各元件可用性的乘積。例如:API Gateway 99.95% × 訂單服務 99.9% × 資料庫 99.95% × 金流閘道 99.9% = 99.70%,低於每個元件的可用性。因此對外承諾的 SLO 不能高於關鍵路徑上相依元件的串聯結果,除非有降級或冗餘設計。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
NFR-007 | 必須 | 對外提供的服務必須定義 SLI 與 SLO;SLI 以「好事件 ÷ 全部事件」計算,SLO 不得為 100% | 👁 架構審查;🤖 Prometheus 規則(12.4) |
NFR-008 | 必須 | SLO 必須考慮關鍵路徑上相依元件的串聯可用性;無法達成時必須設計降級或冗餘,並在 ADR 說明 | 👁 架構審查:檢查可用性計算 |
NFR-009 | 應該 | 訂定錯誤預算政策:錯誤預算耗盡時,暫停功能發布,優先處理可靠性問題 | 👁 錯誤預算政策文件 |
NFR-010 | 應該 | 對內 SLO 應比對外 SLA 嚴格,保留緩衝 | 👁 架構審查 |
SLO 以 YAML 定義並納入版本控制,作為產生監控規則與儀表板的來源(企業內部格式;需要跨工具標準時可採用 OpenSLO 規格):
# slo/order-api.yaml
# ✅ NFR-007 SLI 為「好事件 ÷ 全部事件」,SLO 不是 100%
service: order-api
slos:
- name: order-api-availability
sli:
description: 回應碼非 5xx 的請求比例
good: sum(rate(http_server_requests_seconds_count{application="order-api",status!~"5.."}[5m]))
total: sum(rate(http_server_requests_seconds_count{application="order-api"}[5m]))
objective: 0.999 # ✅ NFR-010 對內 99.9%,對外 SLA 為 99.5%
window: 28d
- name: order-api-latency
sli:
description: 800 ms 內完成的請求比例
good: sum(rate(http_server_requests_seconds_bucket{application="order-api",le="0.8"}[5m]))
total: sum(rate(http_server_requests_seconds_count{application="order-api"}[5m]))
objective: 0.99
window: 28d
# ✅ NFR-009 錯誤預算政策
errorBudgetPolicy:
- when: 剩餘錯誤預算 < 25%
action: 新功能發布需 SRE 同意
- when: 錯誤預算耗盡
action: 凍結功能發布,只允許可靠性修正與安全修補,直到預算恢復# ❌ NFR-007 SLO 設為 100%:任何一次失敗都違反 SLO,錯誤預算為 0,團隊無法做任何變更
objective: 1.0
# ❌ NFR-008 承諾 99.99%,但關鍵路徑上的金流閘道只有 99.9%,且沒有降級設計
objective: 0.9999上例
le="0.8"的寫法需要 Spring Boot 開啟 histogram 並設定 0.8 秒的 SLO 邊界(management.metrics.distribution.slo.http.server.requests=800ms),否則不會有這個 bucket。詳見 12.4。
🔍 2.4 審查與驗證
自動檢查: 以 promtool check rules 驗證由 SLO 產生的錄製規則與告警規則(NFR-007,見 12.4)。
人工審查問題:
- SLI 的「好事件」定義是否反映使用者感受?例如 4xx 是否應該算失敗?(
NFR-007) - 請自行重算關鍵路徑的串聯可用性,是否低於宣稱的 SLO?(
NFR-008) - 錯誤預算耗盡時,誰有權決定凍結發布?政策是否經過業務單位同意?(
NFR-009) - 對內 SLO 是否比對外 SLA 嚴格?(
NFR-010)
AI 常見錯誤: AI 常宣稱「本架構可達 99.99% 可用性」,卻沒有任何計算;或把可用性與停機時間換算錯誤(例如 99.9% 寫成每月 4.3 分鐘,那是 99.99% 的數字)。請用上方的換算表核對(NFR-008)。
2.5 成本與永續性目標
AWS Well-Architected 的成本最佳化與永續性支柱,要求把成本與資源效率當作品質屬性來設計,而不是上線後才檢討帳單。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
NFR-011 | 應該 | 定義單位成本目標(例如每千筆訂單的基礎設施成本),並在架構審查時估算 | 👁 架構審查 |
NFR-012 | 必須 | 所有雲端資源與 Kubernetes 工作負載必須標記成本歸屬標籤(系統、環境、成本中心),未標記的資源不得建立 | 🤖 Kyverno/OPA 政策、雲端標籤政策 |
NFR-013 | 應該 | 非正式環境在非上班時間自動縮減規模;工作負載的資源請求(requests)依實測用量設定,避免長期閒置 | 🤖 排程縮放設定;👁 定期檢視使用率報表 |
# ✅ NFR-012 工作負載標記成本歸屬標籤
apiVersion: apps/v1
kind: Deployment
metadata:
name: order-api
namespace: order
labels:
app.kubernetes.io/name: order-api
app.kubernetes.io/part-of: online-order
cost-center: "CC-1234"
environment: production
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: order-api
template:
metadata:
labels:
app.kubernetes.io/name: order-api
cost-center: "CC-1234"
environment: production
spec:
containers:
- name: order-api
image: registry.example.com/order/order-api:1.4.2
resources:
requests:
cpu: 500m # ✅ NFR-013 依壓測實測用量設定
memory: 768Mi
limits:
memory: 768Mi<!-- ✅ NFR-011 架構審查時估算單位成本 -->
| 項目 | 每月成本 | 每月訂單數 | 每千筆訂單成本 |
| --- | --- | --- | --- |
| 運算(3 副本 × 0.5 vCPU) | NT$ 9,000 | 900,000 | NT$ 10.0 |
| 資料庫(主+1 唯讀副本) | NT$ 18,000 | 900,000 | NT$ 20.0 |
| 合計 | NT$ 27,000 | 900,000 | **NT$ 30.0** |🔍 2.5 審查與驗證
自動檢查: 以准入政策(ValidatingAdmissionPolicy、Kyverno 或 OPA Gatekeeper)拒絕缺少 cost-center 標籤的工作負載(NFR-012,政策範例見 13.6)。
人工審查問題:
- 是否估算過單位成本?流量成長 10 倍時,成本是線性成長還是更快?(
NFR-011) - 資源請求是否有壓測或監控數據支持,還是直接抄範本?(
NFR-013)
AI 常見錯誤: AI 產生的 Kubernetes 設定常把 requests 與 limits 設成固定的範本值(例如 cpu: 1000m、memory: 2Gi),沒有任何依據,造成大量閒置成本(NFR-013)。
3. 架構風格與系統拆分
架構風格決定系統的「骨架」:有幾個部署單元、模組之間怎麼溝通、資料放在哪裡。v1.x 預設所有系統都採用微服務;v2.0 改為依品質目標與團隊規模選擇,並以「模組化單體」作為大多數新系統的起點。
3.1 架構風格的選擇
| 風格 | 部署單元 | 適合情境 | 主要代價 |
|---|---|---|---|
| 分層單體 | 1 | 小型系統、生命週期短、業務簡單 | 缺乏模組邊界,規模變大後容易變成「大泥球」 |
| 模組化單體 | 1 | 大多數新系統;團隊 2–30 人;業務邊界仍在探索 | 模組共用發布週期與執行環境;需要以測試守住邊界 |
| 微服務 | 多個 | 多個團隊需要獨立發布;各模組的擴展或可用性需求差異大 | 分散式系統的複雜度:網路失敗、資料一致性、維運與可觀測性成本 |
| 事件驅動 | 多個 | 業務流程以事件串接、需要高度解耦或事件重播 | 最終一致性、除錯困難、事件版本管理 |
| Serverless | 多個函式 | 突發、間歇性的工作負載;事件觸發的處理 | 冷啟動、執行時間限制、供應商綁定、本機測試困難 |
選擇時依序回答下列問題。只要有一題答「否」,就先不要選擇微服務:
flowchart TD
Q1{"是否有多個團隊<br/>需要獨立發布?"} -- 否 --> MM["模組化單體"]
Q1 -- 是 --> Q2{"業務邊界是否<br/>已經穩定?"}
Q2 -- 否 --> MM
Q2 -- 是 --> Q3{"是否已具備 CI/CD、<br/>容器平台與分散式追蹤?"}
Q3 -- 否 --> MM2["模組化單體<br/>+先補齊平台能力"]
Q3 -- 是 --> Q4{"各模組的擴展或可用性<br/>需求是否差異很大?"}
Q4 -- 否 --> MM3["模組化單體<br/>或少量服務"]
Q4 -- 是 --> MS["微服務<br/>(依 3.4 拆分)"]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
STY-001 | 必須 | 架構風格的選擇必須以 ADR 記錄,並說明團隊規模、發布獨立性、品質目標與平台成熟度如何支持這個選擇 | 👁 ADR 審查 |
STY-002 | 應該 | 新系統預設採用模組化單體;只有在上方決策流程的所有問題都答「是」時,才採用微服務 | 👁 ADR 審查 |
STY-003 | 不應該 | 為了「未來可能需要擴展」而在第一版就拆分微服務 | 👁 ADR 審查 |
<!-- ❌ STY-001 / STY-003 沒有理由的微服務 -->
# ADR-0001 採用微服務架構
本系統採用微服務架構,以提升擴展性與彈性。
(團隊 4 人、使用者 300 人、沒有 Kubernetes 平台,且未比較其他選項)
<!-- ✅ STY-001 / STY-002 以決策條件說明選擇 -->
# ADR-0001 採用模組化單體
- 團隊:1 個團隊、6 人,沒有獨立發布的需求
- 業務邊界:訂單、庫存、付款的邊界仍在調整
- 平台:已有 Kubernetes,但尚未導入分散式追蹤
- 結論:採用模組化單體,以 Spring Modulith 驗證模組邊界;
當「付款」需要由另一個團隊獨立發布時,再依 ADR-0016 的拆分條件抽出🔍 3.1 審查與驗證
人工審查問題:
- ADR 是否說明了團隊數量與發布獨立性的需求?(
STY-001) - 若選擇微服務,平台是否已具備 CI/CD、容器平台、集中式日誌與分散式追蹤?(
STY-002) - 選擇微服務的理由是否是「現在」的需求,而不是「未來可能」?(
STY-003)
AI 常見錯誤: 不論需求規模,AI 幾乎總是推薦「微服務 + API Gateway + Kafka + Redis + Kubernetes」的組合,因為訓練資料中的架構範例多半如此。審查時請要求 AI 說明為什麼模組化單體不夠(STY-002、STY-003)。
3.2 模組化單體與 Spring Modulith
模組化單體是「一個部署單元,內部依業務能力切成邊界清楚的模組」。它保留單體的簡單(單一部署、本地交易、容易除錯),同時保留未來拆分的可能。邊界必須由工具守住,否則很快就會退化。
Spring Modulith 以套件結構定義模組:應用程式主類別所在套件的直接子套件,就是一個模組。模組的根套件是公開 API,子套件預設是內部實作,其他模組不得存取。
com.example.shop ← ShopApplication(@SpringBootApplication)
├── order ← 模組:訂單(根套件 = 公開 API)
│ ├── OrderManagement.java ← 公開的服務介面
│ ├── OrderPlaced.java ← 公開的領域事件
│ ├── package-info.java ← @ApplicationModule 宣告允許的依賴
│ ├── domain/ ← 內部:實體、值物件、Repository 介面
│ ├── application/ ← 內部:Use Case 實作
│ └── adapter/ ← 內部:Web、持久化、外部系統轉接器
├── inventory ← 模組:庫存(被訂單模組同步呼叫,不依賴訂單模組)
│ ├── InventoryManagement.java
│ └── internal/
├── payment ← 模組:付款
│ ├── api/ ← @NamedInterface("api"):開放給其他模組的子套件
│ └── internal/
└── shipping ← 模組:出貨(監聽 OrderPlaced 事件)
└── internal/| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
STY-004 | 必須 | 模組化單體必須以工具驗證模組邊界(Spring Modulith ApplicationModules.verify() 或 ArchUnit),並在 CI 執行 | 🧪 ModularityTests |
STY-005 | 必須 | 模組只能透過其他模組的公開 API(根套件或 @NamedInterface)互動;不得存取其他模組的內部套件或直接存取其他模組的資料表 | 🧪 ModularityTests;👁 檢查 SQL 是否跨模組 JOIN |
STY-006 | 應該 | 每個模組以 package-info.java 的 @ApplicationModule(allowedDependencies = …) 明確宣告允許依賴的模組 | 🧪 ModularityTests |
STY-007 | 應該 | 模組之間的副作用(例如下單後建立出貨單、寄送通知)優先以領域事件溝通,而不是直接呼叫對方的服務 | 👁 架構審查;🧪 Modulith Scenario 測試 |
@org.springframework.modulith.ApplicationModule(
displayName = "訂單",
allowedDependencies = {"inventory", "payment :: api"})
// ✅ STY-006 明確宣告訂單模組只能依賴 inventory 的公開 API 與 payment 的 api 具名介面
package com.example.shop.order;@org.springframework.modulith.NamedInterface("api")
// ✅ STY-005 payment 模組只公開 api 子套件,internal 子套件對其他模組不可見
package com.example.shop.payment.api;package com.example.shop;
import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;
import org.springframework.modulith.docs.Documenter;
// ✅ STY-004 以測試驗證模組邊界:循環依賴、存取內部套件、違反 allowedDependencies 都會失敗
class ModularityTests {
private final ApplicationModules modules = ApplicationModules.of(ShopApplication.class);
@Test
void verifiesModularStructure() {
modules.verify();
}
@Test
void writesDocumentation() {
// 產生 C4 元件圖與模組說明(PlantUML/AsciiDoc),可納入 arc42 第 5 章
new Documenter(modules).writeDocumentation();
}
}package com.example.shop.order.application;
import com.example.shop.inventory.internal.StockRepository; // ❌ STY-005 存取 inventory 模組的內部套件
class PlaceOrderService {
// modules.verify() 會回報:Module 'order' depends on non-exposed type
// com.example.shop.inventory.internal.StockRepository within module 'inventory'!
}模組間以事件溝通(STY-007)。@ApplicationModuleListener 是 Spring Modulith 提供的組合註解,等同於「交易提交後、非同步、在新交易中」處理事件。搭配 Event Publication Registry(spring-modulith-starter-jdbc),事件會先寫入資料庫,處理失敗時可以重送,這就是模組化單體版本的 Transactional Outbox(見 4.4):
package com.example.shop.shipping.internal;
import com.example.shop.order.OrderPlaced;
import org.springframework.modulith.events.ApplicationModuleListener;
import org.springframework.stereotype.Component;
// ✅ STY-007 出貨模組監聽訂單模組的公開事件,訂單模組不需要知道出貨模組的存在
@Component
class OrderPlacedListener {
private final ShipmentService shipmentService;
OrderPlacedListener(ShipmentService shipmentService) {
this.shipmentService = shipmentService;
}
@ApplicationModuleListener
void on(OrderPlaced event) {
shipmentService.createShipment(event.orderId(), event.lines());
}
}模組依賴必須是單向的:訂單模組同步呼叫庫存模組預留庫存(使用者需要立即知道庫存是否足夠),因此庫存模組不能再監聽訂單模組的事件,否則兩個模組互相依賴,
verify()會回報循環依賴。下單後不需要立即結果的副作用,交給只依賴訂單模組的出貨、通知模組以事件處理。
🔍 3.2 審查與驗證
自動檢查: CI 執行 ModularityTests(STY-004~STY-006)。要確認測試有效,可以故意在 order 模組 import 另一個模組的 internal 類別,測試必須失敗。
人工審查問題:
- 是否有 SQL 或 JPA 關聯直接跨到其他模組的資料表?Modulith 只檢查 Java 型別依賴,檢查不到 SQL。(
STY-005) -
allowedDependencies是否只列出真正需要的模組?(STY-006) - 模組之間的同步呼叫是否是必要的查詢,而非可以改用事件的副作用?(
STY-007)
AI 常見錯誤: AI 常把所有模組共用的類別放在 common 或 shared 模組,結果所有模組都依賴它,變成新的耦合中心;也常用 @EventListener 取代 @ApplicationModuleListener,導致事件在交易提交前就被處理、交易回滾時庫存仍被扣除(STY-005、STY-007)。
3.3 領域驅動設計:戰略設計
領域驅動設計(Domain-Driven Design,DDD)的戰略設計用來找出模組與服務的邊界。架構層級需要掌握三個概念:
| 概念 | 意義 | 判斷方式 |
|---|---|---|
| 通用語言(Ubiquitous Language) | 業務與開發在一個邊界內使用一致的名詞 | 同一個詞在程式碼、文件、會議中意思相同 |
| 限界上下文(Bounded Context) | 一個模型有效的邊界;邊界內名詞意義一致 | 「商品」在目錄上下文是「可銷售的品項」,在庫存上下文是「倉庫中的 SKU」,兩者是不同模型 |
| 上下文對映(Context Map) | 限界上下文之間的關係與整合方式 | 誰是上游、誰是下游、用什麼方式轉換模型 |
上下文對映的常見關係模式:
| 模式 | 意義 | 適用情境 |
|---|---|---|
| 合作關係(Partnership) | 兩個團隊共同規劃、同步發布 | 緊密合作的兩個團隊 |
| 共享核心(Shared Kernel) | 共用一小部分模型與程式碼 | 很少使用;共享的部分要極小並有共同的擁有者 |
| 客戶—供應商(Customer–Supplier) | 下游提出需求,上游排入計畫 | 同一組織內的上下游團隊 |
| 順從者(Conformist) | 下游直接採用上游的模型 | 上游不會因下游調整(例如使用外部標準) |
| 防腐層(Anticorruption Layer,ACL) | 下游以轉換層隔離上游模型 | 整合舊系統或外部系統,避免對方的模型污染自己 |
| 開放主機服務(Open Host Service)+公開語言(Published Language) | 上游提供穩定、文件化的協定給多個下游 | 對多個系統提供的 API 或事件 |
| 各行其道(Separate Ways) | 不整合 | 整合成本高於收益 |
flowchart LR
%% ✅ STY-008 上下文對映標示上下游與關係模式
Catalog["目錄上下文"] -- "OHS / PL<br/>商品事件" --> Order["訂單上下文"]
Order -- "Customer–Supplier<br/>預留庫存 API" --> Inventory["庫存上下文"]
Order -- "ACL<br/>付款轉接器" --> Legacy["舊付款系統<br/>(外部)"]
Order -- "OHS / PL<br/>OrderPlaced 事件" --> Shipping["出貨上下文"]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
STY-008 | 應該 | 系統設計時繪製上下文對映,標示每個關係的上下游與整合模式 | 👁 架構審查 |
STY-009 | 必須 | 整合舊系統或外部系統時,必須以防腐層轉換對方的模型;外部模型的類別不得出現在領域層 | 🤖 ArchUnit:domain 套件不得依賴外部系統的用戶端套件 |
STY-010 | 應該 | 每個限界上下文維護自己的名詞表(arc42 第 12 章),同一名詞在不同上下文意義不同時必須註明 | 👁 文件審查 |
package com.example.shop.payment.internal;
import com.example.shop.payment.api.PaymentResult;
import com.example.shop.payment.api.PaymentStatus;
// ✅ STY-009 防腐層:把舊付款系統的回應碼轉換成本系統的模型,外部模型不外流
class LegacyPaymentTranslator {
PaymentResult translate(LegacyPaymentResponse response) {
PaymentStatus status = switch (response.rtnCode()) {
case "0000" -> PaymentStatus.AUTHORIZED;
case "1001", "1002" -> PaymentStatus.DECLINED;
case "9999" -> PaymentStatus.UNKNOWN; // 逾時或系統錯誤,需查詢確認
default -> PaymentStatus.FAILED;
};
return new PaymentResult(response.txnNo(), status);
}
/** 舊付款系統的回應格式,只存在於轉接器內部。 */
record LegacyPaymentResponse(String txnNo, String rtnCode, String rtnMsg) {
}
}// ❌ STY-009 外部系統的回應類別直接進入領域模型,舊系統改格式時整個訂單模組都要改(片段)
public class Order {
private LegacyPaymentResponse paymentResponse; // 外部模型污染領域層
}(片段:違規示意,未編譯)
<!-- ✅ STY-010 名詞表(arc42 第 12 章):同名不同義的名詞註明所屬上下文 -->
| 名詞 | 上下文 | 定義 | 程式中的型別 |
| --- | --- | --- | --- |
| 商品 | 目錄 | 可對外銷售的品項,含名稱、價格、圖片 | `catalog.Product` |
| 商品 | 庫存 | 倉庫中的 SKU,含儲位與數量 | `inventory.StockItem` |
| 訂單 | 訂單 | 消費者送出的購買請求,含明細與狀態 | `order.domain.Order` |
| 出貨單 | 出貨 | 依訂單建立的出貨作業,一張訂單可拆成多張出貨單 | `shipping.Shipment` |🔍 3.3 審查與驗證
自動檢查: ArchUnit 規則:noClasses().that().resideInAPackage("..domain..").should().dependOnClassesThat().resideInAPackage("..legacy..")(STY-009)。
人工審查問題:
- 上下文對映是否標示了每條關係的上下游?下游團隊是否知道上游變更時會被通知?(
STY-008) - 領域類別中是否出現外部系統的欄位名稱或代碼(例如
rtnCode)?(STY-009) - 名詞表是否處理了「同名不同義」的名詞?(
STY-010)
AI 常見錯誤: AI 常以資料表或實體來劃分服務(「使用者服務」「商品服務」「訂單服務」各自對應一張主表),這是**實體服務(Entity Service)**反模式,任何業務流程都需要呼叫多個服務才能完成(STY-008)。
3.4 微服務拆分準則
確定採用微服務後,拆分的依據是業務能力與團隊擁有權,而不是技術層或資料表。拆分的結果必須讓大多數需求變更只影響一個服務。
| 準則 | 說明 | 檢查方式 |
|---|---|---|
| 業務能力 | 每個服務對應一個限界上下文或業務能力 | 服務名稱是業務名詞 |
| 單一團隊擁有 | 一個服務只由一個團隊負責(Conway 定律、Team Topologies 的串流對齊團隊) | 服務目錄中每個服務只有一個擁有團隊 |
| 獨立部署 | 一個服務可以單獨部署,不需要同時部署其他服務 | 過去 3 個月有多少次發布需要多個服務同時部署 |
| 資料擁有權 | 每個服務擁有自己的資料,其他服務只能透過 API 或事件取得 | 沒有其他服務的連線字串指向該服務的資料庫 |
| 適當大小 | 一個團隊可以完整理解與維護 | 不以程式碼行數判斷,以「團隊認知負荷」判斷 |
常見的拆分反模式:
| 反模式 | 症狀 | 改善方式 |
|---|---|---|
| 分散式單體(Distributed Monolith) | 服務必須一起部署、一起測試;一個服務當機全部不能用 | 合併過度拆分的服務,或改用事件解耦 |
| 共用資料庫 | 多個服務讀寫同一組資料表 | 每個服務擁有自己的 schema,透過 API 或事件同步 |
| 實體服務(Entity Service) | 服務只是資料表的 CRUD 包裝 | 依業務能力重新劃分 |
| 過細的奈米服務(Nanoservice) | 一個功能需要呼叫 5 個以上的服務 | 合併緊密耦合的服務 |
| 同步呼叫鏈過長 | A → B → C → D 同步呼叫,延遲與失敗率相乘 | 鏈長度不超過 3 層;改用事件或資料複本 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
STY-011 | 必須 | 每個微服務擁有自己的資料儲存;不得有兩個服務讀寫同一個 schema 或資料表 | 👁 架構審查:檢查各服務的資料來源設定;🤖 資料庫帳號權限只授予單一 schema |
STY-012 | 必須 | 每個服務必須能單獨部署;部署一個服務不得要求同時部署其他服務 | 🧪 契約測試(4.6);👁 發布紀錄 |
STY-013 | 應該 | 處理單一使用者請求的同步呼叫鏈不超過 3 層 | 🤖 分散式追蹤分析(Trace 深度);👁 循序圖審查 |
STY-014 | 必須 | 每個服務在服務目錄中登錄唯一的擁有團隊、聯絡方式與 SLO | 🤖 服務目錄(例如 Backstage catalog-info.yaml)必要欄位檢查 |
系統整體架構(更新自 v1.x 的 2.1 節):
graph TB
%% ✅ STY-011 每個服務擁有自己的資料庫;STY-013 同步呼叫不超過 3 層
subgraph Client["前端層"]
WEB["Web 應用<br/>Vue 3 / TypeScript"]
MOBILE["行動 App"]
end
subgraph Edge["邊界層"]
CDN["CDN / WAF"]
GW["API Gateway<br/>Gateway API 實作"]
BFF["Web BFF"]
end
subgraph Services["業務服務層"]
ORDER["訂單服務"]
INV["庫存服務"]
PAY["付款服務"]
NOTIFY["通知服務"]
end
subgraph Data["資料層"]
ODB[("訂單 DB<br/>PostgreSQL")]
IDB[("庫存 DB<br/>PostgreSQL")]
PDB[("付款 DB<br/>PostgreSQL")]
CACHE[("快取<br/>Redis")]
BROKER[["事件代理<br/>Kafka"]]
end
subgraph Platform["平台層"]
IDP["身分提供者<br/>Keycloak / OIDC"]
OTEL["OpenTelemetry Collector"]
VAULT["機密管理"]
end
WEB --> CDN --> GW
MOBILE --> GW
GW --> BFF
BFF --> ORDER
BFF --> INV
ORDER --> ODB
ORDER --> CACHE
ORDER -- "預留庫存(同步)" --> INV
ORDER -- "授權付款(同步)" --> PAY
INV --> IDB
PAY --> PDB
ORDER -- "OrderPlaced" --> BROKER
BROKER -- "訂閱" --> NOTIFY
BROKER -- "訂閱" --> INV
GW -. "驗證 Token" .-> IDP
Services -. "Traces / Metrics / Logs" .-> OTEL# catalog-info.yaml(Backstage 服務目錄)
# ✅ STY-014 每個服務登錄唯一擁有團隊與 SLO
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: order-service
description: 訂單建立、查詢與狀態管理
annotations:
example.com/slo: "availability 99.9% / 28d; latency p99 800ms"
example.com/oncall: "order-team-oncall"
spec:
type: service
lifecycle: production
owner: group:order-team
system: online-order
providesApis:
- order-api
dependsOn:
- component:inventory-service
- component:payment-service
- resource:order-db# ❌ STY-011 庫存服務的設定直接連到訂單服務的資料庫
spring:
datasource:
url: jdbc:postgresql://order-db:5432/order # 庫存服務不得存取訂單資料庫# ✅ STY-012 部署前以 Pact Broker 確認:此版本與正式環境上的所有消費者/提供者契約相容,才允許單獨部署
pact-broker can-i-deploy \
--pacticipant order-service --version "${GIT_SHA}" \
--to-environment production<!-- ❌ STY-012 發布說明要求「訂單服務 v2.3 必須與庫存服務 v1.8、付款服務 v3.1 同時部署」,這是分散式單體的徵兆 -->🔍 3.4 審查與驗證
自動檢查: 每個服務使用專屬的資料庫帳號,帳號只對自己的 schema 有權限,跨 schema 存取會在執行時失敗(STY-011);分散式追蹤可統計每個請求的同步呼叫深度(STY-013)。
人工審查問題:
- 畫出最重要的 3 個使用者情境的循序圖:是否有超過 3 層的同步呼叫?(
STY-013) - 過去的需求中,有多少比例需要同時修改多個服務?超過 20% 通常代表拆分錯誤。(
STY-012) - 是否有服務沒有明確的擁有團隊,或由多個團隊共同維護?(
STY-014)
AI 常見錯誤: AI 產生的微服務架構常讓所有服務連到同一個資料庫(「為了方便 JOIN」),這是分散式單體,同時具有單體與微服務的缺點(STY-011)。
3.5 演進式遷移:Strangler Fig
將既有系統遷移到新架構時,不要一次性重寫。**Strangler Fig(絞殺者模式)**在舊系統前方放置路由層,逐步把功能導向新系統,直到舊系統可以下線。
flowchart LR
U["使用者"] --> R["路由層<br/>API Gateway"]
R -- "/orders/**(已遷移)" --> N["新訂單服務"]
R -- "其他路徑" --> L["舊系統"]
N -. "ACL 讀取尚未遷移的資料" .-> L| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
STY-015 | 應該 | 系統遷移採用漸進式策略(Strangler Fig),以路由層切換流量;不得採用需要長期凍結舊系統功能的一次性重寫 | 👁 遷移計畫審查 |
STY-016 | 必須 | 每個遷移階段都要有可回退的切換機制(路由開關或功能旗標)與比對驗證(新舊結果比對或影子流量) | 🧪 切換與回退演練紀錄 |
以 Kubernetes Gateway API 的 HTTPRoute 實作路由層,依路徑把已遷移的功能導向新服務:
# ✅ STY-015 以路由層逐步切換;STY-016 以權重控制流量比例,可隨時改回 0 回退
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: orders-migration
namespace: shop
spec:
parentRefs:
- name: public-gateway
namespace: gateway
hostnames:
- shop.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /api/orders
backendRefs:
- name: order-service # 新服務
port: 8080
weight: 10 # 先導入 10% 流量
- name: legacy-shop # 舊系統
port: 8080
weight: 90
- backendRefs:
- name: legacy-shop
port: 8080<!-- ❌ STY-015 / STY-016 一次性重寫,沒有回退機制 -->
- 2026-Q1~Q4:重寫整個系統,期間舊系統凍結功能
- 2027-01-01:一次切換到新系統,舊系統下線🔍 3.5 審查與驗證
自動檢查: 以 kubeconform 驗證 HTTPRoute 的格式(需載入 Gateway API 的 CRD schema,見 13.7)。
人工審查問題:
- 每個階段是否可以在 5 分鐘內回退到舊系統?是否演練過?(
STY-016) - 新舊系統並行期間,資料的權威來源(source of truth)是哪一邊?是否有同步與比對機制?(
STY-016) - 遷移計畫是否讓舊系統長期凍結功能?業務單位是否同意?(
STY-015)
AI 常見錯誤: AI 常提出「先完整重寫再切換」的計畫,並低估資料遷移與新舊並行的成本(STY-015)。
4. 整合與通訊
模組或服務之間的通訊方式,直接決定系統的耦合程度、延遲與失敗行為。本章說明同步與非同步通訊的選擇、邊界閘道、服務網格,以及在分散式環境下確保資料一致的模式。
4.1 同步與非同步通訊的選擇
| 方式 | 典型技術 | 適用 | 不適用 |
|---|---|---|---|
| 同步請求/回應 | REST(HTTP/JSON)、gRPC | 呼叫端需要立即得到結果(查詢、驗證、授權) | 長時間處理;只是通知對方「發生了某事」 |
| 非同步訊息(命令) | 訊息佇列(RabbitMQ、SQS) | 交辦工作給另一方處理,不需要立即結果 | 需要立即回應的使用者操作 |
| 非同步事件 | 事件串流(Kafka)、模組事件 | 通知「已發生的事實」,讓多個訂閱者各自反應 | 需要知道「對方是否處理成功」的流程 |
| 查詢語言 | GraphQL | 前端需要彈性組合多個資料來源(通常在 BFF) | 服務間通訊 |
協定選擇:
| 協定 | 優點 | 缺點 | 建議使用處 |
|---|---|---|---|
| REST + JSON | 通用、易除錯、工具完整 | 文字格式較大;契約需另以 OpenAPI 描述 | 對外 API、前後端、大多數服務間呼叫 |
| gRPC + Protobuf | 高效能、強型別、支援串流 | 瀏覽器需要 gRPC-Web;除錯較不直覺 | 內部高流量、低延遲的服務間呼叫 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-001 | 必須 | 每一個遠端呼叫(HTTP、gRPC、資料庫、快取、訊息代理)都必須設定連線逾時與讀取逾時,不得使用無限等待的預設值 | 👁 程式碼審查;🧪 故障注入測試(對方延遲時呼叫端會逾時) |
INT-002 | 必須 | 逾時時間必須依呼叫端的 SLO 由外往內遞減:上游的總逾時大於下游逾時加上重試的總和 | 👁 架構審查:檢查逾時預算表 |
INT-003 | 應該 | 不需要立即結果的副作用(通知、統計、同步到其他系統)以非同步事件處理,不放在使用者請求的同步路徑上 | 👁 循序圖審查 |
INT-004 | 應該 | 服務間的 HTTP 用戶端以宣告式介面(Spring Framework 7 HTTP Service Client)實作,逾時與基底網址由設定檔管理 | 👁 程式碼審查 |
逾時預算(INT-002): 假設使用者請求的 SLO 是 p99 800 ms,Gateway 逾時 1 秒,則訂單服務呼叫付款服務的逾時必須小於 1 秒扣除自身處理時間;若還要重試一次,單次逾時必須更短。常見錯誤是每一層都設 30 秒,上游早已逾時放棄,下游仍在處理,浪費資源。
<!-- ✅ INT-002 逾時預算表:由外往內遞減 -->
| 呼叫 | 逾時 | 重試 | 最壞情況耗時 |
| --- | --- | --- | --- |
| 瀏覽器 → Gateway | 10 s(前端顯示處理中) | 0 | 10 s |
| Gateway → 訂單服務 | 3 s | 0 | 3 s |
| 訂單服務 → 付款服務 | 1 s | 1 次(僅限冪等操作) | 2 s + 退避 0.2 s |
| 付款服務 → 金流閘道 | 0.8 s | 0 | 0.8 s |以 Spring Framework 7 的 HTTP Service Client 宣告服務間呼叫(INT-004),Spring Boot 4 會依 spring.http.serviceclient.<群組> 的設定建立用戶端:
package com.example.shop.payment.internal;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;
// ✅ INT-004 宣告式 HTTP 用戶端,不在程式中寫死網址與逾時
@HttpExchange("/v1/payments")
interface PaymentGatewayClient {
@PostExchange("/authorizations")
AuthorizationResponse authorize(@RequestBody AuthorizationRequest request);
record AuthorizationRequest(String orderId, long amountInCents, String currency) {
}
record AuthorizationResponse(String transactionId, String resultCode) {
}
}package com.example.shop.payment.internal;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.service.registry.ImportHttpServices;
// ✅ INT-004 以群組註冊 HTTP Service Client,群組名稱對應設定檔
@Configuration(proxyBeanMethods = false)
@ImportHttpServices(group = "payment-gateway", types = PaymentGatewayClient.class)
class PaymentClientConfig {
}# application.yml
spring:
http:
clients:
connect-timeout: 1s # ✅ INT-001 所有 HTTP 用戶端的預設逾時
read-timeout: 3s
serviceclient:
payment-gateway:
base-url: https://pg.example.com
connect-timeout: 500ms # ✅ INT-002 依逾時預算覆寫個別群組
read-timeout: 800ms# ❌ INT-001 Spring Boot 3.x 的舊屬性:在 Boot 4 已棄用(改為 spring.http.clients.*)
spring:
http:
client:
read-timeout: 30s # ❌ INT-002 30 秒遠大於上游 Gateway 的 3 秒逾時sequenceDiagram
%% ✅ INT-003 使用者只等待必要的同步步驟;通知與統計以事件非同步處理
participant U as 使用者
participant O as 訂單服務
participant P as 付款服務
participant K as 事件代理
participant N as 通知服務
U->>O: POST /orders
O->>P: 授權付款(同步,需要結果)
P-->>O: 已授權
O->>K: OrderPlaced(交易提交後)
O-->>U: 201 Created
K-->>N: OrderPlaced
N->>N: 寄送確認信(非同步,不影響回應時間)🔍 4.1 審查與驗證
自動檢查: 以 Spring Boot 的 spring-boot-properties-migrator 在啟動時列出已棄用或已改名的屬性;本指引的建置腳本也會比對 YAML 範例中的屬性是否存在於 Boot 4.1 的設定中繼資料(INT-001)。
人工審查問題:
- 每一個
RestClient、WebClient、gRPC stub、JDBC 連線池、Redis 用戶端是否都有逾時設定?(INT-001) - 請畫出逾時預算表:下游逾時加重試是否小於上游逾時?(
INT-002) - 使用者請求的同步路徑上,是否有可以改為非同步的副作用(寄信、寫稽核紀錄到外部系統)?(
INT-003)
AI 常見錯誤: AI 產生的 HTTP 用戶端常常沒有設定任何逾時(Java HttpClient 預設沒有讀取逾時),或使用 Boot 3.x 的 spring.http.client.* 屬性;在 Boot 4 中仍可運作但已棄用,應改為 spring.http.clients.*(INT-001)。
4.2 API Gateway 與 Kubernetes Gateway API
API Gateway 位於系統邊界,負責橫切的、與業務無關的職責。業務邏輯不屬於 Gateway。
| 職責 | 放在 Gateway | 放在服務 |
|---|---|---|
| TLS 終止、HTTP/2、壓縮 | ✅ | |
| 路由、流量切分、金絲雀發布 | ✅ | |
| 驗證存取權杖(簽章、有效期限、audience) | ✅(粗粒度) | ✅(細粒度授權必須在服務內) |
| 速率限制、請求大小限制 | ✅ | |
| CORS、安全標頭 | ✅ | |
| 業務規則、資料轉換、資料彙整 | ✅(或 BFF) |
Kubernetes 的 Gateway API(gateway.networking.k8s.io)是 Ingress 的後繼標準,以角色分工設計:平台團隊管理 GatewayClass 與 Gateway,應用團隊管理自己的 HTTPRoute。Istio、Envoy Gateway、Kong、NGINX Gateway Fabric 等都實作了此標準。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-005 | 必須 | Gateway 不得包含業務邏輯(業務規則判斷、資料彙整、資料格式轉換);需要為特定前端彙整資料時使用 BFF | 👁 架構審查:檢查 Gateway 外掛與腳本 |
INT-006 | 應該 | 新的 Kubernetes 叢集以 Gateway API 取代 Ingress;平台團隊管理 Gateway,應用團隊只管理自己命名空間的 HTTPRoute | 🤖 kubeconform;👁 RBAC 審查 |
INT-007 | 必須 | 對外的 Gateway 只接受 HTTPS;HTTP 只用於導向 HTTPS | 🤖 kubeconform+政策檢查 listener 設定 |
INT-008 | 應該 | 每個 HTTPRoute 規則設定請求逾時,與 4.1 的逾時預算一致 | 🤖 政策檢查 spec.rules[].timeouts |
# ✅ INT-006 平台團隊管理的 Gateway;INT-007 只開放 HTTPS,HTTP 僅導向
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public-gateway
namespace: gateway
spec:
gatewayClassName: istio
listeners:
- name: https
protocol: HTTPS
port: 443
hostname: "*.example.com"
tls:
mode: Terminate
certificateRefs:
- name: wildcard-example-com
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
gateway-access: public
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: http-to-https
namespace: gateway
spec:
parentRefs:
- name: public-gateway
sectionName: http
rules:
- filters:
- type: RequestRedirect
requestRedirect:
scheme: https
statusCode: 301# ✅ INT-006 應用團隊在自己的命名空間管理 HTTPRoute;INT-008 設定逾時
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: order-api
namespace: order
spec:
parentRefs:
- name: public-gateway
namespace: gateway
sectionName: https
hostnames:
- api.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /orders
timeouts:
request: 3s
backendRefs:
- name: order-api
port: 8080# ❌ INT-005 在 Gateway 以腳本實作業務規則(VIP 會員打折),業務邏輯散落在基礎設施中
plugins:
- name: pre-function
config:
access:
- |
if kong.request.get_header("x-member-level") == "VIP" then
kong.service.request.set_header("x-discount", "0.9")
end🔍 4.2 審查與驗證
自動檢查: 以 kubeconform 搭配 Gateway API 的 JSON Schema 驗證資源格式(INT-006~INT-008,指令見 13.7)。
人工審查問題:
- Gateway 的外掛、Lua/JavaScript 腳本中是否有業務規則?(
INT-005) -
allowedRoutes是否限制了哪些命名空間可以掛上公開的 Gateway?(INT-006) - HTTP listener 是否只有導向 HTTPS 的路由?(
INT-007)
AI 常見錯誤: AI 仍常產生 networking.k8s.io/v1 的 Ingress 搭配大量廠商專屬的 annotation(例如 nginx.ingress.kubernetes.io/*),這些 annotation 不可攜,且 Ingress NGINX 專案已於 2026-03 停止維護;新叢集應改用 Gateway API(INT-006)。
4.3 服務網格 (Service Mesh)
服務網格把服務間通訊的橫切需求(mTLS、重試、流量管理、L7 授權、遙測)從應用程式移到基礎設施。Istio 提供兩種資料平面:
| 模式 | 架構 | 優點 | 代價 |
|---|---|---|---|
| Sidecar | 每個 Pod 注入 Envoy 代理 | 功能完整、成熟 | 每個 Pod 額外的 CPU/記憶體;升級需重啟 Pod |
| Ambient | 每個節點一個 ztunnel(L4、mTLS)+選用的 waypoint 代理(L7) | 資源用量低、升級不需重啟應用 Pod | L7 功能需要部署 waypoint |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-009 | 應該 | 只有在需要「所有服務間 mTLS」或「跨多個服務一致的 L7 流量/授權政策」時才導入服務網格,並以 ADR 記錄;服務少於 10 個時優先考慮應用層函式庫與 NetworkPolicy | 👁 ADR 審查 |
INT-010 | 必須 | 導入服務網格時,mTLS 必須設為 STRICT,不得長期停留在 PERMISSIVE | 🤖 政策檢查 PeerAuthentication |
INT-011 | 不應該 | 在服務網格與應用程式同時設定重試,造成重試次數相乘 | 👁 架構審查:比對網格與應用程式的重試設定 |
# ✅ INT-010 命名空間啟用 Ambient 模式,並強制 mTLS;✅ SEC-004 以服務身分(ServiceAccount)而非 IP 授權
apiVersion: v1
kind: Namespace
metadata:
name: order
labels:
istio.io/dataplane-mode: ambient
---
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default
namespace: order
spec:
mtls:
mode: STRICT
---
# 只允許 shop 命名空間的 BFF 以 GET/POST 呼叫訂單服務(L4 身分授權)
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
name: order-api-allow-bff
namespace: order
spec:
selector:
matchLabels:
app.kubernetes.io/name: order-api
action: ALLOW
rules:
- from:
- source:
principals:
- cluster.local/ns/shop/sa/web-bffAmbient 模式下,ztunnel 只處理 L4。
AuthorizationPolicy若使用 HTTP 方法或路徑等 L7 條件,必須部署 waypoint 代理並以targetRefs指向它,否則政策不會生效。
# ❌ INT-011 網格最多 4 次嘗試(首次+重試 3 次)× 應用程式 Resilience4j 最多 4 次嘗試 = 對付款服務最多 16 次呼叫
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: payment
spec:
hosts: [payment]
http:
- route:
- destination:
host: payment
retries:
attempts: 3<!-- ✅ INT-009 導入服務網格的 ADR 摘要:說明需求與更簡單方案的不足 -->
# ADR-0024 導入 Istio Ambient 模式
- 需求:資安稽核要求所有服務間流量 mTLS(目前 38 個服務),並以服務身分做存取控制
- 替代方案:各服務自行設定 TLS 憑證 → 38 個服務的憑證輪替與信任鏈維運成本過高;
NetworkPolicy 只能依 IP/標籤控制 L3/L4,無法提供 mTLS 與服務身分
- 決策:採用 Ambient 模式(不注入 sidecar,資源成本較低),L7 政策只在需要的命名空間部署 waypoint🔍 4.3 審查與驗證
自動檢查: 以 istioctl analyze 檢查網格設定;政策引擎檢查 PeerAuthentication 不得為 PERMISSIVE(INT-010)。
人工審查問題:
- 導入服務網格的 ADR 是否說明了為什麼應用層函式庫與 NetworkPolicy 不足?(
INT-009) - 重試是否只在一個層級設定?網格與應用程式是否同時重試?(
INT-011) - Ambient 模式下使用 L7 條件的授權政策,是否有對應的 waypoint?(
INT-010)
AI 常見錯誤: AI 產生的 Istio 設定常使用已移除的 v1alpha3、v1beta1 API 版本;Istio 1.22 起 networking.istio.io/v1 與 security.istio.io/v1 已是正式版本,應優先使用(INT-010)。
4.4 可靠的訊息傳遞:Outbox 與冪等
雙寫問題: 一個操作同時「寫資料庫」與「發送訊息」時,兩者無法在同一個交易中完成。如果先寫資料庫再發送訊息,發送失敗會遺失事件;如果先發送訊息再寫資料庫,資料庫寫入失敗會產生不存在的事件。
Transactional Outbox 的解法是:在同一個資料庫交易中,把業務資料與「待發送的事件」一起寫入;再由另一個程序讀取 outbox 並發送訊息。這保證「資料寫入成功 ⇔ 事件最終會被發送」,但事件可能被發送超過一次,因此消費端必須冪等。
sequenceDiagram
participant API as 訂單服務
participant DB as 訂單資料庫
participant Relay as Outbox 中繼<br/>(排程或 CDC)
participant K as Kafka
participant C as 出貨服務(消費者)
API->>DB: 同一交易:INSERT orders、INSERT outbox、COMMIT
Relay->>DB: 讀取未發送的 outbox
Relay->>K: 發送 OrderPlaced
Relay->>DB: 標記已發送
K->>C: 投遞 OrderPlaced(可能重複)
C->>C: 以事件 ID 去重,已處理則略過| 方案 | 說明 | 適用 |
|---|---|---|
| Spring Modulith Event Publication Registry | 模組事件在交易中寫入 event_publication 資料表,處理失敗可重送;可再外部化到 Kafka | 模組化單體、Spring 應用 |
| Outbox 資料表 + 排程中繼 | 自行建立 outbox 資料表,以排程程式輪詢發送 | 簡單、低流量 |
| Outbox 資料表 + CDC(Debezium) | 以資料庫異動日誌讀取 outbox,延遲低、不需輪詢 | 高流量、多種資料庫 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-012 | 必須 | 「寫入資料」與「發布事件」必須保證一致:使用 Transactional Outbox(或 Modulith Event Publication Registry),不得在交易中或交易後直接呼叫訊息代理而無補償機制 | 👁 程式碼審查;🧪 整合測試:模擬代理不可用,確認事件最終被送出 |
INT-013 | 必須 | 訊息消費者必須冪等:以事件 ID 去重,或讓處理邏輯本身可重複執行 | 🧪 測試:同一事件投遞兩次,結果與投遞一次相同 |
INT-014 | 應該 | 會改變狀態的對外 API(例如建立訂單、付款)支援 Idempotency-Key 請求標頭,讓用戶端可以安全重試 | 🧪 API 測試:同一 key 重送兩次只建立一筆 |
INT-015 | 必須 | 無法處理的訊息(格式錯誤、超過重試次數)必須送到死信佇列(DLQ)並告警,不得無限重試阻塞後續訊息,也不得直接丟棄 | 👁 設定審查;🤖 DLQ 深度告警(12.4) |
以 Spring Modulith 的事件外部化實作 outbox(INT-012):
package com.example.shop.order;
import java.util.List;
import org.springframework.modulith.events.Externalized;
// ✅ INT-012 模組事件透過 Event Publication Registry 寫入資料庫,
// 提交後再外部化到 Kafka 的 order.events 主題,以 orderId 作為分割鍵
@Externalized("order.events::#{#this.orderId()}")
public record OrderPlaced(String eventId, String orderId, List<Line> lines) {
public record Line(String sku, int quantity) {
}
}# application.yml
spring:
modulith:
events:
jdbc:
schema-initialization:
enabled: false # 正式環境以 Flyway 建立 event_publication 資料表
republish-outstanding-events-on-restart: true # ✅ INT-012 重啟時重送未完成的事件
externalization:
enabled: true冪等消費者(INT-013)。去重紀錄與業務資料寫在同一個交易中,重複的事件會因主鍵衝突而略過:
-- ✅ INT-013 去重資料表:以 (consumer, event_id) 為主鍵
CREATE TABLE processed_event (
consumer VARCHAR(100) NOT NULL,
event_id VARCHAR(64) NOT NULL,
processed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT pk_processed_event PRIMARY KEY (consumer, event_id)
);package com.example.shop.shipping.internal;
import com.example.shop.order.OrderPlaced;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;
@Component
class OrderPlacedKafkaConsumer {
private final JdbcClient jdbc;
private final ShipmentService shipmentService;
OrderPlacedKafkaConsumer(JdbcClient jdbc, ShipmentService shipmentService) {
this.jdbc = jdbc;
this.shipmentService = shipmentService;
}
// ✅ INT-013 去重與建立出貨單在同一個交易;重複投遞時 INSERT 不會新增資料列,直接略過
@KafkaListener(topics = "order.events", groupId = "shipping")
@Transactional
void on(OrderPlaced event) {
int inserted = jdbc.sql("""
INSERT INTO processed_event (consumer, event_id) VALUES ('shipping', :id)
ON CONFLICT DO NOTHING
""")
.param("id", event.eventId())
.update();
if (inserted == 0) {
return; // 已處理過
}
shipmentService.createShipment(event.orderId(), event.lines());
}
}// ❌ INT-012 交易提交前直接送 Kafka:交易回滾時事件已送出;Kafka 不可用時訂單建立失敗(片段)
@Transactional
public Order placeOrder(PlaceOrderCommand command) {
Order order = orderRepository.save(Order.from(command));
kafkaTemplate.send("order.events", order.id(), OrderPlaced.from(order));
return order;
}(片段:違規示意,未編譯)
### ✅ INT-014 用戶端以 Idempotency-Key 安全重試;伺服器對同一 key 回傳第一次的結果
POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324
{"items":[{"sku":"A-001","quantity":2}]}
Idempotency-Key標頭目前是 IETF HTTPAPI 工作小組的草案(draft-ietf-httpapi-idempotency-key-header),已被多數金流 API 採用。伺服器應保存 key 與第一次的回應至少 24 小時;同一 key 但請求內容不同時回傳422。
🔍 4.4 審查與驗證
自動檢查: 整合測試以 Testcontainers 啟動 Kafka 與資料庫,先停止 Kafka 再下單,確認訂單成功、事件在 Kafka 恢復後送出(INT-012);同一事件送兩次,確認只建立一張出貨單(INT-013)。
人工審查問題:
- 程式中是否有
kafkaTemplate.send(...)、rabbitTemplate.convertAndSend(...)出現在@Transactional方法內?(INT-012) - 每個消費者是否說明了它的冪等策略?(
INT-013) - 消費者的重試次數、退避與 DLQ 是否有設定?DLQ 是否有告警與處理流程?(
INT-015)
AI 常見錯誤: AI 產生的事件發布程式碼幾乎都是在 @Transactional 方法中直接呼叫 kafkaTemplate.send(),並假設 Kafka 保證「恰好一次」。Kafka 的 exactly-once 只涵蓋 Kafka 內部的讀—處理—寫,不涵蓋外部資料庫,消費端仍必須冪等(INT-012、INT-013)。
4.5 分散式交易與 Saga
微服務之間不使用兩階段提交(2PC/XA):它需要所有參與者同時可用,鎖定時間長,且多數訊息代理與雲端資料庫不支援。跨服務的業務流程改用 Saga:把流程拆成一連串本地交易,每一步失敗時執行補償動作撤銷前面已完成的步驟。
| 方式 | 說明 | 優點 | 缺點 |
|---|---|---|---|
| 編排式(Orchestration) | 由一個協調者依序呼叫各步驟並處理補償 | 流程集中、容易理解與監控 | 協調者可能變成過於聰明的中心 |
| 協作式(Choreography) | 各服務監聽事件,自行決定下一步 | 鬆耦合 | 流程分散,難以追蹤全貌;步驟多時容易失控 |
步驟超過 3 個或需要清楚的狀態追蹤時,優先使用編排式。
stateDiagram-v2
[*] --> 待處理
待處理 --> 庫存已預留: 預留庫存成功
待處理 --> 已取消: 預留庫存失敗
庫存已預留 --> 已付款: 付款授權成功
庫存已預留 --> 釋放庫存中: 付款授權失敗
釋放庫存中 --> 已取消: 補償:釋放庫存
已付款 --> 已完成: 建立出貨單成功
已付款 --> 退款中: 建立出貨單失敗
退款中 --> 釋放庫存中: 補償:退款
已完成 --> [*]
已取消 --> [*]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-016 | 必須 | 跨服務的資料一致性以 Saga 實作,不得使用跨服務的分散式交易(2PC/XA) | 👁 架構審查 |
INT-017 | 必須 | Saga 的每一個步驟都必須定義補償動作(或明確標示為不需補償的「樞紐步驟」),補償動作必須冪等 | 👁 Saga 設計審查;🧪 每個失敗分支的測試 |
INT-018 | 必須 | Saga 的狀態必須持久化,服務重啟後能從中斷的步驟繼續;必須有逾時與人工介入的處理方式 | 🧪 測試:在每個步驟間重啟服務 |
<!-- ✅ INT-017 每個步驟都定義補償動作 -->
| 步驟 | 服務 | 動作 | 補償動作 | 冪等鍵 |
| --- | --- | --- | --- | --- |
| 1 | 庫存 | 預留庫存 | 釋放庫存 | orderId |
| 2 | 付款 | 授權付款 | 取消授權/退款 | orderId |
| 3 | 物流 | 建立出貨單(樞紐步驟,之後不再補償) | — | orderId |
| 4 | 訂單 | 標記完成 | — | orderId |-- ✅ INT-018 Saga 狀態持久化,重啟後依 status 與 step 繼續;deadline 用於逾時處理
CREATE TABLE order_saga (
order_id VARCHAR(36) NOT NULL PRIMARY KEY,
status VARCHAR(30) NOT NULL,
step SMALLINT NOT NULL,
retry_count SMALLINT NOT NULL DEFAULT 0,
deadline TIMESTAMP WITH TIME ZONE NOT NULL,
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
version BIGINT NOT NULL DEFAULT 0
);
CREATE INDEX ix_order_saga_status_deadline ON order_saga (status, deadline);<!-- ❌ INT-016 以 XA 分散式交易同時更新訂單、庫存、付款三個服務的資料庫 -->
<!-- ❌ INT-017 付款失敗時沒有釋放庫存,庫存被永久預留 -->🔍 4.5 審查與驗證
人工審查問題:
- Saga 的每一個步驟是否都有補償動作或標示為樞紐步驟?補償動作本身失敗時怎麼辦?(
INT-017) - 服務在任兩個步驟之間重啟,Saga 是否能繼續?卡住的 Saga 由誰、怎麼處理?(
INT-018) - 使用者在 Saga 進行中看到什麼狀態?(例如「付款處理中」)(
INT-016)
AI 常見錯誤: AI 常以 @Transactional 包住多個遠端呼叫,以為這樣就能「一起回滾」;本地交易無法回滾已經完成的遠端呼叫(INT-016)。
4.6 事件與 API 契約
服務之間的介面就是契約。契約變更若破壞相容性,會讓其他服務在執行時失敗。
| 契約類型 | 規格標準 | 相容性檢查工具 |
|---|---|---|
| 同步 API | OpenAPI 3.1(第 5 章) | oasdiff、Spectral |
| 非同步事件 | AsyncAPI 3.x、CloudEvents 1.0 | Schema Registry 相容性檢查 |
| 事件資料結構 | JSON Schema、Avro、Protobuf | Schema Registry(BACKWARD 相容) |
| 消費端期望 | 消費者驅動契約(CDC) | Pact、Spring Cloud Contract |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
INT-019 | 應該 | 跨服務事件採用 CloudEvents 格式的信封(id、source、type、specversion、time),事件型別名稱包含版本 | 🤖 Schema 驗證 |
INT-020 | 必須 | 事件的資料結構必須在 Schema Registry 或版本庫中管理,變更必須維持向後相容(只新增選填欄位);不相容的變更必須發布新版本的事件型別 | 🤖 Schema Registry 相容性模式 BACKWARD;🤖 CI 比對 |
INT-021 | 應該 | 對外提供事件的服務以 AsyncAPI 文件描述其頻道、訊息與結構 | 🤖 asyncapi validate |
INT-022 | 應該 | 服務間的同步 API 以消費者驅動契約測試驗證,提供者的 CI 必須執行所有消費者的契約 | 🧪 Pact/Spring Cloud Contract |
{
"specversion": "1.0",
"id": "8f2c1f7e-2c1a-4f8b-9d7e-3a2b1c0d9e8f",
"source": "/shop/order-service",
"type": "com.example.shop.order.placed.v1",
"time": "2026-10-07T09:30:00+08:00",
"datacontenttype": "application/json",
"subject": "ORD-20261007-000123",
"data": {
"$comment": "✅ INT-019 CloudEvents 信封,type 包含版本 v1",
"orderId": "ORD-20261007-000123",
"lines": [{ "sku": "A-001", "quantity": 2 }]
}
}# order-events.asyncapi.yaml
# ✅ INT-021 以 AsyncAPI 3.1 描述訂單服務發布的事件
asyncapi: 3.1.0
info:
title: 訂單事件
version: 1.0.0
description: 訂單服務發布的領域事件
defaultContentType: application/cloudevents+json
channels:
orderEvents:
address: order.events
messages:
orderPlaced:
$ref: '#/components/messages/OrderPlaced'
operations:
publishOrderPlaced:
action: send
channel:
$ref: '#/channels/orderEvents'
messages:
- $ref: '#/channels/orderEvents/messages/orderPlaced'
components:
messages:
OrderPlaced:
name: com.example.shop.order.placed.v1
title: 訂單已建立
payload:
type: object
required: [orderId, lines]
properties:
orderId:
type: string
lines:
type: array
items:
type: object
required: [sku, quantity]
properties:
sku:
type: string
quantity:
type: integer
minimum: 1{
"$comment": "❌ INT-020 直接把 quantity 從 integer 改成 string 並沿用 v1,所有既有消費者解析失敗",
"type": "com.example.shop.order.placed.v1",
"data": { "orderId": "ORD-1", "lines": [{ "sku": "A-001", "quantity": "2" }] }
}// ✅ INT-022 提供者在 CI 中驗證 Pact Broker 上所有消費者的契約(Pact JVM,片段)
@Provider("order-service")
@PactBroker(url = "${PACT_BROKER_URL}")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderApiProviderPactTest {
@TestTemplate
@ExtendWith(PactVerificationSpringProvider.class)
void verifyConsumerContracts(PactVerificationContext context) {
context.verifyInteraction();
}
}(片段:示意,未編譯;需要 au.com.dius.pact.provider:junit5spring 相依)
🔍 4.6 審查與驗證
自動檢查: npx @asyncapi/cli validate order-events.asyncapi.yaml(INT-021);Schema Registry 將主題的相容性設為 BACKWARD,不相容的 schema 註冊會被拒絕(INT-020)。
人工審查問題:
- 事件結構的變更是否只新增選填欄位?刪除欄位或改型別時,是否發布了新版本的事件型別並保留舊版一段時間?(
INT-020) - 事件是否包含足夠的資訊讓消費者處理,而不需要再回呼發布者查詢(避免「事件通知+回呼」造成的耦合)?(
INT-019) - 提供者的 CI 是否執行消費者的契約測試?(
INT-022)
AI 常見錯誤: AI 產生的 AsyncAPI 文件常混用 2.x 的 publish/subscribe 語法與 3.x 的 operations;3.x 已改為以 operations 的 action: send/receive 描述(INT-021)。
5. API 設計
API 是系統之間的長期契約。一旦被外部使用,修改的成本會遠高於第一次設計。本章規範 REST API 的設計、錯誤格式、版本管理與文件。程式碼層級的 Controller 寫法請見 程式寫作指引 的 Spring Boot 章節。
5.1 API 優先與 OpenAPI 規格
API 優先(API-first):先寫 OpenAPI 規格、經過審查,再實作。規格是前後端、測試與文件的共同來源,可以平行開發,並在 CI 中自動檢查規格品質與相容性。
| OpenAPI 版本 | 發布 | 狀態 |
|---|---|---|
| 3.0.x | 2017 | 仍被廣泛支援 |
| 3.1.x | 2021(3.1.1 於 2024-10) | 與 JSON Schema 2020-12 完全相容;主流工具已支援,本指引的撰寫基準 |
| 3.2.x | 2025-09(3.2.1 於 2026-09) | 新增 QUERY 方法、串流(itemSchema)、階層式標籤等;部分程式碼產生器與檢查工具尚未完整支援 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-001 | 必須 | 對外或跨團隊的 API 必須先撰寫 OpenAPI 規格並經審查,規格存放於版本庫,與實作一起版本控制 | 👁 PR 審查 |
API-002 | 應該 | OpenAPI 規格以 3.1 撰寫;工具鏈(程式碼產生器、檢查工具、閘道)全部支援 3.2 後再升級 | 🤖 規格檔的 openapi 欄位檢查 |
API-003 | 必須 | CI 以 Spectral 或 Redocly 檢查規格品質,並以 oasdiff 比對前一版,偵測破壞性變更 | 🤖 Spectral/Redocly lint;🤖 oasdiff breaking |
API-004 | 必須 | 實作必須與規格一致:以契約測試或由規格產生介面的方式確保,不得只靠人工對照 | 🧪 契約測試;🤖 OpenAPI Generator 產生介面 |
# openapi/order-api.yaml
# ✅ API-001 規格先行;API-002 以 OpenAPI 3.1 撰寫
openapi: 3.1.1
info:
title: 訂單 API
version: 1.2.0
description: 建立與查詢訂單。
contact:
name: 訂單團隊
email: order-team@example.com
license:
name: Proprietary
identifier: LicenseRef-Proprietary
servers:
- url: https://api.example.com
security:
- bearerAuth: []
tags:
- name: orders
description: 訂單
paths:
/orders:
post:
tags: [orders]
operationId: placeOrder
summary: 建立訂單
description: 建立一筆新訂單。支援 Idempotency-Key,同一個 key 重送時回傳第一次的結果。
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlaceOrderRequest'
responses:
'201':
description: 已建立
headers:
Location:
description: 新訂單的網址
schema:
type: string
format: uri
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/Problem'
'409':
$ref: '#/components/responses/Problem'
'422':
$ref: '#/components/responses/Problem'
/orders/{orderId}:
get:
tags: [orders]
operationId: getOrder
summary: 查詢單筆訂單
description: 查詢目前使用者自己的訂單;查無資料或無權查看都回 404。
parameters:
- name: orderId
in: path
required: true
schema:
type: string
pattern: '^ORD-[0-9]{8}-[0-9]{6}$' # ✅ API-008 對外使用有格式的業務編號,不暴露資料庫流水號
responses:
'200':
description: 訂單內容
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'404':
$ref: '#/components/responses/Problem'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 用戶端產生的唯一值,用於安全重試(見 INT-014)
schema:
type: string
maxLength: 64
responses:
Problem:
description: 錯誤(RFC 9457 Problem Details)
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetail'
schemas:
PlaceOrderRequest:
type: object
required: [items]
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/OrderItem'
OrderItem:
type: object
required: [sku, quantity]
properties:
sku:
type: string
maxLength: 20
quantity:
type: integer
minimum: 1
maximum: 999
Order:
type: object
required: [orderId, status, items, createdAt]
properties:
orderId:
type: string
status:
type: string
enum: [PENDING, PAID, SHIPPED, CANCELLED]
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
createdAt:
type: string
format: date-time
ProblemDetail:
type: object
properties:
type:
type: string
format: uri-reference
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
format: uri-referenceCI 檢查(API-003):
# .github/workflows/api-contract.yml
# ✅ API-003 檢查規格品質,並與 main 分支的規格比對破壞性變更
name: api-contract
on:
pull_request:
paths: ['openapi/**']
permissions:
contents: read
jobs:
lint-and-diff:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- name: Lint
run: npx --yes @redocly/cli@2 lint openapi/order-api.yaml
- name: Breaking changes
run: |
git show origin/main:openapi/order-api.yaml > /tmp/base.yaml
docker run --rm -v /tmp:/base -v "$PWD/openapi:/rev" tufin/oasdiff \
breaking /base/base.yaml /rev/order-api.yaml --fail-on ERR# ❌ API-001 / API-004 沒有規格,只靠程式碼註解產生文件;規格是實作的副產品,審查時已來不及修改設計
# ❌ API-002 宣告 3.2.0,但團隊使用的程式碼產生器尚未支援,產生的用戶端缺少欄位
openapi: 3.2.0🔍 5.1 審查與驗證
自動檢查: npx @redocly/cli lint openapi/*.yaml 與 oasdiff breaking(API-003)。本指引的範例規格已以 Redocly CLI 2.x 檢查通過。
人工審查問題:
- 規格是否在實作前審查過?PR 中規格與實作是否一起變更?(
API-001) - 每個操作是否都有
operationId、所有可能的錯誤回應,以及required欄位?(API-003) - 有沒有機制確保實作與規格一致(產生介面或契約測試)?(
API-004)
AI 常見錯誤: AI 產生的 OpenAPI 常混用 3.0 與 3.1 語法,例如在 3.1 使用 nullable: true(3.1 應寫成 type: [string, "null"]),或在 3.0 使用 examples 陣列(API-002)。
5.2 資源與 URL 設計
| 原則 | ✅ 正確 | ❌ 錯誤 |
|---|---|---|
| 資源用名詞複數 | /orders、/orders/{orderId} | /getOrder、/order/list |
| 動作用 HTTP 方法表達 | POST /orders | POST /orders/create |
| 多字以 kebab-case | /shipping-addresses | /shippingAddresses、/shipping_addresses |
| 巢狀不超過兩層 | /orders/{orderId}/items | /customers/{id}/orders/{id}/items/{id}/discounts |
| 過濾、排序、分頁用查詢參數 | /orders?status=PAID&sort=-createdAt | /orders/paid/sort-by-date |
| 非 CRUD 的業務動作用子資源 | POST /orders/{orderId}/cancellation | POST /cancelOrder?id=1 |
HTTP 方法的語意:
| 方法 | 用途 | 安全(不改變狀態) | 冪等 |
|---|---|---|---|
| GET | 讀取 | 是 | 是 |
| POST | 建立、執行動作 | 否 | 否(以 Idempotency-Key 補足,見 INT-014) |
| PUT | 整筆取代 | 否 | 是 |
| PATCH | 部分更新 | 否 | 不一定(JSON Merge Patch 是冪等的) |
| DELETE | 刪除 | 否 | 是 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-005 | 必須 | URL 以名詞複數表示資源,動作以 HTTP 方法表達;路徑不得包含動詞(業務動作以子資源表示) | 🤖 Spectral 自訂規則(路徑不得含 get、create、update、delete) |
API-006 | 必須 | GET 不得改變伺服器狀態;PUT 與 DELETE 必須冪等 | 👁 程式碼審查;🧪 API 測試 |
API-007 | 應該 | 路徑以 kebab-case,JSON 欄位以 camelCase;同一組織的所有 API 一致 | 🤖 Spectral 規則 |
API-008 | 必須 | 資源識別碼不得使用可猜測的連續流水號暴露給外部;使用 UUID、ULID 或有格式的業務編號,並一律做物件層級授權檢查(見 SEC-008) | 👁 規格審查 |
# .spectral.yaml — 企業 API 規則集
# ✅ API-005 / API-007 以 Spectral 自訂規則自動檢查 URL 設計
extends: ["spectral:oas"]
rules:
no-verbs-in-path:
description: 路徑不得包含動詞(API-005)
severity: error
given: $.paths
then:
field: "@key"
function: pattern
functionOptions:
notMatch: "/(get|create|update|delete|remove|add|list)[A-Za-z-]*(/|$)"
paths-kebab-case:
description: 路徑片段使用 kebab-case(API-007)
severity: error
given: $.paths
then:
field: "@key"
function: pattern
functionOptions:
match: "^(/([a-z0-9]+(-[a-z0-9]+)*|\\{[a-zA-Z]+\\}))+$"
properties-camel-case:
description: JSON 欄位使用 camelCase(API-007)
severity: warn
given: $..properties
then:
field: "@key"
function: casing
functionOptions:
type: camel# ❌ API-005 / API-007 路徑含動詞、混用命名風格
paths:
/getOrderList:
post: {}
/orders/{id}/cancel_order:
get: {} # ❌ API-006 以 GET 執行取消,爬蟲或預先載入就會取消訂單🔍 5.2 審查與驗證
自動檢查: npx @stoplight/spectral-cli lint openapi/order-api.yaml --ruleset .spectral.yaml(API-005、API-007)。
人工審查問題:
- 是否有 GET 端點會寫入資料(包括「順便」更新最後讀取時間以外的業務狀態)?(
API-006) - 外部可見的識別碼是否可被猜測?換一個 ID 是否就能看到別人的資料?(
API-008)
AI 常見錯誤: AI 常產生 POST /api/order/create、GET /api/order/delete/{id} 這類 RPC 風格的路徑,並以資料庫自動遞增主鍵作為對外 ID(API-005、API-008)。
5.3 HTTP 狀態碼
| 狀態碼 | 意義 | 使用時機 |
|---|---|---|
| 200 OK | 成功 | GET、PUT、PATCH 成功並回傳內容 |
| 201 Created | 已建立 | POST 建立資源,必須附 Location 標頭 |
| 202 Accepted | 已受理 | 非同步處理,回傳查詢進度的網址 |
| 204 No Content | 成功,無內容 | DELETE 成功、PUT 不回傳內容 |
| 400 Bad Request | 請求格式錯誤 | JSON 無法解析、欄位型別錯誤、必填欄位缺漏 |
| 401 Unauthorized | 未驗證 | 沒有或無效的存取權杖,附 WWW-Authenticate |
| 403 Forbidden | 無權限 | 已驗證但沒有權限 |
| 404 Not Found | 不存在 | 資源不存在,或使用者無權知道它存在 |
| 409 Conflict | 狀態衝突 | 重複建立、版本衝突、狀態不允許此操作 |
| 412 Precondition Failed | 前置條件不符 | If-Match 的 ETag 不符(樂觀鎖) |
| 415 Unsupported Media Type | 不支援的格式 | Content-Type 錯誤 |
| 422 Unprocessable Content | 業務規則驗證失敗 | 格式正確但違反業務規則(庫存不足、金額超過上限) |
| 429 Too Many Requests | 超過速率限制 | 附 Retry-After |
| 500 Internal Server Error | 未預期的伺服器錯誤 | 不得包含堆疊追蹤等內部資訊 |
| 503 Service Unavailable | 暫時無法服務 | 維護中、相依服務熔斷,附 Retry-After |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-009 | 必須 | 狀態碼必須反映實際結果;不得所有回應都回 200 再以本文中的代碼表示錯誤 | 🧪 API 測試;🤖 規格檢查每個操作都定義錯誤回應 |
API-010 | 必須 | 建立資源回 201 並附 Location;非同步處理回 202 並附查詢進度的網址 | 🧪 API 測試 |
API-011 | 必須 | 使用者無權存取的資源,若「資源是否存在」本身是敏感資訊,回 404 而不是 403 | 👁 程式碼審查;🧪 授權測試 |
### ❌ API-009 錯誤也回 200,用戶端、閘道、監控都無法判斷失敗(錯誤率指標永遠是 0)
HTTP/1.1 200 OK
Content-Type: application/json
{"success": false, "code": "E1001", "message": "庫存不足"}
### ✅ API-009 / API-010 建立成功回 201 + Location
HTTP/1.1 201 Created
Location: https://api.example.com/orders/ORD-20261007-000123
Content-Type: application/json
{"orderId": "ORD-20261007-000123", "status": "PENDING"}🔍 5.3 審查與驗證
人工審查問題:
- 是否有「所有回應都是 200」的包裝格式?(
API-009) - 業務規則錯誤是用 422 還是 400?團隊是否一致?(
API-009) - 查詢他人的訂單時回傳什麼?是否洩漏「該訂單存在」?(
API-011)
AI 常見錯誤: AI 常沿用 v1.x 的 ApiResponse<T>{success, code, message, data} 包裝格式並一律回 200,這會讓 HTTP 層的監控、重試與快取全部失效(API-009)。
5.4 錯誤回應:RFC 9457 Problem Details
錯誤回應統一採用 RFC 9457(Problem Details for HTTP APIs,取代 RFC 7807),媒體類型為 application/problem+json。Spring Framework 內建 ProblemDetail 與 ErrorResponse,Spring Boot 以 spring.mvc.problemdetails.enabled=true 讓框架例外也以此格式回應。
| 欄位 | 意義 | 範例 |
|---|---|---|
type | 錯誤類型的 URI,用戶端以此判斷錯誤種類 | https://api.example.com/problems/insufficient-stock |
title | 錯誤類型的簡短說明(同一 type 固定) | 庫存不足 |
status | HTTP 狀態碼 | 422 |
detail | 這一次錯誤的具體說明 | 商品 A-001 庫存 1,請求 2 |
instance | 發生錯誤的請求路徑或識別 | /orders |
| 擴充欄位 | 自訂欄位 | errors、traceId |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-012 | 必須 | 所有錯誤回應採用 RFC 9457 格式(application/problem+json),並啟用 spring.mvc.problemdetails.enabled | 🧪 API 測試檢查 Content-Type 與欄位 |
API-013 | 必須 | 每種業務錯誤定義穩定的 type URI,並在 API 文件列出;用戶端以 type 判斷錯誤,而非比對 detail 文字 | 👁 規格審查 |
API-014 | 必須 | 錯誤回應不得包含堆疊追蹤、SQL、內部類別名稱或主機資訊;包含 traceId 供查詢日誌 | 🧪 API 測試:觸發 500 並檢查回應內容 |
API-015 | 應該 | 欄位驗證錯誤以擴充欄位 errors 一次列出所有欄位錯誤(欄位路徑與訊息) | 🧪 API 測試 |
package com.example.shop.order.adapter.web;
import com.example.shop.inventory.InsufficientStockException;
import com.example.shop.order.domain.OrderNotFoundException;
import io.micrometer.tracing.Tracer;
import java.net.URI;
import java.util.List;
import java.util.Map;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
// ✅ API-012 統一以 ProblemDetail(RFC 9457)回應錯誤
@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {
private static final String PROBLEM_BASE = "https://api.example.com/problems/";
private final Tracer tracer;
ApiExceptionHandler(Tracer tracer) {
this.tracer = tracer;
}
// ✅ API-013 每種業務錯誤有穩定的 type URI
@ExceptionHandler
ProblemDetail handle(InsufficientStockException ex) {
ProblemDetail problem = ProblemDetail.forStatusAndDetail(
HttpStatus.UNPROCESSABLE_CONTENT,
"商品 %s 庫存 %d,請求 %d".formatted(ex.sku(), ex.available(), ex.requested()));
problem.setType(URI.create(PROBLEM_BASE + "insufficient-stock"));
problem.setTitle("庫存不足");
return withTraceId(problem);
}
// ✅ API-011 查無資料或無權查看都回 404,不洩漏資源是否存在
@ExceptionHandler
ProblemDetail handle(OrderNotFoundException ex) {
ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
problem.setType(URI.create(PROBLEM_BASE + "order-not-found"));
problem.setTitle("查無訂單");
return withTraceId(problem);
}
// ✅ API-015 一次列出所有欄位驗證錯誤
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
ProblemDetail problem = ex.getBody();
problem.setType(URI.create(PROBLEM_BASE + "validation-failed"));
problem.setTitle("請求內容驗證失敗");
List<Map<String, String>> errors = ex.getBindingResult().getFieldErrors().stream()
.map(e -> Map.of("field", e.getField(),
"message", String.valueOf(e.getDefaultMessage())))
.toList();
problem.setProperty("errors", errors);
return handleExceptionInternal(ex, withTraceId(problem), headers, status, request);
}
// ✅ API-014 未預期錯誤只回傳通用訊息與 traceId,細節只寫日誌
@ExceptionHandler
ProblemDetail handle(Exception ex) {
logger.error("未預期的錯誤", ex);
ProblemDetail problem = ProblemDetail.forStatusAndDetail(
HttpStatus.INTERNAL_SERVER_ERROR, "系統發生錯誤,請稍後再試或提供 traceId 給客服");
return withTraceId(problem);
}
private ProblemDetail withTraceId(ProblemDetail problem) {
var span = tracer.currentSpan();
if (span != null) {
problem.setProperty("traceId", span.context().traceId());
}
return problem;
}
}# application.yml
spring:
mvc:
problemdetails:
enabled: true # ✅ API-012 框架例外(404、405、415…)也以 Problem Details 回應回應範例:
### ✅ API-012 / API-015 欄位驗證錯誤
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/validation-failed",
"title": "請求內容驗證失敗",
"status": 400,
"detail": "Invalid request content.",
"instance": "/orders",
"errors": [
{"field": "items[0].quantity", "message": "必須大於或等於 1"},
{"field": "items[1].sku", "message": "不得為空白"}
],
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}
### ❌ API-014 錯誤回應洩漏內部資訊
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{"error": "org.postgresql.util.PSQLException: ERROR: relation \"orders_tmp\" does not exist at com.example.shop.order..."}🔍 5.4 審查與驗證
自動檢查: API 測試對每個錯誤情境檢查 Content-Type: application/problem+json、type、status(API-012、API-013);故意觸發未預期例外,斷言回應本文不包含 Exception、at com.、SQL 等字串(API-014)。
人工審查問題:
- 錯誤類型清單(
typeURI)是否寫在 API 文件中?(API-013) -
server.error.include-stacktrace、include-message是否保持預設(never)?(API-014)
AI 常見錯誤: AI 常在 @ExceptionHandler 中把 ex.getMessage() 直接放進 detail,例外訊息可能包含 SQL 或內部資料;也常使用 HttpStatus.UNPROCESSABLE_ENTITY,Spring Framework 7 已將它標為棄用,改用 UNPROCESSABLE_CONTENT(依 RFC 9110 的名稱)(API-014)。
5.5 分頁、排序與過濾
| 方式 | 參數 | 優點 | 缺點 | 適用 |
|---|---|---|---|---|
| 頁碼(Offset) | page、size | 可跳頁、容易實作 | 深分頁效能差;資料異動時會重複或遺漏 | 後台管理、資料量小 |
| 游標(Cursor/Keyset) | cursor、limit | 效能穩定,不受資料異動影響 | 不能跳頁 | 大量資料、無限捲動、對外 API |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-016 | 必須 | 回傳集合的端點必須分頁,並設定每頁筆數上限(例如 100);不得提供一次回傳全部資料的端點 | 🧪 API 測試:size=10000 時被限制;🤖 規格檢查 |
API-017 | 應該 | 大量資料或對外 API 使用游標分頁;游標為不透明字串,用戶端不得解析 | 👁 規格審查 |
API-018 | 應該 | 不直接序列化 Spring Data 的 Page 物件;以穩定的 DTO 結構回傳分頁資訊 | 👁 程式碼審查 |
{
"$comment": "✅ API-016 / API-017 游標分頁,回傳下一頁的游標與連結",
"items": [
{ "orderId": "ORD-20261007-000123", "status": "PAID" },
{ "orderId": "ORD-20261007-000122", "status": "PENDING" }
],
"page": {
"limit": 20,
"nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTA3VDA5OjMwOjAwWiIsImlkIjoxMjJ9",
"hasMore": true
},
"links": {
"next": "/orders?limit=20&cursor=eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTA3VDA5OjMwOjAwWiIsImlkIjoxMjJ9"
}
}# application.yml
spring:
data:
web:
pageable:
max-page-size: 100 # ✅ API-016 限制每頁筆數上限
serialization-mode: via-dto # ✅ API-018 以穩定的 DTO 結構序列化 Page🔍 5.5 審查與驗證
人工審查問題:
- 是否有回傳
List<T>而沒有分頁的集合端點?資料成長 100 倍時會怎樣?(API-016) - 使用頁碼分頁的查詢,深分頁(第 1000 頁)的 SQL 執行計畫是否可接受?(
API-017)
AI 常見錯誤: AI 常產生 findAll() 直接回傳整張表的端點,或以 page=1&size=999999 「取得全部」(API-016)。
5.6 API 版本管理與棄用
什麼是破壞性變更? 會讓既有用戶端失敗的變更:刪除或改名欄位、改變欄位型別或格式、新增必填的請求欄位、改變錯誤碼或狀態碼的意義、刪除端點、收緊驗證規則。新增選填的請求欄位、新增回應欄位、新增端點不是破壞性變更,用戶端必須容忍未知欄位。
Spring Framework 7 內建 API 版本管理:版本可以放在路徑、標頭、查詢參數或媒體類型參數。企業標準採用標頭(API-Version),對外公開 API 亦可採用路徑(/v1/)。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-019 | 必須 | 破壞性變更必須發布新的主版本,舊版本在棄用期間持續運作;非破壞性變更不升主版本 | 🤖 oasdiff breaking |
API-020 | 必須 | 棄用 API 時以 Deprecation(RFC 9745)與 Sunset(RFC 8594)回應標頭通知,並提供 Link 指向遷移說明;Sunset 時間不得早於 Deprecation | 🧪 API 測試檢查標頭 |
API-021 | 應該 | 對外 API 的棄用期至少 6 個月,內部 API 至少一個發布週期;期間監控舊版本的呼叫量,歸零或屆期才下線 | 👁 棄用計畫;🤖 依版本統計的呼叫量指標 |
API-022 | 應該 | 用戶端必須忽略不認得的回應欄位(容錯讀取,Tolerant Reader) | 🧪 用戶端測試:回應多一個欄位時不失敗 |
# application.yml
spring:
mvc:
apiversion:
use:
header: API-Version # ✅ API-019 以標頭指定版本
default: "1.0"
supported: ["1.0", "2.0"]package com.example.shop.order.adapter.web;
import java.net.URI;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.accept.StandardApiVersionDeprecationHandler;
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
// ✅ API-020 以 Spring Framework 7 的棄用處理器自動加上 Deprecation、Sunset 與 Link 標頭
@Configuration(proxyBeanMethods = false)
class ApiVersionConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
StandardApiVersionDeprecationHandler handler = new StandardApiVersionDeprecationHandler();
// 日期以 UTC 設定:Sunset 標頭會依傳入的時區輸出,只有 UTC 才會產生 HTTP 規定的 GMT 格式
handler.configureVersion("1.0")
.setDeprecationDate(ZonedDateTime.of(2026, 9, 30, 16, 0, 0, 0, ZoneOffset.UTC)) // 台北 10/01 00:00
.setSunsetDate(ZonedDateTime.of(2027, 3, 31, 16, 0, 0, 0, ZoneOffset.UTC)) // ✅ API-021 棄用期 6 個月
.setSunsetLink(URI.create("https://developer.example.com/orders/migration-v2"));
configurer.setDeprecationHandler(handler);
}
}package com.example.shop.order.adapter.web;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
// ✅ API-019 同一路徑依版本對應到不同處理方法;1.0 在棄用期間持續運作
@RestController
class OrderVersionedController {
@GetMapping(path = "/orders/{orderId}/summary", version = "1.0")
OrderSummaryV1 summaryV1(@PathVariable String orderId) {
return new OrderSummaryV1(orderId, 1200);
}
@GetMapping(path = "/orders/{orderId}/summary", version = "2.0")
OrderSummaryV2 summaryV2(@PathVariable String orderId) {
return new OrderSummaryV2(orderId, new Amount(1200, "TWD"));
}
record OrderSummaryV1(String orderId, long total) {
}
/** 2.0 的破壞性變更:total 由數字改為含幣別的物件。 */
record OrderSummaryV2(String orderId, Amount total) {
}
record Amount(long value, String currency) {
}
}### ✅ API-020 以 API-Version: 1.0 呼叫已棄用版本時的實際回應標頭(Spring Framework 7.0.9 實測)
HTTP/1.1 200 OK
Deprecation: @1790784000
Sunset: Wed, 31 Mar 2027 16:00:00 GMT
Link: <https://developer.example.com/orders/migration-v2>; rel="sunset"; type="text/html"
Content-Type: application/json
### 以不支援的版本 API-Version: 3.0 呼叫:框架回 400 Problem Details
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{"detail":"Invalid API version: '3.0.0'.","instance":"/orders/ORD-20261007-000123/summary","status":400,"title":"Bad Request"}Deprecation 的值是 RFC 9651 的日期格式(@ 加上 Unix 秒數,1790784000 即 2026-09-30T16:00:00Z)。Sunset 必須是 HTTP 日期格式(GMT):Spring 會依傳入 ZonedDateTime 的時區輸出,若傳入台北時間,標頭會變成 Thu, 1 Apr 2027 00:00:00 +0800,不符合 RFC 9110 的格式,部分用戶端會無法解析。因此上例以 UTC 設定日期。
<!-- ❌ API-019 在 v1 直接把 total 從數字改成物件,所有既有用戶端解析失敗 -->
<!-- ❌ API-020 沒有任何棄用通知,某天直接下線舊版 -->import { z } from 'zod';
// ✅ API-022 容錯讀取:z.object 預設會略過未知欄位,提供者新增回應欄位時用戶端不會失敗
export const OrderSummary = z.object({
orderId: z.string(),
total: z.number(),
});
// ❌ API-022 .strict() 遇到任何未知欄位就失敗,提供者新增一個欄位就會讓用戶端壞掉
export const OrderSummaryStrict = z.object({ orderId: z.string(), total: z.number() }).strict();🔍 5.6 審查與驗證
自動檢查: oasdiff breaking base.yaml rev.yaml --fail-on ERR 偵測破壞性變更(API-019);API 測試以 API-Version: 1.0 呼叫,斷言回應包含 Deprecation 與 Sunset(API-020)。
人工審查問題:
- 這次的變更是否為破壞性變更?若是,是否發布了新版本?(
API-019) - 實際呼叫舊版本,
Sunset標頭是否為 GMT 格式、時間是否晚於Deprecation?(API-020) - 舊版本的呼叫量是否有監控?下線前誰負責通知用戶端?(
API-021) - 用戶端的 JSON 解析是否設定忽略未知欄位(Jackson 預設
FAIL_ON_UNKNOWN_PROPERTIES在 Spring Boot 中為false)?(API-022)
AI 常見錯誤: AI 常把版本號放在每個 Controller 的 @RequestMapping("/api/v1/...") 並複製整個 Controller 產生 v2,造成大量重複程式;Spring Framework 7 起可以用 version 屬性在同一個 Controller 中對應不同版本(API-019)。
5.7 速率限制與請求保護
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-023 | 必須 | 對外 API 必須設定速率限制(依用戶端或使用者),超過時回 429 並附 Retry-After | 🧪 壓測:超過門檻時回 429 |
API-024 | 必須 | 限制請求本文大小、陣列元素數量與字串長度,並在規格中標示(maxLength、maxItems) | 🤖 Spectral 規則:字串與陣列必須有上限 |
API-025 | 可以 | 回應中提供 RateLimit-Policy 與 RateLimit 標頭,讓用戶端主動降速(IETF 草案,已獲 IESG 核准,待正式發布為 RFC) | 🧪 API 測試 |
# ✅ API-023 以 Envoy Gateway 的 BackendTrafficPolicy 依用戶端 ID 限流(每分鐘 600 次)
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
name: order-api-ratelimit
namespace: order
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: order-api
rateLimit:
type: Global
global:
rules:
- clientSelectors:
- headers:
- name: x-client-id
type: Distinct
limit:
requests: 600
unit: Minute### ✅ API-023 超過速率限制;API-025 告知用戶端剩餘額度(草案格式)
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30
RateLimit-Policy: "per-client";q=600;w=60
RateLimit: "per-client";r=0;t=30
{"type": "https://api.example.com/problems/rate-limited", "title": "請求過於頻繁", "status": 429}# ❌ API-024 字串與陣列沒有上限,攻擊者可送出 100 MB 的 JSON 或 100 萬筆明細
items:
type: array
items:
type: object
properties:
note:
type: string🔍 5.7 審查與驗證
自動檢查: Spectral 規則要求每個 type: string 有 maxLength 或 enum/format,每個 type: array 有 maxItems(API-024);壓測確認超量時回 429(API-023)。
人工審查問題:
- 速率限制是依 IP、用戶端 ID 還是使用者?在 NAT 或企業代理後方的使用者會不會被誤擋?(
API-023) - 速率限制的計數是否跨 Gateway 副本共用(Global)?(
API-023)
AI 常見錯誤: AI 常把限流實作在單一應用程式實例的記憶體中,部署 3 個副本後實際上限變成 3 倍(API-023)。
5.8 API 文件
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
API-026 | 必須 | 正式環境不得公開 Swagger UI 與 /v3/api-docs;API 文件發布在開發者入口網站或內部文件站 | 🧪 部署後檢查:正式環境這些路徑回 404 |
API-027 | 應該 | API 文件包含:驗證方式、錯誤類型清單、速率限制、版本與棄用政策、範例請求與回應 | 👁 文件審查 |
# application-prod.yml
# ✅ API-026 正式環境關閉 springdoc 的 UI 與規格端點
springdoc:
api-docs:
enabled: false
swagger-ui:
enabled: false# ❌ API-026 正式環境開放 Swagger UI,攻擊者可直接看到所有端點與參數
springdoc:
swagger-ui:
enabled: true
path: /swagger-ui.html<!-- ✅ API-027 開發者入口網站上的 API 文件結構 -->
# 訂單 API v1.2
1. 快速開始:取得用戶端憑證、第一個請求的 curl 範例
2. 身分驗證:OAuth 2.0 Client Credentials,scope 清單(orders.read、orders.write)
3. 錯誤處理:Problem Details 格式與所有 type URI(insufficient-stock、order-not-found、rate-limited…)
4. 速率限制:每個用戶端每分鐘 600 次;429 與 Retry-After 的處理方式
5. 版本與棄用政策:API-Version 標頭、棄用期 6 個月、Deprecation/Sunset 標頭
6. 冪等:Idempotency-Key 的使用方式與保存期限
7. API 參考:由 openapi/order-api.yaml 產生
8. 變更紀錄🔍 5.8 審查與驗證
自動檢查: 部署後的冒煙測試對正式環境呼叫 /swagger-ui/index.html 與 /v3/api-docs,必須回 404 或 401(API-026)。
人工審查問題:
- 使用 springdoc 時版本是否為 3.x(對應 Spring Boot 4)?2.x 只支援 Boot 3。(
API-026) - API 文件是否列出所有錯誤類型與速率限制?(
API-027)
AI 常見錯誤: AI 產生的設定常加上 springdoc-openapi-starter-webmvc-ui 2.x 版並在所有環境開啟 Swagger UI(API-026)。
6. 前端架構
本章處理前端的架構決策:渲染方式、前端與後端的邊界、多團隊協作方式,以及效能、無障礙與多語系的架構要求。元件與程式碼寫法請見 前端開發指引 與 程式寫作指引。
6.1 渲染策略的選擇
| 策略 | 說明 | 適用 | 代價 |
|---|---|---|---|
| SPA(Client-Side Rendering) | 瀏覽器下載 JavaScript 後渲染 | 登入後的業務系統、互動密集的後台 | 首次載入較慢;SEO 差 |
| SSR(Server-Side Rendering) | 伺服器渲染 HTML,瀏覽器再接手互動 | 對外網站、需要 SEO 或首屏速度 | 需要 Node.js 執行環境;架構較複雜 |
| SSG(Static Site Generation) | 建置時產生靜態 HTML | 文件、行銷頁、內容少變動的網站 | 內容更新需要重新建置 |
| MPA(傳統伺服器端模板) | 每個頁面由後端模板產生 | 表單為主的簡單系統 | 互動體驗較差 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
FE-001 | 應該 | 渲染策略依頁面性質選擇並記錄於 ADR:登入後的業務系統預設 SPA;對外、需 SEO 的頁面採 SSR 或 SSG | 👁 ADR 審查 |
FE-002 | 必須 | 定義前端效能預算,以 Core Web Vitals 的「良好」門檻為目標:LCP ≤ 2.5 秒、INP ≤ 200 毫秒、CLS ≤ 0.1(第 75 百分位) | 🤖 Lighthouse CI 斷言;🤖 真實使用者監控(RUM) |
{
"$comment": "✅ FE-002 lighthouserc.json:以 Lighthouse CI 在 PR 中檢查效能預算",
"ci": {
"collect": {
"url": ["http://localhost:4173/", "http://localhost:4173/orders"],
"numberOfRuns": 3
},
"assert": {
"assertions": {
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
"total-blocking-time": ["warn", { "maxNumericValue": 200 }],
"resource-summary:script:size": ["error", { "maxNumericValue": 350000 }]
}
}
}
}INP(Interaction to Next Paint)需要真實使用者的互動才能量測,Lighthouse 以 TBT(Total Blocking Time)作為實驗室替代指標。正式環境應以
web-vitals函式庫回報 RUM 數據。
<!-- ❌ FE-002 沒有效能預算,只寫「頁面載入要快」;首頁 JavaScript 隨功能增加到 3 MB 才被發現 --><!-- ✅ FE-001 渲染策略依頁面性質選擇並記錄於 ADR -->
# ADR-0030 前端渲染策略
| 頁面 | 性質 | 策略 | 理由 |
| --- | --- | --- | --- |
| 商品目錄、活動頁 | 對外、需 SEO | SSR(Nuxt) | 搜尋引擎索引、首屏速度 |
| 說明中心 | 內容少變動 | SSG | 可放 CDN,無伺服器成本 |
| 會員中心、訂單管理 | 登入後操作 | SPA(Vue) | 互動多、不需 SEO |🔍 6.1 審查與驗證
自動檢查: npx @lhci/cli autorun 在 CI 執行 lighthouserc.json 的斷言(FE-002)。
人工審查問題:
- 對外頁面是否需要 SEO?若需要,為什麼選擇 SPA?(
FE-001) - 效能預算是否以第 75 百分位的真實使用者數據追蹤?(
FE-002)
AI 常見錯誤: AI 仍常以 FID(First Input Delay)作為互動指標;FID 已於 2024-03 被 INP 取代(FE-002)。
6.2 BFF 與瀏覽器端的權杖安全
BFF(Backend for Frontend) 是專為某一種前端服務的後端層,負責彙整多個服務的資料、轉換成前端需要的格式,並處理瀏覽器端的身分驗證。
瀏覽器中的 JavaScript 可以被 XSS 攻擊讀取,因此 IETF 的 OAuth 2.0 for Browser-Based Applications(draft-ietf-oauth-browser-based-apps)建議:存取權杖由 BFF 保管,瀏覽器只持有 HttpOnly 的工作階段 Cookie。
sequenceDiagram
participant B as 瀏覽器(SPA)
participant F as BFF
participant I as 身分提供者(OIDC)
participant A as 訂單 API
B->>F: GET /login
F->>I: 授權碼流程 + PKCE
I-->>F: 存取權杖、更新權杖(保存在 BFF 的工作階段)
F-->>B: Set-Cookie: SESSION(HttpOnly、Secure、SameSite=Strict)
B->>F: GET /api/orders(帶 Cookie)
F->>A: GET /orders(Authorization: Bearer 存取權杖)
A-->>F: 訂單資料
F-->>B: 前端需要的格式| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
FE-003 | 必須 | 瀏覽器端不得在 localStorage、sessionStorage 或可被 JavaScript 讀取的 Cookie 保存存取權杖或更新權杖;採用 BFF 模式由伺服器端保管 | 🤖 ESLint no-restricted-properties 禁止 localStorage.setItem 存放 token;👁 架構審查 |
FE-004 | 必須 | 工作階段 Cookie 必須設定 HttpOnly、Secure、SameSite(Strict 或 Lax),並以 __Host- 前綴限定網域 | 🧪 API 測試檢查 Set-Cookie 屬性 |
FE-005 | 應該 | 一種前端(Web、行動 App)對應一個 BFF,由前端團隊擁有;BFF 只做資料彙整與格式轉換,不包含業務規則 | 👁 架構審查 |
# BFF(Spring Boot)的 application.yml
server:
servlet:
session:
cookie:
name: __Host-SESSION # ✅ FE-004 __Host- 前綴:必須 Secure、Path=/、不可指定 Domain
http-only: true
secure: true
same-site: strict
path: /
spring:
security:
oauth2:
client:
registration:
corp-idp:
client-id: web-bff
client-secret: ${BFF_CLIENT_SECRET} # 由機密管理注入(SEC-011)
authorization-grant-type: authorization_code
scope: [openid, profile, orders.read, orders.write]
provider:
corp-idp:
issuer-uri: https://idp.example.com/realms/corp// ❌ FE-003 把存取權杖存在 localStorage,任何 XSS 都能讀走(片段)
const { access_token } = await response.json();
localStorage.setItem('access_token', access_token);(片段:違規示意,未編譯)
<!-- ✅ FE-005 Web BFF 由前端團隊擁有,只做彙整與格式轉換 -->
GET /bff/order-page/{orderId}
→ 呼叫 訂單 API(訂單明細)+ 物流 API(配送狀態)+ 目錄 API(商品圖片)
→ 組成「訂單頁」需要的單一 JSON
<!-- ❌ FE-005 BFF 自行計算折扣與運費:同一份業務規則在 Web BFF 與 App BFF 各實作一次,結果不一致 -->🔍 6.2 審查與驗證
自動檢查: ESLint 設定 no-restricted-properties 禁止 localStorage.setItem/sessionStorage.setItem,或以自訂規則掃描 token 字樣(FE-003);整合測試檢查登入後的 Set-Cookie 包含 HttpOnly; Secure; SameSite=Strict(FE-004)。
人工審查問題:
- 前端程式碼中是否出現
access_token、Authorization標頭的組裝?若有,權杖從哪裡來?(FE-003) - BFF 是否開始出現業務規則(價格計算、權限判斷)?(
FE-005)
AI 常見錯誤: 幾乎所有 AI 產生的 SPA 登入範例都把 JWT 存在 localStorage 並以 Axios 攔截器加上 Authorization 標頭,這正是 FE-003 禁止的做法。
6.3 微前端
微前端把一個前端應用拆成多個可以獨立開發、獨立部署的部分,由不同團隊負責。它解決的是組織規模問題,不是技術問題;單一團隊使用微前端只會增加複雜度。
| 整合方式 | 說明 | 優點 | 缺點 |
|---|---|---|---|
| 建置時整合(npm 套件) | 各團隊發布套件,主應用一起建置 | 簡單、型別安全 | 無法獨立部署 |
| 執行時整合(Module Federation) | 主應用在執行時載入遠端模組 | 可獨立部署、共用相依 | 版本相容性需管理;除錯較難 |
| 伺服器端/邊緣組裝 | 伺服器或 CDN 組合多個片段 | 對 SEO 友善 | 架構複雜 |
| iframe | 以 iframe 嵌入 | 隔離最徹底 | 體驗差、無障礙與響應式困難 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
FE-006 | 應該 | 只有在 3 個以上團隊需要獨立發布前端時才採用微前端,並以 ADR 記錄 | 👁 ADR 審查 |
FE-007 | 必須 | 採用微前端時,框架核心套件(Vue/React、路由、狀態管理)必須以 singleton 共用並鎖定主版本;各微前端之間不得直接引用彼此的內部模組,只能透過公開的事件或介面溝通 | 🤖 建置設定檢查;👁 程式碼審查 |
FE-008 | 必須 | 所有微前端使用同一套設計系統(Design System)元件庫,確保一致的外觀與無障礙行為 | 👁 UI 審查 |
// vite.config.ts(主應用,使用 @module-federation/vite)
// ✅ FE-007 框架核心以 singleton 共用,並鎖定主版本(片段)
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { federation } from '@module-federation/vite';
export default defineConfig({
plugins: [
vue(),
federation({
name: 'shell',
remotes: {
orders: {
type: 'module',
name: 'orders',
entry: 'https://orders.example.com/remoteEntry.js',
},
},
shared: {
vue: { singleton: true, requiredVersion: '^3.5.0' },
'vue-router': { singleton: true, requiredVersion: '^4.5.0' },
pinia: { singleton: true, requiredVersion: '^3.0.0' },
},
}),
],
});(片段:設定示意,未編譯;套件版本以專案為準)
// ❌ FE-007 訂單微前端直接 import 會員微前端的內部 store,兩者無法獨立部署(片段)
import { useMemberStore } from '../../member-app/src/stores/member';(片段:違規示意,未編譯)
{
"$comment": "✅ FE-006 依 ADR-0031(4 個團隊需獨立發布)採用微前端;✅ FE-008 每個微前端使用同一主版本的設計系統",
"name": "@example/orders-mfe",
"dependencies": {
"@example/design-system": "^4.2.0",
"vue": "^3.5.0"
}
}🔍 6.3 審查與驗證
人工審查問題:
- 有幾個團隊要獨立發布前端?少於 3 個時,為什麼不用單一應用+模組邊界?(
FE-006) - 共用的框架套件是否設為 singleton?主應用與遠端的版本範圍是否相容?(
FE-007) - 所有微前端是否使用同一版本範圍的設計系統?(
FE-008)
AI 常見錯誤: AI 常把微前端當作「現代化前端架構」的預設選項推薦給單一團隊的專案(FE-006)。
6.4 響應式設計與無障礙
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
FE-009 | 必須 | 對外與內部系統都必須符合 WCAG 2.2 AA 等級;新功能上線前通過自動化與人工無障礙檢查 | 🤖 axe-core/Lighthouse accessibility;👁 鍵盤與螢幕閱讀器測試 |
FE-010 | 應該 | 以行動優先(mobile-first)設計版面,斷點定義於設計系統中統一管理,不在各元件自行定義 | 👁 UI 審查 |
WCAG 2.2(2023-10 發布)在 2.1 之上新增的 AA 準則,是 AI 與舊版設計最常遺漏的項目:
| 準則 | 要求 | 檢查方式 |
|---|---|---|
| 2.4.11 Focus Not Obscured (Minimum) | 取得焦點的元件不得被固定標頭、浮動按鈕完全遮住 | 以鍵盤 Tab 逐一檢查 |
| 2.5.7 Dragging Movements | 拖曳操作必須有不需拖曳的替代方式 | 檢查排序、滑桿是否有按鈕替代 |
| 2.5.8 Target Size (Minimum) | 點擊目標至少 24×24 CSS 像素(或有足夠間距) | 開發者工具量測 |
| 3.2.6 Consistent Help | 求助方式(客服連結)在各頁位置一致 | 人工檢查 |
| 3.3.7 Redundant Entry | 同一流程不要求重複輸入已提供的資料 | 檢查多步驟表單 |
| 3.3.8 Accessible Authentication (Minimum) | 登入不得只依賴認知測驗(例如記憶、轉錄驗證碼),需允許貼上與密碼管理器 | 檢查登入頁 |
/* ✅ FE-009 WCAG 2.2 的 2.5.8:點擊目標至少 24×24;2.4.11:捲動時保留固定標頭的高度,避免焦點被遮住 */
:root {
--header-height: 64px;
--target-min: 24px;
}
html {
scroll-padding-top: var(--header-height);
}
.icon-button {
min-inline-size: var(--target-min);
min-block-size: var(--target-min);
}
/* ✅ FE-010 斷點由設計系統統一定義(mobile-first:預設為小螢幕,再往上擴充) */
@media (min-width: 768px) {
.order-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
}
}<!-- ❌ FE-009 登入頁禁止貼上密碼(違反 3.3.8),圖示按鈕只有 16×16 且沒有可讀名稱 -->
<input type="password" onpaste="return false">
<button class="icon-16"><svg aria-hidden="true"></svg></button>🔍 6.4 審查與驗證
自動檢查: 在 E2E 測試中執行 axe-core(例如 @axe-core/playwright),以 wcag22aa 標籤檢查(FE-009)。自動化工具只能找出約三到四成的無障礙問題,鍵盤操作與螢幕閱讀器仍需人工測試。
人工審查問題:
- 只用鍵盤是否能完成主要流程?焦點是否一直可見且未被遮住?(
FE-009) - 斷點是否來自設計系統的變數?(
FE-010)
AI 常見錯誤: AI 常以「符合 WCAG 2.1」為目標,遺漏 2.2 新增的準則;也常產生只有圖示、沒有 aria-label 的按鈕(FE-009)。
6.5 多語系與時區
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
FE-011 | 必須 | 使用者可見的文字不得寫死在元件中,一律透過 i18n 資源檔;資源檔以語系代碼(BCP 47,例如 zh-TW、en-US)命名 | 🤖 ESLint @intlify/vue-i18n/no-raw-text 或對應規則 |
FE-012 | 必須 | 後端與 API 以 UTC 或含時區位移的 ISO 8601 格式(例如 2026-10-07T09:30:00+08:00)傳遞時間;前端依使用者時區顯示 | 🧪 API 測試;👁 規格審查(format: date-time) |
FE-013 | 應該 | 數字、貨幣、日期以 Intl API 依語系格式化,不自行拼接字串 | 👁 程式碼審查 |
// ✅ FE-012 API 回傳含時區的 ISO 8601;FE-013 以 Intl 依使用者語系與時區格式化
export function formatOrderTime(isoDateTime: string, locale: string, timeZone: string): string {
return new Intl.DateTimeFormat(locale, {
dateStyle: 'medium',
timeStyle: 'short',
timeZone,
}).format(new Date(isoDateTime));
}
export function formatAmount(amount: number, locale: string, currency: string): string {
return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);
}
// formatAmount(1200, 'zh-TW', 'TWD') → "$1,200.00"
// formatOrderTime('2026-10-07T01:30:00Z', 'zh-TW', 'Asia/Taipei') → "2026年10月7日 上午9:30"// ❌ FE-011 文字寫死;FE-012 API 回傳沒有時區的時間字串,跨時區使用者看到錯誤時間(片段)
const label = '訂單建立時間:' + order.createdAt; // createdAt = "2026-10-07 09:30:00"(片段:違規示意,未編譯)
🔍 6.5 審查與驗證
自動檢查: ESLint 的 i18n 規則禁止模板中的裸文字(FE-011);OpenAPI 規格中時間欄位必須是 format: date-time(FE-012)。
人工審查問題:
- 資料庫存放時間的欄位型別是否含時區(PostgreSQL
timestamptz)?(FE-012) - 貨幣金額是否以整數最小單位或十進位字串傳遞,避免浮點誤差?(
FE-013)
AI 常見錯誤: AI 常以 new Date().toLocaleString() 不指定時區格式化時間,結果依伺服器或瀏覽器的預設時區而變(FE-012)。
7. 後端分層架構
本章定義一個服務或模組內部的結構。目標是讓業務規則不依賴框架與基礎設施:更換資料庫、訊息代理或 Web 框架時,業務規則不需要修改,也可以不啟動 Spring 就完成單元測試。
7.1 Clean Architecture 與六角形架構
Clean Architecture(Robert C. Martin)、六角形架構(Ports and Adapters,Alistair Cockburn)與洋蔥架構的核心是同一條規則:依賴只能由外往內指向業務核心。
flowchart TB
subgraph Adapters["轉接器層 adapter(外層)"]
WEB["Web 轉接器<br/>Controller、DTO"]
PERSIST["持久化轉接器<br/>JDBC/JPA 實作"]
MSG["訊息轉接器<br/>Kafka Listener、Publisher"]
EXT["外部系統轉接器<br/>HTTP Client、ACL"]
end
subgraph App["應用層 application"]
UC["Use Case<br/>交易邊界、流程協調"]
end
subgraph Domain["領域層 domain(核心)"]
ENT["實體、值物件、領域服務"]
PORT["Port 介面<br/>OrderRepository"]
end
WEB --> UC
MSG --> UC
UC --> ENT
UC --> PORT
PERSIST -. "實作" .-> PORT
EXT -. "實作" .-> PORT| 層 | 套件 | 職責 | 可以依賴 | 不可以依賴 |
|---|---|---|---|---|
| 領域層 | ..domain.. | 業務規則、實體、值物件、領域事件、Port 介面 | Java 標準函式庫、JSpecify 等無框架的函式庫 | Spring、JPA、Jackson、HTTP、其他層 |
| 應用層 | ..application.. | Use Case、交易邊界、呼叫 Port、發布事件 | 領域層、Spring 的交易與事件 API | 轉接器層、Web、JPA 實體 |
| 轉接器層 | ..adapter.. | 把外部世界(HTTP、資料庫、訊息)轉換為應用層的呼叫或 Port 的實作 | 應用層、領域層、框架 | 其他轉接器(Web 不得直接呼叫持久化) |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
BE-001 | 必須 | 服務內部採用分層(或六角形)架構,依賴方向只能由外往內:轉接器 → 應用 → 領域 | 🤖 ArchUnit layeredArchitecture() |
BE-002 | 必須 | 領域層不得依賴 Spring、JPA、Jackson、Servlet 等框架或基礎設施套件 | 🤖 ArchUnit |
BE-003 | 必須 | 領域層以 Port 介面定義對外部資源的需求(例如 OrderRepository),由轉接器層實作 | 🤖 ArchUnit:持久化實作類別位於 ..adapter.. |
BE-004 | 不應該 | 對於純 CRUD、沒有業務規則的簡單模組,硬套四層與 Port;此時可採用簡化的兩層(Controller → Repository),但必須在模組的 package-info.java 或 ADR 中說明 | 👁 架構審查 |
/**
* 參考資料模組(幣別、國家代碼):純 CRUD、沒有業務規則,採簡化的兩層結構(Controller → Repository)。
* ✅ BE-004 簡化分層的理由記錄於此;LayeringArchTest 的層級定義不包含本模組。
*/
package com.example.shop.refdata;(片段:示意,未編譯)
🔍 7.1 審查與驗證
自動檢查: 7.2 的 LayeringArchTest(BE-001~BE-003)。
人工審查問題:
- 業務規則(金額計算、狀態轉換是否允許)是寫在領域物件中,還是散落在 Controller 與 Service?(
BE-001) - 這個模組是否真的有業務規則?若只有 CRUD,是否過度分層?(
BE-004)
AI 常見錯誤: AI 產生的「Clean Architecture」常讓領域實體同時帶有 @Entity、@Table、@JsonProperty 註解,形式上分了層,實際上領域層完全依賴 JPA 與 Jackson(BE-002)。
7.2 分層規則與依賴方向
以下是訂單模組的完整範例。先看領域層:沒有任何框架註解,業務規則(下單時的數量與狀態檢查)寫在實體中。
package com.example.shop.order.domain;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
// ✅ BE-002 領域實體不依賴任何框架:沒有 @Entity、@Table、@JsonProperty
public final class Order {
static final int MAX_LINES = 100;
private final OrderId id;
private final String customerId;
private final List<OrderLine> lines;
private final Instant createdAt;
private OrderStatus status;
private Order(OrderId id, String customerId, List<OrderLine> lines, OrderStatus status, Instant createdAt) {
this.id = Objects.requireNonNull(id);
this.customerId = Objects.requireNonNull(customerId);
this.lines = List.copyOf(lines);
this.status = Objects.requireNonNull(status);
this.createdAt = Objects.requireNonNull(createdAt);
}
/** 建立新訂單;業務規則在這裡檢查,而不是在 Controller。 */
public static Order place(OrderId id, String customerId, List<OrderLine> lines, Instant now) {
if (lines.isEmpty() || lines.size() > MAX_LINES) {
throw new IllegalArgumentException("訂單明細必須介於 1 到 " + MAX_LINES + " 筆");
}
return new Order(id, customerId, new ArrayList<>(lines), OrderStatus.PENDING, now);
}
/** 由持久化轉接器重建既有訂單。 */
public static Order restore(OrderId id, String customerId, List<OrderLine> lines, OrderStatus status,
Instant createdAt) {
return new Order(id, customerId, lines, status, createdAt);
}
public void cancel() {
if (status == OrderStatus.SHIPPED) {
throw new IllegalStateException("已出貨的訂單不能取消:" + id.value());
}
status = OrderStatus.CANCELLED;
}
public OrderId id() {
return id;
}
public String customerId() {
return customerId;
}
public List<OrderLine> lines() {
return lines;
}
public OrderStatus status() {
return status;
}
public Instant createdAt() {
return createdAt;
}
}package com.example.shop.order.domain;
import java.util.Objects;
/** 訂單編號,格式 ORD-yyyyMMdd-nnnnnn。 */
public record OrderId(String value) {
public OrderId {
Objects.requireNonNull(value);
if (!value.matches("ORD-\\d{8}-\\d{6}")) {
throw new IllegalArgumentException("訂單編號格式錯誤:" + value);
}
}
}package com.example.shop.order.domain;
public record OrderLine(String sku, int quantity) {
public OrderLine {
if (sku == null || sku.isBlank()) {
throw new IllegalArgumentException("sku 不得為空白");
}
if (quantity < 1 || quantity > 999) {
throw new IllegalArgumentException("數量必須介於 1 到 999");
}
}
}package com.example.shop.order.domain;
public enum OrderStatus {
PENDING, PAID, SHIPPED, CANCELLED
}package com.example.shop.order.domain;
import java.util.Optional;
// ✅ BE-003 Port:領域層宣告「需要什麼」,不關心用 JDBC 或 JPA 實作
public interface OrderRepository {
void save(Order order);
Optional<Order> findById(OrderId id);
OrderId nextId();
}package com.example.shop.order.domain;
public class OrderNotFoundException extends RuntimeException {
public OrderNotFoundException(OrderId id) {
super("查無訂單:" + id.value());
}
}應用層:Use Case 協調領域物件與 Port,並定義交易邊界。
package com.example.shop.order.application;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderLine;
import java.util.List;
public interface PlaceOrderUseCase {
OrderId place(PlaceOrderCommand command);
record PlaceOrderCommand(String customerId, List<OrderLine> lines) {
}
}package com.example.shop.order.application;
import com.example.shop.inventory.InventoryManagement;
import com.example.shop.order.OrderPlaced;
import com.example.shop.order.domain.Order;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderRepository;
import java.time.Clock;
import java.util.UUID;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
// ✅ BE-001 應用層依賴領域層與其他模組的公開 API,不依賴轉接器
// ✅ BE-011 交易邊界在應用層的 Use Case
// ✅ BE-006 實作類別為 package-private,其他套件只能透過 PlaceOrderUseCase 介面使用
@Service
class PlaceOrderService implements PlaceOrderUseCase {
private final OrderRepository orders;
private final InventoryManagement inventory;
private final ApplicationEventPublisher events;
private final Clock clock;
PlaceOrderService(OrderRepository orders, InventoryManagement inventory,
ApplicationEventPublisher events, Clock clock) {
this.orders = orders;
this.inventory = inventory;
this.events = events;
this.clock = clock;
}
@Override
@Transactional
public OrderId place(PlaceOrderCommand command) {
Order order = Order.place(orders.nextId(), command.customerId(), command.lines(), clock.instant());
command.lines().forEach(line -> inventory.reserve(order.id().value(), line.sku(), line.quantity()));
orders.save(order);
events.publishEvent(new OrderPlaced(
UUID.randomUUID().toString(),
order.id().value(),
order.lines().stream().map(l -> new OrderPlaced.Line(l.sku(), l.quantity())).toList()));
return order.id();
}
}上例中
inventory.reserve(...)是同一個部署單元內的模組呼叫(本地交易),所以可以放在交易內。若庫存是另一個服務,遠端呼叫不得放在資料庫交易內(BE-012),應改用 Saga(4.5)。
package com.example.shop.order.application;
import com.example.shop.order.domain.Order;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderNotFoundException;
import com.example.shop.order.domain.OrderRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
// ✅ BE-013 只讀的 Use Case 標示 readOnly,可由資料來源路由導向唯讀副本
@Service
public class OrderQueryService {
private final OrderRepository orders;
OrderQueryService(OrderRepository orders) {
this.orders = orders;
}
@Transactional(readOnly = true)
public Order get(OrderId id) {
return orders.findById(id).orElseThrow(() -> new OrderNotFoundException(id));
}
}轉接器層:Controller 只負責 HTTP 與 DTO 的轉換,呼叫 Use Case,不包含業務規則。
package com.example.shop.order.adapter.web;
import com.example.shop.order.application.OrderQueryService;
import com.example.shop.order.application.PlaceOrderUseCase;
import com.example.shop.order.application.PlaceOrderUseCase.PlaceOrderCommand;
import com.example.shop.order.domain.Order;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderLine;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.Size;
import java.net.URI;
import java.time.Instant;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
// ✅ BE-001 轉接器只做協定轉換,依賴應用層;不直接使用持久化轉接器
@RestController
@RequestMapping("/orders")
class OrderController {
private final PlaceOrderUseCase placeOrder;
private final OrderQueryService queries;
OrderController(PlaceOrderUseCase placeOrder, OrderQueryService queries) {
this.placeOrder = placeOrder;
this.queries = queries;
}
// ✅ API-010 建立成功回 201 與 Location
@PostMapping
ResponseEntity<OrderResponse> place(@AuthenticationPrincipal Jwt jwt,
@Valid @RequestBody PlaceOrderRequest request) {
OrderId id = placeOrder.place(new PlaceOrderCommand(jwt.getSubject(), request.toLines()));
URI location = ServletUriComponentsBuilder.fromCurrentRequest()
.path("/{orderId}").buildAndExpand(id.value()).toUri();
return ResponseEntity.created(location).body(OrderResponse.from(queries.get(id)));
}
@GetMapping("/{orderId}")
OrderResponse get(@PathVariable String orderId) {
return OrderResponse.from(queries.get(new OrderId(orderId)));
}
record PlaceOrderRequest(@NotEmpty @Size(max = 100) List<@Valid Item> items) {
List<OrderLine> toLines() {
return items.stream().map(i -> new OrderLine(i.sku(), i.quantity())).toList();
}
}
record Item(@NotBlank @Size(max = 20) String sku, @Min(1) @Max(999) int quantity) {
}
record OrderResponse(String orderId, String status, List<Item> items, Instant createdAt) {
static OrderResponse from(Order order) {
return new OrderResponse(order.id().value(), order.status().name(),
order.lines().stream().map(l -> new Item(l.sku(), l.quantity())).toList(),
order.createdAt());
}
}
}這個範例的
GET /orders/{orderId}為了聚焦在分層,省略了「只能查詢自己的訂單」的物件層級授權檢查;實際系統必須加上,見 11.4(SEC-008)。
以 ArchUnit 把分層規則寫成測試(BE-001~BE-003):
package com.example.shop.architecture;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
// ✅ BE-007 由黃金路徑範本產生,專案建立的第一天就存在
@AnalyzeClasses(packages = "com.example.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class LayeringArchTest {
// ✅ BE-001 依賴方向:adapter → application → domain
@ArchTest
static final ArchRule layers_are_respected = layeredArchitecture()
.consideringOnlyDependenciesInLayers()
.layer("Adapter").definedBy("com.example.shop.*.adapter..")
.layer("Application").definedBy("com.example.shop.*.application..")
.layer("Domain").definedBy("com.example.shop.*.domain..")
.whereLayer("Adapter").mayNotBeAccessedByAnyLayer()
.whereLayer("Application").mayOnlyBeAccessedByLayers("Adapter")
.whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Adapter");
// ✅ BE-002 領域層不得依賴框架
@ArchTest
static final ArchRule domain_is_framework_free = noClasses()
.that().resideInAPackage("com.example.shop..domain..")
.should().dependOnClassesThat().resideInAnyPackage(
"org.springframework..", "jakarta.persistence..", "jakarta.servlet..",
"com.fasterxml.jackson..", "tools.jackson..");
// ✅ BE-003 Port 的實作(Repository 類別)必須放在轉接器層
@ArchTest
static final ArchRule repository_implementations_live_in_adapters = classes()
.that().implement("com.example.shop.order.domain.OrderRepository")
.should().resideInAPackage("..adapter..");
// ✅ BE-001 Web 轉接器不得直接呼叫持久化轉接器
@ArchTest
static final ArchRule web_does_not_use_persistence = noClasses()
.that().resideInAPackage("..adapter.web..")
.should().dependOnClassesThat().resideInAPackage("..adapter.persistence..");
}// ❌ BE-002 領域實體依賴 JPA 與 Jackson;LayeringArchTest 的 domain_is_framework_free 會失敗(片段)
package com.example.shop.order.domain;
@jakarta.persistence.Entity
public class Order {
@com.fasterxml.jackson.annotation.JsonProperty("order_id")
private String id;
}(片段:違規示意,未編譯)
🔍 7.2 審查與驗證
自動檢查: CI 執行 LayeringArchTest。驗證測試有效的方法:在領域類別加上一個 org.springframework 的 import,測試必須失敗(BE-001~BE-003)。本指引的範例已執行這項負向測試。
人工審查問題:
- ArchUnit 規則的套件名稱是否與專案實際的套件名稱一致?(規則不匹配任何類別時,ArchUnit 預設會失敗,不要關閉這個檢查)(
BE-001) - 領域物件是否有公開的 setter,讓外部可以繞過業務規則直接改狀態?(
BE-001)
AI 常見錯誤: AI 常把 Spring Boot 4 使用的 Jackson 3(套件 tools.jackson)與 Jackson 2(com.fasterxml.jackson)混淆;BE-002 的規則應同時排除兩者(BE-002)。
7.3 套件結構
套件結構採用先依功能(模組)、再依層:最上層是業務模組,模組內才分 domain、application、adapter。這樣同一個功能的程式碼放在一起,模組邊界也清楚。
com.example.shop
├── ShopApplication.java
├── order/ ← 業務模組(先依功能)
│ ├── OrderPlaced.java ← 模組公開 API
│ ├── package-info.java
│ ├── domain/ ← 再依層
│ │ ├── Order.java
│ │ ├── OrderId.java
│ │ ├── OrderLine.java
│ │ ├── OrderStatus.java
│ │ ├── OrderRepository.java ← Port
│ │ └── OrderNotFoundException.java
│ ├── application/
│ │ ├── PlaceOrderUseCase.java
│ │ └── PlaceOrderService.java
│ └── adapter/
│ ├── web/
│ │ ├── OrderController.java
│ │ └── ApiExceptionHandler.java
│ └── persistence/
│ └── JdbcOrderRepository.java ← Port 的實作
├── inventory/
├── payment/
└── shipping/應用程式主類別放在根套件,Spring Modulith 以它的套件判斷模組(每個直接子套件是一個模組):
package com.example.shop;
import java.time.Clock;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
@ConfigurationPropertiesScan
public class ShopApplication {
public static void main(String[] args) {
SpringApplication.run(ShopApplication.class, args);
}
/** 以 Clock 取得時間,測試時可替換為固定時間。 */
@Bean
Clock clock() {
return Clock.systemUTC();
}
}| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
BE-005 | 必須 | 最上層套件依業務模組劃分(package by feature),不得依技術層劃分(controller、service、repository 在最上層) | 🤖 ArchUnit:com.example.shop 的直接子套件名稱不得為技術名詞 |
BE-006 | 應該 | 模組內的類別預設為 package-private,只有需要被其他套件使用的類別才宣告為 public | 👁 程式碼審查 |
package com.example.shop.architecture;
import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchCondition;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.lang.ConditionEvents;
import com.tngtech.archunit.lang.SimpleConditionEvent;
import java.util.Set;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
@AnalyzeClasses(packages = "com.example.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class PackageStructureArchTest {
private static final Set<String> TECHNICAL_NAMES =
Set.of("controller", "controllers", "service", "services", "repository", "repositories",
"dto", "entity", "entities", "util", "utils", "common");
// ✅ BE-005 最上層套件依功能劃分,不得出現技術名詞
@ArchTest
static final ArchRule top_level_packages_are_features = classes()
.that().resideInAPackage("com.example.shop..")
.should(notResideInTechnicalTopLevelPackage());
private static ArchCondition<JavaClass> notResideInTechnicalTopLevelPackage() {
return new ArchCondition<>("not reside in a technical top-level package") {
@Override
public void check(JavaClass javaClass, ConditionEvents events) {
String rest = javaClass.getPackageName().replaceFirst("^com\\.example\\.shop\\.?", "");
String top = rest.isEmpty() ? "" : rest.split("\\.")[0];
if (TECHNICAL_NAMES.contains(top)) {
events.add(SimpleConditionEvent.violated(javaClass,
javaClass.getName() + " 位於技術名詞的最上層套件 " + top));
}
}
};
}
}❌ BE-005 依技術層劃分:一個功能的程式碼散落在 4 個套件,模組邊界不存在
com.example.shop
├── controller/ OrderController, InventoryController, PaymentController
├── service/ OrderService, InventoryService, PaymentService
├── repository/ OrderRepository, InventoryRepository, PaymentRepository
└── dto/ ...🔍 7.3 審查與驗證
自動檢查: PackageStructureArchTest(BE-005)。
人工審查問題:
- 新增的類別是否放在正確的模組與層?(
BE-005) - 是否有不必要的
public類別?(BE-006)
AI 常見錯誤: AI 建立新專案時幾乎都以 controller/service/repository/dto 作為最上層套件,並將所有類別宣告為 public(BE-005、BE-006)。
7.4 架構測試的導入策略
新專案從第一天就加入架構測試(LayeringArchTest、ModularityTests)。既有專案一次修完所有違規通常不切實際,ArchUnit 的 FreezingArchRule 可以「凍結」現有的違規,只阻擋新增的違規,再逐步清償。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
BE-007 | 必須 | 新專案在第一個 Sprint 就加入分層與模組邊界的架構測試 | 🤖 CI 測試報告中有架構測試 |
BE-008 | 應該 | 既有專案導入架構測試時,以 FreezingArchRule 凍結現有違規,並將違規清單(archunit_store)納入版本控制,定期檢視減少的進度 | 🤖 CI;👁 技術債檢視 |
package com.example.shop.architecture;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.library.freeze.FreezingArchRule;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
@AnalyzeClasses(packages = "com.example.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class LegacyFreezeArchTest {
// ✅ BE-008 既有違規被記錄在 archunit_store,只有「新增」的違規會讓測試失敗
@ArchTest
static final ArchRule no_new_field_injection = FreezingArchRule.freeze(
noClasses().should().dependOnClassesThat()
.haveFullyQualifiedName("org.springframework.beans.factory.annotation.Autowired")
.as("不得使用 @Autowired 欄位注入(新程式碼一律使用建構子注入)"));
}# src/test/resources/archunit.properties
# ✅ BE-008 違規清單存放於版本庫,CI 中不允許自動新增違規
freeze.store.default.path=src/test/resources/archunit_store
freeze.store.default.allowStoreUpdate=false第一次在本機建立違規清單時,必須同時加上
-Darchunit.freeze.store.default.allowStoreCreation=true與-Darchunit.freeze.store.default.allowStoreUpdate=true執行一次(只開前者時,寫入初始違規會因「不允許更新」而失敗),再把產生的archunit_store提交到版本庫。CI 中不得開啟這兩個設定,否則新增的違規會被自動記錄、永遠不會失敗。
🔍 7.4 審查與驗證
自動檢查: CI 執行所有 *ArchTest 與 ModularityTests;檢查 CI 設定沒有 allowStoreUpdate=true 或 allowStoreCreation=true(BE-007、BE-008)。
人工審查問題:
-
archunit_store的違規數量是否隨時間減少?PR 是否偷偷增加了凍結的違規?(BE-008)
AI 常見錯誤: AI 遇到架構測試失敗時,常建議加上 @ArchIgnore 或把規則改寬鬆,而不是修正違規的程式碼(BE-007)。
7.5 依賴注入與組態
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
BE-009 | 必須 | 一律使用建構子注入;不得使用欄位注入(@Autowired 欄位) | 🤖 ArchUnit(7.4);🤖 PMD/IntelliJ 檢查 |
BE-010 | 必須 | 組態以 @ConfigurationProperties 綁定到型別安全的 record,並以 Bean Validation 在啟動時驗證;不得在業務程式中散落 @Value 或 Environment.getProperty | 🧪 啟動測試:缺少必要設定時啟動失敗 |
package com.example.shop.order;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
// ✅ BE-010 型別安全的組態,啟動時驗證:設定錯誤時應用程式啟動失敗,而不是執行到一半才出錯
@Validated
@ConfigurationProperties("shop.order")
public record OrderProperties(
@Min(1) @Max(100) int maxLines,
@NotNull Duration paymentTimeout,
@NotNull Duration unpaidOrderExpiry) {
}# application.yml
shop:
order:
max-lines: 100
payment-timeout: 800ms
unpaid-order-expiry: 30m// ❌ BE-009 欄位注入,無法在不啟動 Spring 的情況下測試;❌ BE-010 設定散落、沒有驗證(片段)
@Service
public class OrderService {
@Autowired
private OrderRepository orderRepository;
@Value("${shop.order.payment-timeout:30000}")
private long paymentTimeoutMillis;
}(片段:違規示意,未編譯)
🔍 7.5 審查與驗證
自動檢查: 7.4 的 LegacyFreezeArchTest 或 PMD 規則阻擋欄位注入(BE-009);以 ApplicationContextRunner 撰寫測試,缺少 shop.order.payment-timeout 時 context 啟動失敗(BE-010)。
人工審查問題:
-
@Value是否帶有預設值(例如:30000),掩蓋了「正式環境忘記設定」的錯誤?(BE-010) - 組態類別是否有
@Validated?沒有的話 Bean Validation 註解不會生效。(BE-010)
AI 常見錯誤: AI 常在 @ConfigurationProperties 上加了 @NotNull 等驗證註解,卻忘記 @Validated,驗證完全不會執行(BE-010)。
7.6 交易邊界
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
BE-011 | 必須 | 交易邊界設在應用層的 Use Case 方法;Controller 與領域層不得宣告 @Transactional | 🤖 ArchUnit:@Transactional 只出現在 ..application.. 與 ..adapter.persistence.. |
BE-012 | 必須 | 資料庫交易內不得呼叫遠端服務(HTTP、gRPC、外部 API)或等待使用者輸入;交易必須短 | 👁 程式碼審查;🤖 連線池「連線持有時間」監控 |
BE-013 | 應該 | 只讀取資料的 Use Case 使用 @Transactional(readOnly = true),讓資料來源路由可以導向唯讀副本(8.4) | 👁 程式碼審查 |
package com.example.shop.architecture;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import org.springframework.transaction.annotation.Transactional;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noMethods;
@AnalyzeClasses(packages = "com.example.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class TransactionBoundaryArchTest {
// ✅ BE-011 Controller 與領域層不得宣告交易
@ArchTest
static final ArchRule no_transactional_methods_outside_application = noMethods()
.that().areDeclaredInClassesThat().resideInAnyPackage("..adapter.web..", "..domain..")
.should().beAnnotatedWith(Transactional.class);
@ArchTest
static final ArchRule no_transactional_classes_outside_application = noClasses()
.that().resideInAnyPackage("..adapter.web..", "..domain..")
.should().beAnnotatedWith(Transactional.class);
}// ❌ BE-012 交易內呼叫金流閘道:金流慢 3 秒,資料庫連線就被占用 3 秒,尖峰時連線池耗盡(片段)
@Transactional
public void pay(OrderId id) {
Order order = orders.findById(id).orElseThrow();
PaymentResult result = paymentGateway.authorize(order); // 遠端呼叫
order.markPaid(result.transactionId());
orders.save(order);
}(片段:違規示意,未編譯)
正確的做法是把遠端呼叫移到交易外:先在短交易中把訂單標記為「付款處理中」,交易提交後呼叫金流,再以另一個短交易寫入結果;失敗時由 Saga 或補償流程處理(4.5)。
🔍 7.6 審查與驗證
自動檢查: TransactionBoundaryArchTest(BE-011);以 HikariCP 指標 hikaricp_connections_usage_seconds 監控連線持有時間,p99 超過 100 ms 時告警(BE-012)。
人工審查問題:
-
@Transactional方法內是否有RestClient、HttpExchange介面、KafkaTemplate、檔案或 SFTP 操作?(BE-012) - 只讀的查詢是否標示
readOnly = true?(BE-013)
AI 常見錯誤: AI 常把 @Transactional 放在 Controller 或整個 Service 類別上,讓整個請求(包含遠端呼叫)都在交易中(BE-011、BE-012)。
8. 資料架構
資料通常比程式碼活得更久。程式可以重寫,資料一旦結構錯誤、遺失或外洩,影響會延續多年。本章規範資料儲存的選擇、擁有權、讀寫分離、結構演進與資料分級。資料表與索引的設計細節請見 資料庫設計指引。
8.1 資料儲存選型
| 類型 | 代表產品 | 適用 | 不適用 |
|---|---|---|---|
| 關聯式資料庫 | PostgreSQL、Oracle、SQL Server | 交易資料、需要 ACID 與複雜查詢(預設選擇) | 極高寫入量的時間序列、非結構化文件 |
| 鍵值/快取 | Redis、Valkey | 快取、工作階段、計數器、分散式鎖 | 唯一的資料來源(除非啟用持久化並了解其限制) |
| 文件資料庫 | MongoDB | 結構多變、以單一文件為存取單位的資料 | 需要跨文件交易與關聯查詢 |
| 搜尋引擎 | Elasticsearch、OpenSearch | 全文檢索、日誌分析 | 交易資料的權威來源 |
| 時間序列 | Prometheus、TimescaleDB | 監控指標、感測資料 | 一般業務資料 |
| 物件儲存 | S3、MinIO | 檔案、影像、備份、資料湖 | 需要低延遲隨機更新的資料 |
| 事件串流 | Kafka | 事件傳遞與重播 | 隨機查詢 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-001 | 應該 | 交易資料預設使用關聯式資料庫;採用其他類型的儲存作為權威來源時,必須以 ADR 說明一致性、備份與查詢需求如何被滿足 | 👁 ADR 審查 |
DATA-002 | 必須 | 每一份資料都要有明確的權威來源(system of record);快取、搜尋索引、讀取模型都是衍生資料,必須可以從權威來源重建 | 👁 架構審查:資料流圖標示權威來源 |
<!-- ✅ DATA-002 資料清單標示權威來源與衍生資料的重建方式 -->
| 資料 | 權威來源 | 衍生資料 | 重建方式 |
| --- | --- | --- | --- |
| 訂單 | 訂單 DB(PostgreSQL) | 訂單搜尋索引(OpenSearch) | 由 OrderPlaced/OrderUpdated 事件重播,或批次全量匯入 |
| 商品價格 | 目錄 DB | Redis 快取 | 快取失效後由目錄 DB 重新載入 |
<!-- ❌ DATA-002 Redis 中的購物車資料沒有持久化,也沒有其他來源,Redis 重啟後全部消失 --><!-- ✅ DATA-001 以非關聯式儲存作為權威來源時,ADR 說明一致性、備份與查詢 -->
# ADR-0035 商品規格以 MongoDB 作為權威來源
- 需求:各品類的規格欄位差異極大(3C 有 40 個欄位、服飾有 8 個),每月新增品類
- 一致性:商品規格只以單一文件為單位更新,不需要跨文件交易
- 備份:每日快照+oplog 連續備份,RPO 5 分鐘,每季還原演練(RES-016)
- 查詢:前台搜尋由 OpenSearch 索引提供(衍生資料,可由 MongoDB 重建)🔍 8.1 審查與驗證
人工審查問題:
- 每一個資料儲存是權威來源還是衍生資料?衍生資料遺失時要多久才能重建?(
DATA-002) - 採用 NoSQL 作為權威來源的理由是什麼?是否只是「比較新」?(
DATA-001)
AI 常見錯誤: AI 常把 Redis 當成主要資料庫使用(例如訂單暫存只放 Redis),或同時引入 MongoDB、Elasticsearch、Redis 而沒有說明哪一個是權威來源(DATA-001、DATA-002)。
8.2 資料擁有權與存取
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-003 | 必須 | 每個服務或模組擁有自己的 schema;應用程式使用的資料庫帳號只具備自己 schema 的 DML 權限,不具備 DDL 權限(DDL 由遷移專用帳號執行) | 🧪 以應用程式帳號執行 CREATE TABLE 必須失敗;👁 權限審查 |
DATA-004 | 必須 | 資料存取透過轉接器層的 Repository 實作(7.2);SQL 使用參數綁定,不得以字串串接組合使用者輸入 | 🤖 SpotBugs/FindSecBugs SQL_INJECTION_*;🤖 Semgrep |
DATA-005 | 必須 | 樂觀鎖(版本欄位)保護並發更新;長時間的使用者操作不得以資料庫的悲觀鎖等待 | 🧪 並發更新測試 |
-- V202610010900__create_order_schema.sql(由遷移帳號執行)
-- ✅ DATA-003 每個模組擁有自己的 schema,應用程式帳號只有 DML 權限
CREATE SCHEMA IF NOT EXISTS ordering;
CREATE TABLE ordering.orders (
id VARCHAR(20) NOT NULL PRIMARY KEY,
customer_id VARCHAR(64) NOT NULL,
status VARCHAR(20) NOT NULL,
created_at TIMESTAMP WITH TIME ZONE NOT NULL,
version BIGINT NOT NULL DEFAULT 0,
CONSTRAINT ck_orders_status CHECK (status IN ('PENDING', 'PAID', 'SHIPPED', 'CANCELLED'))
);
CREATE TABLE ordering.order_line (
order_id VARCHAR(20) NOT NULL REFERENCES ordering.orders (id),
line_no SMALLINT NOT NULL,
sku VARCHAR(20) NOT NULL,
quantity INTEGER NOT NULL CHECK (quantity BETWEEN 1 AND 999),
PRIMARY KEY (order_id, line_no)
);
CREATE SEQUENCE ordering.order_no_seq;
-- 應用程式帳號(由平台建立,密碼由機密管理注入)只授予 DML 權限
GRANT USAGE ON SCHEMA ordering TO order_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ordering TO order_app;
GRANT USAGE ON ALL SEQUENCES IN SCHEMA ordering TO order_app;持久化轉接器實作領域層的 Port(BE-003),以 JdbcClient 與具名參數存取資料(DATA-004):
package com.example.shop.order.adapter.persistence;
import com.example.shop.order.domain.Order;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderLine;
import com.example.shop.order.domain.OrderRepository;
import com.example.shop.order.domain.OrderStatus;
import java.sql.Timestamp;
import java.time.Clock;
import java.time.LocalDate;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.List;
import java.util.Optional;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.stereotype.Repository;
// ✅ BE-003 Port 的實作位於轉接器層;✅ DATA-004 一律使用具名參數綁定
@Repository
class JdbcOrderRepository implements OrderRepository {
private static final DateTimeFormatter DAY = DateTimeFormatter.BASIC_ISO_DATE;
private static final ZoneId TAIPEI = ZoneId.of("Asia/Taipei");
private final JdbcClient jdbc;
private final Clock clock;
JdbcOrderRepository(JdbcClient jdbc, Clock clock) {
this.jdbc = jdbc;
this.clock = clock;
}
@Override
public OrderId nextId() {
long seq = jdbc.sql("SELECT nextval('ordering.order_no_seq')").query(Long.class).single();
return new OrderId("ORD-%s-%06d".formatted(LocalDate.now(clock.withZone(TAIPEI)).format(DAY), seq % 1_000_000));
}
@Override
public void save(Order order) {
jdbc.sql("""
INSERT INTO ordering.orders (id, customer_id, status, created_at)
VALUES (:id, :customerId, :status, :createdAt)
ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status, version = ordering.orders.version + 1
""")
.param("id", order.id().value())
.param("customerId", order.customerId())
.param("status", order.status().name())
.param("createdAt", Timestamp.from(order.createdAt()))
.update();
jdbc.sql("DELETE FROM ordering.order_line WHERE order_id = :id").param("id", order.id().value()).update();
int lineNo = 1;
for (OrderLine line : order.lines()) {
jdbc.sql("INSERT INTO ordering.order_line (order_id, line_no, sku, quantity) VALUES (:id, :no, :sku, :qty)")
.param("id", order.id().value())
.param("no", lineNo++)
.param("sku", line.sku())
.param("qty", line.quantity())
.update();
}
}
@Override
public Optional<Order> findById(OrderId id) {
List<OrderLine> lines = jdbc.sql("""
SELECT sku, quantity FROM ordering.order_line WHERE order_id = :id ORDER BY line_no
""")
.param("id", id.value())
.query((rs, n) -> new OrderLine(rs.getString("sku"), rs.getInt("quantity")))
.list();
return jdbc.sql("SELECT customer_id, status, created_at FROM ordering.orders WHERE id = :id")
.param("id", id.value())
.query((rs, n) -> Order.restore(id, rs.getString("customer_id"),
lines, OrderStatus.valueOf(rs.getString("status")),
rs.getTimestamp("created_at").toInstant()))
.optional();
}
}樂觀鎖(DATA-005):更新時以 WHERE version = :expected 條件判斷,影響 0 筆代表資料已被別人修改,回應 409 或 412(5.3)。
-- ✅ DATA-005 樂觀鎖:版本不符時不更新任何資料列,應用程式據此回報衝突
UPDATE ordering.orders
SET status = 'CANCELLED', version = version + 1
WHERE id = 'ORD-20261007-000123'
AND version = 3;// ❌ DATA-004 以字串串接組合 SQL,sku 參數可被注入(片段)
String sql = "SELECT * FROM ordering.order_line WHERE sku = '" + sku + "'";
jdbcTemplate.queryForList(sql);(片段:違規示意,未編譯)
🔍 8.2 審查與驗證
自動檢查: SpotBugs+FindSecBugs 偵測字串串接的 SQL(DATA-004);整合測試以應用程式帳號執行 DDL,必須因權限不足而失敗(DATA-003)。本章的 SQL 範例已在 PostgreSQL 18 實際執行。
人工審查問題:
- 應用程式的資料庫帳號是否為 schema 擁有者或具備 DDL 權限?(
DATA-003) - 並發修改同一筆資料時,後寫入的人是否會覆蓋前一個人的修改而不自知?(
DATA-005)
AI 常見錯誤: AI 常讓應用程式以資料庫超級使用者(postgres、sa)連線,並在啟動時自動執行 DDL(spring.jpa.hibernate.ddl-auto=update)(DATA-003)。
8.3 CQRS 與讀取模型
CQRS(Command Query Responsibility Segregation)把「寫入模型」與「讀取模型」分開:寫入端維持正規化與業務規則,讀取端依查詢需求建立反正規化的資料(讀取模型、投影)。它解決的是讀寫需求差異很大的問題,代價是讀取模型與寫入模型之間的最終一致性。
| 需要 CQRS 的徵兆 | 不需要 CQRS 的情境 |
|---|---|
| 查詢需要彙整多個模組或服務的資料 | 一般的 CRUD 表單 |
| 讀取量是寫入量的數十倍以上,且查詢條件複雜 | 讀寫比例接近、查詢簡單 |
| 報表查詢拖慢交易處理 | 資料量小 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-006 | 應該 | 只有在出現上述徵兆時才導入 CQRS,並以 ADR 記錄可接受的資料延遲(例如「讀取模型最多落後 5 秒」) | 👁 ADR 審查 |
DATA-007 | 必須 | 讀取模型由事件或 CDC 更新,更新程序必須冪等(INT-013),並監控讀取模型的延遲 | 🧪 重播事件測試;🤖 延遲指標告警 |
-- ✅ DATA-007 讀取模型:訂單摘要,由 OrderPlaced/OrderStatusChanged 事件投影;
-- 以 last_event_at 判斷事件先後,舊事件不覆蓋新狀態(冪等且可重播)
CREATE TABLE ordering.order_summary_view (
order_id VARCHAR(20) NOT NULL PRIMARY KEY,
customer_id VARCHAR(64) NOT NULL,
status VARCHAR(20) NOT NULL,
item_count INTEGER NOT NULL,
last_event_at TIMESTAMP WITH TIME ZONE NOT NULL
);
INSERT INTO ordering.order_summary_view (order_id, customer_id, status, item_count, last_event_at)
VALUES ('ORD-20261007-000123', 'cust-1', 'PAID', 2, TIMESTAMP WITH TIME ZONE '2026-10-07 09:31:00+08')
ON CONFLICT (order_id) DO UPDATE
SET status = EXCLUDED.status,
last_event_at = EXCLUDED.last_event_at
WHERE ordering.order_summary_view.last_event_at < EXCLUDED.last_event_at;<!-- ❌ DATA-006 只有 3 張表的後台系統導入 CQRS + Event Sourcing,查詢結果延遲讓使用者以為資料沒有存檔 -->🔍 8.3 審查與驗證
人工審查問題:
- 讀取模型的最大延遲是多少?使用者剛送出資料後馬上查詢,會看到什麼?(
DATA-006) - 同一事件重送、事件順序顛倒時,讀取模型是否仍然正確?(
DATA-007)
AI 常見錯誤: AI 常把 CQRS 與 Event Sourcing 綁在一起推薦;兩者是獨立的模式,大多數系統用 CQRS 不需要 Event Sourcing(DATA-006)。
8.4 讀寫分離與資料分割
擴展資料庫的順序:先最佳化查詢與索引 → 快取(第 9 章)→ 讀寫分離 → 分割(partitioning)→ 分片(sharding)。越後面的手段複雜度越高,不應跳過前面的步驟。
| 手段 | 解決的問題 | 代價 |
|---|---|---|
| 讀寫分離(唯讀副本) | 讀取量大 | 複寫延遲:剛寫入的資料在副本上可能還看不到 |
| 資料表分割(Partitioning) | 單表過大、需要依時間清除舊資料 | 查詢必須帶分割鍵才能有效裁剪 |
| 分片(Sharding) | 單一資料庫的寫入量或容量到達上限 | 跨分片查詢與交易困難、重新分片成本極高 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-008 | 應該 | 讀寫分離以交易的唯讀屬性路由:@Transactional(readOnly = true) 導向唯讀副本,其餘導向主庫;不在業務程式中手動選擇資料來源 | 🧪 整合測試:唯讀交易使用副本連線 |
DATA-009 | 必須 | 「寫入後立即讀取」的流程(例如下單後顯示訂單)必須讀主庫,不得受複寫延遲影響 | 👁 程式碼審查;🧪 測試 |
DATA-010 | 應該 | 依時間成長、需要定期清除的大型資料表(日誌、交易明細)採用資料庫原生的分割功能;分片必須以 ADR 說明為什麼前面的手段都不足 | 👁 ADR 審查 |
Spring Framework 6.1 起,LazyConnectionDataSourceProxy 可以設定唯讀資料來源,依交易的唯讀屬性自動路由(DATA-008):
package com.example.shop.config;
import javax.sql.DataSource;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.jdbc.DataSourceBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.jdbc.datasource.LazyConnectionDataSourceProxy;
// ✅ DATA-008 依 @Transactional(readOnly = true) 自動導向唯讀副本,業務程式不需要知道有兩個資料來源
@Configuration(proxyBeanMethods = false)
class DataSourceConfig {
@Bean
@ConfigurationProperties("app.datasource.primary")
DataSource primaryDataSource() {
return DataSourceBuilder.create().build();
}
@Bean
@ConfigurationProperties("app.datasource.replica")
DataSource replicaDataSource() {
return DataSourceBuilder.create().build();
}
@Bean
@Primary
DataSource dataSource(@Qualifier("primaryDataSource") DataSource primary,
@Qualifier("replicaDataSource") DataSource replica) {
LazyConnectionDataSourceProxy proxy = new LazyConnectionDataSourceProxy(primary);
proxy.setReadOnlyDataSource(replica);
return proxy;
}
}// ❌ DATA-009 下單後立刻以唯讀交易查詢,可能讀到尚未複寫的副本而回 404(片段)
@Transactional(readOnly = true)
public OrderView afterPlaced(OrderId id) {
return orders.findById(id).map(OrderView::from).orElseThrow(); // 副本延遲時查不到
}(片段:違規示意,未編譯)
PostgreSQL 宣告式分割(DATA-010):以月份分割交易明細,清除舊資料時直接卸離並刪除分割區,不需要大量 DELETE:
-- ✅ DATA-010 依時間分割;主鍵必須包含分割鍵
CREATE TABLE ordering.payment_log (
id BIGINT GENERATED ALWAYS AS IDENTITY,
order_id VARCHAR(20) NOT NULL,
event VARCHAR(30) NOT NULL,
created_at TIMESTAMP WITH TIME ZONE NOT NULL,
PRIMARY KEY (id, created_at)
) PARTITION BY RANGE (created_at);
CREATE TABLE ordering.payment_log_2026_10 PARTITION OF ordering.payment_log
FOR VALUES FROM ('2026-10-01 00:00:00+08') TO ('2026-11-01 00:00:00+08');
CREATE TABLE ordering.payment_log_2026_11 PARTITION OF ordering.payment_log
FOR VALUES FROM ('2026-11-01 00:00:00+08') TO ('2026-12-01 00:00:00+08');
-- 保留期滿:卸離並刪除整個分割區
ALTER TABLE ordering.payment_log DETACH PARTITION ordering.payment_log_2026_10;
DROP TABLE ordering.payment_log_2026_10;🔍 8.4 審查與驗證
自動檢查: 整合測試以 Testcontainers 啟動主庫與副本(或以兩個不同的 DataSource 模擬),斷言唯讀交易取得的連線來自副本(DATA-008)。
人工審查問題:
- 哪些流程是「寫入後立即讀取」?它們是否讀主庫?(
DATA-009) - 分割表的查詢是否都帶有分割鍵?執行計畫是否有裁剪分割區?(
DATA-010) - 導入分片前,是否已經做過查詢最佳化、快取、讀寫分離與分割?(
DATA-010)
AI 常見錯誤: AI 仍常以自行繼承 AbstractRoutingDataSource 並搭配 ThreadLocal 與 AOP 的方式實作讀寫分離,程式量大且容易在交易開始前就取得錯誤的連線;Spring Framework 6.1 起可以直接使用 LazyConnectionDataSourceProxy.setReadOnlyDataSource()(DATA-008)。
8.5 資料庫結構演進
資料庫結構以遷移腳本管理(Flyway 或 Liquibase),與程式碼一起版本控制。結構變更必須能在不停機的情況下進行,這需要 Expand–Contract(擴展—收縮) 模式:先以相容的方式擴展結構,等所有程式都改用新結構後,再收縮移除舊結構。
以「把 orders.customer_id 改名為 buyer_id」為例:
| 階段 | 資料庫變更 | 應用程式版本 | 可回退? |
|---|---|---|---|
| 1. 擴展 | 新增 buyer_id(可為 null) | v1 只寫 customer_id | 是 |
| 2. 雙寫 | — | v2 同時寫兩個欄位,讀 customer_id | 是 |
| 3. 回填 | 批次把舊資料複製到 buyer_id | v2 | 是 |
| 4. 切換讀取 | — | v3 讀寫 buyer_id,仍寫 customer_id | 是 |
| 5. 收縮 | 移除 customer_id、buyer_id 設為 NOT NULL | v4 只用 buyer_id | 否(需確認 v3 以前已全部下線) |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-011 | 必須 | 所有結構變更以版本化的遷移腳本管理;已套用到任何共用環境的腳本不得修改,修正以新的腳本進行 | 🤖 flyway validate(checksum 不符時失敗) |
DATA-012 | 必須 | 正式環境的結構變更必須向後相容,讓新舊版本的應用程式可以同時運作(Expand–Contract);刪除或改名欄位必須分多次發布 | 👁 遷移腳本審查 |
DATA-013 | 必須 | 正式環境停用 Flyway 的 clean,並開啟 validate-on-migrate | 🤖 設定檢查 |
DATA-014 | 應該 | 遷移腳本以時間戳記版本命名(V202610071030__add_buyer_id.sql),避免多人並行開發時版本號衝突 | 🤖 CI 檢查檔名格式 |
DATA-015 | 必須 | 在大型資料表上建立索引或加上限制條件時,使用不鎖表的方式(PostgreSQL CREATE INDEX CONCURRENTLY、先 NOT VALID 再 VALIDATE CONSTRAINT) | 👁 遷移腳本審查 |
# application.yml
spring:
flyway:
locations: classpath:db/migration
clean-disabled: true # ✅ DATA-013 正式環境不得清除資料庫
validate-on-migrate: true # ✅ DATA-011 已套用的腳本被修改時啟動失敗
out-of-order: false-- V202610071030__expand_add_buyer_id.sql
-- ✅ DATA-014 以時間戳記作為版本號,多人並行開發不會衝突
-- ✅ DATA-012 擴展階段:新增可為 null 的欄位,舊版程式不受影響
ALTER TABLE ordering.orders ADD COLUMN buyer_id VARCHAR(64);-- V202610151030__contract_drop_customer_id.sql
-- ✅ DATA-012 收縮階段:確認所有使用 customer_id 的版本都已下線後才執行
-- ✅ DATA-015 先以 NOT VALID 加上限制(不掃描既有資料、只鎖很短時間),再驗證既有資料
ALTER TABLE ordering.orders ADD CONSTRAINT ck_orders_buyer_id_not_null CHECK (buyer_id IS NOT NULL) NOT VALID;
ALTER TABLE ordering.orders VALIDATE CONSTRAINT ck_orders_buyer_id_not_null;
ALTER TABLE ordering.orders ALTER COLUMN buyer_id SET NOT NULL;
ALTER TABLE ordering.orders DROP CONSTRAINT ck_orders_buyer_id_not_null;
ALTER TABLE ordering.orders DROP COLUMN customer_id;-- V202610071100__index_order_line_sku.sql
-- ✅ DATA-015 不鎖表建立索引;CONCURRENTLY 不能在交易中執行,Flyway 會自動偵測並以非交易方式執行此腳本
CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_order_line_sku ON ordering.order_line (sku);-- ❌ DATA-012 一次改名:部署期間舊版程式仍在使用 customer_id,全部失敗
ALTER TABLE ordering.orders RENAME COLUMN customer_id TO buyer_id;
-- ❌ DATA-015 一般的 CREATE INDEX 會阻擋寫入,千萬筆的資料表可能鎖住數分鐘
CREATE INDEX ix_orders_status ON ordering.orders (status);PostgreSQL 12 起,
SET NOT NULL若能從已驗證的CHECK (col IS NOT NULL)限制得知沒有 null 值,就會略過全表掃描;這就是上面收縮腳本先建立並驗證 CHECK 限制的原因。
🔍 8.5 審查與驗證
自動檢查: CI 以 Testcontainers 啟動與正式環境相同版本的資料庫,從空白資料庫執行所有遷移,並執行 flyway validate(DATA-011);腳本檔名以正規表示式 ^V\d{12}__[a-z0-9_]+\.sql$ 檢查(DATA-014)。本章的遷移腳本已在 PostgreSQL 18 依序執行。
人工審查問題:
- 這個遷移腳本套用後,目前正式環境的版本還能正常運作嗎?(
DATA-012) - 腳本是否在大表上執行會鎖表的操作?資料量多大?預估執行多久?(
DATA-015) - PR 是否修改了已存在的遷移腳本?(
DATA-011)
AI 常見錯誤: AI 產生的遷移腳本常直接 RENAME COLUMN 或 ALTER COLUMN TYPE,並修改既有的 V1__init.sql 加入新欄位(DATA-011、DATA-012)。
8.6 資料分級與生命週期
| 等級 | 定義 | 範例 | 儲存與傳輸要求 | 日誌與非正式環境 |
|---|---|---|---|---|
| 機密(Restricted) | 外洩會造成重大法律或財務損失 | 身分證字號、信用卡號、密碼雜湊、健康資料 | 欄位層級加密或代碼化;存取需稽核 | 不得出現在日誌;非正式環境必須以假資料替代 |
| 敏感(Confidential) | 個人資料或內部營運資料 | 姓名、電話、地址、Email、訂單金額 | 靜態加密(磁碟/資料庫層);傳輸加密 | 日誌中遮蔽;非正式環境遮蔽或假資料 |
| 內部(Internal) | 僅限內部使用 | 系統設定、內部文件 | 傳輸加密 | 可記錄 |
| 公開(Public) | 可公開 | 商品目錄、公告 | — | 可記錄 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-016 | 必須 | 每個資料欄位標示資料等級,記錄於資料字典;機密等級欄位必須欄位層級加密或代碼化(見 11.6) | 👁 資料字典審查;🤖 掃描工具比對欄位名稱 |
DATA-017 | 必須 | 每類資料定義保存期限與到期處理方式(刪除、匿名化、封存),並以排程自動執行 | 👁 保存政策審查;🧪 排程執行紀錄 |
DATA-018 | 必須 | 非正式環境不得使用未遮蔽的正式環境個人資料 | 👁 資料複製流程審查 |
# data-classification/ordering.yaml
# ✅ DATA-016 資料字典標示每個欄位的等級;DATA-017 定義保存期限
schema: ordering
tables:
orders:
retention: 7y # 稅務法規要求保存 7 年,到期後匿名化
expiry-action: anonymize
columns:
id: internal
customer_id: confidential
status: internal
created_at: internal
customer_contact:
retention: 2y-after-last-order
expiry-action: delete
columns:
name: confidential
phone: confidential
national_id: restricted # 欄位層級加密,見 SEC-014<!-- ❌ DATA-018 把正式環境資料庫完整複製到測試環境,測試人員可以看到所有客戶的姓名、電話與身分證字號 -->🔍 8.6 審查與驗證
人工審查問題:
- 新增的欄位是否在資料字典中標示等級?機密欄位是否加密?(
DATA-016) - 保存期限是否有法規依據?到期處理是否真的有排程在執行?(
DATA-017) - 測試環境的資料從哪裡來?(
DATA-018)
AI 常見錯誤: AI 設計的資料表常把身分證字號、信用卡號以明文欄位儲存,並在 toString() 或日誌中輸出整個物件(DATA-016)。
8.7 多資料庫支援策略
部分企業產品需要支援多種資料庫(PostgreSQL、Oracle、SQL Server)。這會大幅增加測試與維運成本,必須是明確的業務需求。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
DATA-019 | 應該 | 只有在產品需要部署到客戶既有資料庫時才支援多種資料庫,並以 ADR 列出支援的產品與版本 | 👁 ADR 審查 |
DATA-020 | 必須 | 支援多種資料庫時,CI 必須對每一種支援的資料庫執行遷移與整合測試(Testcontainers);不得只在其中一種資料庫上測試 | 🧪 CI 測試矩陣 |
# .github/workflows/db-matrix.yml(節錄)
# ✅ DATA-020 每一種支援的資料庫都執行整合測試
jobs:
integration-test:
runs-on: ubuntu-24.04
strategy:
matrix:
database: [postgresql, oracle, sqlserver]
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: temurin
java-version: '25'
- run: ./mvnw -B verify -Ddb.vendor=${{ matrix.database }}<!-- ❌ DATA-020 宣稱支援 Oracle 與 SQL Server,但 CI 只用 H2 測試,客戶上線才發現語法不相容 --><!-- ✅ DATA-019 ADR 明列支援的資料庫產品與版本 -->
# ADR-0040 產品支援的資料庫
- 理由:本產品部署在客戶機房,需使用客戶既有的資料庫授權
- 支援:PostgreSQL 16–18、Oracle Database 19c/23ai、SQL Server 2022/2025
- 不支援:MySQL(無客戶需求)、H2(僅供本機開發,不得用於任何測試環境)
- 每個支援的版本都在 CI 矩陣中執行遷移與整合測試(DATA-020)🔍 8.7 審查與驗證
人工審查問題:
- 支援多種資料庫是業務需求還是「以防萬一」?(
DATA-019) - 整合測試是否用真實的資料庫(Testcontainers),而不是 H2 這類記憶體資料庫?(
DATA-020)
AI 常見錯誤: AI 常以 H2 作為整合測試資料庫,並宣稱「H2 相容模式可以模擬 Oracle/PostgreSQL」;相容模式只涵蓋部分語法,無法取代真實資料庫(DATA-020)。
9. 效能與擴展性
效能問題的根本原因通常在架構:不必要的遠端呼叫、缺少快取、在請求路徑上做了太多事、資料庫查詢沒有索引。本章的原則是先量測、再最佳化,每一個效能機制都要能用數據證明它的效果。
9.1 效能設計原則
Little 定律是容量規劃的基礎:系統中同時處理的請求數 = 到達率 × 平均處理時間。例如 500 TPS、平均 200 ms,系統中同時有 500 × 0.2 = 100 個請求在處理;若每個請求占用一個資料庫連線 50 ms,則平均需要 500 × 0.05 = 25 個連線,連線池應設定在這個數字之上並保留尖峰餘裕。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-001 | 必須 | 效能最佳化必須以量測數據(壓測、APM、執行計畫)為依據,並在最佳化前後比較;不接受「感覺比較快」 | 👁 PR 附上量測數據 |
PERF-002 | 應該 | 連線池、執行緒池、佇列大小以 Little 定律估算後,再以壓測驗證;設定值與計算過程記錄於架構文件 | 👁 架構審查 |
PERF-003 | 必須 | 避免 N+1 查詢與在迴圈中呼叫遠端服務;需要多筆資料時以批次查詢取得 | 🧪 測試中統計 SQL 次數;🤖 APM 偵測 |
<!-- ✅ PERF-002 連線池大小的計算與驗證紀錄 -->
| 參數 | 值 | 計算 |
| --- | --- | --- |
| 尖峰到達率 | 500 TPS | 行銷活動預估(QS-01) |
| 每請求平均持有連線時間 | 50 ms | APM 量測 |
| 平均需要的連線數 | 25 | 500 × 0.05 |
| 設定的連線池大小(每副本) | 15 | 3 個副本 × 15 = 45,約為平均值的 1.8 倍 |
| 驗證 | k6 500 TPS 30 分鐘,連線等待 p99 = 2 ms | 報告:perf/2026-10-05.html |// ❌ PERF-003 N+1:每筆訂單各查一次商品服務,100 筆訂單就是 100 次遠端呼叫(片段)
for (Order order : orders) {
for (OrderLine line : order.lines()) {
Product product = productClient.get(line.sku());
views.add(OrderLineView.of(line, product));
}
}
// ✅ PERF-003 先收集所有 sku,一次批次查詢
Set<String> skus = orders.stream().flatMap(o -> o.lines().stream()).map(OrderLine::sku).collect(toSet());
Map<String, Product> products = productClient.getAll(skus);(片段:示意,未編譯)
<!-- ✅ PERF-001 效能改善的 PR 附上前後量測(相同環境、相同 k6 腳本) -->
## 效能量測:訂單查詢加上 (customer_id, created_at) 複合索引
| 指標 | 改善前 | 改善後 |
| --- | --- | --- |
| GET /orders p99(200 TPS) | 1,240 ms | 85 ms |
| 資料庫 CPU | 78% | 22% |
| 執行計畫 | Seq Scan on orders | Index Scan using ix_orders_customer_created |🔍 9.1 審查與驗證
自動檢查: 整合測試以 datasource-proxy 或 Hibernate Statistics 斷言單一 API 呼叫的 SQL 次數上限(PERF-003)。
人工審查問題:
- 這個效能改善是否附上前後的量測數據?(
PERF-001) - 連線池與執行緒池的大小從哪裡來?(
PERF-002) - 迴圈內是否有資料庫查詢或遠端呼叫?(
PERF-003)
AI 常見錯誤: AI 常建議把連線池設到 100 以上「以提升效能」;過大的連線池會讓資料庫的上下文切換與鎖競爭變嚴重,反而變慢(PERF-002)。
9.2 快取策略
| 模式 | 讀取 | 寫入 | 適用 |
|---|---|---|---|
| Cache-Aside(旁路快取) | 先查快取,沒有再查資料庫並寫入快取 | 寫資料庫後刪除快取 | 最常用;讀多寫少 |
| Read-Through | 由快取元件負責載入 | — | 快取元件支援載入器時 |
| Write-Through | — | 同步寫入快取與資料庫 | 寫入後立即被讀取的資料 |
| Write-Behind | — | 先寫快取,非同步寫資料庫 | 可容忍遺失的計數、統計(需謹慎) |
快取層級:
| 層級 | 位置 | 延遲 | 一致性 | 適用 |
|---|---|---|---|---|
| 瀏覽器/CDN | 使用者端、邊緣節點 | 最低 | 依 Cache-Control | 靜態資源、公開內容 |
| 本地快取 | 應用程式記憶體(Caffeine) | 微秒 | 各副本不一致 | 極少變動的參考資料 |
| 分散式快取 | Redis/Valkey | 毫秒 | 所有副本共用 | 一般業務快取 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-004 | 必須 | 每個快取都要設定 TTL,並記錄「資料過時多久可以接受」;不得有永不過期的業務快取 | 🤖 設定檢查;👁 快取清單審查 |
PERF-005 | 必須 | 資料更新時以「先寫資料庫、再刪除快取」的方式失效,而不是更新快取內容 | 👁 程式碼審查 |
PERF-006 | 必須 | 熱門鍵的快取失效時要防止快取擊穿(大量請求同時打到資料庫):使用 @Cacheable(sync = true) 或單一載入機制,並為 TTL 加上隨機抖動 | 👁 程式碼審查;🧪 壓測 |
PERF-007 | 必須 | 快取的鍵包含所有影響結果的參數(使用者、語系、權限);個人化或含權限的資料不得以共用鍵快取 | 👁 程式碼審查;🧪 測試:不同使用者取得不同結果 |
PERF-008 | 應該 | 快取的鍵以 <服務>:<資料類型>:<版本>:<識別碼> 命名,結構變更時遞增版本以避免讀到舊格式 | 👁 程式碼審查 |
PERF-009 | 必須 | 快取不可用時系統必須能降級運作(直接查資料庫),快取錯誤不得讓請求失敗 | 🧪 故障注入:停止 Redis 後 API 仍可用 |
package com.example.shop.catalog;
import java.time.Duration;
import org.springframework.boot.cache.autoconfigure.RedisCacheManagerBuilderCustomizer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.cache.RedisCacheConfiguration;
// ✅ PERF-004 每個快取明確設定 TTL;PERF-008 鍵前綴含服務、類型與版本
@Configuration(proxyBeanMethods = false)
@EnableCaching
class CacheConfig {
@Bean
RedisCacheManagerBuilderCustomizer cacheTtlCustomizer() {
return builder -> builder
.transactionAware() // ✅ PERF-005 在交易中的快取刪除延到交易提交後才執行
.withCacheConfiguration("products", RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofMinutes(10))
.prefixCacheNameWith("shop:catalog:v2:"))
.withCacheConfiguration("categories", RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofHours(1))
.prefixCacheNameWith("shop:catalog:v2:"));
}
}package com.example.shop.catalog;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class ProductService {
private final ProductRepository products;
ProductService(ProductRepository products) {
this.products = products;
}
// ✅ PERF-006 sync = true:同一個鍵同時只有一個執行緒載入,避免快取擊穿
@Cacheable(cacheNames = "products", key = "#sku", sync = true)
public Product get(String sku) {
return products.findBySku(sku);
}
// ✅ PERF-005 先寫資料庫,交易提交後刪除快取(CacheConfig 設定了 transactionAware)
@Transactional
@CacheEvict(cacheNames = "products", key = "#sku")
public void changePrice(String sku, long priceInCents) {
products.updatePrice(sku, priceInCents);
}
}# application.yml
spring:
data:
redis:
url: ${REDIS_URL}
timeout: 200ms # ✅ PERF-009 快取逾時要短,慢的快取比沒有快取更糟
connect-timeout: 500ms
cache:
redis:
time-to-live: 10m # ✅ PERF-004 沒有個別設定的快取也有預設 TTL快取故障時降級(PERF-009):以 CacheErrorHandler 記錄錯誤並繼續執行原方法,而不是讓請求失敗:
package com.example.shop.catalog;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cache.Cache;
import org.springframework.cache.annotation.CachingConfigurer;
import org.springframework.cache.interceptor.CacheErrorHandler;
import org.springframework.cache.interceptor.SimpleCacheErrorHandler;
import org.springframework.context.annotation.Configuration;
// ✅ PERF-009 快取讀寫失敗只記錄警告,方法照常執行(直接查資料庫)
@Configuration(proxyBeanMethods = false)
class CacheErrorConfig implements CachingConfigurer {
private static final Logger log = LoggerFactory.getLogger(CacheErrorConfig.class);
@Override
public CacheErrorHandler errorHandler() {
return new SimpleCacheErrorHandler() {
@Override
public void handleCacheGetError(RuntimeException ex, Cache cache, Object key) {
log.warn("快取讀取失敗,改查資料庫:cache={}", cache.getName(), ex);
}
@Override
public void handleCachePutError(RuntimeException ex, Cache cache, Object key, Object value) {
log.warn("快取寫入失敗:cache={}", cache.getName(), ex);
}
@Override
public void handleCacheEvictError(RuntimeException ex, Cache cache, Object key) {
// 刪除失敗代表快取可能有過時資料,必須告警
log.error("快取刪除失敗,資料可能過時直到 TTL 到期:cache={}", cache.getName(), ex);
}
};
}
}// ❌ PERF-007 以 sku 為鍵快取「含會員價」的結果:第一位查詢的 VIP 會員價格會被所有人看到(片段)
@Cacheable(cacheNames = "prices", key = "#sku")
public Price priceFor(String sku, Member member) {
return pricing.calculate(sku, member.level());
}
// ✅ PERF-007 鍵包含所有影響結果的參數
@Cacheable(cacheNames = "prices", key = "#sku + ':' + #member.level()")(片段:示意,未編譯)
🔍 9.2 審查與驗證
自動檢查: 故障注入測試:以 Testcontainers 啟動 Redis,測試中途停止容器,API 仍回 200(PERF-009)。
人工審查問題:
- 每個快取的 TTL 是多少?業務單位是否同意資料最多過時這麼久?(
PERF-004) - 快取方法的回傳結果是否受「使用者、語系、權限」影響?鍵是否包含這些參數?(
PERF-007) - 更新資料時是刪除快取還是更新快取?並發時會不會寫回舊值?(
PERF-005)
AI 常見錯誤: AI 常忽略 @CacheEvict 預設在方法返回時立即執行、而不是在交易提交後執行:交易尚未提交時其他請求可能把舊值重新載入快取。需要時以 transactionAware() 延後刪除。AI 也常在更新資料時以 @CachePut 更新快取內容,並發情況下可能把舊值寫回快取;也常產生沒有 TTL 的 RedisCacheConfiguration.defaultCacheConfig()(預設永不過期)(PERF-004、PERF-005)。
9.3 CDN 與靜態資源
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-010 | 必須 | 檔名含內容雜湊的靜態資源(JS、CSS、圖片)設定 Cache-Control: public, max-age=31536000, immutable;HTML 入口檔設定 Cache-Control: no-cache,確保使用者取得最新版本 | 🧪 部署後以 curl -I 檢查標頭 |
PERF-011 | 必須 | 含個人資料或需要登入的 API 回應設定 Cache-Control: no-store,不得被 CDN 或共用代理快取 | 🧪 API 測試檢查標頭 |
# 前端靜態檔案伺服器(nginx)
server {
listen 8080;
root /usr/share/nginx/html;
# ✅ PERF-010 檔名含雜湊的資源:長期快取且不重新驗證
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404;
}
# ✅ PERF-010 HTML 入口:每次向伺服器確認是否有新版本
location / {
add_header Cache-Control "no-cache";
try_files $uri /index.html;
}
}### ✅ PERF-011 含個人資料的 API 回應不得被任何快取保存
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
### ❌ PERF-010 index.html 被設定長期快取:部署新版後使用者仍載入舊版,舊版引用的 JS 檔已不存在而白畫面
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: public, max-age=86400🔍 9.3 審查與驗證
自動檢查: 部署後的冒煙測試以 curl -sI https://shop.example.com/ 與一個 /assets/*.js 檔,斷言 Cache-Control 符合規則(PERF-010)。
人工審查問題:
- CDN 是否會快取帶有
Authorization或 Cookie 的請求?(PERF-011) - 部署新版時,舊版的雜湊資源是否保留一段時間,讓仍在使用舊頁面的使用者不會出錯?(
PERF-010)
AI 常見錯誤: AI 常對整個網站設定相同的 max-age,包括 index.html(PERF-010)。
9.4 非同步處理與 Virtual Threads
Java 21 起的 Virtual Threads 讓每個請求使用一個輕量的虛擬執行緒,I/O 等待時不占用平台執行緒,適合大量阻塞 I/O 的服務。Java 24(JEP 491)解決了 synchronized 區塊會「釘住」載體執行緒的問題,Java 25 LTS 是建議的執行版本。
使用 Virtual Threads 後,「執行緒池大小」不再限制並行數量,下游資源(資料庫連線、外部 API 的配額)會成為新的瓶頸,必須以並行限制保護。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-012 | 應該 | I/O 密集的 Spring Boot 服務(Java 21 以上,建議 25)啟用 Virtual Threads(spring.threads.virtual.enabled=true) | 🤖 設定檢查;🧪 壓測比較 |
PERF-013 | 必須 | 啟用 Virtual Threads 時,對下游有限資源的呼叫必須設定並行上限(Spring Framework 7 @ConcurrencyLimit 或 Resilience4j Bulkhead) | 👁 程式碼審查;🧪 壓測 |
PERF-014 | 必須 | 使用者請求中不需要立即完成的工作(寄信、產生報表、呼叫慢速外部系統)改為非同步處理,回應 202 或以事件觸發 | 👁 循序圖審查 |
# application.yml
spring:
threads:
virtual:
enabled: true # ✅ PERF-012 Tomcat、@Async、排程都改用 Virtual Threadspackage com.example.shop.payment.internal;
import org.springframework.resilience.annotation.ConcurrencyLimit;
import org.springframework.stereotype.Component;
// ✅ PERF-013 金流閘道合約限制同時 20 筆;Virtual Threads 下必須自行限制並行數
@Component
class PaymentGatewayAdapter {
private final PaymentGatewayClient client;
PaymentGatewayAdapter(PaymentGatewayClient client) {
this.client = client;
}
@ConcurrencyLimit(limit = 20, policy = ConcurrencyLimit.ThrottlePolicy.REJECT)
PaymentGatewayClient.AuthorizationResponse authorize(PaymentGatewayClient.AuthorizationRequest request) {
return client.authorize(request);
}
}package com.example.shop.payment.internal;
import org.springframework.context.annotation.Configuration;
import org.springframework.resilience.annotation.EnableResilientMethods;
// ✅ PERF-013 啟用 @ConcurrencyLimit 與 @Retryable 的處理;沒有這個註解,兩者都不會生效
@Configuration(proxyBeanMethods = false)
@EnableResilientMethods
class ResilienceConfig {
}
policy = REJECT讓超過上限的呼叫立即失敗(由呼叫端降級或回 503);預設的BLOCK會讓呼叫排隊等待,在 Virtual Threads 下排隊的請求不會占用平台執行緒,但會累積延遲。依情境選擇並在 ADR 記錄。
// ❌ PERF-014 下單 API 同步產生 PDF 並寄送 Email,使用者等待 5 秒;郵件伺服器故障時下單失敗(片段)
@PostMapping("/orders")
OrderResponse place(@RequestBody PlaceOrderRequest request) {
Order order = placeOrder.place(request.toCommand());
byte[] pdf = invoiceRenderer.render(order);
mailSender.send(order.customerEmail(), pdf);
return OrderResponse.from(order);
}(片段:違規示意,未編譯)
🔍 9.4 審查與驗證
自動檢查: 壓測比較啟用前後的吞吐量與 p99;啟用 Virtual Threads 後以 JFR 事件 jdk.VirtualThreadPinned 檢查是否有釘住(Java 24 起 synchronized 不再釘住,但原生方法呼叫仍會)(PERF-012)。
人工審查問題:
- 啟用 Virtual Threads 後,資料庫連線池、外部 API 是否有並行限制?(
PERF-013) - 有沒有
@EnableResilientMethods?(PERF-013) - 使用者請求的同步路徑上是否有慢速的、非必要的工作?(
PERF-014)
AI 常見錯誤: AI 常在啟用 Virtual Threads 的同時保留 ThreadPoolTaskExecutor 的固定執行緒池,或以為 Virtual Threads 會「自動提升效能」而不設定任何並行限制,結果在尖峰時打爆資料庫連線池與外部 API(PERF-013)。
9.5 水平擴展與負載平衡
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-015 | 必須 | 服務必須是無狀態的:工作階段、上傳暫存、排程鎖等狀態放在外部儲存,任何副本都能處理任何請求 | 🧪 測試:同一使用者的連續請求分散到不同副本仍正常 |
PERF-016 | 必須 | 服務必須支援優雅關機:收到 SIGTERM 後停止接收新請求、完成處理中的請求,再結束(server.shutdown=graceful) | 🧪 滾動更新期間持續壓測,錯誤率為 0 |
PERF-017 | 應該 | 以 HorizontalPodAutoscaler 依 CPU 或業務指標自動擴展,並設定縮減的穩定時間以避免震盪 | 🤖 kubeconform;🧪 壓測觀察擴縮行為 |
PERF-018 | 不應該 | 依賴負載平衡器的工作階段黏著(session affinity)來維持狀態 | 👁 設定審查 |
# application.yml
server:
shutdown: graceful # ✅ PERF-016 收到 SIGTERM 後停止接收新請求
spring:
lifecycle:
timeout-per-shutdown-phase: 20s # 處理中的請求最多等待 20 秒# ✅ PERF-017 依 CPU 自動擴展;縮減時等待 5 分鐘穩定期,每分鐘最多縮減 1 個副本
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: order-api
namespace: order
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: order-api
minReplicas: 3
maxReplicas: 12
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
behavior:
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Pods
value: 1
periodSeconds: 60
scaleUp:
stabilizationWindowSeconds: 0
policies:
- type: Percent
value: 100
periodSeconds: 30優雅關機還需要搭配 Kubernetes 的
terminationGracePeriodSeconds(必須大於timeout-per-shutdown-phase)與preStop延遲,讓負載平衡器有時間把 Pod 移出端點清單。完整設定見 13.3。
# ❌ PERF-018 以 sessionAffinity 綁定使用者到特定 Pod;Pod 重啟或縮減時使用者的工作階段遺失
apiVersion: v1
kind: Service
metadata:
name: legacy-web
spec:
selector:
app.kubernetes.io/name: legacy-web
sessionAffinity: ClientIP
ports:
- port: 8080// ❌ PERF-015 購物車放在應用程式記憶體:使用者的下一個請求打到別的副本時購物車消失(片段)
@Service
class CartService {
private final Map<String, Cart> carts = new ConcurrentHashMap<>();
}
// ✅ PERF-015 狀態放在外部儲存,任何副本都能處理同一位使用者的請求
@Service
class CartService {
private final CartRepository carts; // 以 Redis 或資料庫實作
}(片段:示意,未編譯)
🔍 9.5 審查與驗證
自動檢查: 滾動更新期間以 k6 持續送出請求,斷言錯誤率為 0(PERF-016);kubeconform 驗證 HPA(PERF-017)。
人工審查問題:
- 服務是否把任何狀態放在記憶體或本機磁碟(上傳檔案、工作階段、排程執行紀錄)?(
PERF-015) -
terminationGracePeriodSeconds是否大於應用程式的關機等待時間?(PERF-016)
AI 常見錯誤: AI 產生的 HPA 常使用已移除的 autoscaling/v2beta2 API 版本,或沒有設定 behavior,導致流量波動時副本數劇烈震盪(PERF-017)。
9.6 效能測試與容量規劃
| 測試類型 | 目的 | 負載型態 | 時間 |
|---|---|---|---|
| 負載測試(Load) | 驗證預期尖峰下是否達到品質目標 | 逐步升到預期尖峰並維持 | 30–60 分鐘 |
| 壓力測試(Stress) | 找出系統的極限與崩潰行為 | 逐步增加直到失敗 | 至失敗為止 |
| 浸泡測試(Soak) | 找出記憶體洩漏、連線洩漏等長時間問題 | 一般負載長時間維持 | 4–24 小時 |
| 尖峰測試(Spike) | 驗證突然暴增時的擴展與保護機制 | 瞬間增加數倍 | 數分鐘 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PERF-019 | 必須 | 上線前執行負載測試,並以第 2 章的品質情境作為通過門檻(寫在測試腳本的 thresholds 中,不符合時測試失敗) | 🧪 k6/Gatling 報告 |
PERF-020 | 必須 | 效能測試環境的規格、資料量與正式環境相當(或按比例縮放並記錄換算方式);不得以空資料庫測試 | 👁 測試計畫審查 |
PERF-021 | 應該 | 重大版本發布前執行浸泡測試;系統容量每年或業務量變化 50% 以上時重新評估 | 🧪 浸泡測試報告 |
// perf/place-order.js(k6)
// ✅ PERF-019 品質情境 QS-01 寫成 thresholds:p99 ≤ 800 ms、錯誤率 ≤ 0.1%,不符合時 k6 以非 0 結束碼失敗
import http from 'k6/http';
import { check } from 'k6';
export const options = {
scenarios: {
peak: {
executor: 'ramping-arrival-rate',
startRate: 50,
timeUnit: '1s',
preAllocatedVUs: 200,
maxVUs: 1000,
stages: [
{ target: 500, duration: '5m' }, // 爬升到尖峰 500 TPS
{ target: 500, duration: '30m' }, // 維持 30 分鐘
{ target: 0, duration: '2m' },
],
},
},
thresholds: {
'http_req_duration{name:place-order}': ['p(99)<800'],
'http_req_failed{name:place-order}': ['rate<0.001'],
},
};
const BASE_URL = __ENV.BASE_URL;
const TOKEN = __ENV.TOKEN;
export default function () {
const payload = JSON.stringify({ items: [{ sku: 'A-001', quantity: 1 }] });
const res = http.post(`${BASE_URL}/orders`, payload, {
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${TOKEN}`,
'Idempotency-Key': crypto.randomUUID(),
},
tags: { name: 'place-order' },
});
check(res, { 'status is 201': (r) => r.status === 201 });
}<!-- ❌ PERF-019 壓測腳本沒有 thresholds,報告只有平均回應時間,無法判斷是否通過 -->
<!-- ❌ PERF-020 在只有 100 筆訂單的測試資料庫壓測,正式環境有 5,000 萬筆,索引與執行計畫完全不同 --><!-- ✅ PERF-021 浸泡測試計畫 -->
| 項目 | 內容 |
| --- | --- |
| 負載 | 平日尖峰的 70%(350 TPS),持續 8 小時 |
| 觀察 | JVM 堆積使用量趨勢、GC 次數、連線池使用量、檔案描述元數量、p99 延遲 |
| 通過條件 | 8 小時內 p99 增幅 < 10%;Full GC 後的堆積使用量沒有持續上升 |
| 時機 | 每個主要版本發布前;業務量變化 50% 以上時重新執行容量評估 |🔍 9.6 審查與驗證
自動檢查: k6 run perf/place-order.js 的結束碼(thresholds 未達成時為非 0)作為 CI 或發布閘門(PERF-019);本指引的 k6 腳本已以 k6 inspect 檢查語法。
人工審查問題:
- 壓測的門檻是否與品質情境一致?是否以百分位數判斷?(
PERF-019) - 測試資料量與正式環境的比例是多少?(
PERF-020) - 壓測的瓶頸在哪裡?報告是否指出瓶頸資源(CPU、連線池、資料庫鎖)?(
PERF-019)
AI 常見錯誤: AI 產生的 k6 腳本常使用 vus 加 duration 的「封閉模型」,請求速率會隨回應變慢而下降,掩蓋了效能問題;驗證吞吐量目標應使用 ramping-arrival-rate 或 constant-arrival-rate 的「開放模型」(PERF-019)。
10. 韌性、高可用與災難復原
在分散式系統中,「某個元件正在故障」是常態而不是例外。本章分成四個層次:元件層的韌性模式(單一呼叫失敗時怎麼辦)、部署層的高可用(單一節點或機房失效時怎麼辦)、災難復原(整個區域或資料損毀時怎麼辦),以及業務連續性(組織如何在重大事件中持續營運)。
10.1 韌性模式
| 模式 | 解決的問題 | 關鍵參數 | 工具 |
|---|---|---|---|
| 逾時(Timeout) | 呼叫無限等待 | 連線逾時、讀取逾時 | HTTP 用戶端設定(INT-001) |
| 重試(Retry) | 暫時性失敗 | 次數、指數退避、隨機抖動 | Resilience4j Retry、Spring @Retryable |
| 熔斷(Circuit Breaker) | 下游持續失敗時仍不斷呼叫,拖垮自己 | 失敗率門檻、慢呼叫門檻、開啟時間 | Resilience4j CircuitBreaker |
| 隔艙(Bulkhead) | 一個慢的下游耗盡所有執行緒或連線 | 最大並行數 | Resilience4j Bulkhead、@ConcurrencyLimit |
| 限流(Rate Limiter) | 超過下游可承受的速率 | 每單位時間的呼叫數 | Resilience4j RateLimiter、Gateway |
| 降級(Fallback) | 失敗時仍提供有限的服務 | 降級的回應內容 | 程式邏輯 |
熔斷器的狀態轉換:
stateDiagram-v2
[*] --> CLOSED
CLOSED --> OPEN: 失敗率或慢呼叫率超過門檻
OPEN --> HALF_OPEN: 等待時間到期
HALF_OPEN --> CLOSED: 試探呼叫成功率達標
HALF_OPEN --> OPEN: 試探呼叫仍失敗| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-001 | 必須 | 對外部系統與其他服務的同步呼叫必須有熔斷器,並同時以失敗率與慢呼叫率判斷 | 👁 程式碼審查;🧪 故障注入:下游延遲時熔斷器開啟 |
RES-002 | 必須 | 只對冪等操作或帶冪等鍵的操作重試;重試必須有次數上限、指數退避與隨機抖動;不得重試 4xx 等不會因重試而成功的錯誤 | 👁 程式碼審查;🧪 測試 |
RES-003 | 應該 | 不同的下游使用獨立的隔艙(並行上限),一個慢的下游不得耗盡其他呼叫共用的資源 | 👁 設定審查;🧪 壓測 |
RES-004 | 必須 | 每個熔斷或隔艙都要定義降級行為(快取的舊資料、預設值、「處理中」狀態或明確的 503),並經過業務單位同意 | 👁 降級清單審查 |
RES-005 | 必須 | 熔斷器狀態、重試次數、隔艙拒絕次數必須輸出為監控指標並設定告警 | 🤖 Prometheus 規則(12.4) |
Resilience4j(Spring Boot 4 使用 resilience4j-spring-boot4)設定:
# application.yml
resilience4j:
circuitbreaker:
instances:
paymentGateway: # ✅ RES-001 失敗率與慢呼叫率都會觸發熔斷
sliding-window-type: COUNT_BASED
sliding-window-size: 50
minimum-number-of-calls: 20
failure-rate-threshold: 50
slow-call-duration-threshold: 800ms
slow-call-rate-threshold: 50
wait-duration-in-open-state: 30s
permitted-number-of-calls-in-half-open-state: 5
automatic-transition-from-open-to-half-open-enabled: true
retry:
instances:
paymentGateway: # ✅ RES-002 有上限、指數退避+隨機抖動,只重試暫時性錯誤
max-attempts: 3 # 含第一次呼叫,共 3 次
wait-duration: 200ms
enable-exponential-backoff: true
exponential-backoff-multiplier: 2
enable-randomized-wait: true
randomized-wait-factor: 0.5
retry-exceptions:
- java.net.SocketTimeoutException
- org.springframework.web.client.HttpServerErrorException$ServiceUnavailable
ignore-exceptions:
- org.springframework.web.client.HttpClientErrorException
bulkhead:
instances:
paymentGateway: # ✅ RES-003 金流與其他下游各自獨立的並行上限
max-concurrent-calls: 20
max-wait-duration: 0
logisticsApi:
max-concurrent-calls: 10
max-wait-duration: 0package com.example.shop.payment.internal;
import com.example.shop.payment.api.PaymentResult;
import com.example.shop.payment.api.PaymentStatus;
import io.github.resilience4j.bulkhead.annotation.Bulkhead;
import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import io.github.resilience4j.retry.annotation.Retry;
import org.springframework.stereotype.Service;
@Service
class PaymentAuthorizationService {
private final PaymentGatewayClient client;
PaymentAuthorizationService(PaymentGatewayClient client) {
this.client = client;
}
// ✅ RES-001 / RES-002 / RES-003 熔斷、重試、隔艙;授權請求以 orderId 作為冪等鍵,可安全重試
// ✅ RES-004 熔斷或隔艙拒絕時降級為「處理中」,由對帳排程稍後確認結果
@CircuitBreaker(name = "paymentGateway", fallbackMethod = "pending")
@Retry(name = "paymentGateway")
@Bulkhead(name = "paymentGateway")
PaymentResult authorize(String orderId, long amountInCents) {
var response = client.authorize(
new PaymentGatewayClient.AuthorizationRequest(orderId, amountInCents, "TWD"));
PaymentStatus status = "0000".equals(response.resultCode())
? PaymentStatus.AUTHORIZED : PaymentStatus.DECLINED;
return new PaymentResult(response.transactionId(), status);
}
private PaymentResult pending(String orderId, long amountInCents, Throwable cause) {
return new PaymentResult(null, PaymentStatus.UNKNOWN);
}
}Resilience4j 註解的預設套用順序由外而內為:Retry → CircuitBreaker → RateLimiter → TimeLimiter → Bulkhead。也就是每次重試都會經過熔斷器,熔斷器開啟後重試會立即失敗,不會再呼叫下游。
只需要簡單重試、不需要熔斷時,可以使用 Spring Framework 7 內建的 @Retryable(需要 @EnableResilientMethods,見 9.4):
package com.example.shop.shipping.internal;
import java.util.List;
import org.springframework.resilience.annotation.Retryable;
import org.springframework.stereotype.Component;
import org.springframework.web.client.HttpServerErrorException;
import org.springframework.web.client.ResourceAccessException;
@Component
class LogisticsNotifier {
private final LogisticsClient client;
LogisticsNotifier(LogisticsClient client) {
this.client = client;
}
// ✅ RES-002 只重試暫時性錯誤;最多重試 3 次,延遲 200 ms 起每次加倍,加上 ±100 ms 抖動
@Retryable(includes = {ResourceAccessException.class, HttpServerErrorException.class},
maxRetries = 3, delay = 200, multiplier = 2, jitter = 100, maxDelay = 2000)
void notifyShipment(String shipmentId, List<String> parcelNos) {
client.notify(shipmentId, parcelNos);
}
}# ❌ RES-002 重試沒有退避、包含 4xx 錯誤,而且對「建立付款」這種非冪等操作重試,可能重複扣款
resilience4j:
retry:
instances:
createPayment:
max-attempts: 10
wait-duration: 0
retry-exceptions:
- java.lang.Exception🔍 10.1 審查與驗證
自動檢查: 故障注入測試:以 WireMock 讓金流 mock 延遲 2 秒,驗證熔斷器在 20 次呼叫後開啟、API 回傳降級結果(RES-001、RES-004);resilience4j_circuitbreaker_state 指標存在且有告警規則(RES-005)。
人工審查問題:
- 被重試的操作是否冪等?若不是,是否帶有冪等鍵?(
RES-002) - 最壞情況下的總耗時(重試次數 × 逾時 + 退避時間)是否小於上游逾時?(
RES-002,見 INT-002) - 降級行為是什麼?使用者會看到什麼?業務單位是否同意?(
RES-004)
AI 常見錯誤: AI 常把 max-attempts 解讀為「重試次數」(實際包含第一次呼叫),或以 retry-exceptions: java.lang.Exception 重試所有錯誤;Spring @Retryable 的 maxRetries 則不包含第一次呼叫,兩者容易混淆(RES-002)。
10.2 高可用部署
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-006 | 必須 | 正式環境的線上服務至少 3 個副本,並以 topologySpreadConstraints 分散到至少 2 個(建議 3 個)可用區域(AZ)與不同節點 | 🤖 政策檢查;🤖 kubeconform |
RES-007 | 必須 | 每個多副本的線上服務都要設定 PodDisruptionBudget,確保節點維護或升級時仍有足夠副本提供服務 | 🤖 政策檢查:Deployment 必須有對應的 PDB |
RES-008 | 必須 | 資料庫、快取、訊息代理等有狀態元件必須跨 AZ 部署並具備自動容錯移轉;容錯移轉時間與資料遺失量符合 10.4 的 RTO/RPO | 🧪 容錯移轉演練紀錄 |
RES-009 | 必須 | 單點故障清單:架構文件列出所有單點(包括 DNS、憑證、身分提供者、CI/CD),並說明緩解方式 | 👁 架構審查 |
# ✅ RES-006 3 個副本,跨 AZ 與節點平均分布
apiVersion: apps/v1
kind: Deployment
metadata:
name: order-api
namespace: order
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: order-api
template:
metadata:
labels:
app.kubernetes.io/name: order-api
spec:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
app.kubernetes.io/name: order-api
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: ScheduleAnyway
labelSelector:
matchLabels:
app.kubernetes.io/name: order-api
containers:
- name: order-api
image: registry.example.com/order/order-api:1.4.2
---
# ✅ RES-007 自願中斷(節點排空、叢集升級)時,最多同時只能有 1 個副本不可用
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: order-api
namespace: order
spec:
maxUnavailable: 1
selector:
matchLabels:
app.kubernetes.io/name: order-api<!-- ✅ RES-009 單點故障清單 -->
| 元件 | 是否單點 | 失效影響 | 緩解方式 |
| --- | --- | --- | --- |
| 訂單 API | 否(3 副本、3 AZ) | — | — |
| PostgreSQL | 否(主+同步備援,跨 AZ) | 容錯移轉約 30 秒寫入中斷 | 應用程式重試連線 |
| 企業身分提供者 | **是** | 無法登入;已登入者在權杖到期前不受影響 | 權杖有效期 15 分鐘;IdP 由資訊部以 HA 部署(SLA 99.95%) |
| 公開 DNS | 否(雙 DNS 供應商) | — | — |
<!-- ❌ RES-006 / RES-007 replicas: 2 且沒有 PDB;叢集升級時兩個副本可能同時被排空,服務中斷 --># ✅ RES-008 以 CloudNativePG 部署跨 AZ 的 PostgreSQL:1 主 2 備、至少 1 個同步備援,主庫故障時自動容錯移轉
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: order-db
namespace: order-data
spec:
instances: 3
imageName: ghcr.io/cloudnative-pg/postgresql:18
postgresql:
synchronous:
method: any
number: 1
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
cnpg.io/cluster: order-db
storage:
size: 100Gi🔍 10.2 審查與驗證
自動檢查: 准入政策(Kyverno/Gatekeeper)拒絕正式環境 replicas < 3、缺少 topologySpreadConstraints 或沒有對應 PDB 的 Deployment(RES-006、RES-007,政策範例見 13.6)。
人工審查問題:
-
whenUnsatisfiable: DoNotSchedule是否會在某個 AZ 容量不足時讓 Pod 無法排程?是否接受?(RES-006) - PDB 的
maxUnavailable與副本數是否合理?minAvailable等於副本數會讓節點永遠無法排空。(RES-007) - 單點故障清單是否包含身分提供者、憑證到期、CI/CD 與 Container Registry?(
RES-009)
AI 常見錯誤: AI 產生的 PDB 常設定 minAvailable 等於 replicas,導致節點無法排空、叢集升級卡住;也常使用已移除的 policy/v1beta1(RES-007)。
10.3 健康檢查
Kubernetes 有三種探針,用途不同,設錯會讓系統在下游故障時自己重啟自己,擴大災情:
| 探針 | 問題 | 失敗時 Kubernetes 的動作 | 應該檢查 | 不應該檢查 |
|---|---|---|---|---|
| Startup | 應用程式啟動完成了嗎? | 持續等待,超過次數後重啟 | 應用程式內部狀態 | — |
| Liveness | 應用程式還活著嗎?(是否死鎖) | 重啟容器 | 應用程式內部狀態(Spring LivenessState) | 資料庫、快取、下游服務 |
| Readiness | 現在可以接收流量嗎? | 從 Service 端點移除,不重啟 | 應用程式狀態+必要的相依(資料庫) | 非必要的下游服務 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-010 | 必須 | Liveness 探針不得檢查外部相依(資料庫、快取、其他服務);只反映應用程式本身是否需要重啟 | 👁 設定審查;🧪 故障注入:資料庫停止時 Pod 不重啟 |
RES-011 | 必須 | Readiness 探針只納入「沒有它就無法提供任何服務」的相依;非必要的下游以熔斷與降級處理 | 👁 設定審查 |
RES-012 | 應該 | 啟動較慢的服務使用 Startup 探針,而不是把 Liveness 的 initialDelaySeconds 設得很長 | 🤖 政策檢查 |
RES-013 | 必須 | 健康檢查端點與管理端點使用獨立的管理埠,不對外公開;/actuator 只開放必要的端點 | 🧪 部署後檢查:對外網址無法存取 /actuator |
# application.yml
management:
server:
port: 8081 # ✅ RES-013 管理埠與業務埠分開,管理埠不經過 Gateway
endpoints:
web:
exposure:
include: health,prometheus # ✅ RES-013 只開放必要端點
endpoint:
health:
probes:
enabled: true
add-additional-paths: true # 在主埠也提供 /livez、/readyz(供 kubelet 以外的檢查使用)
group:
liveness:
include: livenessState # ✅ RES-010 不含 db、redis
readiness:
include: readinessState,db # ✅ RES-011 只納入必要的資料庫# Deployment 的容器設定(節錄)
containers:
- name: order-api
image: registry.example.com/order/order-api:1.4.2
ports:
- name: http
containerPort: 8080
- name: management
containerPort: 8081
startupProbe: # ✅ RES-012 啟動最多等待 30 × 5 = 150 秒
httpGet:
path: /actuator/health/liveness
port: management
periodSeconds: 5
failureThreshold: 30
livenessProbe:
httpGet:
path: /actuator/health/liveness
port: management
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: management
periodSeconds: 5
failureThreshold: 3# ❌ RES-010 liveness 使用預設的 /actuator/health(包含 db、redis 檢查):
# 資料庫短暫故障 → 所有 Pod 的 liveness 失敗 → 全部重啟 → 重啟時大量重連,延長故障時間
livenessProbe:
httpGet:
path: /actuator/health
port: 8080
initialDelaySeconds: 120 # ❌ RES-012 以很長的延遲代替 startupProbe🔍 10.3 審查與驗證
自動檢查: 故障注入測試:停止測試環境的資料庫 2 分鐘,Pod 的 restartCount 不得增加,readiness 變為未就緒,資料庫恢復後自動恢復(RES-010、RES-011)。
人工審查問題:
- liveness 的路徑是否為
/actuator/health/liveness,而不是/actuator/health?(RES-010) - readiness 群組包含哪些相依?其中一個下游故障時,是否會讓「所有」副本都不接流量?(
RES-011) - 管理埠是否沒有被 Service 或 Gateway 對外公開?(
RES-013)
AI 常見錯誤: AI 產生的 Kubernetes 設定最常見的錯誤,就是 liveness 與 readiness 都指向 /actuator/health,並開放 management.endpoints.web.exposure.include=*(RES-010、RES-013)。
10.4 災難復原:RTO 與 RPO
| 名詞 | 意義 | 問題 |
|---|---|---|
| RTO(Recovery Time Objective) | 從災難發生到服務恢復的最長可接受時間 | 「最多可以停多久?」 |
| RPO(Recovery Point Objective) | 可接受遺失的最大資料量(以時間表示) | 「最多可以遺失多少分鐘的資料?」 |
系統依業務影響分級,每一級對應不同的災難復原策略與成本:
| 等級 | 範例 | RTO | RPO | 策略 | 相對成本 |
|---|---|---|---|---|---|
| Tier 1 關鍵 | 交易、付款 | ≤ 15 分鐘 | ≈ 0(同步複寫) | 多區域熱備援(Warm Standby)或主動—主動(Multi-site) | 最高 |
| Tier 2 重要 | 訂單查詢、會員 | ≤ 4 小時 | ≤ 15 分鐘 | 前導燈(Pilot Light):資料持續複寫,運算資源災時啟動 | 中 |
| Tier 3 一般 | 報表、內部工具 | ≤ 24 小時 | ≤ 24 小時 | 備份與還原(Backup & Restore) | 低 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-014 | 必須 | 每個系統依業務影響分析(10.5)定義等級、RTO 與 RPO,並選擇對應的災難復原策略 | 👁 架構審查 |
RES-015 | 必須 | 備份遵循 3-2-1-1-0 原則:3 份資料、2 種媒體、1 份異地、1 份離線或不可變(immutable)、還原驗證 0 錯誤 | 👁 備份設定審查;🧪 還原測試報告 |
RES-016 | 必須 | 至少每季執行一次還原演練,每年執行一次完整的災難復原演練,並記錄實際的 RTO 與 RPO;實際值超過目標時必須改善 | 🧪 演練紀錄 |
RES-017 | 必須 | 災難復原所需的一切(基礎設施即程式碼、部署腳本、機密、DNS 切換步驟)必須在災難發生時可以取得,不得只存在於受災區域 | 👁 DR 手冊審查 |
# dr-plan/order-system.yaml
# ✅ RES-014 系統等級、RTO/RPO 與策略;RES-016 演練紀錄
system: online-order
tier: 1
rto: 15m
rpo: 0s
strategy: warm-standby
primary-region: ap-east-taipei
dr-region: ap-northeast-tokyo
components:
- name: order-db
replication: synchronous-in-region, asynchronous-cross-region # 跨區非同步,實際 RPO 約 5 秒
backup:
full: daily
wal-archive: continuous
copies: [primary-region-object-storage, dr-region-object-storage, offline-vault] # ✅ RES-015
immutable-retention: 35d
- name: order-api
dr-replicas: 1 # 平時 1 個副本待命,災時擴展到 3 個
drills:
- date: 2026-07-15
type: full-region-failover
measured-rto: 22m # 超過目標 15 分鐘 → 改善項目 DR-07:DNS TTL 由 300 秒降為 60 秒
measured-rpo: 4s<!-- ❌ RES-015 / RES-016 每天備份,但備份與資料庫在同一個區域、同一個帳號,且從未做過還原測試 -->
<!-- ❌ RES-014 文件寫 RPO = 0,但跨區域複寫是非同步的,實際 RPO 是複寫延遲(數秒到數分鐘) --><!-- ✅ RES-017 DR 手冊:災難發生時所需的一切都能在受災區域以外取得 -->
| 項目 | 存放位置 | 受災區域失效時是否可用 |
| --- | --- | --- |
| 基礎設施即程式碼(Terraform、Helm、Kustomize) | Git(雲端代管,多區域) | ✔ |
| 容器映像 | 複寫到 DR 區域的 Registry | ✔ |
| 機密 | Vault(DR 區域有效能待命叢集) | ✔ |
| DNS 切換步驟與權限 | DR 手冊(Git+離線紙本) | ✔ |
| 資料庫備份 | DR 區域物件儲存+離線保管庫 | ✔ |🔍 10.4 審查與驗證
人工審查問題:
- 宣稱的 RPO 與實際的複寫方式是否一致?非同步複寫的 RPO 不可能是 0。(
RES-014) - 備份是否有一份在不同帳號或離線、不可被同一組憑證刪除(防勒索軟體)?(
RES-015) - 最近一次還原演練是什麼時候?實際花了多久?(
RES-016) - 受災區域完全無法存取時,DR 手冊、IaC 與機密是否還能取得?(
RES-017)
AI 常見錯誤: AI 常宣稱「多區域部署可達成 RPO = 0、RTO < 1 分鐘」,卻沒有說明同步跨區複寫對寫入延遲的影響與成本(RES-014)。
10.5 業務連續性規劃
業務連續性管理(Business Continuity Management,BCM)依 ISO 22301:2019(2024 年增修氣候變遷相關要求)建立,範圍大於 IT 災難復原:它處理的是組織如何在重大事件(天災、疫情、供應商中斷、資安事件)中持續提供關鍵業務。IT 災難復原是業務連續性計畫的一部分。
flowchart LR
BIA["業務影響分析<br/>BIA"] --> RA["風險評估"]
RA --> STR["持續營運策略<br/>(含 IT DR 策略)"]
STR --> BCP["業務連續性計畫<br/>BCP"]
BCP --> EX["演練與測試"]
EX --> REV["檢討與改善"]
REV --> BIA業務影響分析(BIA) 是起點:找出關鍵業務流程、它們中斷後的影響如何隨時間增加,以及可容忍的最長中斷時間(MTPD)。IT 系統的 RTO 必須小於它所支援業務流程的 MTPD。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-018 | 必須 | 支援關鍵業務的系統必須有業務影響分析,列出支援的業務流程、MTPD 與相依的系統、人員、供應商 | 👁 BIA 文件審查 |
RES-019 | 必須 | 系統的 RTO 必須小於其支援業務流程的 MTPD;相依系統的 RTO 不得大於依賴它的系統的 RTO | 👁 架構審查:比對相依系統的 RTO |
RES-020 | 應該 | 業務連續性計畫包含 IT 無法恢復時的人工替代作業程序(例如紙本或離線作業),並每年演練 | 🧪 演練紀錄 |
<!-- ✅ RES-018 業務影響分析:中斷影響隨時間增加 -->
| 業務流程 | 1 小時 | 4 小時 | 1 天 | MTPD | 支援系統(RTO) | 外部相依 |
| --- | --- | --- | --- | --- | --- | --- |
| 線上下單 | 營收損失 50 萬 | 營收損失 200 萬、客訴 | 媒體報導、合作廠商求償 | 2 小時 | 訂單系統(15 分鐘)、金流閘道(供應商 SLA 30 分鐘) | 金流服務商、物流商 |
| 月結報表 | 無 | 無 | 延後對帳 | 3 天 | 報表系統(24 小時) | — |
<!-- ✅ RES-019 相依檢查:訂單系統 RTO 15 分鐘 < 下單流程 MTPD 2 小時 ✔
❌ RES-019 但訂單系統依賴的「會員系統」RTO 為 4 小時 > 15 分鐘,會員系統故障時訂單系統無法在 15 分鐘內恢復 -->
<!-- ✅ RES-020 人工替代作業:金流閘道中斷超過 30 分鐘時,客服改以電話記錄訂單,恢復後補登(每年 3 月演練) -->🔍 10.5 審查與驗證
人工審查問題:
- 系統的 RTO 是依據業務的 MTPD 訂定,還是 IT 自己決定的?(
RES-018、RES-019) - 請列出關鍵路徑上所有相依系統的 RTO:有沒有比本系統更長的?(
RES-019) - 外部供應商(金流、雲端、簡訊)的 SLA 與中斷時的替代方案是什麼?(
RES-018)
AI 常見錯誤: AI 常把業務連續性計畫等同於「資料庫備份與異地備援」,遺漏人員、供應商與人工替代作業(RES-020)。
10.6 混沌工程與故障演練
混沌工程(Chaos Engineering)以受控的實驗主動注入故障,驗證系統的韌性設計真的有效。每個實驗都要有:穩態假設(正常時的可量測指標)、注入的故障、爆炸半徑的限制、中止條件。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
RES-021 | 應該 | 每個韌性機制(熔斷、降級、容錯移轉、自動擴展)至少有一個故障演練驗證,先在預備環境執行,成熟後再於正式環境的限定範圍執行 | 🧪 實驗紀錄 |
RES-022 | 必須 | 故障實驗必須定義穩態假設、爆炸半徑(範圍與時間上限)與中止條件,並事先通知值班人員 | 👁 實驗計畫審查 |
# ✅ RES-021 以 Chaos Mesh 對金流轉接器注入 3 秒延遲,驗證 QS-02(10 秒內熔斷)
# ✅ RES-022 爆炸半徑:只影響 staging 的一個 Pod,持續 10 分鐘後自動停止
apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
name: payment-gateway-latency
namespace: chaos-testing
annotations:
example.com/steady-state: "order-api p99 < 800ms 且錯誤率 < 0.1%(降級回應不計為錯誤)"
example.com/abort-condition: "order-api 5xx 比例 > 5% 持續 1 分鐘"
spec:
action: delay
mode: one
selector:
namespaces:
- payment-staging
labelSelectors:
app.kubernetes.io/name: payment-gateway-mock
delay:
latency: 3s
jitter: 200ms
duration: 10m<!-- ❌ RES-022 在正式環境隨機刪除 Pod,沒有事先通知、沒有中止條件,也沒有定義要觀察什麼 -->🔍 10.6 審查與驗證
人工審查問題:
- 實驗的穩態假設是否可量測?實驗前後的指標是否記錄?(
RES-022) - 爆炸半徑是否受限?誰有權在實驗中途中止?(
RES-022) - 實驗發現的問題是否有改善項目與負責人?(
RES-021)
AI 常見錯誤: AI 常把混沌工程描述為「在正式環境隨機製造故障」,忽略了穩態假設與爆炸半徑控制這兩個核心要素(RES-022)。
11. 安全架構
安全不是上線前加上去的功能,而是架構的屬性。OWASP Top 10:2025 把「不安全的設計(A06)」與「軟體供應鏈失效(A03)」列為主要風險,正說明許多漏洞在寫程式之前就已經決定了。本章規範安全架構的決策;程式碼層級的安全寫法請見 安全程式碼指引。
11.1 安全設計與威脅建模
威脅建模在設計階段回答四個問題(Threat Modeling Manifesto):我們在做什麼?可能出什麼錯?我們要怎麼處理?我們做得夠好嗎?最常用的分類方法是 STRIDE:
| 威脅 | 意義 | 違反的安全屬性 | 典型控制 |
|---|---|---|---|
| Spoofing 偽冒 | 冒充其他使用者或系統 | 真實性 | 身分驗證、mTLS |
| Tampering 竄改 | 修改資料或程式 | 完整性 | 簽章、存取控制、輸入驗證 |
| Repudiation 否認 | 否認做過某個操作 | 不可否認性 | 稽核日誌 |
| Information disclosure 資訊洩漏 | 未授權讀取資料 | 機密性 | 加密、授權、遮蔽 |
| Denial of service 阻斷服務 | 讓系統無法使用 | 可用性 | 限流、資源上限、自動擴展 |
| Elevation of privilege 權限提升 | 取得不該有的權限 | 授權 | 最小權限、物件層級授權 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-001 | 必須 | 新系統與重大變更(新的外部介面、新的資料類型、新的信任邊界)必須進行威脅建模:繪製含信任邊界的資料流程圖,以 STRIDE 逐一分析,並追蹤每個威脅的處理方式 | 👁 威脅模型審查 |
SEC-002 | 必須 | 系統的安全需求以 OWASP ASVS 5.0 為基準:一般系統 Level 2,處理高敏感資料或金流的系統 Level 3 | 👁 資安審查:ASVS 檢核表 |
SEC-003 | 必須 | 預設拒絕:所有端點預設需要身分驗證與授權,公開端點以白名單列出並經資安審查 | 🧪 安全測試:未列入白名單的端點未帶權杖時回 401 |
flowchart LR
%% ✅ SEC-001 資料流程圖標示信任邊界(虛線框)
U["使用者瀏覽器"]
subgraph DMZ["信任邊界:網際網路 → 邊界"]
GW["API Gateway / WAF"]
end
subgraph APP["信任邊界:應用程式網段"]
BFF["Web BFF"]
ORD["訂單服務"]
end
subgraph DATA["信任邊界:資料網段"]
DB[("訂單資料庫")]
end
PG["金流閘道(外部)"]
U -- "HTTPS:Cookie" --> GW
GW -- "HTTPS" --> BFF
BFF -- "mTLS:存取權杖" --> ORD
ORD -- "TLS:JDBC" --> DB
ORD -- "HTTPS:API 金鑰" --> PG<!-- ✅ SEC-001 威脅清單:每個威脅都有處理方式與追蹤 -->
| 編號 | 元素 | STRIDE | 威脅 | 處理方式 | 狀態 |
| --- | --- | --- | --- | --- | --- |
| T-01 | BFF → 訂單服務 | S | 內部攻擊者偽冒 BFF 呼叫訂單服務 | mTLS+AuthorizationPolicy(INT-010) | 已緩解 |
| T-02 | GET /orders/{id} | I | 使用者以他人訂單編號查詢 | 物件層級授權(SEC-008) | 已緩解 |
| T-03 | 訂單服務 → 金流 | I | API 金鑰外洩 | 機密管理+每 90 天輪替(SEC-011) | 已緩解 |
| T-04 | POST /orders | D | 大量下單耗盡庫存 | 限流(API-023)+每使用者未付款訂單上限 | 已接受風險(附理由) |<!-- ❌ SEC-001 「威脅模型」只有一句「系統使用 HTTPS 與 JWT,已足夠安全」,沒有資料流程圖與威脅清單 --><!-- ✅ SEC-002 以 ASVS 5.0 Level 2 作為安全需求基準,逐章記錄適用性與驗證方式 -->
| ASVS 5.0 章節 | 適用 | 驗證方式 | 狀態 |
| --- | --- | --- | --- |
| V1 Encoding and Sanitization | ✔ | SAST、程式碼審查 | 通過 |
| V4 API and Web Service | ✔ | API 測試、Spectral | 通過 |
| V6 Authentication | ✔(由企業 IdP 提供) | IdP 設定審查 | 通過 |
| V8 Authorization | ✔ | 跨使用者存取測試(SEC-008) | 通過 |
| V9 Self-contained Tokens | ✔ | 權杖驗證測試(SEC-009) | 通過 |
| V13 Configuration | ✔ | kubeconform、准入政策 | 通過 |
| V16 Security Logging and Error Handling | ✔ | 稽核日誌測試(SEC-019) | 進行中 |
| V17 WebRTC | 不適用 | — | — |🔍 11.1 審查與驗證
人工審查問題:
- 資料流程圖是否標示了所有信任邊界?每條跨越邊界的資料流是否都分析過 STRIDE?(
SEC-001) - 「已接受風險」的威脅是否有核准人與理由?(
SEC-001) - 公開端點的白名單有哪些?每一個是否必要?(
SEC-003)
AI 常見錯誤: AI 產生的威脅模型常只列出通用的威脅(SQL Injection、XSS),沒有對應到本系統的資料流程與信任邊界(SEC-001)。
11.2 零信任架構
零信任(Zero Trust,NIST SP 800-207)的核心是:不因網路位置而信任。內部網路中的請求和來自網際網路的請求一樣,都必須驗證身分、檢查授權、加密傳輸。NIST SP 800-207A(2023)進一步說明了在雲原生與多雲環境中,以服務身分而非 IP 位址做存取控制。
| 原則 | 實作方式 |
|---|---|
| 每個請求都驗證 | 服務間呼叫以 mTLS 驗證服務身分,並傳遞使用者的存取權杖 |
| 最小權限 | 每個服務只能呼叫它需要的服務(AuthorizationPolicy、NetworkPolicy) |
| 假設已被入侵 | 網段隔離、限制橫向移動、完整的稽核日誌 |
| 以身分取代靜態憑證 | Workload Identity(Kubernetes ServiceAccount 對應雲端 IAM 角色) |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-004 | 必須 | 服務間呼叫必須驗證呼叫者身分(mTLS 或服務權杖),不得以「來自內部網路」作為信任依據 | 👁 架構審查;🧪 未帶憑證的服務間呼叫被拒絕 |
SEC-005 | 必須 | 每個 Kubernetes 命名空間預設拒絕所有進出流量(default-deny NetworkPolicy),再以白名單開放必要的流量 | 🤖 政策檢查:命名空間必須有 default-deny |
SEC-006 | 應該 | 工作負載存取雲端資源使用 Workload Identity(例如 EKS Pod Identity、GKE Workload Identity、Azure Workload Identity),不使用長期有效的存取金鑰 | 👁 設定審查;🤖 掃描 Secret 中的雲端金鑰格式 |
# ✅ SEC-005 命名空間預設拒絕所有進出流量
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny-all
namespace: order
spec:
podSelector: {}
policyTypes:
- Ingress
- Egress
---
# ✅ SEC-005 白名單:只允許 Gateway 命名空間進入訂單 API 的 8080 埠
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: order-api-allow-from-gateway
namespace: order
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: order-api
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: gateway
ports:
- protocol: TCP
port: 8080
---
# ✅ SEC-005 白名單:允許訂單 API 連到資料庫與 DNS
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: order-api-egress
namespace: order
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: order-api
policyTypes:
- Egress
egress:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: order-data
ports:
- protocol: TCP
port: 5432
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
podSelector:
matchLabels:
k8s-app: kube-dns
ports:
- protocol: UDP
port: 53
- protocol: TCP
port: 53# ❌ SEC-006 以長期有效的雲端存取金鑰作為環境變數,金鑰外洩後可被任意使用直到手動撤銷
env:
- name: AWS_ACCESS_KEY_ID
value: AKIAXXXXXXXXXXXXXXXX🔍 11.2 審查與驗證
自動檢查: 准入政策要求每個應用命名空間都有 default-deny-all(SEC-005);以 gitleaks/trufflehog 掃描版本庫與 Kubernetes Secret 中的雲端金鑰格式(SEC-006)。
人工審查問題:
- 在叢集內任一個 Pod 執行
curl http://order-api.order:8080/orders,是否會被拒絕?(SEC-004、SEC-005) - Egress 白名單是否包含 DNS?是否開放了不必要的外部網段(例如
0.0.0.0/0)?(SEC-005)
AI 常見錯誤: AI 產生的 NetworkPolicy 常只有 Ingress、沒有 Egress,或寫了 default-deny 卻忘記開放 DNS,導致所有服務名稱解析失敗(SEC-005)。
11.3 身分驗證
| 情境 | 標準做法 |
|---|---|
| 使用者登入(Web) | OpenID Connect 授權碼流程+PKCE,權杖由 BFF 保管(6.2) |
| 使用者登入(行動 App) | OIDC 授權碼流程+PKCE,以系統瀏覽器登入(RFC 8252) |
| 服務呼叫 API(無使用者) | OAuth 2.0 Client Credentials,或 mTLS 服務身分 |
| API 驗證存取權杖 | 驗證簽章、iss、aud、exp、nbf,並依 scope/角色授權 |
OAuth 2.1(draft-ietf-oauth-v2-1,尚未成為 RFC)整合了 OAuth 2.0 與 RFC 9700(OAuth 2.0 安全最佳實務,2025-01)的要求:授權碼流程一律使用 PKCE、移除 Implicit 與 Resource Owner Password Credentials 授權方式、重新導向 URI 必須完全比對。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-007 | 必須 | 使用者登入使用 OIDC 授權碼流程+PKCE;不得使用 Implicit 或 Resource Owner Password Credentials 授權方式;不得自行實作密碼驗證與工作階段管理 | 👁 架構審查;🤖 IdP 用戶端設定檢查 |
SEC-009 | 必須 | API 必須驗證存取權杖的簽章、發行者(iss)、對象(aud)與有效期限;存取權杖有效期不超過 15 分鐘 | 🧪 安全測試:錯誤 aud、過期權杖回 401 |
# application.yml(資源伺服器)
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://idp.example.com/realms/corp # ✅ SEC-009 驗證簽章與 iss
audiences:
- order-api # ✅ SEC-009 驗證 aud,拒絕發給其他 API 的權杖package com.example.shop.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
@Configuration(proxyBeanMethods = false)
@EnableMethodSecurity
class SecurityConfig {
@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
// ✅ SEC-003 公開端點以白名單列出
.requestMatchers(HttpMethod.GET, "/products/**").permitAll()
// ✅ SEC-010 功能層級授權:依 scope 控制
.requestMatchers(HttpMethod.POST, "/orders").hasAuthority("SCOPE_orders.write")
.requestMatchers(HttpMethod.GET, "/orders/**").hasAuthority("SCOPE_orders.read")
// ✅ SEC-003 其餘一律拒絕,而不是「其餘只要登入即可」
.anyRequest().denyAll())
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults())) // ✅ SEC-009
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.headers(h -> h
// ✅ SEC-015 安全標頭
.httpStrictTransportSecurity(hsts -> hsts.maxAgeInSeconds(31_536_000).includeSubDomains(true))
.contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'none'; frame-ancestors 'none'")));
return http.build();
}
}// ❌ SEC-007 自行實作帳號密碼登入並簽發 JWT;❌ SEC-009 權杖有效期 30 天、沒有 aud(片段)
String token = Jwts.builder()
.subject(user.getUsername())
.expiration(Date.from(Instant.now().plus(30, ChronoUnit.DAYS)))
.signWith(Keys.hmacShaKeyFor("my-secret-key-my-secret-key-123456".getBytes()))
.compact();(片段:違規示意,未編譯)
🔍 11.3 審查與驗證
自動檢查: 安全測試以錯誤的 aud、錯誤的 iss、過期權杖、alg: none 的權杖呼叫 API,全部必須回 401(SEC-009)。
人工審查問題:
- 系統是否自行儲存與驗證密碼?若是,為什麼不使用企業身分提供者?(
SEC-007) - 存取權杖的有效期多長?撤銷使用者權限後,最長多久生效?(
SEC-009) - 資源伺服器是否設定了
audiences?(SEC-009)
AI 常見錯誤: AI 產生的 Spring Security 設定常以 .anyRequest().authenticated() 結尾(只要登入就能存取未明列的端點),或自行以 jjwt 簽發 HS256 權杖並把金鑰寫在程式碼中(SEC-003、SEC-007)。
11.4 授權與物件層級存取控制
OWASP API Security Top 10:2023 的第一名是 API1 Broken Object Level Authorization(BOLA):使用者把網址中的 ID 換成別人的,就能讀取或修改別人的資料。功能層級授權(「這個角色可以呼叫這個 API」)無法防止 BOLA,必須在每一次存取時檢查「這個使用者能否存取這一筆資料」。
| 層級 | 問題 | 實作位置 |
|---|---|---|
| 功能層級 | 這個角色/scope 能否呼叫這個操作? | SecurityFilterChain、@PreAuthorize |
| 物件層級 | 這個使用者能否存取這一筆資料? | 應用層 Use Case 或查詢條件 |
| 欄位層級 | 這個使用者能否看到或修改這個欄位? | 回應 DTO 依角色組裝、輸入 DTO 白名單 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-008 | 必須 | 每一個以 ID 存取資料的操作,都必須檢查目前使用者對該筆資料的權限;查詢條件包含擁有者,或在讀取後比對,無權限時回 404(API-011) | 🧪 授權測試:使用者 A 以使用者 B 的 ID 存取必須失敗 |
SEC-010 | 必須 | 功能層級授權集中定義(SecurityFilterChain 或方法安全註解),不得散落在各 Controller 的 if 判斷中 | 👁 程式碼審查 |
package com.example.shop.order.application;
import com.example.shop.order.domain.Order;
import com.example.shop.order.domain.OrderId;
import com.example.shop.order.domain.OrderNotFoundException;
import com.example.shop.order.domain.OrderRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
// ✅ SEC-008 物件層級授權:只能查詢自己的訂單;查無或無權限都回 OrderNotFoundException(404)
@Service
public class CustomerOrderQuery {
private final OrderRepository orders;
CustomerOrderQuery(OrderRepository orders) {
this.orders = orders;
}
@Transactional(readOnly = true)
public Order getOwnOrder(String requesterId, OrderId id) {
return orders.findById(id)
.filter(order -> order.customerId().equals(requesterId))
.orElseThrow(() -> new OrderNotFoundException(id));
}
}// ❌ SEC-008 只檢查「已登入」,任何人只要知道或猜到訂單編號就能看到別人的訂單(片段)
@GetMapping("/orders/{orderId}")
OrderResponse get(@PathVariable String orderId) {
return OrderResponse.from(orderRepository.findById(new OrderId(orderId)).orElseThrow());
}(片段:違規示意,未編譯)
🔍 11.4 審查與驗證
自動檢查: 為每個以 ID 存取資料的端點撰寫「跨使用者存取」測試:以使用者 A 的權杖存取使用者 B 的資源,斷言回 404(SEC-008)。
人工審查問題:
- 每個帶有
{id}路徑參數的端點,是否都能指出物件層級授權的檢查位置?(SEC-008) - 批次或列表 API 的查詢條件是否限定在使用者有權存取的範圍?(
SEC-008) - 角色與 scope 的檢查是否集中?(
SEC-010)
AI 常見錯誤: AI 產生的 CRUD API 幾乎都沒有物件層級授權,只有 @PreAuthorize("hasRole('USER')") 這類功能層級檢查,這正是 BOLA 漏洞的典型樣子(SEC-008)。
11.5 OWASP Top 10:2025 與 API Security Top 10 對照
OWASP Top 10:2025(2025-11 發布)與 2021 版相比:A03「軟體供應鏈失效」由「易受攻擊與過時的元件」擴大而來,A10「例外狀況處理不當」為新增,SSRF 併入 A01。下表把每個風險對應到本指引的架構控制:
| 編號 | 風險 | 主要架構控制 | 本指引規則 |
|---|---|---|---|
| A01:2025 | Broken Access Control(含 SSRF) | 預設拒絕、物件層級授權、Egress 白名單 | SEC-003、SEC-008、SEC-005 |
| A02:2025 | Security Misconfiguration | 設定即程式碼、准入政策、關閉不必要端點 | RES-013、API-026、PLT-013、PLT-011 |
| A03:2025 | Software Supply Chain Failures | SBOM、相依掃描、簽章與來源證明、釘選版本 | SEC-016~SEC-018 |
| A04:2025 | Cryptographic Failures | TLS、靜態加密、金鑰管理 | SEC-012~SEC-014 |
| A05:2025 | Injection | 參數化查詢、輸入驗證、輸出編碼 | DATA-004、API-024 |
| A06:2025 | Insecure Design | 威脅建模、品質情境、ADR | SEC-001、NFR-001、GOV-006 |
| A07:2025 | Authentication Failures | OIDC、PKCE、權杖驗證 | SEC-007、SEC-009 |
| A08:2025 | Software or Data Integrity Failures | 映像簽章驗證、事件結構相容性 | SEC-017、INT-020 |
| A09:2025 | Logging & Alerting Failures | 稽核日誌、安全事件告警 | SEC-019、OBS-008 |
| A10:2025 | Mishandling of Exceptional Conditions | 失效時安全(fail closed)、統一錯誤處理 | SEC-020、API-014 |
OWASP API Security Top 10:2023 中與架構最相關的項目:
| 編號 | 風險 | 架構控制 |
|---|---|---|
| API1 | Broken Object Level Authorization | SEC-008 |
| API2 | Broken Authentication | SEC-007、SEC-009 |
| API3 | Broken Object Property Level Authorization | 回應 DTO 只包含允許的欄位、輸入 DTO 白名單(大量指派) |
| API4 | Unrestricted Resource Consumption | API-016、API-023、API-024 |
| API5 | Broken Function Level Authorization | SEC-010 |
| API6 | Unrestricted Access to Sensitive Business Flows | 業務流程限流(每使用者下單上限)、機器人防護 |
| API7 | Server Side Request Forgery | Egress 白名單(SEC-005)、禁止使用者提供任意網址 |
| API8 | Security Misconfiguration | RES-013、API-026 |
| API9 | Improper Inventory Management | 服務目錄(STY-014)、API 版本與棄用(API-021) |
| API10 | Unsafe Consumption of APIs | 防腐層(STY-009)、驗證外部 API 回應、逾時(INT-001) |
11.6 機密管理與資料保護
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-011 | 必須 | 機密(密碼、API 金鑰、私鑰、權杖)不得出現在程式碼、版本庫、容器映像或未加密的 ConfigMap;由機密管理系統(Vault、雲端 Secret Manager)透過 External Secrets 等方式注入,並定期輪替 | 🤖 gitleaks/trufflehog 掃描版本庫與映像;👁 設定審查 |
SEC-012 | 必須 | 所有傳輸都要加密,包括內部服務間與資料庫連線;TLS 最低 1.2,優先使用 1.3 | 🤖 TLS 掃描(testssl.sh);👁 連線字串審查(sslmode=verify-full) |
SEC-013 | 必須 | 靜態資料加密(磁碟、資料庫、備份、物件儲存),金鑰由 KMS 管理並定期輪替;金鑰與資料分開存放 | 👁 雲端設定審查 |
SEC-014 | 必須 | 機密等級(8.6)的欄位以欄位層級加密或代碼化(tokenization)保護,日誌與錯誤訊息中遮蔽 | 👁 資料字典審查;🧪 測試:日誌中不出現原始值 |
# ✅ SEC-011 以 External Secrets Operator 從 Vault 同步機密,版本庫中只有「參照」,沒有機密本身
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: order-api-secrets
namespace: order
spec:
refreshInterval: 1h
secretStoreRef:
kind: ClusterSecretStore
name: corp-vault
target:
name: order-api-secrets
creationPolicy: Owner
data:
- secretKey: SPRING_DATASOURCE_PASSWORD
remoteRef:
key: order/prod/db
property: password
- secretKey: PAYMENT_GATEWAY_API_KEY
remoteRef:
key: order/prod/payment-gateway
property: api-key# application.yml
spring:
datasource:
# ✅ SEC-012 資料庫連線驗證伺服器憑證與主機名稱(verify-full),不是只加密(require)
url: jdbc:postgresql://order-db.order-data:5432/shop?sslmode=verify-full&sslrootcert=/etc/ssl/db/ca.crt
username: order_app
password: ${SPRING_DATASOURCE_PASSWORD} # ✅ SEC-011 由 ExternalSecret 注入# ❌ SEC-011 機密以明文寫在 ConfigMap 與 application.yml,並提交到版本庫
apiVersion: v1
kind: ConfigMap
metadata:
name: order-api-config
data:
SPRING_DATASOURCE_PASSWORD: "P@ssw0rd123"
---
# ❌ SEC-012 sslmode=disable:內部網路明文傳輸資料庫流量
spring:
datasource:
url: jdbc:postgresql://order-db:5432/shop?sslmode=disable# ✅ SEC-013 Kubernetes API Server 以 KMS v2 加密 etcd 中的 Secret(金鑰由外部 KMS 管理,可輪替)
# 檔案:/etc/kubernetes/encryption-config.yaml(以 --encryption-provider-config 指定)
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- kms:
apiVersion: v2
name: corp-kms
endpoint: unix:///var/run/kms-plugin/socket.sock
timeout: 3s
- identity: {}🔍 11.6 審查與驗證
自動檢查: CI 執行 gitleaks 掃描每次提交(SEC-011);Trivy 掃描映像中的機密(trivy image --scanners secret)(SEC-011)。
人工審查問題:
- Kubernetes
Secret是否只是 base64 編碼?叢集是否啟用 etcd 靜態加密?(SEC-011、SEC-013) - 資料庫連線是
sslmode=require(只加密)還是verify-full(驗證身分)?(SEC-012) - 機密輪替時,應用程式是否需要重新部署?輪替流程是否演練過?(
SEC-011)
AI 常見錯誤: AI 產生的 Kubernetes 範例常把密碼直接放在 Secret 的 stringData 並提交到版本庫,或以 sslmode=disable 連線資料庫(SEC-011、SEC-012)。
11.7 Web 安全標頭
| 標頭 | 建議值 | 防護 |
|---|---|---|
Strict-Transport-Security | max-age=31536000; includeSubDomains | 強制 HTTPS,防止降級攻擊 |
Content-Security-Policy | 依應用程式設定,至少 default-src 'self'; frame-ancestors 'none'; object-src 'none' | XSS、點擊劫持 |
X-Content-Type-Options | nosniff | MIME 類型混淆 |
Referrer-Policy | strict-origin-when-cross-origin | 洩漏網址中的資訊 |
Permissions-Policy | 關閉不需要的瀏覽器功能,例如 camera=(), microphone=(), geolocation=() | 濫用瀏覽器功能 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-015 | 必須 | 所有 HTML 與 API 回應設定上表的安全標頭;CSP 不得使用 'unsafe-inline' 與 'unsafe-eval' 執行腳本(以 nonce 或 hash 取代) | 🧪 部署後以 curl -I 或 Mozilla HTTP Observatory 檢查 |
# 前端靜態檔案伺服器(nginx)
# ✅ SEC-015 安全標頭;CSP 不允許 inline script
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https://api.example.com; frame-ancestors 'none'; object-src 'none'; base-uri 'self'" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;# ❌ SEC-015 CSP 允許 unsafe-inline 與 unsafe-eval,等於沒有 XSS 防護
add_header Content-Security-Policy "default-src * 'unsafe-inline' 'unsafe-eval'";🔍 11.7 審查與驗證
自動檢查: 冒煙測試以 curl -sI 檢查所有標頭存在(SEC-015)。
人工審查問題:
- CSP 是否包含
'unsafe-inline'或萬用字元*?(SEC-015) - 標頭是否加了
always?(nginx 預設只在 2xx/3xx 回應加上add_header)(SEC-015)
AI 常見錯誤: AI 仍常產生已被瀏覽器棄用的 X-XSS-Protection: 1; mode=block,或為了讓前端框架能運作而在 CSP 加上 'unsafe-inline'(SEC-015)。
11.8 軟體供應鏈安全
SLSA(Supply-chain Levels for Software Artifacts)1.2(2025-11)定義了兩條軌道:
| 軌道 | 等級 | 要求重點 |
|---|---|---|
| Build | L1 | 產生建置來源證明(provenance) |
| Build | L2 | 由代管的建置平台產生並簽署來源證明 |
| Build | L3 | 建置平台強化:建置之間互相隔離,簽章金鑰無法被建置流程存取 |
| Source | L1–L4 | 版本控制、保留歷史、強制的技術控制、雙人審查(1.2 新增) |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-016 | 必須 | 每個建置產物(JAR、容器映像)產生 SBOM(CycloneDX 或 SPDX),並以弱點掃描作為發布閘門:有可修補的 Critical/High 弱點時阻擋發布 | 🤖 Trivy/Grype;🤖 CI 閘門 |
SEC-017 | 必須 | 容器映像由 CI 簽章並產生建置來源證明(目標 SLSA Build L3);正式環境只部署通過簽章驗證的映像 | 🤖 cosign verify;🤖 准入政策驗證簽章 |
SEC-018 | 必須 | 第三方 GitHub Actions 以完整的 commit SHA 釘選;套件相依以 lock 檔鎖定,並以 Dependabot/Renovate 自動提出更新 | 🤖 actionlint+自訂檢查;👁 PR 審查 |
# .github/workflows/release.yml(節錄)
# ✅ SEC-018 所有 Actions 以完整 commit SHA 釘選,註解標示版本
# ✅ SEC-016 產生 SBOM 並以弱點掃描作為閘門;✅ SEC-017 簽章並產生來源證明
name: release
on:
push:
tags: ['v*']
permissions:
contents: read
jobs:
image:
runs-on: ubuntu-24.04
permissions:
contents: read
packages: write
id-token: write # 以 OIDC 取得簽章用的短期憑證(keyless),不需要長期金鑰
attestations: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: build
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
push: true
tags: ghcr.io/example/order-api:${{ github.ref_name }}
- uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
with:
image: ghcr.io/example/order-api@${{ steps.build.outputs.digest }}
format: cyclonedx-json
output-file: sbom.cdx.json
- uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
with:
image-ref: ghcr.io/example/order-api@${{ steps.build.outputs.digest }}
severity: CRITICAL,HIGH
ignore-unfixed: true
exit-code: '1'
- uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
- name: Sign image (keyless)
run: cosign sign --yes ghcr.io/example/order-api@${{ steps.build.outputs.digest }}
- uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-name: ghcr.io/example/order-api
subject-digest: ${{ steps.build.outputs.digest }}
push-to-registry: true# ❌ SEC-018 以可變的標籤引用第三方 Action:標籤被改指向惡意版本時,下一次建置就會執行惡意程式碼
- uses: some-org/some-action@main
- uses: some-org/other-action@v1🔍 11.8 審查與驗證
自動檢查: actionlint 檢查工作流程語法;以腳本檢查所有非 ./ 開頭的 uses: 都以 40 位十六進位 SHA 結尾(SEC-018);部署前以 cosign verify 或 Kyverno verifyImages 政策驗證簽章(SEC-017)。本指引的工作流程範例已以 actionlint 檢查,SHA 為查證當日各 Action 最新版本的實際 commit。
人工審查問題:
- 弱點掃描的閘門是否真的會讓建置失敗(
exit-code: '1')?例外清單(.trivyignore)是否有到期日與理由?(SEC-016) - 部署時以標籤(
:1.4.2)還是以 digest(@sha256:…)引用映像?(SEC-017) - 工作流程的
permissions是否最小化?(SEC-018)
AI 常見錯誤: AI 產生的 GitHub Actions 幾乎都以 @v4、@main 引用第三方 Action,沒有設定 permissions;版本號也常停留在訓練資料當時的舊版(例如 actions/checkout@v4)(SEC-018)。
11.9 稽核日誌與例外處理
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
SEC-019 | 必須 | 安全相關事件(登入成功與失敗、權限變更、存取機密資料、管理操作、授權失敗)必須寫入稽核日誌,記錄「誰、何時、從哪裡、對什麼、做了什麼、結果」;稽核日誌集中保存、不可被應用程式修改或刪除,保存期限依法規 | 🧪 測試:操作後稽核日誌有對應紀錄;👁 保存設定審查 |
SEC-020 | 必須 | 例外狀況必須「失效時安全」(fail closed):授權檢查、簽章驗證、限流等安全機制發生錯誤時拒絕請求,而不是放行 | 🧪 故障注入:授權服務無法連線時請求被拒絕 |
{
"$comment": "✅ SEC-019 稽核事件:誰、何時、從哪裡、對什麼、做了什麼、結果;不含個資原始值",
"@timestamp": "2026-10-07T01:30:12.345Z",
"event.category": "authorization",
"event.action": "order.view",
"event.outcome": "failure",
"user.id": "u-7f3a",
"source.ip": "203.0.113.24",
"resource.type": "order",
"resource.id": "ORD-20261007-000123",
"trace.id": "4bf92f3577b34da6a3ce929d0e0e4736",
"reason": "not-owner"
}// ❌ SEC-020 授權服務錯誤時放行(fail open):攻擊者只要讓授權服務逾時就能繞過檢查(片段)
boolean allowed;
try {
allowed = policyClient.check(user, resource);
} catch (Exception e) {
log.warn("授權服務錯誤,暫時放行", e);
allowed = true;
}(片段:違規示意,未編譯)
🔍 11.9 審查與驗證
人工審查問題:
- 稽核日誌與一般應用程式日誌是否分開保存?應用程式帳號能否刪除稽核紀錄?(
SEC-019) - 安全機制的
catch區塊中,預設行為是拒絕還是放行?(SEC-020)
AI 常見錯誤: AI 為了「提升可用性」,常在授權或驗證失敗的例外處理中回傳 true 或略過檢查;這正是 OWASP Top 10:2025 新增 A10 所描述的問題(SEC-020)。
12. 可觀測性
監控回答「系統是否正常」,可觀測性回答「系統為什麼不正常」。在分散式系統中,一個請求會經過多個服務,若沒有串連起來的追蹤、日誌與指標,故障時只能逐台登入主機猜測原因。本章以 OpenTelemetry(CNCF 的可觀測性標準)作為企業標準。
12.1 可觀測性架構
| 訊號 | 回答的問題 | 標準 | 企業採用 |
|---|---|---|---|
| 追蹤(Traces) | 這個請求經過了哪些服務、每一段花了多久? | OpenTelemetry、W3C Trace Context | Spring Boot 4 Micrometer Tracing → OTLP → Collector → 追蹤後端 |
| 指標(Metrics) | 系統整體的趨勢與健康狀態? | Prometheus、OpenMetrics、OTLP | Micrometer → /actuator/prometheus → Prometheus |
| 日誌(Logs) | 某個時間點發生了什麼事? | 結構化 JSON(ECS/OTel 語意慣例) | Spring Boot 結構化日誌 → 收集器 → 日誌後端 |
| 剖析(Profiles) | 程式碼中哪一段耗用 CPU/記憶體? | OpenTelemetry Profiles(發展中) | 選用:持續剖析工具 |
flowchart LR
subgraph Apps["應用程式(Spring Boot 4)"]
A1["訂單 API"]
A2["付款服務"]
end
A1 -- "OTLP(traces、logs)" --> COL["OpenTelemetry Collector<br/>(Gateway 模式)"]
A2 -- "OTLP" --> COL
PROM["Prometheus"] -- "抓取 /actuator/prometheus" --> A1
PROM -- "抓取" --> A2
COL --> TR["追蹤後端<br/>(Tempo/Jaeger)"]
COL --> LOG["日誌後端<br/>(Loki/Elasticsearch)"]
PROM --> AM["Alertmanager"]
TR --> G["Grafana"]
LOG --> G
PROM --> G| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
OBS-001 | 必須 | 以 OpenTelemetry 作為追蹤與日誌的標準協定(OTLP);所有遙測資料帶有資源屬性 service.name、service.version、deployment.environment.name | 🧪 部署後檢查追蹤後端中的資源屬性 |
OBS-002 | 必須 | 應用程式把遙測資料送到 OpenTelemetry Collector,而不是直接送到特定的後端;後端的更換、取樣與遮蔽在 Collector 處理 | 👁 架構審查;🤖 otelcol-contrib validate |
Spring Boot 4 以 spring-boot-starter-opentelemetry 整合 OpenTelemetry:
# application.yml
spring:
application:
name: order-api # ✅ OBS-001 成為 service.name
management:
opentelemetry:
resource-attributes: # ✅ OBS-001 共通的資源屬性
service.namespace: shop
service.version: ${APP_VERSION:unknown}
deployment.environment.name: ${DEPLOY_ENV}
tracing:
export:
otlp:
endpoint: http://otel-collector.observability:4318/v1/traces # ✅ OBS-002 送到 Collector
logging:
export:
otlp:
endpoint: http://otel-collector.observability:4318/v1/logs
tracing:
sampling:
probability: 1.0 # 應用程式端全部送出,由 Collector 做尾端取樣(OBS-004)OpenTelemetry Collector 設定(Collector 0.144 起元件名稱改為 snake_case,例如 otlp_grpc、k8s_attributes;舊名稱仍可使用但會輸出棄用警告):
# otel-collector.yaml
# ✅ OBS-002 應用程式只認識 Collector;後端、取樣、遮蔽都在這裡處理
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_percentage: 80
spike_limit_percentage: 20
# ✅ OBS-004 尾端取樣:保留所有錯誤與慢請求,其餘保留 10%
tail_sampling:
decision_wait: 10s
policies:
- name: keep-errors
type: status_code
status_code:
status_codes: [ERROR]
- name: keep-slow
type: latency
latency:
threshold_ms: 800
- name: baseline
type: probabilistic
probabilistic:
sampling_percentage: 10
# ✅ OBS-005 遮蔽敏感屬性:刪除授權標頭,雜湊化使用者 Email
attributes/redact:
actions:
- key: http.request.header.authorization
action: delete
- key: user.email
action: hash
batch: {}
exporters:
otlp_grpc/traces:
endpoint: tempo.observability:4317
tls:
ca_file: /etc/otel/ca.crt
otlp_http/logs:
endpoint: http://loki.observability:3100/otlp
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, attributes/redact, tail_sampling, batch]
exporters: [otlp_grpc/traces]
logs:
receivers: [otlp]
processors: [memory_limiter, attributes/redact, batch]
exporters: [otlp_http/logs]尾端取樣必須讓同一個 Trace 的所有 Span 送到同一個 Collector 實例。Collector 有多個副本時,前面需要一層使用
load_balancingexporter(以traceID為路由鍵)的 Collector。
# ❌ OBS-002 應用程式直接連到特定廠商的後端,更換後端或調整取樣都要修改並重新部署所有服務
management:
opentelemetry:
tracing:
export:
otlp:
endpoint: https://otlp.vendor-x.example/v1/traces
headers:
api-key: 0123456789abcdef🔍 12.1 審查與驗證
自動檢查: otelcol-contrib validate --config=otel-collector.yaml(OBS-002)。本章的 Collector 設定已以 otelcol-contrib 0.162.0 驗證。
人工審查問題:
- 追蹤後端中能否依
service.name與deployment.environment.name過濾?(OBS-001) - 是否有服務直接把遙測資料送到 SaaS 後端,繞過 Collector?(
OBS-002)
AI 常見錯誤: AI 產生的 Collector 設定常使用舊的元件名稱(otlp exporter、k8sattributes)與已移除的 logging exporter(改為 debug);Spring Boot 端則常使用 Boot 3.x 的 management.otlp.tracing.endpoint,在 Boot 4 已改為 management.opentelemetry.tracing.export.otlp.endpoint(OBS-001、OBS-002)。
12.2 分散式追蹤
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
OBS-003 | 必須 | 所有服務以 W3C Trace Context(traceparent 標頭)傳遞追蹤內容,包括非同步路徑:訊息標頭(Kafka)、@Async、排程工作 | 🧪 端到端測試:一個請求的追蹤包含非同步消費者的 Span |
OBS-004 | 應該 | 取樣策略記錄於架構文件:錯誤與慢請求必須保留(尾端取樣),一般請求可依流量取樣 | 👁 架構審查 |
# application.yml
spring:
task:
execution:
propagate-context: true # ✅ OBS-003 @Async 與 TaskExecutor 傳遞追蹤內容
kafka:
template:
observation-enabled: true # ✅ OBS-003 Kafka 發送時在訊息標頭加上 traceparent
listener:
observation-enabled: true # ✅ OBS-003 消費時延續同一個 Trace
management:
tracing:
propagation:
type: [w3c]<!-- ❌ OBS-003 Kafka 未啟用 observation:訂單 API 的追蹤在發送事件後就斷了,
出貨服務處理失敗時,無法從使用者的請求追到失敗的消費者 -->
<!-- ❌ OBS-004 以 management.tracing.sampling.probability: 0.01 做頭端取樣,
99% 的錯誤請求沒有追蹤資料可查 -->🔍 12.2 審查與驗證
自動檢查: 端到端測試送出一筆訂單後,以追蹤後端的 API 查詢該 Trace ID,斷言包含 order-api 與 shipping 兩個服務的 Span(OBS-003)。
人工審查問題:
- 非同步路徑(訊息、排程、執行緒池)是否都能延續追蹤?(
OBS-003) - 錯誤請求的追蹤保留率是多少?(
OBS-004)
AI 常見錯誤: AI 常以 Spring Cloud Sleuth 設定追蹤;Sleuth 已停止開發,Spring Boot 3 起由 Micrometer Tracing 取代(OBS-003)。
12.3 日誌
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
OBS-005 | 必須 | 日誌以結構化 JSON 輸出到標準輸出(stdout),包含時間(UTC)、等級、服務名稱、traceId、spanId;不得包含密碼、權杖、完整卡號與未遮蔽的個人資料 | 🧪 測試:擷取日誌輸出並斷言格式與遮蔽;🤖 日誌掃描規則 |
OBS-006 | 必須 | 正式環境預設日誌等級為 INFO;日誌保存期限依法規、主管機關要求與資料分級訂定並集中保存(本指引範例以稽核日誌 180 天為基準) | 👁 設定審查 |
Spring Boot 3.4 起內建結構化日誌,不需要自訂 logback-spring.xml:
# application.yml
logging:
structured:
format:
console: ecs # ✅ OBS-005 以 Elastic Common Schema 格式輸出 JSON;MDC 中的 traceId、spanId 一併輸出
ecs:
service:
name: ${spring.application.name}
version: ${APP_VERSION} # 必須明確設定,否則會帶入 classpath 上其他 JAR 的版本號
environment: ${DEPLOY_ENV}
level:
root: INFO # ✅ OBS-006 正式環境預設 INFO
com.example.shop: INFO{
"$comment": "✅ OBS-005 一行一筆 JSON,含 traceId 與 spanId,可在日誌後端以 traceId 串起追蹤(欄位結構依 Spring Boot 4.1.1 實際輸出,實際輸出為單行)",
"@timestamp": "2026-10-07T01:30:12.345Z",
"log": { "level": "WARN", "logger": "com.example.shop.payment.internal.PaymentAuthorizationService" },
"process": { "pid": 1, "thread": { "name": "tomcat-handler-42" } },
"service": { "name": "order-api", "version": "1.4.2", "environment": "production", "node": {} },
"message": "金流閘道熔斷,訂單改為付款處理中",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"spanId": "00f067aa0ba902b7",
"ecs": { "version": "8.11" }
}// ❌ OBS-005 以字串串接輸出整個請求物件:內含卡號與 Email,而且非結構化,無法查詢(片段)
log.info("付款請求:" + request);
// ✅ OBS-005 只輸出必要的識別碼,敏感資料不進日誌
log.info("付款請求:orderId={}, amount={}", request.orderId(), request.amountInCents());(片段:示意,未編譯)
🔍 12.3 審查與驗證
自動檢查: 以 OutputCaptureExtension 擷取日誌,斷言每一行都是合法 JSON、包含 traceId,且不包含測試資料中的卡號與 Email(OBS-005)。
人工審查問題:
- 日誌中是否會輸出整個 DTO 或實體(
toString())?其中有沒有個人資料?(OBS-005) - 日誌是否寫入容器內的檔案而非 stdout?(
OBS-005) - 日誌保存期限是否符合法規與資料分級?(
OBS-006)
實測發現: 未設定 logging.structured.ecs.service.version 時,Spring Boot 會從 classpath 上的 JAR manifest 推斷版本,可能輸出與應用程式無關的版本號;請一律以部署時的 APP_VERSION 明確設定(OBS-001)。
AI 常見錯誤: AI 仍常產生數十行的 logback-spring.xml 搭配 logstash-logback-encoder 來輸出 JSON;Spring Boot 3.4 起以 logging.structured.format.console 一行設定即可(OBS-005)。
12.4 指標與 SLO 告警
| 方法 | 適用對象 | 指標 |
|---|---|---|
| RED | 服務(請求驅動) | Rate(請求速率)、Errors(錯誤率)、Duration(延遲分布) |
| USE | 資源(CPU、記憶體、連線池、佇列) | Utilization(使用率)、Saturation(飽和度、排隊)、Errors(錯誤) |
| Golden Signals | 服務整體 | 延遲、流量、錯誤、飽和度 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
OBS-007 | 必須 | 每個服務提供 RED 指標,延遲以直方圖(histogram)記錄並包含 SLO 邊界;每個有限資源(連線池、執行緒、佇列)提供 USE 指標 | 🤖 Prometheus 抓取檢查 |
OBS-008 | 必須 | 安全事件必須告警:授權失敗(401/403)異常增加、稽核日誌中斷、熔斷器長時間開啟、DLQ 有訊息 | 🤖 promtool check rules;🧪 告警演練 |
OBS-009 | 必須 | 可用性告警以 SLO 錯誤預算的燃燒率為基礎,使用多視窗(長視窗+短視窗)避免誤報;不以 CPU 使用率等原因指標作為呼叫值班的告警 | 🤖 promtool check rules、promtool test rules |
OBS-010 | 必須 | 指標標籤不得使用高基數的值(使用者 ID、訂單編號、完整 URL、Email);URL 以路由樣板(/orders/{orderId})表示 | 👁 程式碼審查;🤖 Prometheus 序列數監控 |
OBS-011 | 必須 | 每個告警都有嚴重度與處理手冊(runbook)連結;會呼叫值班的告警必須是需要人立即處理的症狀 | 🤖 規則檢查 annotations.runbook_url |
# application.yml
management:
metrics:
tags:
application: ${spring.application.name} # 告警規則以 application 標籤區分服務
distribution:
percentiles-histogram:
http.server.requests: true # ✅ OBS-007 延遲以直方圖記錄
slo:
http.server.requests: 800ms # ✅ OBS-007 加入 SLO 邊界(le="0.8"),對應 QS-01多視窗、多燃燒率告警(Google SRE Workbook 的建議做法)。以 99.9% 的 SLO 為例,錯誤預算為 0.1%;燃燒率 14.4 代表以這個速度 2 天內會用完 28 天的預算:
| 嚴重度 | 長視窗 | 短視窗 | 燃燒率 | 錯誤率門檻 | 意義 |
|---|---|---|---|---|---|
| page | 1 小時 | 5 分鐘 | 14.4 | 1.44% | 1 小時內耗用 2% 的預算 |
| page | 6 小時 | 30 分鐘 | 6 | 0.6% | 6 小時內耗用 5% 的預算 |
| ticket | 1 天 | 2 小時 | 3 | 0.3% | 1 天內耗用 10% 的預算 |
# prometheus/rules/order-api-slo.yaml
# ✅ OBS-009 多視窗燃燒率告警;✅ OBS-011 每個告警有嚴重度與 runbook
groups:
- name: order-api-slo-recording
rules:
- record: slo:order_api_errors:ratio_rate5m
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[5m]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[5m]))
- record: slo:order_api_errors:ratio_rate30m
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[30m]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[30m]))
- record: slo:order_api_errors:ratio_rate1h
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[1h]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[1h]))
- record: slo:order_api_errors:ratio_rate2h
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[2h]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[2h]))
- record: slo:order_api_errors:ratio_rate6h
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[6h]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[6h]))
- record: slo:order_api_errors:ratio_rate1d
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[1d]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[1d]))
- name: order-api-slo-alerts
rules:
- alert: OrderApiErrorBudgetFastBurn
expr: |
(slo:order_api_errors:ratio_rate1h > (14.4 * 0.001) and slo:order_api_errors:ratio_rate5m > (14.4 * 0.001))
or
(slo:order_api_errors:ratio_rate6h > (6 * 0.001) and slo:order_api_errors:ratio_rate30m > (6 * 0.001))
labels:
severity: page
annotations:
summary: 訂單 API 錯誤預算快速燃燒
description: 錯誤率 {{ $value | humanizePercentage }},以此速度將在數天內耗盡 28 天的錯誤預算。
runbook_url: https://runbooks.example.com/order-api/error-budget-burn
- alert: OrderApiErrorBudgetSlowBurn
expr: |
slo:order_api_errors:ratio_rate1d > (3 * 0.001) and slo:order_api_errors:ratio_rate2h > (3 * 0.001)
labels:
severity: ticket
annotations:
summary: 訂單 API 錯誤預算緩慢燃燒
runbook_url: https://runbooks.example.com/order-api/error-budget-burn
- name: order-api-security-and-resilience
rules:
# ✅ OBS-008 授權失敗異常增加(可能是撞庫、權杖外洩或 BOLA 掃描)
- alert: OrderApiAuthFailuresSpike
expr: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"401|403"}[5m])) > 5
and
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"401|403"}[5m]))
> 3 * sum(rate(http_server_requests_seconds_count{application="order-api",status=~"401|403"}[1h] offset 1d))
for: 10m
labels:
severity: page
team: security
annotations:
summary: 訂單 API 授權失敗次數異常
runbook_url: https://runbooks.example.com/security/auth-failure-spike
# ✅ OBS-008 / RES-005 熔斷器長時間開啟
- alert: CircuitBreakerOpen
expr: max by (application, name) (resilience4j_circuitbreaker_state{state="open"}) == 1
for: 5m
labels:
severity: page
annotations:
summary: '{{ $labels.application }} 對 {{ $labels.name }} 的熔斷器已開啟超過 5 分鐘'
runbook_url: https://runbooks.example.com/resilience/circuit-breaker-open
# ✅ OBS-008 / INT-015 死信佇列有新訊息
- alert: DeadLetterTopicNotEmpty
expr: sum by (topic) (increase(kafka_topic_partition_current_offset{topic=~".+\\.DLT"}[15m])) > 0
labels:
severity: ticket
annotations:
summary: '死信主題 {{ $labels.topic }} 有新的無法處理訊息'
runbook_url: https://runbooks.example.com/messaging/dead-letter# ❌ OBS-009 以 CPU 使用率呼叫值班:CPU 80% 不代表使用者受影響,造成大量誤報與告警疲勞
- alert: HighCpu
expr: process_cpu_usage > 0.8
labels:
severity: page// ❌ OBS-010 以訂單編號作為指標標籤:每筆訂單產生一條新的時間序列,Prometheus 記憶體爆炸(片段)
meterRegistry.counter("orders.placed", "orderId", order.id().value()).increment();
// ✅ OBS-010 標籤只使用低基數的值
meterRegistry.counter("orders.placed", "channel", order.channel().name()).increment();(片段:示意,未編譯)
🔍 12.4 審查與驗證
自動檢查: promtool check rules prometheus/rules/*.yaml;以 promtool test rules 撰寫單元測試,輸入模擬的錯誤率序列,斷言在預期時間點觸發告警(OBS-008、OBS-009)。本章的規則已以 promtool 3.15.0 檢查通過。
人工審查問題:
- 這個告警響起時,值班人員需要立即做什麼?若答案是「觀察」,它就不該是 page 等級。(
OBS-011) - 新增的指標標籤有多少種可能的值?(
OBS-010) - 錯誤率的分母是否排除了健康檢查等非使用者流量?(
OBS-009)
AI 常見錯誤: AI 產生的告警規則常以單一視窗的錯誤率(例如 5 分鐘內 > 1%)呼叫值班,短暫的尖峰就會誤報;或把燃燒率門檻算錯(14.4 × 0.1% = 1.44%,不是 14.4%)(OBS-009)。
12.5 儀表板與值班
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
OBS-012 | 應該 | 儀表板與告警規則以程式碼管理(JSON/YAML 納入版本控制),透過 CI/CD 部署,不在 UI 中手動修改 | 👁 版本庫審查 |
OBS-013 | 必須 | 每個正式環境的服務都有值班輪值與升級路徑;重大事件後 5 個工作天內完成無責檢討(blameless postmortem),改善項目有負責人與期限 | 👁 事件紀錄審查 |
# ✅ OBS-012 Grafana 儀表板以 ConfigMap 交由 Grafana sidecar 自動載入,儀表板 JSON 存放於版本庫
apiVersion: v1
kind: ConfigMap
metadata:
name: order-api-dashboard
namespace: observability
labels:
grafana_dashboard: "1"
data:
order-api.json: |
{
"title": "訂單 API(RED)",
"uid": "order-api-red",
"schemaVersion": 41,
"panels": [
{
"type": "timeseries",
"title": "p99 延遲",
"targets": [
{ "expr": "histogram_quantile(0.99, sum by (le) (rate(http_server_requests_seconds_bucket{application=\"order-api\"}[5m])))" }
]
}
]
}<!-- ✅ OBS-013 事後檢討摘要 -->
# 事件檢討:2026-09-28 金流閘道逾時造成下單失敗
- 影響:09:12–09:47(35 分鐘),下單失敗率 23%,耗用 28 天錯誤預算的 61%
- 根本原因:金流閘道熔斷器的 slow-call 門檻設為 5 秒,大於 Gateway 逾時 3 秒,熔斷器從未開啟
- 改善項目:
| 項目 | 負責人 | 期限 |
| --- | --- | --- |
| slow-call-duration-threshold 改為 800ms(RES-001、INT-002) | 李小華 | 2026-10-03 |
| 新增故障演練:金流延遲 3 秒(RES-021) | 陳志明 | 2026-10-15 |🔍 12.5 審查與驗證
人工審查問題:
- 儀表板是否有人在 UI 中修改而沒有同步回版本庫?(
OBS-012) - 事件檢討是否聚焦在系統與流程,而不是追究個人?改善項目是否有期限?(
OBS-013)
AI 常見錯誤: AI 產生的事件檢討常只寫「已修正」而沒有根本原因分析與預防措施(OBS-013)。
13. 容器與部署平台
本章規範應用程式如何封裝成容器映像、如何在 Kubernetes 上執行,以及如何以宣告式、可稽核的方式管理部署。v1.x 的第 10.3、10.4 與第 11 章內容在此合併更新為 Kubernetes 1.37 的寫法。
13.1 容器映像
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-001 | 必須 | 以多階段建置產生映像:建置階段使用 JDK,執行階段只包含 JRE(或更精簡的基底)與應用程式;容器以非 root 使用者執行 | 🤖 hadolint;🤖 Trivy 設定掃描 |
PLT-002 | 必須 | 基底映像以 digest 釘選,並由自動化工具(Renovate/Dependabot)定期更新;不得使用 latest 標籤 | 🤖 hadolint DL3006、DL3007;👁 PR 審查 |
PLT-003 | 必須 | 映像中不得包含機密、原始碼、建置工具與測試資料;以 .dockerignore 排除不必要的檔案 | 🤖 Trivy --scanners secret;🤖 dive/映像大小檢查 |
Spring Boot 的分層 JAR(layered jar)把相依套件與應用程式分成不同的映像層,相依沒有變更時重新建置只需要上傳很小的應用程式層:
# syntax=docker/dockerfile:1
# ✅ PLT-001 多階段建置;PLT-002 基底映像以 digest 釘選(註解標示對應的標籤,由 Renovate 更新)
# 建置階段:JDK + Maven Wrapper
FROM eclipse-temurin:25-jdk-noble@sha256:589ff4cc3f71aab462e7048a47a0d10edf57fbccde3fceea2281e610bf5880b4 AS build
WORKDIR /workspace
COPY .mvn/ .mvn/
COPY mvnw pom.xml ./
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -q dependency:go-offline
COPY src/ src/
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -q package -DskipTests \
&& java -Djarmode=tools -jar target/*.jar extract --layers --launcher --destination target/extracted
# 執行階段:只有 JRE,以非 root 使用者執行
FROM eclipse-temurin:25-jre-noble@sha256:d9a39a23634650173f1e2bbc176227af9728587ecf0f4b62d53e9355cd7a19ab
WORKDIR /app
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --no-create-home app
COPY --from=build /workspace/target/extracted/dependencies/ ./
COPY --from=build /workspace/target/extracted/spring-boot-loader/ ./
COPY --from=build /workspace/target/extracted/snapshot-dependencies/ ./
COPY --from=build /workspace/target/extracted/application/ ./
USER 10001:10001
EXPOSE 8080 8081
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-XX:+ExitOnOutOfMemoryError", "org.springframework.boot.loader.launch.JarLauncher"]建置階段的
-DskipTests只是為了讓映像建置快速;測試必須在 CI 的前一個步驟執行並通過(14.2),映像只由通過測試的提交建置。
# .dockerignore(✅ PLT-003 排除不應進入建置內容的檔案)
.git
.github
**/target
**/node_modules
**/*.env
**/*.pem
**/*.key
docs/# ❌ PLT-001 單階段、以 root 執行、包含完整 JDK 與 Maven
# ❌ PLT-002 使用 latest 標籤,每次建置的基底可能不同
# ❌ PLT-003 把整個專案目錄(含 .git 與 .env)複製進映像
FROM maven:latest
COPY . /app
WORKDIR /app
RUN mvn package
ENV DB_PASSWORD=P@ssw0rd123
CMD ["java", "-jar", "target/app.jar"]🔍 13.1 審查與驗證
自動檢查: hadolint Dockerfile(PLT-001、PLT-002);trivy image --scanners vuln,secret,misconfig(PLT-003)。本章的 Dockerfile 已以 hadolint 檢查,digest 為查證當日 Docker Hub 上對應標籤的實際值。
人工審查問題:
- 執行階段的映像是否包含 JDK、Maven、shell 工具等不必要的元件?(
PLT-001) -
USER是否為數字 UID?(Kubernetes 的runAsNonRoot只能驗證數字 UID)(PLT-001) -
.dockerignore是否排除了.git、.env與金鑰檔?(PLT-003)
AI 常見錯誤: AI 產生的 Dockerfile 常使用 openjdk:17 等已停止更新的映像(Docker 官方的 openjdk 映像已於 2022 年棄用),並以 root 執行;Spring Boot 3.3 起分層解壓縮的指令改為 -Djarmode=tools ... extract --layers,舊的 -Djarmode=layertools 已棄用(PLT-001)。
13.2 JVM 的容器設定
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-004 | 必須 | JVM 的堆積記憶體以容器記憶體的比例設定(-XX:MaxRAMPercentage,通常 70–80%),不寫死 -Xmx;容器的記憶體 requests 等於 limits | 👁 設定審查;🧪 壓測時觀察 OOMKilled 次數 |
PLT-005 | 應該 | 設定 CPU requests;是否設定 CPU limits 依叢集政策決定,若設定,必須以壓測確認沒有 CPU 節流(container_cpu_cfs_throttled_periods_total)造成延遲 | 🤖 指標監控 |
# ✅ PLT-004 記憶體 requests = limits,堆積為容器記憶體的 75%(見 Dockerfile 的 MaxRAMPercentage)
# ✅ PLT-005 設定 CPU requests;不設定 CPU limits(叢集政策允許時)
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
memory: 1Gi為什麼不是 100%?JVM 除了堆積之外,還需要中繼空間(Metaspace)、執行緒堆疊、直接記憶體(Netty、NIO)與 JIT 程式碼快取。堆積設為容器記憶體的 100%,容器很快會被 OOMKilled。
# ❌ PLT-004 -Xmx 寫死 2g,但容器 limits 只有 1Gi:JVM 以為還有空間,容器先被 OOMKilled
env:
- name: JAVA_TOOL_OPTIONS
value: "-Xmx2g"
resources:
limits:
memory: 1Gi🔍 13.2 審查與驗證
人工審查問題:
- 堆積上限、容器記憶體上限、實際用量(壓測時的 RSS)三者的關係是否合理?(
PLT-004) - 若設定了 CPU limits,壓測時是否有 CPU 節流?(
PLT-005)
AI 常見錯誤: AI 常同時設定 -Xmx 與 MaxRAMPercentage(-Xmx 優先,比例設定無效),或把 JVM 參數設為與容器限制無關的固定值(PLT-004)。
13.3 工作負載設定
以下是符合本指引的完整 Deployment 範例,整合了高可用(10.2)、健康檢查(10.3)、資源(13.2)與安全設定:
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-006 | 必須 | 容器的 securityContext 符合 Pod Security Standards 的 restricted 等級:runAsNonRoot、allowPrivilegeEscalation: false、移除所有 capabilities、seccompProfile: RuntimeDefault,並建議 readOnlyRootFilesystem: true | 🤖 Pod Security Admission(13.6);🤖 kubeconform |
PLT-007 | 必須 | 優雅關機:preStop 先等待數秒讓負載平衡器移除端點,terminationGracePeriodSeconds 大於 preStop 等待加上應用程式的關機等待時間(PERF-016) | 👁 設定審查;🧪 滾動更新時錯誤率為 0 |
PLT-008 | 必須 | 不需要呼叫 Kubernetes API 的工作負載設定 automountServiceAccountToken: false,並使用專屬的 ServiceAccount | 🤖 政策檢查 |
# order-api 完整 Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: order-api
namespace: order
labels:
app.kubernetes.io/name: order-api
app.kubernetes.io/part-of: online-order
app.kubernetes.io/version: "1.4.2"
cost-center: "CC-1234"
spec:
replicas: 3
revisionHistoryLimit: 5
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
selector:
matchLabels:
app.kubernetes.io/name: order-api
template:
metadata:
labels:
app.kubernetes.io/name: order-api
cost-center: "CC-1234"
spec:
serviceAccountName: order-api
automountServiceAccountToken: false # ✅ PLT-008
terminationGracePeriodSeconds: 45 # ✅ PLT-007 > preStop 10 秒 + 應用程式關機 20 秒
securityContext: # ✅ PLT-006 Pod 層級
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
fsGroup: 10001
seccompProfile:
type: RuntimeDefault
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels:
app.kubernetes.io/name: order-api
containers:
- name: order-api
# 以 digest 部署,確保與通過簽章驗證的映像一致(SEC-017)
image: ghcr.io/example/order-api@sha256:4f8e2b7c1a9d3e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f
ports:
- name: http
containerPort: 8080
- name: management
containerPort: 8081
env:
- name: DEPLOY_ENV
value: production
- name: APP_VERSION
value: "1.4.2"
envFrom:
- secretRef:
name: order-api-secrets # 由 ExternalSecret 產生(SEC-011)
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
memory: 1Gi
securityContext: # ✅ PLT-006 容器層級
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]
volumeMounts:
- name: tmp
mountPath: /tmp # readOnlyRootFilesystem 時,提供可寫入的暫存目錄
lifecycle:
preStop:
sleep:
seconds: 10 # ✅ PLT-007 等待負載平衡器移除端點
startupProbe:
httpGet:
path: /actuator/health/liveness
port: management
periodSeconds: 5
failureThreshold: 30
livenessProbe:
httpGet:
path: /actuator/health/liveness
port: management
periodSeconds: 10
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: management
periodSeconds: 5
volumes:
- name: tmp
emptyDir:
sizeLimit: 256Mi上例的映像 digest 為示意值。
lifecycle.preStop.sleep是 Kubernetes 1.30 起預設啟用(Beta)、1.34 GA 的原生休眠動作,不再需要在映像中保留sleep指令與 shell。
# ❌ PLT-006 以 root 執行並允許權限提升;❌ PLT-007 沒有 preStop,滾動更新時部分請求打到正在關閉的 Pod
securityContext:
privileged: true
runAsUser: 0🔍 13.3 審查與驗證
自動檢查: kubeconform -strict(格式)、Pod Security Admission 的 restricted 等級(安全設定)(PLT-006);准入政策檢查 automountServiceAccountToken(PLT-008)。本節的 Deployment 已以 kubeconform(Kubernetes 1.37.1 schema)驗證。
人工審查問題:
-
readOnlyRootFilesystem: true時,應用程式需要寫入的路徑(/tmp、Tomcat 工作目錄)是否以emptyDir掛載?(PLT-006) -
terminationGracePeriodSeconds是否大於 preStop 等待加上spring.lifecycle.timeout-per-shutdown-phase?(PLT-007) - 映像以標籤還是 digest 部署?(
SEC-017)
AI 常見錯誤: AI 產生的 Deployment 常缺少 securityContext、使用 image: xxx:latest,並以 preStop: exec: command: ["sh", "-c", "sleep 10"] 實作延遲;精簡映像中可能沒有 sh,應改用原生的 sleep 動作(PLT-006、PLT-007)。
13.4 組態與機密管理
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-009 | 必須 | 同一個映像部署到所有環境;環境差異只透過組態(環境變數、ConfigMap、Secret)注入,不為各環境建置不同的映像(12-Factor App 的 Config 原則) | 👁 CI/CD 流程審查:各環境的映像 digest 相同 |
PLT-010 | 應該 | ConfigMap 變更時觸發滾動更新(以內容雜湊命名或加上註解),避免部分 Pod 使用舊設定 | 👁 設定審查 |
# kustomization.yaml(正式環境 overlay)
# ✅ PLT-009 同一個映像 digest;環境差異只在 overlay 的組態
# ✅ PLT-010 configMapGenerator 產生帶內容雜湊的名稱,內容變更時自動觸發滾動更新
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: order
resources:
- ../../base
images:
- name: ghcr.io/example/order-api
digest: sha256:4f8e2b7c1a9d3e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f
configMapGenerator:
- name: order-api-config
literals:
- SPRING_PROFILES_ACTIVE=prod
- SHOP_ORDER_PAYMENT_TIMEOUT=800ms<!-- ❌ PLT-009 為測試與正式環境分別建置映像(application-prod.yml 打包進正式映像),
正式環境執行的程式碼與測試過的不同 -->🔍 13.4 審查與驗證
人工審查問題:
- 測試環境與正式環境部署的映像 digest 是否相同?(
PLT-009) - 修改 ConfigMap 後,Pod 是否會自動重新載入或重啟?(
PLT-010)
AI 常見錯誤: AI 常建議以 Maven profile 為各環境建置不同的 JAR,或把各環境的設定檔打包進映像(PLT-009)。
13.5 GitOps 與環境推進
GitOps:以 Git 版本庫作為叢集期望狀態的唯一來源,由叢集內的控制器(Argo CD、Flux)持續比對並同步。所有變更都經過 PR 審查,叢集狀態可稽核、可回復。
flowchart LR
DEV["開發者"] -- "PR" --> APP["應用程式版本庫"]
APP -- "CI:測試、建置、簽章" --> REG["Container Registry"]
APP -- "CI:更新映像 digest(PR)" --> CFG["部署設定版本庫"]
CFG -- "Argo CD 同步" --> STG["預備環境"]
CFG -- "人工核准 PR 後同步" --> PROD["正式環境"]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-011 | 必須 | 正式環境的部署與設定變更只能透過 GitOps(PR → 審查 → 自動同步)進行;不得以 kubectl apply/edit 直接修改,並啟用偏移偵測與自動修正 | 🤖 Argo CD selfHeal;🤖 叢集稽核日誌告警 |
PLT-012 | 必須 | 環境推進(測試 → 預備 → 正式)推進的是同一個映像 digest;正式環境的推進需要核准 | 👁 推進紀錄審查 |
# ✅ PLT-011 Argo CD Application:自動同步、自動修正偏移、自動刪除版本庫中已移除的資源
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: order-api-prod
namespace: argocd
spec:
project: shop
source:
repoURL: https://git.example.com/shop/deploy-config.git
targetRevision: main
path: order-api/overlays/prod
destination:
server: https://kubernetes.default.svc
namespace: order
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- ServerSideApply=true# ❌ PLT-011 值班人員直接修改正式環境:變更沒有審查紀錄,下一次同步時又被覆蓋或造成偏移
kubectl -n order set image deployment/order-api order-api=ghcr.io/example/order-api:hotfix
kubectl -n order edit configmap order-api-config#!/usr/bin/env bash
# promote.sh — ✅ PLT-012 推進到正式環境的是預備環境驗證過的同一個 digest(以 PR 送出,需核准後合併)
set -euo pipefail
DIGEST=$(yq '.images[] | select(.name == "ghcr.io/example/order-api") | .digest' \
order-api/overlays/staging/kustomization.yaml)
cd order-api/overlays/prod
kustomize edit set image "ghcr.io/example/order-api@${DIGEST}"
git switch -c "promote/order-api-${DIGEST:7:12}"
git commit -am "promote order-api ${DIGEST} to production"
gh pr create --title "Promote order-api to production" --body "Digest: ${DIGEST}(預備環境驗證通過)"🔍 13.5 審查與驗證
自動檢查: Argo CD 的同步狀態為 Synced、健康狀態為 Healthy;叢集稽核日誌中,非 GitOps 控制器的使用者對正式命名空間的寫入操作觸發告警(PLT-011)。
人工審查問題:
- 誰有正式環境的
kubectl寫入權限?緊急修正的流程是什麼?事後是否回寫版本庫?(PLT-011) - 正式環境使用的 digest 是否與預備環境驗證過的相同?(
PLT-012)
AI 常見錯誤: AI 常以 CI 管線中的 kubectl apply 或 helm upgrade 直接部署到正式環境,CI 因此需要正式叢集的管理權限(PLT-011)。
13.6 准入政策與 Pod Security
准入控制(Admission Control)在資源寫入叢集前檢查是否符合政策,是本指引「🤖」類規則在部署端的最後一道防線。
| 機制 | 特性 | 適用 |
|---|---|---|
| Pod Security Admission | Kubernetes 內建,以命名空間標籤套用 privileged/baseline/restricted 三個等級 | 所有叢集的基本安全設定 |
| ValidatingAdmissionPolicy | Kubernetes 內建(1.30 GA),以 CEL 表達式撰寫,只能檢查單一物件 | 標籤、欄位值等單一物件規則 |
| Kyverno/OPA Gatekeeper | 外部政策引擎,可跨物件檢查、修改資源、驗證映像簽章 | 「Deployment 必須有 PDB」、「映像必須有簽章」等進階規則 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-013 | 必須 | 所有應用程式命名空間以 Pod Security Admission 強制 restricted 等級 | 🤖 命名空間標籤檢查 |
PLT-014 | 必須 | 本指引中可在部署端檢查的「必須」規則(成本標籤 NFR-012、副本與分散 RES-006、PDB RES-007、映像簽章 SEC-017)以准入政策強制執行;政策本身納入版本控制並有測試 | 🤖 政策測試(kubectl apply --dry-run=server、kyverno test) |
# ✅ PLT-013 命名空間強制 restricted 等級
apiVersion: v1
kind: Namespace
metadata:
name: order
labels:
pod-security.kubernetes.io/enforce: restricted
pod-security.kubernetes.io/enforce-version: latest
pod-security.kubernetes.io/warn: restricted
gateway-access: public# ✅ PLT-014 / NFR-012 以 ValidatingAdmissionPolicy(CEL)要求工作負載標記成本歸屬
# ✅ PLT-014 / RES-006 正式環境的 Deployment 至少 3 個副本
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: workload-baseline
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["deployments", "statefulsets"]
validations:
- expression: "has(object.metadata.labels) && 'cost-center' in object.metadata.labels"
message: "工作負載必須有 cost-center 標籤(NFR-012)"
- expression: "!(has(object.metadata.labels) && object.metadata.labels['environment'] == 'production') || object.spec.replicas >= 3"
message: "正式環境的工作負載至少需要 3 個副本(RES-006)"
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
name: workload-baseline
spec:
policyName: workload-baseline
validationActions: [Deny]
matchResources:
namespaceSelector:
matchLabels:
pod-security.kubernetes.io/enforce: restricted# ❌ PLT-013 為了讓某個需要 root 的工具能執行,把整個應用命名空間降為 privileged
metadata:
labels:
pod-security.kubernetes.io/enforce: privileged🔍 13.6 審查與驗證
自動檢查: 以 kubectl apply --dry-run=server 送出故意違規的 Deployment(缺少標籤、副本數 1),必須被拒絕(PLT-014);檢查所有應用命名空間的 pod-security.kubernetes.io/enforce 標籤(PLT-013)。
人工審查問題:
- 政策的
failurePolicy是Fail還是Ignore?Ignore時政策服務故障會讓所有資源都通過。(PLT-014) - 有哪些命名空間被排除在政策之外?理由是什麼?(
PLT-013)
AI 常見錯誤: AI 仍常推薦已於 Kubernetes 1.25 移除的 PodSecurityPolicy(policy/v1beta1);替代方案是 Pod Security Admission 與政策引擎(PLT-013)。
13.7 部署設定的自動驗證
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
PLT-015 | 必須 | CI 以 kubeconform(-strict,指定目標 Kubernetes 版本,並載入所使用 CRD 的 schema)驗證所有 Kubernetes 資源;Helm chart 先以 helm template 展開再驗證 | 🤖 CI |
PLT-016 | 應該 | 優先使用雲端代管的資料庫、快取與訊息服務;在 Kubernetes 中自建有狀態服務必須以 ADR 說明備份、升級與容錯移轉的維運能力 | 👁 ADR 審查 |
#!/usr/bin/env bash
# validate-manifests.sh
# ✅ PLT-015 依目標版本嚴格驗證;CRD(Gateway API、Argo CD、External Secrets 等)使用社群維護的 schema 目錄
set -euo pipefail
kustomize build deploy/order-api/overlays/prod > /tmp/rendered.yaml
kubeconform -strict -summary \
-kubernetes-version 1.37.1 \
-schema-location default \
-schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
/tmp/rendered.yaml# ❌ PLT-015 以 -ignore-missing-schemas 略過所有找不到 schema 的資源,CRD 拼錯欄位完全不會被發現
kubeconform -ignore-missing-schemas deploy/<!-- ✅ PLT-016 自建有狀態服務的 ADR 說明維運能力 -->
# ADR-0044 在 Kubernetes 自建 Kafka(Strimzi),不使用雲端代管服務
- 理由:資料不得離開自有機房(法規);目前的雲端供應商在本區域沒有代管 Kafka
- 備份與復原:主題設定由 GitOps 管理;資料以 MirrorMaker 2 複寫到 DR 叢集
- 升級:由平台團隊每季依 Strimzi 版本升級,先在預備叢集演練
- 容錯移轉:3 個 broker 跨 3 個 AZ,min.insync.replicas=2
- 值班:平台團隊 7×24🔍 13.7 審查與驗證
自動檢查: CI 執行 validate-manifests.sh(PLT-015)。本指引所有的 Kubernetes 範例(含 Gateway API、Istio、External Secrets、Argo CD、Chaos Mesh、Envoy Gateway 的 CRD)已以 kubeconform 0.8.0 驗證。
人工審查問題:
- CI 驗證的 Kubernetes 版本是否與叢集版本一致?(
PLT-015) - 在叢集中自建資料庫的 ADR 是否說明了備份、升級與容錯移轉由誰負責?(
PLT-016)
AI 常見錯誤: AI 常產生已在新版 Kubernetes 移除的 API 版本(extensions/v1beta1、policy/v1beta1、autoscaling/v2beta2、batch/v1beta1),只有指定正確版本的 schema 驗證才能抓出來(PLT-015)。
14. 持續整合與交付
架構的許多品質屬性(可修改性、可靠性、安全)最終取決於能否小步、頻繁、安全地交付變更。本章規範交付管線、測試策略、漸進式發布與交付績效的量測。
14.1 交付流程設計
flowchart LR
PR["Pull Request"] --> CI["CI:建置、單元/架構測試、<br/>靜態分析、相依掃描"]
CI --> IT["整合與契約測試<br/>(Testcontainers)"]
IT --> IMG["建置映像、SBOM、<br/>簽章、來源證明"]
IMG --> STG["部署預備環境<br/>(GitOps)"]
STG --> E2E["E2E、效能、<br/>安全掃描"]
E2E --> APPROVE{"核准"}
APPROVE --> CANARY["正式環境<br/>漸進式發布"]
CANARY --> FULL["全量發布"]
CANARY -- "SLO 惡化" --> RB["自動回退"]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
CICD-001 | 必須 | 主幹(main)受分支保護:必須透過 PR 合併、至少一位審查者核准、所有必要檢查通過;不允許直接推送與強制推送 | 🤖 版本庫設定檢查(Rulesets) |
CICD-002 | 應該 | 採用主幹開發(trunk-based development):分支存活時間不超過 2 天,未完成的功能以功能旗標隱藏,而不是以長期分支隔離 | 🤖 分支存活時間統計 |
CICD-003 | 必須 | 交付管線的每個階段都是自動化的品質閘門;閘門失敗時停止推進,不得以手動略過的方式繼續 | 👁 管線設定審查 |
<!-- ✅ CICD-001 版本庫規則(Rulesets)設定 -->
| 設定 | 值 |
| --- | --- |
| 目標分支 | main |
| Require a pull request before merging | ✔,Required approvals:1,Dismiss stale approvals:✔ |
| Require status checks to pass | ✔:build-test、api-contract、manifests |
| Block force pushes | ✔ |
| Restrict deletions | ✔ |
| Bypass list | 無(緊急修正也走 PR) |
<!-- ❌ CICD-003 品質閘門失敗時,以 workflow_dispatch 的「skip-tests」參數略過測試直接部署 --><!-- ✅ CICD-002 團隊工作協議:主幹開發 -->
- 分支從 main 建立,2 天內合併;超過 2 天的分支在每日站會提出
- 未完成的功能以功能旗標(預設關閉)合併到 main,不以長期分支隔離(CICD-011)
- PR 保持小型(建議 400 行以內的變更),方便審查🔍 14.1 審查與驗證
人工審查問題:
- 誰在 Bypass list 中?是否有人可以略過 PR 直接推送到
main?(CICD-001) - 分支平均存活多久?長期分支的合併衝突是否常造成問題?(
CICD-002) - 管線中是否有
continue-on-error: true或可略過檢查的參數?(CICD-003)
AI 常見錯誤: AI 產生的工作流程常在測試步驟加上 continue-on-error: true 讓管線「保持綠色」(CICD-003)。
14.2 CI 管線
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
CICD-004 | 必須 | 每個 PR 執行:編譯、單元測試、架構測試(ArchUnit/Modulith)、整合測試、靜態分析與相依弱點掃描;任一失敗即阻擋合併 | 🤖 必要狀態檢查 |
CICD-005 | 必須 | 工作流程的 permissions 預設唯讀,只在需要的 job 授予額外權限;使用 OIDC 取得雲端短期憑證,不在 Secrets 中保存長期金鑰 | 🤖 actionlint;👁 審查 |
CICD-006 | 應該 | CI 結果可重現:建置工具以 Wrapper 固定版本(mvnw)、相依以 lock 檔或版本管理鎖定、執行環境指定版本(ubuntu-24.04 而非 ubuntu-latest) | 👁 審查 |
# .github/workflows/ci.yml
# ✅ CICD-004 PR 必要檢查;✅ CICD-005 最小權限;✅ CICD-006 固定執行環境與工具版本
name: ci
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
build-test:
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
with:
distribution: temurin
java-version: '25'
cache: maven
- name: 編譯、單元測試、架構測試、整合測試(Testcontainers)
run: ./mvnw -B -ntp verify
- name: 相依弱點掃描(OWASP Dependency-Check)
run: ./mvnw -B -ntp org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=7
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: always()
with:
name: test-reports
path: |
target/surefire-reports/
target/failsafe-reports/
retention-days: 14# ❌ CICD-005 工作流程擁有寫入所有資源的權限,並以長期金鑰登入雲端
permissions: write-all
jobs:
deploy:
runs-on: ubuntu-latest # ❌ CICD-006 執行環境隨時可能升級
steps:
- run: aws configure set aws_secret_access_key ${{ secrets.AWS_SECRET_KEY }}🔍 14.2 審查與驗證
自動檢查: actionlint .github/workflows/*.yml(CICD-005)。本指引的工作流程範例已以 actionlint 1.7.12 檢查通過。
人工審查問題:
- 工作流程是否有
permissions設定?是否有 job 擁有不必要的寫入權限?(CICD-005) - 必要狀態檢查是否包含架構測試與整合測試?(
CICD-004) -
pull_request_target觸發的工作流程是否會簽出並執行 PR 的程式碼?(可能讓外部 PR 取得 Secrets)(CICD-005)
AI 常見錯誤: AI 產生的工作流程常沒有 permissions 區塊(預設權限依組織設定,可能是讀寫),並使用 ubuntu-latest 與標籤引用的 Actions(CICD-005、CICD-006)。
14.3 測試策略
| 層級 | 目的 | 工具 | 數量 | 執行時機 |
|---|---|---|---|---|
| 單元測試 | 領域邏輯與 Use Case 的正確性 | JUnit 5、AssertJ、Mockito | 最多 | 每次提交 |
| 架構測試 | 分層、模組邊界、命名規則 | ArchUnit、Spring Modulith | 少量但涵蓋所有規則 | 每次提交 |
| 整合測試 | 與真實資料庫、訊息代理的整合 | Spring Boot Test、Testcontainers | 中等 | 每次提交 |
| 契約測試 | 服務間介面相容 | Pact、Spring Cloud Contract | 每個介面 | 每次提交 |
| E2E 測試 | 關鍵使用者流程 | Playwright | 少量(只涵蓋最重要的流程) | 部署預備環境後 |
| 效能測試 | 品質情境的效能目標 | k6、Gatling | 每個關鍵情境 | 每日或發布前 |
| 安全測試 | 弱點與錯誤設定 | ZAP、Trivy、授權測試 | 依威脅模型 | 每次發布 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
CICD-007 | 必須 | 整合測試使用與正式環境相同種類與主要版本的資料庫與訊息代理(Testcontainers),不使用記憶體資料庫替代 | 👁 測試設定審查 |
CICD-008 | 應該 | 領域層與應用層的測試覆蓋率作為趨勢指標追蹤(建議行覆蓋率 ≥ 80%),新程式碼的覆蓋率不得低於門檻;覆蓋率不得作為唯一的品質指標 | 🤖 JaCoCo 報告與門檻 |
CICD-009 | 必須 | 測試必須可重複執行且彼此獨立:不依賴執行順序、外部共用環境或真實時間(以 Clock 注入) | 🤖 以隨機順序執行測試;👁 審查 |
package com.example.shop.order.domain;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Instant;
import java.util.List;
import org.junit.jupiter.api.Test;
// ✅ CICD-009 領域測試不依賴 Spring、資料庫或真實時間,可以任意順序重複執行
class OrderTest {
private static final Instant NOW = Instant.parse("2026-10-07T01:30:00Z");
private static final OrderId ID = new OrderId("ORD-20261007-000123");
@Test
void placesOrderInPendingStatus() {
Order order = Order.place(ID, "cust-1", List.of(new OrderLine("A-001", 2)), NOW);
assertThat(order.status()).isEqualTo(OrderStatus.PENDING);
assertThat(order.createdAt()).isEqualTo(NOW);
}
@Test
void rejectsEmptyOrder() {
assertThatThrownBy(() -> Order.place(ID, "cust-1", List.of(), NOW))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void cannotCancelShippedOrder() {
Order order = Order.restore(ID, "cust-1", List.of(new OrderLine("A-001", 1)), OrderStatus.SHIPPED, NOW);
assertThatThrownBy(order::cancel).isInstanceOf(IllegalStateException.class);
}
}package com.example.shop;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.postgresql.PostgreSQLContainer;
// ✅ CICD-007 整合測試使用與正式環境相同主要版本的 PostgreSQL(Testcontainers 2.x)
@TestConfiguration(proxyBeanMethods = false)
public class TestcontainersConfig {
@Bean
@ServiceConnection
PostgreSQLContainer postgres() {
return new PostgreSQLContainer("postgres:18-alpine");
}
}# ❌ CICD-007 以 H2 的 PostgreSQL 相容模式取代真實資料庫:ON CONFLICT、分割表、CONCURRENTLY 都無法正確測試
spring.datasource.url=jdbc:h2:mem:test;MODE=PostgreSQL<!-- pom.xml(節錄):✅ CICD-008 JaCoCo 對領域層與應用層設定 80% 行覆蓋率門檻 -->
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.15</version>
<executions>
<execution>
<id>prepare-agent</id>
<goals><goal>prepare-agent</goal></goals>
</execution>
<execution>
<id>check</id>
<goals><goal>check</goal></goals>
<configuration>
<rules>
<rule>
<element>PACKAGE</element>
<includes>
<include>com.example.shop.*.domain</include>
<include>com.example.shop.*.application</include>
</includes>
<limits>
<limit>
<counter>LINE</counter>
<value>COVEREDRATIO</value>
<minimum>0.80</minimum>
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
</executions>
</plugin>🔍 14.3 審查與驗證
自動檢查: 以 junit.jupiter.testmethod.order.default=org.junit.jupiter.api.MethodOrderer$Random 隨機排序執行測試,找出順序相依(CICD-009);JaCoCo 的 check 目標設定覆蓋率門檻(CICD-008)。本節的單元測試已實際執行通過。
人工審查問題:
- 新增的業務規則是否有對應的測試?測試是否會在規則被破壞時失敗?(
CICD-008) - 測試中是否使用
Instant.now()、LocalDate.now()等真實時間?(CICD-009) - 整合測試的資料庫版本是否與正式環境一致?(
CICD-007)
AI 常見錯誤: AI 產生的測試常以 H2 取代真實資料庫,或為了提高覆蓋率而撰寫沒有任何斷言的測試(CICD-007、CICD-008)。
14.4 漸進式交付與功能旗標
| 策略 | 說明 | 回退速度 | 成本 |
|---|---|---|---|
| 滾動更新 | 逐步替換舊版 Pod | 中(需要再次滾動) | 低 |
| 藍綠部署 | 新舊兩套環境,一次切換流量 | 快(切回舊環境) | 高(雙倍資源) |
| 金絲雀發布 | 先導入少量流量,依指標逐步增加 | 快(流量切回 0) | 中 |
| 功能旗標 | 程式已部署,以旗標控制功能是否啟用 | 最快(關閉旗標) | 需要管理旗標生命週期 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
CICD-010 | 應該 | Tier 1、Tier 2 系統的正式發布採用金絲雀或藍綠部署,並以 SLO 指標自動判斷是否繼續推進或回退 | 🤖 Argo Rollouts 分析結果;🧪 回退演練 |
CICD-011 | 必須 | 每個功能旗標記錄擁有者、建立日期與預計移除日期;功能全量上線後的旗標必須在兩個發布週期內移除 | 🤖 旗標清單到期檢查 |
CICD-012 | 必須 | 每次發布都有回退方案並經過驗證;資料庫結構變更必須相容於前一版應用程式(DATA-012),讓回退不需要還原資料庫 | 👁 發布檢查表 |
# ✅ CICD-010 Argo Rollouts 金絲雀:10% → 30% → 60% → 100%,每一步以錯誤率分析決定是否繼續
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
name: order-api
namespace: order
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: order-api
workloadRef:
apiVersion: apps/v1
kind: Deployment
name: order-api
strategy:
canary:
steps:
- setWeight: 10
- pause: { duration: 10m }
- analysis:
templates:
- templateName: error-rate
- setWeight: 30
- pause: { duration: 10m }
- setWeight: 60
- pause: { duration: 10m }
---
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
name: error-rate
namespace: order
spec:
metrics:
- name: error-rate
interval: 1m
count: 5
failureLimit: 1
successCondition: result[0] < 0.001
provider:
prometheus:
address: http://prometheus.observability:9090
query: |
sum(rate(http_server_requests_seconds_count{application="order-api",status=~"5.."}[2m]))
/
sum(rate(http_server_requests_seconds_count{application="order-api"}[2m]))# ✅ CICD-011 功能旗標清單:擁有者與到期日,由 CI 檢查已到期的旗標
flags:
- key: new-checkout-flow
owner: order-team
created: 2026-09-01
remove-by: 2026-11-30
description: 新版結帳流程,全量上線後移除舊流程程式碼
- key: payment-provider-b
owner: payment-team
created: 2026-08-15
remove-by: 2026-10-31<!-- ❌ CICD-011 程式中有 200 個功能旗標,其中 150 個已全量開啟一年以上,沒有人知道能不能刪 -->
<!-- ❌ CICD-012 新版本的遷移腳本刪除了舊欄位,回退到舊版時應用程式啟動失敗 -->🔍 14.4 審查與驗證
自動檢查: CI 檢查旗標清單中 remove-by 已過期的旗標並建立待辦(CICD-011);以 kubeconform(Argo Rollouts CRD schema)驗證 Rollout 設定(CICD-010)。
人工審查問題:
- 金絲雀階段的分析指標是否與 SLO 一致?流量太少時分析結果是否有意義?(
CICD-010) - 這次發布若需要回退,資料庫是否相容?是否演練過?(
CICD-012)
AI 常見錯誤: AI 設計的金絲雀發布常只設定流量比例而沒有自動分析,等於只是「慢一點的滾動更新」(CICD-010)。
14.5 交付績效指標(DORA)
DORA(DevOps Research and Assessment)以下列指標衡量軟體交付績效。2023 年起以「失敗部署恢復時間」取代原本的「服務恢復時間(MTTR)」,2024 年新增「部署重工率」,並把指標分為「產出量」與「穩定度」兩組;2025 年的報告(State of AI-assisted Software Development)進一步指出 AI 會放大組織既有的優勢與問題,因此交付指標與平台能力更顯重要。
| 指標 | 意義 | 類型 |
|---|---|---|
| 變更前置時間(Change lead time) | 從提交到部署到正式環境的時間 | 產出量 |
| 部署頻率(Deployment frequency) | 部署到正式環境的頻率 | 產出量 |
| 失敗部署恢復時間(Failed deployment recovery time) | 部署造成問題後恢復服務的時間 | 產出量 |
| 變更失敗率(Change fail rate) | 需要立即修補或回退的部署比例 | 穩定度 |
| 部署重工率(Deployment rework rate) | 為修正正式環境問題而進行的非計畫部署比例 | 穩定度 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
CICD-013 | 應該 | 以自動化方式(版本庫、CI/CD、事件系統的資料)量測 DORA 指標並定期檢視趨勢;指標用於改善流程,不用於評比個人或團隊 | 🤖 指標儀表板 |
-- ✅ CICD-013 由部署紀錄自動計算近 30 天的變更失敗率與部署頻率(PostgreSQL)
SELECT
service,
count(*) AS deployments,
round(count(*) / 30.0, 2) AS deployments_per_day,
round(100.0 * count(*) FILTER (WHERE caused_incident) / count(*), 1) AS change_fail_rate_pct
FROM delivery.deployment
WHERE environment = 'production'
AND deployed_at >= now() - INTERVAL '30 days'
GROUP BY service
ORDER BY service;<!-- ❌ CICD-013 以「每人每月部署次數」排名工程師:鼓勵拆碎提交與灌水,指標失去意義 -->🔍 14.5 審查與驗證
人工審查問題:
- DORA 指標的資料來源是否自動化?是否有人工填報造成的偏差?(
CICD-013) - 指標惡化時,團隊是否有對應的改善行動?(
CICD-013)
AI 常見錯誤: AI 仍常列出 2023 年以前的「四大指標」並使用 MTTR 的定義(CICD-013)。
15. 微服務治理
服務數量增加後,問題會從「單一服務怎麼寫」轉移到「眾多服務怎麼一起運作」:服務如何找到彼此、設定如何管理、排程工作如何不重複執行、事件主題由誰負責、開發團隊如何不必重複打造相同的基礎設施。v1.x 第 12 章以 Consul、Spring Cloud Config 與自行實作的 Redis 分散式鎖為主;v2.0 改以 Kubernetes 原生能力為預設,並修正分散式鎖的正確性問題。
15.1 服務發現
在 Kubernetes 中,Service 與叢集 DNS 已經提供服務發現與負載平衡:呼叫端只需要使用 http://order-api.order:8080,不需要額外的註冊中心。
| 環境 | 建議的服務發現 | 說明 |
|---|---|---|
| 全部在 Kubernetes | Kubernetes Service+DNS(需要 L7 功能時加上服務網格) | 預設選擇 |
| Kubernetes+虛擬機混合 | Consul(含 Kubernetes 同步)或服務網格的多叢集功能 | 需 ADR |
| 無容器平台 | Consul、Eureka(Spring Cloud Netflix Eureka 仍維護中) | 需 ADR |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
MS-001 | 必須 | 在 Kubernetes 中以 Service 與 DNS 作為服務發現機制;引入 Eureka、Consul 等額外的註冊中心必須以 ADR 說明原生機制為何不足 | 👁 ADR 審查;👁 相依清單 |
MS-002 | 不應該 | 在 Kubernetes 中再使用用戶端負載平衡(Spring Cloud LoadBalancer 搭配註冊中心);Service 或服務網格已提供負載平衡 | 👁 相依清單審查 |
# application.yml(呼叫端)
# ✅ MS-001 直接使用 Kubernetes Service 的 DNS 名稱,不需要註冊中心
spring:
http:
serviceclient:
inventory:
base-url: http://inventory-api.inventory.svc.cluster.local:8080
read-timeout: 1s# ❌ MS-001 / MS-002 在 Kubernetes 中額外部署 Eureka,服務啟動時註冊自己的 Pod IP;
# Pod 重新排程後,Eureka 的快取在數十秒內仍指向已不存在的 IP
eureka:
client:
service-url:
defaultZone: http://eureka:8761/eureka/🔍 15.1 審查與驗證
人工審查問題:
- 系統是否全部部署在 Kubernetes?若是,為什麼需要額外的註冊中心?(
MS-001) - 相依清單中是否有
spring-cloud-starter-netflix-eureka-client、spring-cloud-starter-consul-discovery或spring-cloud-starter-loadbalancer?(MS-001、MS-002)
AI 常見錯誤: AI 產生的「微服務架構」幾乎都包含 Eureka 或 Consul 加上 Spring Cloud Gateway 與 Config Server,即使目標平台是 Kubernetes(MS-001)。
15.2 組態管理
| 方案 | 優點 | 缺點 | 適用 |
|---|---|---|---|
| ConfigMap/Secret+GitOps | 平台原生、與部署一起版本控制與審查 | 動態重新載入需要額外處理 | Kubernetes 上的預設選擇 |
| Spring Cloud Config Server(Git 後端) | 集中管理多個服務的設定、支援動態重新整理 | 多一個需要高可用的元件 | 非 Kubernetes 環境,或已大量使用的既有系統 |
| 外部設定服務(Consul KV、雲端參數服務) | 動態、集中 | 供應商相依 | 依平台而定 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
MS-003 | 必須 | 組態以版本控制管理,每一次變更都可以追溯到審查過的 PR;機密與一般組態分開管理(SEC-011) | 👁 GitOps 版本庫審查 |
MS-004 | 應該 | 只有可以安全地在執行中改變的設定(功能旗標、日誌等級、限流門檻)才允許動態重新載入;連線池、執行緒池等結構性設定透過滾動更新套用 | 👁 設計審查 |
# ✅ MS-003 組態與部署設定放在同一個 GitOps 版本庫,變更經 PR 審查(kustomize overlay)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: order
resources:
- ../../base
configMapGenerator:
- name: order-api-config
behavior: merge
literals:
- LOGGING_LEVEL_COM_EXAMPLE_SHOP=INFO
- SHOP_ORDER_MAX_LINES=100<!-- ❌ MS-003 正式環境的設定直接在 Config Server 的管理介面修改,沒有版本紀錄,出問題後不知道誰改了什麼 -->
<!-- ❌ MS-004 以 @RefreshScope 動態改變資料庫連線池大小,重新整理時連線池被重建,處理中的交易失敗 -->🔍 15.2 審查與驗證
人工審查問題:
- 正式環境的設定變更是否都有 PR 紀錄?(
MS-003) - 哪些設定可以動態重新載入?重新載入時會不會重建有狀態的元件?(
MS-004)
AI 常見錯誤: AI 常把 Spring Cloud Config 的 bootstrap.yml 設定方式套用在新專案;Spring Boot 2.4 起改以 spring.config.import=configserver: 匯入,bootstrap.yml 需要額外的相依才會生效(MS-003)。
15.3 排程工作與分散式鎖
服務有多個副本時,@Scheduled 工作會在每一個副本上執行。常見的解法是分散式鎖,但分散式鎖有一個容易被忽略的問題:持有鎖的程序可能因為 GC 停頓或網路延遲,在鎖已經過期、被別人取得之後,才繼續執行並寫入資料。因此:
- 用於「避免重複工作」(效率)的鎖:偶爾重複執行可以接受,使用 ShedLock 或 Kubernetes CronJob 即可。
- 用於「保證正確性」的鎖(例如不能重複扣款):鎖本身不足以保證,必須由資料層提供保證:唯一限制、樂觀鎖,或防護權杖(fencing token)。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
MS-005 | 必須 | 多副本服務中的排程工作必須確保同一時間只有一個執行個體:使用 ShedLock(或同等機制)或改為 Kubernetes CronJob(concurrencyPolicy: Forbid) | 🧪 多副本測試;👁 程式碼審查 |
MS-006 | 必須 | 排程工作必須冪等,重複執行不會產生錯誤結果 | 🧪 測試:連續執行兩次結果相同 |
MS-007 | 必須 | 不得以分散式鎖(Redis、資料庫鎖)作為資料正確性的唯一保證;正確性必須由資料層的唯一限制、樂觀鎖或防護權杖保證 | 👁 設計審查 |
package com.example.shop.order.adapter.scheduling;
import com.example.shop.order.application.ExpireUnpaidOrders;
import net.javacrumbs.shedlock.spring.annotation.SchedulerLock;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
// ✅ MS-005 以 ShedLock 確保多副本中同一時間只有一個執行個體
// ✅ MS-006 工作本身冪等:只處理「仍為待付款且已逾期」的訂單,重複執行不會重複取消
@Component
class ExpireUnpaidOrdersJob {
private final ExpireUnpaidOrders expireUnpaidOrders;
ExpireUnpaidOrdersJob(ExpireUnpaidOrders expireUnpaidOrders) {
this.expireUnpaidOrders = expireUnpaidOrders;
}
@Scheduled(cron = "0 */5 * * * *", zone = "Asia/Taipei")
@SchedulerLock(name = "expireUnpaidOrders", lockAtMostFor = "PT10M", lockAtLeastFor = "PT30S")
void run() {
expireUnpaidOrders.execute();
}
}package com.example.shop.config;
import javax.sql.DataSource;
import net.javacrumbs.shedlock.core.LockProvider;
import net.javacrumbs.shedlock.provider.jdbctemplate.JdbcTemplateLockProvider;
import net.javacrumbs.shedlock.spring.annotation.EnableSchedulerLock;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.scheduling.annotation.EnableScheduling;
// ✅ MS-005 鎖存放在既有的資料庫,以資料庫時間判斷鎖是否過期,避免各副本時鐘不一致
@Configuration(proxyBeanMethods = false)
@EnableScheduling
@EnableSchedulerLock(defaultLockAtMostFor = "PT10M")
class SchedulingConfig {
@Bean
LockProvider lockProvider(DataSource dataSource) {
return new JdbcTemplateLockProvider(JdbcTemplateLockProvider.Configuration.builder()
.withJdbcTemplate(new JdbcTemplate(dataSource))
.usingDbTime()
.build());
}
}-- ShedLock 的鎖資料表(以 Flyway 建立)
CREATE TABLE shedlock (
name VARCHAR(64) NOT NULL PRIMARY KEY,
lock_until TIMESTAMP NOT NULL,
locked_at TIMESTAMP NOT NULL,
locked_by VARCHAR(255) NOT NULL
);
-- ✅ MS-007 防護權杖:每次取得鎖時遞增權杖,寫入時只接受比目前更新的權杖;
-- 鎖過期後才醒來的舊持有者帶著舊權杖寫入,更新 0 筆而被拒絕
CREATE TABLE inventory_snapshot (
sku VARCHAR(20) NOT NULL PRIMARY KEY,
quantity INTEGER NOT NULL,
fencing_token BIGINT NOT NULL
);
INSERT INTO inventory_snapshot (sku, quantity, fencing_token) VALUES ('A-001', 10, 41);
UPDATE inventory_snapshot
SET quantity = 8, fencing_token = 42
WHERE sku = 'A-001'
AND fencing_token < 42;# ✅ MS-005 另一種做法:把排程工作改為 Kubernetes CronJob,禁止同時執行
apiVersion: batch/v1
kind: CronJob
metadata:
name: monthly-settlement
namespace: order
spec:
schedule: "0 2 1 * *"
timeZone: Asia/Taipei
concurrencyPolicy: Forbid
startingDeadlineSeconds: 3600
jobTemplate:
spec:
backoffLimit: 2
template:
spec:
restartPolicy: Never
securityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
containers:
- name: settlement
image: ghcr.io/example/order-batch@sha256:9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b
args: ["--job=monthly-settlement"]
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop: ["ALL"]// ❌ MS-007 以 Redis SETNX 取得鎖後扣款:GC 停頓超過鎖的 TTL 時,另一個副本也取得鎖,造成重複扣款(片段)
if (redis.opsForValue().setIfAbsent("lock:pay:" + orderId, nodeId, Duration.ofSeconds(10))) {
paymentGateway.capture(orderId); // 若在這裡停頓 15 秒,鎖已被別人取得
redis.delete("lock:pay:" + orderId); // 還會刪掉別人的鎖
}(片段:違規示意,未編譯)
🔍 15.3 審查與驗證
自動檢查: 整合測試同時啟動兩個應用程式內容(或兩個執行緒)觸發同一個排程工作,斷言只有一個執行(MS-005)。本節的 SQL 範例已在 PostgreSQL 18 實際執行,第二次以舊權杖更新時影響 0 筆。
人工審查問題:
- 這個鎖是為了效率還是正確性?若是正確性,資料層的保證是什麼?(
MS-007) -
lockAtMostFor是否大於工作的最長執行時間?否則工作還沒結束鎖就過期了。(MS-005) - 工作在中途失敗後重新執行,會不會重複處理已完成的部分?(
MS-006)
AI 常見錯誤: AI 產生的分散式鎖常以 SETNX 加上固定 TTL 實作,釋放鎖時不檢查擁有者(直接 DEL),並宣稱這樣可以「保證不會重複執行」(MS-007)。
15.4 事件與主題治理
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
MS-008 | 必須 | 每個事件主題有唯一的擁有服務(只有擁有者可以發布),並在主題登錄檔記錄:命名、擁有者、事件 schema、分割鍵、保留期限、消費者清單 | 🤖 主題登錄檔檢查;🤖 Kafka ACL |
MS-009 | 應該 | 主題命名採 <領域>.<事件類別> 的格式(例如 order.events),死信主題加上 .DLT 後綴;消費者群組以消費服務的名稱命名 | 🤖 命名規則檢查 |
# topics/order.events.yaml — 主題登錄檔(由平台以 GitOps 建立主題與 ACL)
# ✅ MS-008 擁有者、schema、分割鍵、保留期限、消費者都有記錄;✅ MS-009 命名規則
topic: order.events
owner: order-service
partitions: 12
partition-key: orderId # 同一筆訂單的事件保持順序
retention: 7d
schema:
format: json-schema
subject: order.events-value
compatibility: BACKWARD # INT-020
event-types:
- com.example.shop.order.placed.v1
- com.example.shop.order.cancelled.v1
consumers:
- group: shipping # 消費者群組以服務名稱命名
dead-letter-topic: order.events.shipping.DLT
- group: notification
dead-letter-topic: order.events.notification.DLT
acl:
write: [order-service]
read: [shipping, notification]<!-- ❌ MS-008 多個服務都向 common-events 主題發布各種事件,沒有人知道誰是擁有者、事件格式由誰維護 -->🔍 15.4 審查與驗證
自動檢查: CI 檢查主題登錄檔的必要欄位與命名規則;Kafka ACL 由登錄檔產生,非擁有者發布時被拒絕(MS-008、MS-009)。
人工審查問題:
- 分割鍵是否能保證需要順序的事件落在同一個分割區?(
MS-008) - 保留期限是否足夠讓消費者在故障恢復後重播?(
MS-008)
AI 常見錯誤: AI 常讓所有事件共用一個主題,或在每個服務自行以 KafkaAdmin 建立主題,主題的設定因此散落各處(MS-008)。
15.5 平台工程與黃金路徑
服務數量增加後,每個團隊重複處理 CI/CD、監控、安全設定會造成大量浪費與不一致。平台工程(Platform Engineering)由平台團隊提供內部開發者平台(IDP)與黃金路徑(Golden Path):一套預先整合好本指引規則的範本與自助服務,讓「做對的事」成為最省力的選擇。
| 黃金路徑的內容 | 對應本指引 |
|---|---|
| 專案範本:分層結構、架構測試、ProblemDetail、結構化日誌、OTel、健康檢查 | 第 5、7、10、12 章 |
| CI 範本:測試、掃描、SBOM、簽章 | 第 11、14 章 |
| 部署範本:Deployment、PDB、NetworkPolicy、HPA、ExternalSecret | 第 10、11、13 章 |
| 服務目錄登錄、儀表板、告警範本 | 第 3、12 章 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
MS-010 | 應該 | 平台團隊以範本(例如 Backstage Software Templates)提供符合本指引的新服務骨架;新服務優先從範本建立 | 👁 平台審查 |
MS-011 | 必須 | 黃金路徑範本本身必須通過本指引的所有自動化檢查(架構測試、kubeconform、actionlint、promtool),並隨指引版本更新 | 🤖 範本版本庫的 CI |
# ✅ MS-010 Backstage Software Template:建立符合指引的新服務(節錄)
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: spring-boot-service
title: Spring Boot 4 服務(企業標準)
description: 含分層架構、架構測試、OTel、結構化日誌、健康檢查、Kubernetes 部署範本
spec:
owner: group:platform-team
type: service
parameters:
- title: 服務資訊
required: [name, owner]
properties:
name:
type: string
pattern: '^[a-z][a-z0-9-]{2,30}$'
owner:
type: string
ui:field: OwnerPicker
steps:
- id: fetch
name: 產生專案
action: fetch:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
owner: ${{ parameters.owner }}
- id: publish
name: 建立版本庫
action: publish:github
input:
repoUrl: github.com?owner=example&repo=${{ parameters.name }}
defaultBranch: main
- id: register
name: 登錄服務目錄
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: /catalog-info.yaml使用 GitLab 或其他版本庫平台時,把
publish:github換成對應的發布動作(例如publish:gitlab)。
<!-- ❌ MS-011 黃金路徑範本兩年沒有更新,仍使用 Spring Boot 2.7 與已移除的 Kubernetes API,
新服務一建立就違反指引 -->🔍 15.5 審查與驗證
自動檢查: 範本版本庫的 CI 每週以範本產生一個服務,並執行完整的建置、測試與部署設定驗證(MS-011)。
人工審查問題:
- 新服務有多少比例是從範本建立的?沒有使用範本的原因是什麼?(
MS-010) - 範本的相依版本與本指引 0.2 的基準版本是否一致?(
MS-011)
AI 常見錯誤: AI 產生的專案骨架往往缺少架構測試、可觀測性與安全設定,只有能執行的最小程式碼;以範本為基礎請 AI 修改,比讓 AI 從零產生更可靠(MS-010)。
16. AI 輔助架構設計與審查
生成式 AI 能快速產生架構草稿、ADR、設定檔與程式碼,但它的知識有截止日期、會自信地寫出不存在的設定鍵,也傾向給出「標準答案」而不是適合本系統的答案。本章說明如何讓 AI 依本指引產出,以及人如何審查與驗證 AI 的產出。
16.1 AI 在架構工作中的定位
| 工作 | AI 擅長 | AI 不擅長(必須由人負責) |
|---|---|---|
| 需求與品質屬性 | 把口語需求整理成六段式品質情境的草稿 | 判斷業務優先順序、可接受的風險 |
| 架構選型 | 列出選項與一般性的優缺點 | 評估團隊能力、組織限制、總持有成本 |
| ADR | 依 MADR 格式撰寫草稿 | 做出決策、為決策負責 |
| 設定與程式碼 | 產生大量樣板設定 | 確認版本、設定鍵、API 是否真實存在且適用 |
| 審查 | 依檢核表逐項比對、找出明顯遺漏 | 判斷取捨是否合理、發現需求本身的問題 |
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
AI-001 | 必須 | AI 的產出一律視為草稿;架構決策由具名的人做出並負責(ADR 的 decision-makers 必須是人) | 👁 ADR 審查 |
AI-002 | 必須 | AI 產生的設定、程式碼與文件,必須通過與人工產出相同的所有自動化檢查與審查,不得因為「AI 產生的」而降低或提高標準 | 🤖 CI 必要檢查 |
<!-- ✅ AI-001 ADR 的決策者是人;AI 的角色記錄在「更多資訊」 -->
---
status: accepted
date: 2026-10-07
decision-makers: 架構師 王大明
---
...
## More Information
本 ADR 的選項比較由 AI 產生初稿,經架構師逐項查證並修改評估分數。
<!-- ❌ AI-001 decision-makers: ChatGPT / Claude(AI 不能為決策負責) -->🔍 16.1 審查與驗證
人工審查問題:
- ADR 的決策者是否為具名的人?決策者是否能說明每個選項被排除的理由?(
AI-001) - AI 產生的變更是否跑過完整的 CI?是否有人以「只是設定檔」為由略過審查?(
AI-002)
16.2 讓 AI 依指引產出:提示與專案指示檔
AI 產出的品質取決於它拿到的上下文。架構工作的提示至少要提供:品質情境、限制條件、技術基準版本,以及要遵守的規則編號。
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
AI-003 | 必須 | 要求 AI 產生架構設計時,提示必須包含:品質情境(第 2 章)、限制條件、技術基準版本(0.2)與適用的規則編號;並要求 AI 在產出中標註依據的規則編號 | 👁 PR 附上提示或對話紀錄 |
AI-004 | 應該 | 專案版本庫維護 AI 指示檔(例如 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md),把本指引的關鍵規則與專案的技術基準寫入,讓所有 AI 工具一致遵守 | 👁 版本庫審查 |
<!-- ✅ AI-003 架構設計的提示範本 -->
# 任務
為「線上訂單系統」設計付款模組的整合方式,並以 MADR 4.0 格式產出 ADR 草稿。
# 品質情境(必須滿足)
- QS-01:尖峰 500 TPS 時,下單 p99 ≤ 800 ms
- QS-02:金流閘道連續逾時時,10 秒內熔斷,其他 API 不受影響
# 限制條件
- 團隊 6 人、模組化單體(ADR-0012)、Kubernetes 1.37、Spring Boot 4.1、Java 25
- 金流閘道合約:同時最多 20 筆請求、單筆逾時 3 秒
# 必須遵守的規則
INT-001、INT-002(逾時預算)、RES-001~RES-004(熔斷、重試、隔艙、降級)、
INT-014(冪等鍵)、BE-012(交易內不得呼叫遠端)
# 產出要求
1. 至少比較兩個方案,列出各自的取捨
2. 每個設計決策標註依據的規則編號
3. 列出你使用的每一個設定鍵與版本號,並註明「需人工查證」
4. 計算逾時預算:重試次數 × 逾時 + 退避是否小於上游逾時<!-- AGENTS.md(✅ AI-004 專案層級的 AI 指示檔,節錄) -->
# 專案架構規則(依企業架構設計指引 v2.0)
## 技術基準
- Java 25、Spring Boot 4.1.x、Spring Framework 7、Spring Modulith 2.1、Kubernetes 1.37
- HTTP 用戶端設定使用 `spring.http.clients.*` 與 `spring.http.serviceclient.*`(不要用 Boot 3 的 `spring.http.client.*`)
- OpenTelemetry 設定使用 `management.opentelemetry.*`(不要用 `management.otlp.tracing.*`)
## 必須遵守
- 套件結構:`com.example.shop.<模組>.{domain,application,adapter}`;domain 不得依賴 Spring(BE-001、BE-002)
- 錯誤回應一律 ProblemDetail(API-012);不要產生 `ApiResponse<T>` 包裝
- 遠端呼叫必須有逾時與熔斷(INT-001、RES-001);交易內不得呼叫遠端(BE-012)
- 事件發布使用 Spring Modulith 的 Event Publication Registry(INT-012),不要在 @Transactional 中直接呼叫 KafkaTemplate
- Kubernetes:liveness 只檢查 `/actuator/health/liveness`(RES-010);securityContext 符合 restricted(PLT-006)
- GitHub Actions 以 commit SHA 釘選(SEC-018)
## 完成前必須執行
- `./mvnw verify`(含 ArchUnit 與 Modulith 測試)
- `kubeconform -strict -kubernetes-version 1.37.1 deploy/`
- `actionlint`🔍 16.2 審查與驗證
人工審查問題:
- 提示中是否提供了品質情境與限制條件?若沒有,AI 只能給出通用答案。(
AI-003) - AI 指示檔中的技術基準是否與 0.2 一致,並隨指引更新?(
AI-004)
16.3 審查 AI 產出的五個步驟
flowchart LR
S1["1. 追溯<br/>每個設計是否對應<br/>品質情境與規則?"] --> S2["2. 查證<br/>版本、設定鍵、API<br/>是否真實存在?"]
S2 --> S3["3. 自動檢查<br/>編譯、測試、lint、<br/>schema 驗證"]
S3 --> S4["4. 規則比對<br/>逐節使用<br/>「🔍 審查與驗證」"]
S4 --> S5["5. 重算<br/>可用性、逾時預算、<br/>容量、成本"]| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
AI-005 | 必須 | AI 產出中出現的每一個版本號、設定鍵、API、CLI 參數與標準條號,都必須以官方文件、工具或原始碼查證;無法查證的項目不得進入正式文件 | 🤖 設定鍵比對(Boot 設定中繼資料、schema 驗證);👁 查證紀錄 |
AI-006 | 必須 | AI 產出中的數字(可用性、逾時預算、容量、評估矩陣總分、成本)必須由人重新計算 | 👁 審查紀錄 |
以腳本執行步驟 3 的自動檢查(AI-002、AI-005):
#!/usr/bin/env bash
# verify-ai-output.sh — 對 AI 產出的變更執行與人工產出相同的檢查
# ✅ AI-002 不因 AI 產生而略過任何檢查;✅ AI-005 以工具查證設定與 schema
set -euo pipefail
echo "== 1. 編譯、單元測試、架構測試(ArchUnit、Modulith)"
./mvnw -B -ntp verify
echo "== 2. Kubernetes 資源(含 CRD)"
kubeconform -strict -summary -kubernetes-version 1.37.1 \
-schema-location default \
-schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
deploy/
echo "== 3. GitHub Actions"
actionlint
echo "== 4. Prometheus 規則"
promtool check rules prometheus/rules/*.yaml
echo "== 5. OpenAPI 規格"
npx --yes @redocly/cli@2 lint openapi/*.yaml
echo "== 6. Dockerfile"
hadolint DockerfileSpring Boot 設定鍵的查證(AI-005):在專案中加入 spring-boot-properties-migrator(僅在驗證時),啟動時會列出已改名或已移除的屬性;不存在的屬性則可以由 IDE 的設定中繼資料檢查標示出來。
<!-- ✅ AI-005 暫時加入屬性遷移工具,啟動時報告 AI 使用的舊屬性(驗證完成後移除) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-properties-migrator</artifactId>
<scope>runtime</scope>
</dependency><!-- ✅ AI-006 重算 AI 宣稱的可用性 -->
AI 宣稱:「本架構可用性 99.99%」
關鍵路徑:Gateway 99.95% × 訂單服務 99.9% × 資料庫 99.95% × 金流 99.9%
重算結果:99.70%(見 2.4)→ AI 的宣稱錯誤,需要降級設計或調整 SLO🔍 16.3 審查與驗證
人工審查問題:
- AI 產出中的每個版本號是否查證過?是否比 0.2 的基準舊?(
AI-005) - AI 產出的設定鍵是否存在於目標版本?(以 IDE 或 properties-migrator 檢查)(
AI-005) - 所有數字是否重新計算過?(
AI-006)
16.4 AI 常見錯誤速查表
以下彙整各章「AI 常見錯誤」中最常出現、影響最大的項目,供審查時快速比對:
| 類別 | AI 常見錯誤 | 正確做法 | 規則 |
|---|---|---|---|
| 架構風格 | 不論規模都推薦微服務+Kafka+Redis+Service Mesh | 依決策流程選擇,預設模組化單體 | STY-002、GOV-002 |
| 架構風格 | 所有服務共用一個資料庫 | 每個服務擁有自己的 schema | STY-011 |
| 版本 | 推薦已 EOL 的版本或停止維護的元件(Hystrix、Ribbon、Sleuth) | 依技術雷達與 0.2 基準 | GOV-004、OBS-003 |
| 設定鍵 | 使用 Boot 3 的 spring.http.client.*、management.otlp.tracing.* | Boot 4 的 spring.http.clients.*、management.opentelemetry.* | INT-001、OBS-001 |
| API | ApiResponse<T> 包裝並一律回 200 | RFC 9457 ProblemDetail、正確狀態碼 | API-009、API-012 |
| API | 沒有物件層級授權 | 每次以 ID 存取都檢查擁有權 | SEC-008 |
| 整合 | 在 @Transactional 中直接 kafkaTemplate.send() | Transactional Outbox/Modulith 事件 | INT-012 |
| 整合 | 消費者沒有冪等處理 | 以事件 ID 去重 | INT-013 |
| 韌性 | 沒有逾時;重試所有例外;重試非冪等操作 | 逾時預算、只重試暫時性錯誤與冪等操作 | INT-001、RES-002 |
| 健康檢查 | liveness 檢查資料庫 | liveness 只看應用程式本身 | RES-010 |
| 前端 | JWT 存在 localStorage | BFF 保管權杖、HttpOnly Cookie | FE-003 |
| 資料 | 以 ddl-auto=update 管理結構、修改已套用的遷移腳本 | Flyway 版本化遷移、Expand–Contract | DATA-011、DATA-012 |
| 分散式鎖 | SETNX 保證正確性 | 資料層的防護權杖或唯一限制 | MS-007 |
| Kubernetes | 舊 API 版本、沒有 securityContext、latest 標籤 | 1.37 API、restricted、digest | PLT-006、PLT-015 |
| CI/CD | Actions 以標籤引用、沒有 permissions | commit SHA 釘選、最小權限 | SEC-018、CICD-005 |
| 數字 | 可用性、停機時間、燃燒率、評估矩陣算錯 | 人工重算 | AI-006 |
16.5 AI 使用的資料治理
| 編號 | 等級 | 規則 | 驗證方式 |
|---|---|---|---|
AI-007 | 必須 | 不得把機密、個人資料、客戶資料與未公開的安全弱點資訊輸入未經企業核准的 AI 工具;核准的工具也必須遵守資料分級(8.6) | 👁 資安稽核;🤖 DLP 工具 |
AI-008 | 應該 | PR 描述註明 AI 協助的範圍(例如「設定檔由 AI 產生初稿,已逐項查證」),讓審查者調整審查重點 | 👁 PR 審查 |
<!-- ✅ AI-008 PR 描述 -->
## AI 使用說明
- `deploy/order-api/*.yaml` 由 AI 產生初稿,已以 kubeconform 1.37.1 驗證並人工比對 PLT-006
- 熔斷參數由人依 QS-02 計算,未使用 AI 建議值
<!-- ❌ AI-007 把含有客戶姓名與電話的正式環境錯誤日誌整段貼到公開的 AI 聊天服務請它除錯 -->🔍 16.5 審查與驗證
人工審查問題:
- 提供給 AI 的上下文中是否有機密、個資或客戶資料?(
AI-007) - PR 是否說明 AI 協助的範圍?審查重點是否因此調整(例如加強設定鍵查證)?(
AI-008)
附錄 A 規則總表
本附錄由各章的規則表自動彙整,共 266 條規則,可作為架構審查與 AI 產出審查的檢核清單。
A.1 依領域統計
| 前綴 | 領域 | 章 | 規則數 | 必須 | 應該 | 可以 | 不應該 |
|---|---|---|---|---|---|---|---|
GOV | 架構治理 | 1 | 18 | 11 | 7 | 0 | 0 |
NFR | 品質屬性與非功能需求 | 2 | 13 | 8 | 5 | 0 | 0 |
STY | 架構風格與拆分 | 3 | 16 | 8 | 7 | 0 | 1 |
INT | 整合與通訊 | 4 | 22 | 12 | 9 | 0 | 1 |
API | API 設計 | 5 | 27 | 18 | 8 | 1 | 0 |
FE | 前端架構 | 6 | 13 | 8 | 5 | 0 | 0 |
BE | 後端分層架構 | 7 | 13 | 9 | 3 | 0 | 1 |
DATA | 資料架構 | 8 | 20 | 14 | 6 | 0 | 0 |
PERF | 效能與擴展性 | 9 | 21 | 15 | 5 | 0 | 1 |
RES | 韌性與災難復原 | 10 | 22 | 18 | 4 | 0 | 0 |
SEC | 安全架構 | 11 | 20 | 19 | 1 | 0 | 0 |
OBS | 可觀測性 | 12 | 13 | 11 | 2 | 0 | 0 |
PLT | 容器與部署平台 | 13 | 16 | 13 | 3 | 0 | 0 |
CICD | 持續整合與交付 | 14 | 13 | 8 | 5 | 0 | 0 |
MS | 微服務治理 | 15 | 11 | 7 | 3 | 0 | 1 |
AI | AI 輔助架構設計 | 16 | 8 | 6 | 2 | 0 | 0 |
| 合計 | 266 | 185 | 75 | 1 | 5 |
A.2 驗證方式與範例覆蓋
依各規則表的「驗證方式」欄統計(圖示定義見 0.3)。一條規則可同時有多種驗證方式;「僅人工」表示沒有工具或測試可以替代人工判斷,審查時請特別依照各節「🔍 審查與驗證」的問題確認。
| 前綴 | 規則數 | 🤖 工具檢查 | 🧪 測試或演練 | 👁 僅人工 | 有範例 |
|---|---|---|---|---|---|
GOV | 18 | 7 | 0 | 11 | 18 |
NFR | 13 | 3 | 1 | 9 | 13 |
STY | 16 | 4 | 6 | 6 | 16 |
INT | 22 | 8 | 7 | 7 | 22 |
API | 27 | 10 | 14 | 6 | 27 |
FE | 13 | 5 | 2 | 6 | 13 |
BE | 13 | 9 | 1 | 3 | 13 |
DATA | 20 | 6 | 7 | 8 | 20 |
PERF | 21 | 4 | 13 | 7 | 21 |
RES | 22 | 4 | 10 | 8 | 22 |
SEC | 20 | 8 | 8 | 4 | 20 |
OBS | 13 | 7 | 4 | 4 | 13 |
PLT | 16 | 10 | 2 | 4 | 16 |
CICD | 13 | 9 | 1 | 4 | 13 |
MS | 11 | 3 | 2 | 6 | 11 |
AI | 8 | 3 | 0 | 5 | 8 |
| 合計 | 266 | 100 | 78 | 98 | 266 |
「有範例」指規則編號出現在至少一個範例(程式碼區塊)的 ✅/❌ 標記中,由建置腳本自動檢查。
A.3 規則清單
| 編號 | 等級 | 規則 | 所在章節 |
|---|---|---|---|
GOV-001 | 必須 | 每項架構原則都必須附上「如何判斷有沒有做到」的可觀察標準;不接受只有口號的原則 | 1.2 |
GOV-002 | 應該 | 引入複雜機制(分散式交易、分片、CQRS、Service Mesh、多區域部署)前,必須以 ADR 說明當下的需求與更簡單的替代方案為何不足 | 1.2 |
GOV-003 | 必須 | 新專案只能使用技術雷達 Adopt 或 Trial 環的技術;使用 Trial 環技術必須有 ADR | 1.3 |
GOV-004 | 必須 | 不得使用已結束支援(EOL)或在 12 個月內 EOL 而沒有升級計畫的版本 | 1.3 |
GOV-005 | 應該 | 技術選型以加權評估矩陣比較至少兩個方案,評估項目包含團隊能力、社群活躍度、授權、支援期限與總持有成本 | 1.3 |
GOV-006 | 必須 | 符合上述條件的決策必須以 ADR 記錄,存放於系統版本庫的 docs/adr/,以 PR 審查 | 1.4 |
GOV-007 | 必須 | ADR 採用 MADR 4.0 格式,至少包含:狀態、日期、決策者、背景與問題、考慮的選項(至少兩個)、決策結果與後果、確認方式 | 1.4 |
GOV-008 | 必須 | 已接受(accepted)的 ADR 不得修改決策內容;決策改變時新增一份 ADR,並將舊 ADR 狀態改為 superseded by ADR-NNNN | 1.4 |
GOV-009 | 應該 | ADR 的「確認方式」(Confirmation)必須指出可以驗證此決策被落實的方法,例如 ArchUnit 測試、CI 檢查或指標 | 1.4 |
GOV-010 | 必須 | 每個系統必須有依 arc42 結構撰寫的架構文件,至少包含上表「必須」的章節,存放在系統版本庫(docs-as-code) | 1.5 |
GOV-011 | 必須 | 架構文件必須有 C4 Level 1(System Context)與 Level 2(Container)圖;每個容器標示技術與通訊協定 | 1.5 |
GOV-012 | 應該 | 架構圖以文字描述(Mermaid、PlantUML 或 Structurizr DSL)產生並納入版本控制,不使用無法比對差異的二進位圖檔 | 1.5 |
GOV-013 | 應該 | 每張圖都要有標題、圖例,以及每條連線的說明(做什麼、用什麼協定、同步或非同步) | 1.5 |
GOV-014 | 必須 | 設計審查與上線審查必須留下書面紀錄,包含審查人、結論、風險清單與待辦事項的負責人與期限 | 1.6 |
GOV-015 | 必須 | 上線審查必須以證據判斷品質目標是否達成(壓測報告、故障演練紀錄、弱點掃描報告),不接受「預期可以達成」 | 1.6 |
GOV-016 | 應該 | 審查發現的風險以「風險、影響的品質屬性、可能性、衝擊、緩解措施」記錄於 arc42 第 11 章 | 1.6 |
GOV-017 | 必須 | 本指引中標示 🤖 的「必須」規則,必須在 CI 中以適應度函數自動檢查,檢查失敗時阻擋合併 | 1.7 |
GOV-018 | 應該 | 每個 ADR 的「確認方式」若可自動化,必須實作為適應度函數,並在測試名稱或註解中引用 ADR 編號 | 1.7 |
NFR-001 | 必須 | 每項品質需求都要寫成六段式品質屬性情境,回應量測必須是可量測的數字與條件 | 2.2 |
NFR-002 | 必須 | 回應時間以百分位數(p95、p99)表示,並註明負載條件;不得只用平均值 | 2.2 |
NFR-003 | 必須 | 系統的品質目標必須排序,前 3–5 項寫入 arc42 第 1 章,作為架構取捨的依據 | 2.2 |
NFR-004 | 必須 | 法規與合規要求(個人資料保護法、資通安全管理法、產業規範)必須列為品質需求,並指出對應的控制措施 | 2.2 |
NFR-005 | 應該 | 以效用樹標示每個品質情境的業務重要性與實作難度,(H, H)的情境必須有對應的 ADR 與驗證計畫 | 2.3 |
NFR-006 | 必須 | 每個品質情境必須能追溯到「架構決策」與「驗證方式」(測試、壓測、演練或監控指標);沒有驗證方式的情境視為未完成 | 2.3 |
NFR-007 | 必須 | 對外提供的服務必須定義 SLI 與 SLO;SLI 以「好事件 ÷ 全部事件」計算,SLO 不得為 100% | 2.4 |
NFR-008 | 必須 | SLO 必須考慮關鍵路徑上相依元件的串聯可用性;無法達成時必須設計降級或冗餘,並在 ADR 說明 | 2.4 |
NFR-009 | 應該 | 訂定錯誤預算政策:錯誤預算耗盡時,暫停功能發布,優先處理可靠性問題 | 2.4 |
NFR-010 | 應該 | 對內 SLO 應比對外 SLA 嚴格,保留緩衝 | 2.4 |
NFR-011 | 應該 | 定義單位成本目標(例如每千筆訂單的基礎設施成本),並在架構審查時估算 | 2.5 |
NFR-012 | 必須 | 所有雲端資源與 Kubernetes 工作負載必須標記成本歸屬標籤(系統、環境、成本中心),未標記的資源不得建立 | 2.5 |
NFR-013 | 應該 | 非正式環境在非上班時間自動縮減規模;工作負載的資源請求(requests)依實測用量設定,避免長期閒置 | 2.5 |
STY-001 | 必須 | 架構風格的選擇必須以 ADR 記錄,並說明團隊規模、發布獨立性、品質目標與平台成熟度如何支持這個選擇 | 3.1 |
STY-002 | 應該 | 新系統預設採用模組化單體;只有在上方決策流程的所有問題都答「是」時,才採用微服務 | 3.1 |
STY-003 | 不應該 | 為了「未來可能需要擴展」而在第一版就拆分微服務 | 3.1 |
STY-004 | 必須 | 模組化單體必須以工具驗證模組邊界(Spring Modulith ApplicationModules.verify() 或 ArchUnit),並在 CI 執行 | 3.2 |
STY-005 | 必須 | 模組只能透過其他模組的公開 API(根套件或 @NamedInterface)互動;不得存取其他模組的內部套件或直接存取其他模組的資料表 | 3.2 |
STY-006 | 應該 | 每個模組以 package-info.java 的 @ApplicationModule(allowedDependencies = …) 明確宣告允許依賴的模組 | 3.2 |
STY-007 | 應該 | 模組之間的副作用(例如下單後建立出貨單、寄送通知)優先以領域事件溝通,而不是直接呼叫對方的服務 | 3.2 |
STY-008 | 應該 | 系統設計時繪製上下文對映,標示每個關係的上下游與整合模式 | 3.3 |
STY-009 | 必須 | 整合舊系統或外部系統時,必須以防腐層轉換對方的模型;外部模型的類別不得出現在領域層 | 3.3 |
STY-010 | 應該 | 每個限界上下文維護自己的名詞表(arc42 第 12 章),同一名詞在不同上下文意義不同時必須註明 | 3.3 |
STY-011 | 必須 | 每個微服務擁有自己的資料儲存;不得有兩個服務讀寫同一個 schema 或資料表 | 3.4 |
STY-012 | 必須 | 每個服務必須能單獨部署;部署一個服務不得要求同時部署其他服務 | 3.4 |
STY-013 | 應該 | 處理單一使用者請求的同步呼叫鏈不超過 3 層 | 3.4 |
STY-014 | 必須 | 每個服務在服務目錄中登錄唯一的擁有團隊、聯絡方式與 SLO | 3.4 |
STY-015 | 應該 | 系統遷移採用漸進式策略(Strangler Fig),以路由層切換流量;不得採用需要長期凍結舊系統功能的一次性重寫 | 3.5 |
STY-016 | 必須 | 每個遷移階段都要有可回退的切換機制(路由開關或功能旗標)與比對驗證(新舊結果比對或影子流量) | 3.5 |
INT-001 | 必須 | 每一個遠端呼叫(HTTP、gRPC、資料庫、快取、訊息代理)都必須設定連線逾時與讀取逾時,不得使用無限等待的預設值 | 4.1 |
INT-002 | 必須 | 逾時時間必須依呼叫端的 SLO 由外往內遞減:上游的總逾時大於下游逾時加上重試的總和 | 4.1 |
INT-003 | 應該 | 不需要立即結果的副作用(通知、統計、同步到其他系統)以非同步事件處理,不放在使用者請求的同步路徑上 | 4.1 |
INT-004 | 應該 | 服務間的 HTTP 用戶端以宣告式介面(Spring Framework 7 HTTP Service Client)實作,逾時與基底網址由設定檔管理 | 4.1 |
INT-005 | 必須 | Gateway 不得包含業務邏輯(業務規則判斷、資料彙整、資料格式轉換);需要為特定前端彙整資料時使用 BFF | 4.2 |
INT-006 | 應該 | 新的 Kubernetes 叢集以 Gateway API 取代 Ingress;平台團隊管理 Gateway,應用團隊只管理自己命名空間的 HTTPRoute | 4.2 |
INT-007 | 必須 | 對外的 Gateway 只接受 HTTPS;HTTP 只用於導向 HTTPS | 4.2 |
INT-008 | 應該 | 每個 HTTPRoute 規則設定請求逾時,與 4.1 的逾時預算一致 | 4.2 |
INT-009 | 應該 | 只有在需要「所有服務間 mTLS」或「跨多個服務一致的 L7 流量/授權政策」時才導入服務網格,並以 ADR 記錄;服務少於 10 個時優先考慮應用層函式庫與 NetworkPolicy | 4.3 |
INT-010 | 必須 | 導入服務網格時,mTLS 必須設為 STRICT,不得長期停留在 PERMISSIVE | 4.3 |
INT-011 | 不應該 | 在服務網格與應用程式同時設定重試,造成重試次數相乘 | 4.3 |
INT-012 | 必須 | 「寫入資料」與「發布事件」必須保證一致:使用 Transactional Outbox(或 Modulith Event Publication Registry),不得在交易中或交易後直接呼叫訊息代理而無補償機制 | 4.4 |
INT-013 | 必須 | 訊息消費者必須冪等:以事件 ID 去重,或讓處理邏輯本身可重複執行 | 4.4 |
INT-014 | 應該 | 會改變狀態的對外 API(例如建立訂單、付款)支援 Idempotency-Key 請求標頭,讓用戶端可以安全重試 | 4.4 |
INT-015 | 必須 | 無法處理的訊息(格式錯誤、超過重試次數)必須送到死信佇列(DLQ)並告警,不得無限重試阻塞後續訊息,也不得直接丟棄 | 4.4 |
INT-016 | 必須 | 跨服務的資料一致性以 Saga 實作,不得使用跨服務的分散式交易(2PC/XA) | 4.5 |
INT-017 | 必須 | Saga 的每一個步驟都必須定義補償動作(或明確標示為不需補償的「樞紐步驟」),補償動作必須冪等 | 4.5 |
INT-018 | 必須 | Saga 的狀態必須持久化,服務重啟後能從中斷的步驟繼續;必須有逾時與人工介入的處理方式 | 4.5 |
INT-019 | 應該 | 跨服務事件採用 CloudEvents 格式的信封(id、source、type、specversion、time),事件型別名稱包含版本 | 4.6 |
INT-020 | 必須 | 事件的資料結構必須在 Schema Registry 或版本庫中管理,變更必須維持向後相容(只新增選填欄位);不相容的變更必須發布新版本的事件型別 | 4.6 |
INT-021 | 應該 | 對外提供事件的服務以 AsyncAPI 文件描述其頻道、訊息與結構 | 4.6 |
INT-022 | 應該 | 服務間的同步 API 以消費者驅動契約測試驗證,提供者的 CI 必須執行所有消費者的契約 | 4.6 |
API-001 | 必須 | 對外或跨團隊的 API 必須先撰寫 OpenAPI 規格並經審查,規格存放於版本庫,與實作一起版本控制 | 5.1 |
API-002 | 應該 | OpenAPI 規格以 3.1 撰寫;工具鏈(程式碼產生器、檢查工具、閘道)全部支援 3.2 後再升級 | 5.1 |
API-003 | 必須 | CI 以 Spectral 或 Redocly 檢查規格品質,並以 oasdiff 比對前一版,偵測破壞性變更 | 5.1 |
API-004 | 必須 | 實作必須與規格一致:以契約測試或由規格產生介面的方式確保,不得只靠人工對照 | 5.1 |
API-005 | 必須 | URL 以名詞複數表示資源,動作以 HTTP 方法表達;路徑不得包含動詞(業務動作以子資源表示) | 5.2 |
API-006 | 必須 | GET 不得改變伺服器狀態;PUT 與 DELETE 必須冪等 | 5.2 |
API-007 | 應該 | 路徑以 kebab-case,JSON 欄位以 camelCase;同一組織的所有 API 一致 | 5.2 |
API-008 | 必須 | 資源識別碼不得使用可猜測的連續流水號暴露給外部;使用 UUID、ULID 或有格式的業務編號,並一律做物件層級授權檢查(見 SEC-008) | 5.2 |
API-009 | 必須 | 狀態碼必須反映實際結果;不得所有回應都回 200 再以本文中的代碼表示錯誤 | 5.3 |
API-010 | 必須 | 建立資源回 201 並附 Location;非同步處理回 202 並附查詢進度的網址 | 5.3 |
API-011 | 必須 | 使用者無權存取的資源,若「資源是否存在」本身是敏感資訊,回 404 而不是 403 | 5.3 |
API-012 | 必須 | 所有錯誤回應採用 RFC 9457 格式(application/problem+json),並啟用 spring.mvc.problemdetails.enabled | 5.4 |
API-013 | 必須 | 每種業務錯誤定義穩定的 type URI,並在 API 文件列出;用戶端以 type 判斷錯誤,而非比對 detail 文字 | 5.4 |
API-014 | 必須 | 錯誤回應不得包含堆疊追蹤、SQL、內部類別名稱或主機資訊;包含 traceId 供查詢日誌 | 5.4 |
API-015 | 應該 | 欄位驗證錯誤以擴充欄位 errors 一次列出所有欄位錯誤(欄位路徑與訊息) | 5.4 |
API-016 | 必須 | 回傳集合的端點必須分頁,並設定每頁筆數上限(例如 100);不得提供一次回傳全部資料的端點 | 5.5 |
API-017 | 應該 | 大量資料或對外 API 使用游標分頁;游標為不透明字串,用戶端不得解析 | 5.5 |
API-018 | 應該 | 不直接序列化 Spring Data 的 Page 物件;以穩定的 DTO 結構回傳分頁資訊 | 5.5 |
API-019 | 必須 | 破壞性變更必須發布新的主版本,舊版本在棄用期間持續運作;非破壞性變更不升主版本 | 5.6 |
API-020 | 必須 | 棄用 API 時以 Deprecation(RFC 9745)與 Sunset(RFC 8594)回應標頭通知,並提供 Link 指向遷移說明;Sunset 時間不得早於 Deprecation | 5.6 |
API-021 | 應該 | 對外 API 的棄用期至少 6 個月,內部 API 至少一個發布週期;期間監控舊版本的呼叫量,歸零或屆期才下線 | 5.6 |
API-022 | 應該 | 用戶端必須忽略不認得的回應欄位(容錯讀取,Tolerant Reader) | 5.6 |
API-023 | 必須 | 對外 API 必須設定速率限制(依用戶端或使用者),超過時回 429 並附 Retry-After | 5.7 |
API-024 | 必須 | 限制請求本文大小、陣列元素數量與字串長度,並在規格中標示(maxLength、maxItems) | 5.7 |
API-025 | 可以 | 回應中提供 RateLimit-Policy 與 RateLimit 標頭,讓用戶端主動降速(IETF 草案,已獲 IESG 核准,待正式發布為 RFC) | 5.7 |
API-026 | 必須 | 正式環境不得公開 Swagger UI 與 /v3/api-docs;API 文件發布在開發者入口網站或內部文件站 | 5.8 |
API-027 | 應該 | API 文件包含:驗證方式、錯誤類型清單、速率限制、版本與棄用政策、範例請求與回應 | 5.8 |
FE-001 | 應該 | 渲染策略依頁面性質選擇並記錄於 ADR:登入後的業務系統預設 SPA;對外、需 SEO 的頁面採 SSR 或 SSG | 6.1 |
FE-002 | 必須 | 定義前端效能預算,以 Core Web Vitals 的「良好」門檻為目標:LCP ≤ 2.5 秒、INP ≤ 200 毫秒、CLS ≤ 0.1(第 75 百分位) | 6.1 |
FE-003 | 必須 | 瀏覽器端不得在 localStorage、sessionStorage 或可被 JavaScript 讀取的 Cookie 保存存取權杖或更新權杖;採用 BFF 模式由伺服器端保管 | 6.2 |
FE-004 | 必須 | 工作階段 Cookie 必須設定 HttpOnly、Secure、SameSite(Strict 或 Lax),並以 __Host- 前綴限定網域 | 6.2 |
FE-005 | 應該 | 一種前端(Web、行動 App)對應一個 BFF,由前端團隊擁有;BFF 只做資料彙整與格式轉換,不包含業務規則 | 6.2 |
FE-006 | 應該 | 只有在 3 個以上團隊需要獨立發布前端時才採用微前端,並以 ADR 記錄 | 6.3 |
FE-007 | 必須 | 採用微前端時,框架核心套件(Vue/React、路由、狀態管理)必須以 singleton 共用並鎖定主版本;各微前端之間不得直接引用彼此的內部模組,只能透過公開的事件或介面溝通 | 6.3 |
FE-008 | 必須 | 所有微前端使用同一套設計系統(Design System)元件庫,確保一致的外觀與無障礙行為 | 6.3 |
FE-009 | 必須 | 對外與內部系統都必須符合 WCAG 2.2 AA 等級;新功能上線前通過自動化與人工無障礙檢查 | 6.4 |
FE-010 | 應該 | 以行動優先(mobile-first)設計版面,斷點定義於設計系統中統一管理,不在各元件自行定義 | 6.4 |
FE-011 | 必須 | 使用者可見的文字不得寫死在元件中,一律透過 i18n 資源檔;資源檔以語系代碼(BCP 47,例如 zh-TW、en-US)命名 | 6.5 |
FE-012 | 必須 | 後端與 API 以 UTC 或含時區位移的 ISO 8601 格式(例如 2026-10-07T09:30:00+08:00)傳遞時間;前端依使用者時區顯示 | 6.5 |
FE-013 | 應該 | 數字、貨幣、日期以 Intl API 依語系格式化,不自行拼接字串 | 6.5 |
BE-001 | 必須 | 服務內部採用分層(或六角形)架構,依賴方向只能由外往內:轉接器 → 應用 → 領域 | 7.1 |
BE-002 | 必須 | 領域層不得依賴 Spring、JPA、Jackson、Servlet 等框架或基礎設施套件 | 7.1 |
BE-003 | 必須 | 領域層以 Port 介面定義對外部資源的需求(例如 OrderRepository),由轉接器層實作 | 7.1 |
BE-004 | 不應該 | 對於純 CRUD、沒有業務規則的簡單模組,硬套四層與 Port;此時可採用簡化的兩層(Controller → Repository),但必須在模組的 package-info.java 或 ADR 中說明 | 7.1 |
BE-005 | 必須 | 最上層套件依業務模組劃分(package by feature),不得依技術層劃分(controller、service、repository 在最上層) | 7.3 |
BE-006 | 應該 | 模組內的類別預設為 package-private,只有需要被其他套件使用的類別才宣告為 public | 7.3 |
BE-007 | 必須 | 新專案在第一個 Sprint 就加入分層與模組邊界的架構測試 | 7.4 |
BE-008 | 應該 | 既有專案導入架構測試時,以 FreezingArchRule 凍結現有違規,並將違規清單(archunit_store)納入版本控制,定期檢視減少的進度 | 7.4 |
BE-009 | 必須 | 一律使用建構子注入;不得使用欄位注入(@Autowired 欄位) | 7.5 |
BE-010 | 必須 | 組態以 @ConfigurationProperties 綁定到型別安全的 record,並以 Bean Validation 在啟動時驗證;不得在業務程式中散落 @Value 或 Environment.getProperty | 7.5 |
BE-011 | 必須 | 交易邊界設在應用層的 Use Case 方法;Controller 與領域層不得宣告 @Transactional | 7.6 |
BE-012 | 必須 | 資料庫交易內不得呼叫遠端服務(HTTP、gRPC、外部 API)或等待使用者輸入;交易必須短 | 7.6 |
BE-013 | 應該 | 只讀取資料的 Use Case 使用 @Transactional(readOnly = true),讓資料來源路由可以導向唯讀副本(8.4) | 7.6 |
DATA-001 | 應該 | 交易資料預設使用關聯式資料庫;採用其他類型的儲存作為權威來源時,必須以 ADR 說明一致性、備份與查詢需求如何被滿足 | 8.1 |
DATA-002 | 必須 | 每一份資料都要有明確的權威來源(system of record);快取、搜尋索引、讀取模型都是衍生資料,必須可以從權威來源重建 | 8.1 |
DATA-003 | 必須 | 每個服務或模組擁有自己的 schema;應用程式使用的資料庫帳號只具備自己 schema 的 DML 權限,不具備 DDL 權限(DDL 由遷移專用帳號執行) | 8.2 |
DATA-004 | 必須 | 資料存取透過轉接器層的 Repository 實作(7.2);SQL 使用參數綁定,不得以字串串接組合使用者輸入 | 8.2 |
DATA-005 | 必須 | 樂觀鎖(版本欄位)保護並發更新;長時間的使用者操作不得以資料庫的悲觀鎖等待 | 8.2 |
DATA-006 | 應該 | 只有在出現上述徵兆時才導入 CQRS,並以 ADR 記錄可接受的資料延遲(例如「讀取模型最多落後 5 秒」) | 8.3 |
DATA-007 | 必須 | 讀取模型由事件或 CDC 更新,更新程序必須冪等(INT-013),並監控讀取模型的延遲 | 8.3 |
DATA-008 | 應該 | 讀寫分離以交易的唯讀屬性路由:@Transactional(readOnly = true) 導向唯讀副本,其餘導向主庫;不在業務程式中手動選擇資料來源 | 8.4 |
DATA-009 | 必須 | 「寫入後立即讀取」的流程(例如下單後顯示訂單)必須讀主庫,不得受複寫延遲影響 | 8.4 |
DATA-010 | 應該 | 依時間成長、需要定期清除的大型資料表(日誌、交易明細)採用資料庫原生的分割功能;分片必須以 ADR 說明為什麼前面的手段都不足 | 8.4 |
DATA-011 | 必須 | 所有結構變更以版本化的遷移腳本管理;已套用到任何共用環境的腳本不得修改,修正以新的腳本進行 | 8.5 |
DATA-012 | 必須 | 正式環境的結構變更必須向後相容,讓新舊版本的應用程式可以同時運作(Expand–Contract);刪除或改名欄位必須分多次發布 | 8.5 |
DATA-013 | 必須 | 正式環境停用 Flyway 的 clean,並開啟 validate-on-migrate | 8.5 |
DATA-014 | 應該 | 遷移腳本以時間戳記版本命名(V202610071030__add_buyer_id.sql),避免多人並行開發時版本號衝突 | 8.5 |
DATA-015 | 必須 | 在大型資料表上建立索引或加上限制條件時,使用不鎖表的方式(PostgreSQL CREATE INDEX CONCURRENTLY、先 NOT VALID 再 VALIDATE CONSTRAINT) | 8.5 |
DATA-016 | 必須 | 每個資料欄位標示資料等級,記錄於資料字典;機密等級欄位必須欄位層級加密或代碼化(見 11.6) | 8.6 |
DATA-017 | 必須 | 每類資料定義保存期限與到期處理方式(刪除、匿名化、封存),並以排程自動執行 | 8.6 |
DATA-018 | 必須 | 非正式環境不得使用未遮蔽的正式環境個人資料 | 8.6 |
DATA-019 | 應該 | 只有在產品需要部署到客戶既有資料庫時才支援多種資料庫,並以 ADR 列出支援的產品與版本 | 8.7 |
DATA-020 | 必須 | 支援多種資料庫時,CI 必須對每一種支援的資料庫執行遷移與整合測試(Testcontainers);不得只在其中一種資料庫上測試 | 8.7 |
PERF-001 | 必須 | 效能最佳化必須以量測數據(壓測、APM、執行計畫)為依據,並在最佳化前後比較;不接受「感覺比較快」 | 9.1 |
PERF-002 | 應該 | 連線池、執行緒池、佇列大小以 Little 定律估算後,再以壓測驗證;設定值與計算過程記錄於架構文件 | 9.1 |
PERF-003 | 必須 | 避免 N+1 查詢與在迴圈中呼叫遠端服務;需要多筆資料時以批次查詢取得 | 9.1 |
PERF-004 | 必須 | 每個快取都要設定 TTL,並記錄「資料過時多久可以接受」;不得有永不過期的業務快取 | 9.2 |
PERF-005 | 必須 | 資料更新時以「先寫資料庫、再刪除快取」的方式失效,而不是更新快取內容 | 9.2 |
PERF-006 | 必須 | 熱門鍵的快取失效時要防止快取擊穿(大量請求同時打到資料庫):使用 @Cacheable(sync = true) 或單一載入機制,並為 TTL 加上隨機抖動 | 9.2 |
PERF-007 | 必須 | 快取的鍵包含所有影響結果的參數(使用者、語系、權限);個人化或含權限的資料不得以共用鍵快取 | 9.2 |
PERF-008 | 應該 | 快取的鍵以 <服務>:<資料類型>:<版本>:<識別碼> 命名,結構變更時遞增版本以避免讀到舊格式 | 9.2 |
PERF-009 | 必須 | 快取不可用時系統必須能降級運作(直接查資料庫),快取錯誤不得讓請求失敗 | 9.2 |
PERF-010 | 必須 | 檔名含內容雜湊的靜態資源(JS、CSS、圖片)設定 Cache-Control: public, max-age=31536000, immutable;HTML 入口檔設定 Cache-Control: no-cache,確保使用者取得最新版本 | 9.3 |
PERF-011 | 必須 | 含個人資料或需要登入的 API 回應設定 Cache-Control: no-store,不得被 CDN 或共用代理快取 | 9.3 |
PERF-012 | 應該 | I/O 密集的 Spring Boot 服務(Java 21 以上,建議 25)啟用 Virtual Threads(spring.threads.virtual.enabled=true) | 9.4 |
PERF-013 | 必須 | 啟用 Virtual Threads 時,對下游有限資源的呼叫必須設定並行上限(Spring Framework 7 @ConcurrencyLimit 或 Resilience4j Bulkhead) | 9.4 |
PERF-014 | 必須 | 使用者請求中不需要立即完成的工作(寄信、產生報表、呼叫慢速外部系統)改為非同步處理,回應 202 或以事件觸發 | 9.4 |
PERF-015 | 必須 | 服務必須是無狀態的:工作階段、上傳暫存、排程鎖等狀態放在外部儲存,任何副本都能處理任何請求 | 9.5 |
PERF-016 | 必須 | 服務必須支援優雅關機:收到 SIGTERM 後停止接收新請求、完成處理中的請求,再結束(server.shutdown=graceful) | 9.5 |
PERF-017 | 應該 | 以 HorizontalPodAutoscaler 依 CPU 或業務指標自動擴展,並設定縮減的穩定時間以避免震盪 | 9.5 |
PERF-018 | 不應該 | 依賴負載平衡器的工作階段黏著(session affinity)來維持狀態 | 9.5 |
PERF-019 | 必須 | 上線前執行負載測試,並以第 2 章的品質情境作為通過門檻(寫在測試腳本的 thresholds 中,不符合時測試失敗) | 9.6 |
PERF-020 | 必須 | 效能測試環境的規格、資料量與正式環境相當(或按比例縮放並記錄換算方式);不得以空資料庫測試 | 9.6 |
PERF-021 | 應該 | 重大版本發布前執行浸泡測試;系統容量每年或業務量變化 50% 以上時重新評估 | 9.6 |
RES-001 | 必須 | 對外部系統與其他服務的同步呼叫必須有熔斷器,並同時以失敗率與慢呼叫率判斷 | 10.1 |
RES-002 | 必須 | 只對冪等操作或帶冪等鍵的操作重試;重試必須有次數上限、指數退避與隨機抖動;不得重試 4xx 等不會因重試而成功的錯誤 | 10.1 |
RES-003 | 應該 | 不同的下游使用獨立的隔艙(並行上限),一個慢的下游不得耗盡其他呼叫共用的資源 | 10.1 |
RES-004 | 必須 | 每個熔斷或隔艙都要定義降級行為(快取的舊資料、預設值、「處理中」狀態或明確的 503),並經過業務單位同意 | 10.1 |
RES-005 | 必須 | 熔斷器狀態、重試次數、隔艙拒絕次數必須輸出為監控指標並設定告警 | 10.1 |
RES-006 | 必須 | 正式環境的線上服務至少 3 個副本,並以 topologySpreadConstraints 分散到至少 2 個(建議 3 個)可用區域(AZ)與不同節點 | 10.2 |
RES-007 | 必須 | 每個多副本的線上服務都要設定 PodDisruptionBudget,確保節點維護或升級時仍有足夠副本提供服務 | 10.2 |
RES-008 | 必須 | 資料庫、快取、訊息代理等有狀態元件必須跨 AZ 部署並具備自動容錯移轉;容錯移轉時間與資料遺失量符合 10.4 的 RTO/RPO | 10.2 |
RES-009 | 必須 | 單點故障清單:架構文件列出所有單點(包括 DNS、憑證、身分提供者、CI/CD),並說明緩解方式 | 10.2 |
RES-010 | 必須 | Liveness 探針不得檢查外部相依(資料庫、快取、其他服務);只反映應用程式本身是否需要重啟 | 10.3 |
RES-011 | 必須 | Readiness 探針只納入「沒有它就無法提供任何服務」的相依;非必要的下游以熔斷與降級處理 | 10.3 |
RES-012 | 應該 | 啟動較慢的服務使用 Startup 探針,而不是把 Liveness 的 initialDelaySeconds 設得很長 | 10.3 |
RES-013 | 必須 | 健康檢查端點與管理端點使用獨立的管理埠,不對外公開;/actuator 只開放必要的端點 | 10.3 |
RES-014 | 必須 | 每個系統依業務影響分析(10.5)定義等級、RTO 與 RPO,並選擇對應的災難復原策略 | 10.4 |
RES-015 | 必須 | 備份遵循 3-2-1-1-0 原則:3 份資料、2 種媒體、1 份異地、1 份離線或不可變(immutable)、還原驗證 0 錯誤 | 10.4 |
RES-016 | 必須 | 至少每季執行一次還原演練,每年執行一次完整的災難復原演練,並記錄實際的 RTO 與 RPO;實際值超過目標時必須改善 | 10.4 |
RES-017 | 必須 | 災難復原所需的一切(基礎設施即程式碼、部署腳本、機密、DNS 切換步驟)必須在災難發生時可以取得,不得只存在於受災區域 | 10.4 |
RES-018 | 必須 | 支援關鍵業務的系統必須有業務影響分析,列出支援的業務流程、MTPD 與相依的系統、人員、供應商 | 10.5 |
RES-019 | 必須 | 系統的 RTO 必須小於其支援業務流程的 MTPD;相依系統的 RTO 不得大於依賴它的系統的 RTO | 10.5 |
RES-020 | 應該 | 業務連續性計畫包含 IT 無法恢復時的人工替代作業程序(例如紙本或離線作業),並每年演練 | 10.5 |
RES-021 | 應該 | 每個韌性機制(熔斷、降級、容錯移轉、自動擴展)至少有一個故障演練驗證,先在預備環境執行,成熟後再於正式環境的限定範圍執行 | 10.6 |
RES-022 | 必須 | 故障實驗必須定義穩態假設、爆炸半徑(範圍與時間上限)與中止條件,並事先通知值班人員 | 10.6 |
SEC-001 | 必須 | 新系統與重大變更(新的外部介面、新的資料類型、新的信任邊界)必須進行威脅建模:繪製含信任邊界的資料流程圖,以 STRIDE 逐一分析,並追蹤每個威脅的處理方式 | 11.1 |
SEC-002 | 必須 | 系統的安全需求以 OWASP ASVS 5.0 為基準:一般系統 Level 2,處理高敏感資料或金流的系統 Level 3 | 11.1 |
SEC-003 | 必須 | 預設拒絕:所有端點預設需要身分驗證與授權,公開端點以白名單列出並經資安審查 | 11.1 |
SEC-004 | 必須 | 服務間呼叫必須驗證呼叫者身分(mTLS 或服務權杖),不得以「來自內部網路」作為信任依據 | 11.2 |
SEC-005 | 必須 | 每個 Kubernetes 命名空間預設拒絕所有進出流量(default-deny NetworkPolicy),再以白名單開放必要的流量 | 11.2 |
SEC-006 | 應該 | 工作負載存取雲端資源使用 Workload Identity(例如 EKS Pod Identity、GKE Workload Identity、Azure Workload Identity),不使用長期有效的存取金鑰 | 11.2 |
SEC-007 | 必須 | 使用者登入使用 OIDC 授權碼流程+PKCE;不得使用 Implicit 或 Resource Owner Password Credentials 授權方式;不得自行實作密碼驗證與工作階段管理 | 11.3 |
SEC-009 | 必須 | API 必須驗證存取權杖的簽章、發行者(iss)、對象(aud)與有效期限;存取權杖有效期不超過 15 分鐘 | 11.3 |
SEC-008 | 必須 | 每一個以 ID 存取資料的操作,都必須檢查目前使用者對該筆資料的權限;查詢條件包含擁有者,或在讀取後比對,無權限時回 404(API-011) | 11.4 |
SEC-010 | 必須 | 功能層級授權集中定義(SecurityFilterChain 或方法安全註解),不得散落在各 Controller 的 if 判斷中 | 11.4 |
SEC-011 | 必須 | 機密(密碼、API 金鑰、私鑰、權杖)不得出現在程式碼、版本庫、容器映像或未加密的 ConfigMap;由機密管理系統(Vault、雲端 Secret Manager)透過 External Secrets 等方式注入,並定期輪替 | 11.6 |
SEC-012 | 必須 | 所有傳輸都要加密,包括內部服務間與資料庫連線;TLS 最低 1.2,優先使用 1.3 | 11.6 |
SEC-013 | 必須 | 靜態資料加密(磁碟、資料庫、備份、物件儲存),金鑰由 KMS 管理並定期輪替;金鑰與資料分開存放 | 11.6 |
SEC-014 | 必須 | 機密等級(8.6)的欄位以欄位層級加密或代碼化(tokenization)保護,日誌與錯誤訊息中遮蔽 | 11.6 |
SEC-015 | 必須 | 所有 HTML 與 API 回應設定上表的安全標頭;CSP 不得使用 'unsafe-inline' 與 'unsafe-eval' 執行腳本(以 nonce 或 hash 取代) | 11.7 |
SEC-016 | 必須 | 每個建置產物(JAR、容器映像)產生 SBOM(CycloneDX 或 SPDX),並以弱點掃描作為發布閘門:有可修補的 Critical/High 弱點時阻擋發布 | 11.8 |
SEC-017 | 必須 | 容器映像由 CI 簽章並產生建置來源證明(目標 SLSA Build L3);正式環境只部署通過簽章驗證的映像 | 11.8 |
SEC-018 | 必須 | 第三方 GitHub Actions 以完整的 commit SHA 釘選;套件相依以 lock 檔鎖定,並以 Dependabot/Renovate 自動提出更新 | 11.8 |
SEC-019 | 必須 | 安全相關事件(登入成功與失敗、權限變更、存取機密資料、管理操作、授權失敗)必須寫入稽核日誌,記錄「誰、何時、從哪裡、對什麼、做了什麼、結果」;稽核日誌集中保存、不可被應用程式修改或刪除,保存期限依法規 | 11.9 |
SEC-020 | 必須 | 例外狀況必須「失效時安全」(fail closed):授權檢查、簽章驗證、限流等安全機制發生錯誤時拒絕請求,而不是放行 | 11.9 |
OBS-001 | 必須 | 以 OpenTelemetry 作為追蹤與日誌的標準協定(OTLP);所有遙測資料帶有資源屬性 service.name、service.version、deployment.environment.name | 12.1 |
OBS-002 | 必須 | 應用程式把遙測資料送到 OpenTelemetry Collector,而不是直接送到特定的後端;後端的更換、取樣與遮蔽在 Collector 處理 | 12.1 |
OBS-003 | 必須 | 所有服務以 W3C Trace Context(traceparent 標頭)傳遞追蹤內容,包括非同步路徑:訊息標頭(Kafka)、@Async、排程工作 | 12.2 |
OBS-004 | 應該 | 取樣策略記錄於架構文件:錯誤與慢請求必須保留(尾端取樣),一般請求可依流量取樣 | 12.2 |
OBS-005 | 必須 | 日誌以結構化 JSON 輸出到標準輸出(stdout),包含時間(UTC)、等級、服務名稱、traceId、spanId;不得包含密碼、權杖、完整卡號與未遮蔽的個人資料 | 12.3 |
OBS-006 | 必須 | 正式環境預設日誌等級為 INFO;日誌保存期限依法規、主管機關要求與資料分級訂定並集中保存(本指引範例以稽核日誌 180 天為基準) | 12.3 |
OBS-007 | 必須 | 每個服務提供 RED 指標,延遲以直方圖(histogram)記錄並包含 SLO 邊界;每個有限資源(連線池、執行緒、佇列)提供 USE 指標 | 12.4 |
OBS-008 | 必須 | 安全事件必須告警:授權失敗(401/403)異常增加、稽核日誌中斷、熔斷器長時間開啟、DLQ 有訊息 | 12.4 |
OBS-009 | 必須 | 可用性告警以 SLO 錯誤預算的燃燒率為基礎,使用多視窗(長視窗+短視窗)避免誤報;不以 CPU 使用率等原因指標作為呼叫值班的告警 | 12.4 |
OBS-010 | 必須 | 指標標籤不得使用高基數的值(使用者 ID、訂單編號、完整 URL、Email);URL 以路由樣板(/orders/{orderId})表示 | 12.4 |
OBS-011 | 必須 | 每個告警都有嚴重度與處理手冊(runbook)連結;會呼叫值班的告警必須是需要人立即處理的症狀 | 12.4 |
OBS-012 | 應該 | 儀表板與告警規則以程式碼管理(JSON/YAML 納入版本控制),透過 CI/CD 部署,不在 UI 中手動修改 | 12.5 |
OBS-013 | 必須 | 每個正式環境的服務都有值班輪值與升級路徑;重大事件後 5 個工作天內完成無責檢討(blameless postmortem),改善項目有負責人與期限 | 12.5 |
PLT-001 | 必須 | 以多階段建置產生映像:建置階段使用 JDK,執行階段只包含 JRE(或更精簡的基底)與應用程式;容器以非 root 使用者執行 | 13.1 |
PLT-002 | 必須 | 基底映像以 digest 釘選,並由自動化工具(Renovate/Dependabot)定期更新;不得使用 latest 標籤 | 13.1 |
PLT-003 | 必須 | 映像中不得包含機密、原始碼、建置工具與測試資料;以 .dockerignore 排除不必要的檔案 | 13.1 |
PLT-004 | 必須 | JVM 的堆積記憶體以容器記憶體的比例設定(-XX:MaxRAMPercentage,通常 70–80%),不寫死 -Xmx;容器的記憶體 requests 等於 limits | 13.2 |
PLT-005 | 應該 | 設定 CPU requests;是否設定 CPU limits 依叢集政策決定,若設定,必須以壓測確認沒有 CPU 節流(container_cpu_cfs_throttled_periods_total)造成延遲 | 13.2 |
PLT-006 | 必須 | 容器的 securityContext 符合 Pod Security Standards 的 restricted 等級:runAsNonRoot、allowPrivilegeEscalation: false、移除所有 capabilities、seccompProfile: RuntimeDefault,並建議 readOnlyRootFilesystem: true | 13.3 |
PLT-007 | 必須 | 優雅關機:preStop 先等待數秒讓負載平衡器移除端點,terminationGracePeriodSeconds 大於 preStop 等待加上應用程式的關機等待時間(PERF-016) | 13.3 |
PLT-008 | 必須 | 不需要呼叫 Kubernetes API 的工作負載設定 automountServiceAccountToken: false,並使用專屬的 ServiceAccount | 13.3 |
PLT-009 | 必須 | 同一個映像部署到所有環境;環境差異只透過組態(環境變數、ConfigMap、Secret)注入,不為各環境建置不同的映像(12-Factor App 的 Config 原則) | 13.4 |
PLT-010 | 應該 | ConfigMap 變更時觸發滾動更新(以內容雜湊命名或加上註解),避免部分 Pod 使用舊設定 | 13.4 |
PLT-011 | 必須 | 正式環境的部署與設定變更只能透過 GitOps(PR → 審查 → 自動同步)進行;不得以 kubectl apply/edit 直接修改,並啟用偏移偵測與自動修正 | 13.5 |
PLT-012 | 必須 | 環境推進(測試 → 預備 → 正式)推進的是同一個映像 digest;正式環境的推進需要核准 | 13.5 |
PLT-013 | 必須 | 所有應用程式命名空間以 Pod Security Admission 強制 restricted 等級 | 13.6 |
PLT-014 | 必須 | 本指引中可在部署端檢查的「必須」規則(成本標籤 NFR-012、副本與分散 RES-006、PDB RES-007、映像簽章 SEC-017)以准入政策強制執行;政策本身納入版本控制並有測試 | 13.6 |
PLT-015 | 必須 | CI 以 kubeconform(-strict,指定目標 Kubernetes 版本,並載入所使用 CRD 的 schema)驗證所有 Kubernetes 資源;Helm chart 先以 helm template 展開再驗證 | 13.7 |
PLT-016 | 應該 | 優先使用雲端代管的資料庫、快取與訊息服務;在 Kubernetes 中自建有狀態服務必須以 ADR 說明備份、升級與容錯移轉的維運能力 | 13.7 |
CICD-001 | 必須 | 主幹(main)受分支保護:必須透過 PR 合併、至少一位審查者核准、所有必要檢查通過;不允許直接推送與強制推送 | 14.1 |
CICD-002 | 應該 | 採用主幹開發(trunk-based development):分支存活時間不超過 2 天,未完成的功能以功能旗標隱藏,而不是以長期分支隔離 | 14.1 |
CICD-003 | 必須 | 交付管線的每個階段都是自動化的品質閘門;閘門失敗時停止推進,不得以手動略過的方式繼續 | 14.1 |
CICD-004 | 必須 | 每個 PR 執行:編譯、單元測試、架構測試(ArchUnit/Modulith)、整合測試、靜態分析與相依弱點掃描;任一失敗即阻擋合併 | 14.2 |
CICD-005 | 必須 | 工作流程的 permissions 預設唯讀,只在需要的 job 授予額外權限;使用 OIDC 取得雲端短期憑證,不在 Secrets 中保存長期金鑰 | 14.2 |
CICD-006 | 應該 | CI 結果可重現:建置工具以 Wrapper 固定版本(mvnw)、相依以 lock 檔或版本管理鎖定、執行環境指定版本(ubuntu-24.04 而非 ubuntu-latest) | 14.2 |
CICD-007 | 必須 | 整合測試使用與正式環境相同種類與主要版本的資料庫與訊息代理(Testcontainers),不使用記憶體資料庫替代 | 14.3 |
CICD-008 | 應該 | 領域層與應用層的測試覆蓋率作為趨勢指標追蹤(建議行覆蓋率 ≥ 80%),新程式碼的覆蓋率不得低於門檻;覆蓋率不得作為唯一的品質指標 | 14.3 |
CICD-009 | 必須 | 測試必須可重複執行且彼此獨立:不依賴執行順序、外部共用環境或真實時間(以 Clock 注入) | 14.3 |
CICD-010 | 應該 | Tier 1、Tier 2 系統的正式發布採用金絲雀或藍綠部署,並以 SLO 指標自動判斷是否繼續推進或回退 | 14.4 |
CICD-011 | 必須 | 每個功能旗標記錄擁有者、建立日期與預計移除日期;功能全量上線後的旗標必須在兩個發布週期內移除 | 14.4 |
CICD-012 | 必須 | 每次發布都有回退方案並經過驗證;資料庫結構變更必須相容於前一版應用程式(DATA-012),讓回退不需要還原資料庫 | 14.4 |
CICD-013 | 應該 | 以自動化方式(版本庫、CI/CD、事件系統的資料)量測 DORA 指標並定期檢視趨勢;指標用於改善流程,不用於評比個人或團隊 | 14.5 |
MS-001 | 必須 | 在 Kubernetes 中以 Service 與 DNS 作為服務發現機制;引入 Eureka、Consul 等額外的註冊中心必須以 ADR 說明原生機制為何不足 | 15.1 |
MS-002 | 不應該 | 在 Kubernetes 中再使用用戶端負載平衡(Spring Cloud LoadBalancer 搭配註冊中心);Service 或服務網格已提供負載平衡 | 15.1 |
MS-003 | 必須 | 組態以版本控制管理,每一次變更都可以追溯到審查過的 PR;機密與一般組態分開管理(SEC-011) | 15.2 |
MS-004 | 應該 | 只有可以安全地在執行中改變的設定(功能旗標、日誌等級、限流門檻)才允許動態重新載入;連線池、執行緒池等結構性設定透過滾動更新套用 | 15.2 |
MS-005 | 必須 | 多副本服務中的排程工作必須確保同一時間只有一個執行個體:使用 ShedLock(或同等機制)或改為 Kubernetes CronJob(concurrencyPolicy: Forbid) | 15.3 |
MS-006 | 必須 | 排程工作必須冪等,重複執行不會產生錯誤結果 | 15.3 |
MS-007 | 必須 | 不得以分散式鎖(Redis、資料庫鎖)作為資料正確性的唯一保證;正確性必須由資料層的唯一限制、樂觀鎖或防護權杖保證 | 15.3 |
MS-008 | 必須 | 每個事件主題有唯一的擁有服務(只有擁有者可以發布),並在主題登錄檔記錄:命名、擁有者、事件 schema、分割鍵、保留期限、消費者清單 | 15.4 |
MS-009 | 應該 | 主題命名採 <領域>.<事件類別> 的格式(例如 order.events),死信主題加上 .DLT 後綴;消費者群組以消費服務的名稱命名 | 15.4 |
MS-010 | 應該 | 平台團隊以範本(例如 Backstage Software Templates)提供符合本指引的新服務骨架;新服務優先從範本建立 | 15.5 |
MS-011 | 必須 | 黃金路徑範本本身必須通過本指引的所有自動化檢查(架構測試、kubeconform、actionlint、promtool),並隨指引版本更新 | 15.5 |
AI-001 | 必須 | AI 的產出一律視為草稿;架構決策由具名的人做出並負責(ADR 的 decision-makers 必須是人) | 16.1 |
AI-002 | 必須 | AI 產生的設定、程式碼與文件,必須通過與人工產出相同的所有自動化檢查與審查,不得因為「AI 產生的」而降低或提高標準 | 16.1 |
AI-003 | 必須 | 要求 AI 產生架構設計時,提示必須包含:品質情境(第 2 章)、限制條件、技術基準版本(0.2)與適用的規則編號;並要求 AI 在產出中標註依據的規則編號 | 16.2 |
AI-004 | 應該 | 專案版本庫維護 AI 指示檔(例如 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md),把本指引的關鍵規則與專案的技術基準寫入,讓所有 AI 工具一致遵守 | 16.2 |
AI-005 | 必須 | AI 產出中出現的每一個版本號、設定鍵、API、CLI 參數與標準條號,都必須以官方文件、工具或原始碼查證;無法查證的項目不得進入正式文件 | 16.3 |
AI-006 | 必須 | AI 產出中的數字(可用性、逾時預算、容量、評估矩陣總分、成本)必須由人重新計算 | 16.3 |
AI-007 | 必須 | 不得把機密、個人資料、客戶資料與未公開的安全弱點資訊輸入未經企業核准的 AI 工具;核准的工具也必須遵守資料分級(8.6) | 16.5 |
AI-008 | 應該 | PR 描述註明 AI 協助的範圍(例如「設定檔由 AI 產生初稿,已逐項查證」),讓審查者調整審查重點 | 16.5 |
附錄 B 架構審查檢核表
本檢核表依 1.6 的審查時機整理,每一項都對應到規則編號,審查時可直接引用。「證據」欄說明審查者應要求提供什麼,而不是接受口頭說明。
B.1 概念與設計審查
| # | 檢核項目 | 規則 | 證據 |
|---|---|---|---|
| 1 | 品質需求是否以六段式情境撰寫、可量測、以百分位數表示? | NFR-001、NFR-002 | arc42 第 10 章 |
| 2 | 品質目標是否排序,前 3–5 項寫入 arc42 第 1 章? | NFR-003 | arc42 第 1 章 |
| 3 | 法規要求是否列為品質需求? | NFR-004 | 合規需求表 |
| 4 | 每個品質情境是否追溯到架構決策與驗證方式? | NFR-006 | 追溯表 |
| 5 | SLO 是否定義,並考慮相依元件的串聯可用性? | NFR-007、NFR-008 | SLO 檔、可用性計算 |
| 6 | 架構風格的選擇是否有 ADR,並符合 3.1 的決策流程? | STY-001、STY-002 | ADR |
| 7 | 是否有 C4 Context 與 Container 圖,連線有協定與同步/非同步說明? | GOV-011、GOV-013 | 架構圖 |
| 8 | 每個複雜機制(Kafka、CQRS、Service Mesh、分片、多區域)是否有 ADR? | GOV-002 | ADR 清單 |
| 9 | 每個服務是否擁有自己的資料? | STY-011、DATA-003 | 資料來源設定、資料庫權限 |
| 10 | 逾時預算是否由外往內遞減? | INT-001、INT-002 | 逾時預算表 |
| 11 | 跨服務一致性是否以 Outbox/Saga 處理,並定義補償? | INT-012、INT-016、INT-017 | 循序圖、Saga 步驟表 |
| 12 | 是否完成威脅建模(含信任邊界)? | SEC-001 | 威脅模型 |
| 13 | 每個以 ID 存取資料的 API 是否有物件層級授權? | SEC-008 | 授權設計、測試清單 |
| 14 | 系統等級、RTO/RPO 是否依業務影響分析訂定? | RES-014、RES-018、RES-019 | BIA、DR 計畫 |
| 15 | 單點故障清單是否完整? | RES-009 | 單點故障清單 |
| 16 | 技術選型是否只使用技術雷達 Adopt/Trial 環的技術,且沒有 EOL 版本? | GOV-003、GOV-004 | SBOM、技術雷達 |
B.2 實作審查(抽查)
| # | 檢核項目 | 規則 | 證據 |
|---|---|---|---|
| 1 | 架構測試(ArchUnit、Modulith)是否存在並在 CI 執行? | GOV-017、BE-007、STY-004 | CI 測試報告 |
| 2 | 領域層是否沒有框架相依? | BE-002 | LayeringArchTest |
| 3 | 交易內是否沒有遠端呼叫? | BE-012 | 程式碼審查、連線持有時間指標 |
| 4 | API 錯誤是否使用 ProblemDetail、正確狀態碼? | API-009、API-012 | API 測試 |
| 5 | OpenAPI 規格是否先行、lint 與破壞性變更檢查是否在 CI? | API-001、API-003 | CI 設定 |
| 6 | 遠端呼叫是否有熔斷、重試只用於冪等操作? | RES-001、RES-002 | 設定、故障注入測試 |
| 7 | 消費者是否冪等? | INT-013 | 重複投遞測試 |
| 8 | 遷移腳本是否向後相容? | DATA-011、DATA-012 | 遷移腳本 PR |
| 9 | 日誌是否結構化、含 traceId、沒有個資? | OBS-005 | 日誌樣本 |
| 10 | 機密是否沒有出現在版本庫與映像中? | SEC-011 | gitleaks、Trivy 報告 |
B.3 上線審查
| # | 檢核項目 | 規則 | 證據 |
|---|---|---|---|
| 1 | 負載測試是否以品質情境作為門檻並通過? | PERF-019、PERF-020、GOV-015 | k6/Gatling 報告 |
| 2 | 故障演練(熔斷、AZ 失效、資料庫容錯移轉)是否執行並達標? | RES-016、RES-021 | 演練紀錄 |
| 3 | 還原演練是否在最近一季內執行,實際 RTO/RPO 是否達標? | RES-015、RES-016 | 還原測試報告 |
| 4 | 健康檢查是否正確分離 liveness 與 readiness? | RES-010、RES-011 | Deployment 設定、故障注入結果 |
| 5 | 副本數、跨 AZ 分散與 PDB 是否設定? | RES-006、RES-007 | Deployment、PDB |
| 6 | 安全設定是否符合 restricted?NetworkPolicy 是否預設拒絕? | PLT-006、PLT-013、SEC-005 | 命名空間標籤、政策 |
| 7 | 映像是否簽章並以 digest 部署?SBOM 與弱點掃描是否通過? | SEC-016、SEC-017 | 簽章驗證、掃描報告 |
| 8 | SLO 告警與 runbook 是否就緒?安全事件是否有告警? | OBS-008、OBS-009、OBS-011 | 告警規則、runbook |
| 9 | 回退方案是否驗證過? | CICD-012 | 回退演練紀錄 |
| 10 | 正式環境部署是否透過 GitOps? | PLT-011 | Argo CD 應用程式設定 |
B.4 對照雲端 Well-Architected 支柱
| 支柱(AWS) | 本指引對應章節 | 主要規則 |
|---|---|---|
| 卓越營運 Operational Excellence | 第 12、13、14 章 | OBS-009、PLT-011、CICD-003 |
| 安全 Security | 第 11 章 | SEC-001~SEC-020 |
| 可靠性 Reliability | 第 10 章、2.4 | NFR-007、RES-001~RES-022 |
| 效能效率 Performance Efficiency | 第 9 章 | PERF-001~PERF-021 |
| 成本最佳化 Cost Optimization | 2.5 | NFR-011~NFR-013 |
| 永續性 Sustainability | 2.5、9.5 | NFR-013、PERF-017 |
附錄 C 範本
以下範本為精簡版,可直接複製到專案的 docs/ 目錄使用。完整的填寫說明與範例請見 軟體開發標準程序教學手冊 的範本集。
C.1 ADR 範本(MADR 4.0)
完整版:架構決策紀錄範本
---
status: proposed # proposed | accepted | rejected | deprecated | superseded by ADR-NNNN
date: YYYY-MM-DD
decision-makers: 姓名(必須是人,見 AI-001)
consulted: 被諮詢的人或團隊
informed: 被通知的人或團隊
---
# ADR-NNNN 以一句話描述決策
## Context and Problem Statement
背景與要解決的問題。引用相關的品質情境(QS-xx)與限制條件。
## Decision Drivers
- 驅動因素 1(例如 QS-01 的效能目標)
- 驅動因素 2(例如團隊規模)
## Considered Options
- 選項 A
- 選項 B
## Decision Outcome
選擇「選項 A」,因為……
### Consequences
- 好處:……
- 壞處:……(必須列出,見 GOV-007)
### Confirmation
如何驗證此決策被落實:ArchUnit 測試名稱、CI 檢查、指標或演練(GOV-009)。
## Pros and Cons of the Options
### 選項 A
- 好處:……
- 壞處:……
### 選項 B
- 好處:……
- 壞處:……
## More Information
相關 ADR、規則豁免(0.6)、AI 協助的範圍(AI-008)。C.2 arc42 架構文件大綱
完整版:SAD 系統架構文件範本
docs/architecture/
├── 01-introduction-and-goals.md # 需求概要、品質目標(前 3–5 項)、利害關係人(必須)
├── 02-architecture-constraints.md # 技術、組織、法規限制(必須)
├── 03-context-and-scope.md # C4 System Context 圖、外部介面(必須)
├── 04-solution-strategy.md # 架構風格與關鍵技術決策摘要(必須)
├── 05-building-block-view.md # C4 Container/Component 圖(必須)
├── 06-runtime-view.md # 重要情境的循序圖(應該)
├── 07-deployment-view.md # 部署拓撲、環境、網路(必須)
├── 08-crosscutting-concepts.md # 安全、日誌、錯誤處理、交易、韌性(必須)
├── 09-architecture-decisions.md # 連結到 docs/adr/(必須)
├── 10-quality-requirements.md # 品質樹、品質情境、追溯表(必須)
├── 11-risks-and-technical-debt.md # 風險清單(應該)
├── 12-glossary.md # 名詞表(應該)
└── diagrams/ # Mermaid/Structurizr DSL 原始檔(GOV-012)C.3 品質情境與非功能需求規格
完整版:非功能性需求設計規格範本
## 品質情境
| 編號 | 品質屬性 | 來源 | 刺激 | 環境 | 標的 | 回應 | 回應量測 | 優先(重要性, 難度) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| QS-01 | 效能 | | | | | | p99 ≤ ___ ms,錯誤率 ≤ ___% | (H, M) |
## SLO
| 服務 | SLI(好事件 ÷ 全部事件) | 目標 | 期間 | 對外 SLA |
| --- | --- | --- | --- | --- |
| | | 99.9% | 28 天 | 99.5% |
## 追溯表
| 情境 | 架構決策(ADR) | 取捨點 | 驗證方式 | 驗證結果 |
| --- | --- | --- | --- | --- |
| QS-01 | | | | |C.4 威脅模型範本
完整版:威脅模型範本
# 威脅模型:<系統或功能名稱>
- 版本/日期:
- 參與者:架構師、開發、資安
- 範圍:本次分析涵蓋的元件與資料流
## 1. 資料流程圖
(Mermaid 圖,標示外部實體、處理程序、資料儲存、資料流與信任邊界)
## 2. 資產與資料分級
| 資產 | 資料等級(8.6) | 擁有者 |
| --- | --- | --- |
## 3. 威脅清單(STRIDE)
| 編號 | 元素/資料流 | STRIDE | 威脅描述 | 可能性 | 衝擊 | 處理方式(緩解/接受/轉移/避免) | 控制措施(規則編號) | 狀態 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
## 4. 已接受的風險
| 編號 | 理由 | 核准人 | 重新評估日期 |
| --- | --- | --- | --- |
## 5. 驗證
| 威脅編號 | 驗證方式(測試、掃描、演練) | 結果 |
| --- | --- | --- |附錄 D 參考標準與資源
D.1 國際標準
| 標準 | 名稱 | 本指引章節 |
|---|---|---|
| ISO/IEC/IEEE 42010:2022 | Software, systems and enterprise — Architecture description | 1.1、1.5 |
| ISO/IEC/IEEE 42020:2019 | Software, systems and enterprise — Architecture processes | 1.6 |
| ISO/IEC/IEEE 42030:2019 | Software, systems and enterprise — Architecture evaluation framework | 1.6、2.3 |
| ISO/IEC 25010:2023 | Systems and software Quality Requirements and Evaluation (SQuaRE) — Product quality model | 2.1 |
| ISO 22301:2019 | Security and resilience — Business continuity management systems — Requirements | 10.5 |
| NIST SP 800-207 | Zero Trust Architecture | 11.2 |
| NIST SP 800-207A | A Zero Trust Architecture Model for Access Control in Cloud-Native Applications in Multi-Location Environments | 11.2 |
| WCAG 2.2 | Web Content Accessibility Guidelines 2.2 | 6.4 |
| W3C Trace Context | 分散式追蹤內容傳遞 | 12.2 |
D.2 IETF 規格
| 規格 | 名稱 | 狀態(2026-10) | 本指引章節 |
|---|---|---|---|
| RFC 9457 | Problem Details for HTTP APIs | 標準(取代 RFC 7807) | 5.4 |
| RFC 9745 | The Deprecation HTTP Response Header Field | 標準(2025-03) | 5.6 |
| RFC 8594 | The Sunset HTTP Header Field | 資訊性 | 5.6 |
| RFC 9700 | Best Current Practice for OAuth 2.0 Security | BCP(2025-01) | 11.3 |
| draft-ietf-oauth-v2-1 | The OAuth 2.1 Authorization Framework | 草案 | 11.3 |
| draft-ietf-oauth-browser-based-apps | OAuth 2.0 for Browser-Based Applications | 草案 | 6.2 |
| draft-ietf-httpapi-ratelimit-headers | RateLimit header fields for HTTP | IESG 已核准,待發布 | 5.7 |
| draft-ietf-httpapi-idempotency-key-header | The Idempotency-Key HTTP Header Field | 草案 | 4.4 |
D.3 安全標準
| 標準 | 版本 | 本指引章節 |
|---|---|---|
| OWASP Top 10 | 2025 | 11.5 |
| OWASP API Security Top 10 | 2023 | 11.4、11.5 |
| OWASP ASVS | 5.0.0 | 11.1 |
| SLSA | 1.2 | 11.8 |
| Threat Modeling Manifesto | — | 11.1 |
D.4 架構方法與框架
| 資源 | 用途 | 本指引章節 |
|---|---|---|
| TOGAF Standard | 企業架構方法 | 1.1 |
| AWS Well-Architected Framework | 雲端架構最佳實務(6 大支柱) | 附錄 B.4 |
| Azure Well-Architected Framework | 雲端架構最佳實務(5 大支柱) | 1.1 |
| Google Cloud Well-Architected Framework | 雲端架構最佳實務 | 1.1 |
| arc42 | 架構文件範本 | 1.5、附錄 C.2 |
| C4 Model | 架構圖抽象層級 | 1.5 |
| MADR | ADR 格式 | 1.4、附錄 C.1 |
| SEI ATAM | 架構取捨分析方法 | 2.3 |
| Google SRE Workbook:Alerting on SLOs | 多視窗燃燒率告警 | 12.4 |
| DORA Metrics | 交付績效指標 | 14.5 |
| The Twelve-Factor App | 雲原生應用程式原則 | 13.4 |
| Strangler Fig Application | 漸進式遷移 | 3.5 |
| Transactional Outbox | 可靠的事件發布 | 4.4 |
D.5 技術文件
| 文件 | 本指引章節 |
|---|---|
| OpenAPI Specification 3.1.1/3.2.0 | 5.1 |
| AsyncAPI 3.1 | 4.6 |
| CloudEvents | 4.6 |
| Spring Modulith Reference | 3.2、4.4 |
| Spring Framework Resilience Features | 9.4、10.1 |
| Resilience4j | 10.1 |
| ArchUnit User Guide | 1.7、7.2 |
| OpenTelemetry Documentation | 12.1 |
| Kubernetes Pod Security Standards | 13.3、13.6 |
| Kubernetes Gateway API | 4.2 |
| Istio Ambient Mode | 4.3 |
| ShedLock | 15.3 |
D.6 企業內部相關指引
| 指引 | 關係 |
|---|---|
| 程式寫作指引 | 程式碼層級規範 |
| 系統設計指引 | 系統設計文件 |
| 安全程式碼指引 | 程式碼層級的安全寫法 |
| 資料庫設計指引 | 資料庫實體設計 |
| 前端開發指引 | 前端元件與程式寫法 |
| 測試與品質保證指引 | 測試方法 |
| 12-Factor App 說明與對應解決方案 | 雲原生應用程式原則 |
附錄 E 修訂紀錄與查證紀錄
E.1 版本紀錄
| 版本 | 日期 | 說明 |
|---|---|---|
| v1.x | 2025-10-31 | 初版:12 章,以微服務架構為預設,涵蓋分層、資料庫、效能、高可用、安全、監控、部署與治理 |
| v2.0 | 2026-10-07 | 全面改寫:依國際標準重新組織為 0–16 章與附錄 A–E;每條規則加上編號、等級、驗證方式與範例;每節加上「🔍 審查與驗證」;技術基準更新為 Java 25、Spring Boot 4.1、Kubernetes 1.37;範例經工具實測(E.4) |
E.2 v1.x 章節去向對照
| v1.x 章節 | v2.0 位置 | 說明 |
|---|---|---|
| 1.1 設計核心原則 | 1.2 | 改為附判斷標準的架構原則;SOLID 等程式碼層級原則移至程式寫作指引 |
| 1.2 技術選型原則 | 1.3 | 新增技術雷達與加權評估矩陣 |
| 1.3 架構品質屬性 | 2.1~2.4 | 改依 ISO/IEC 25010:2023;以品質情境與 SLO 取代平均值 |
| 2.1 微服務拆分策略 | 3.1、3.3、3.4 | 新增架構風格選擇流程;架構圖更新 |
| 2.2 API Gateway 設計 | 4.2 | 改以 Kubernetes Gateway API 為標準 |
| 2.3 服務間通訊 | 4.1 | 新增逾時預算 |
| 2.4 服務網格架構 | 4.3 | 新增 Istio Ambient 模式 |
| 3.1 微前端架構 | 6.3 | 新增採用條件 |
| 3.2 前端技術棧 | 6.1、前端開發指引 | 技術棧細節移至前端開發指引 |
| 3.3 響應式設計 | 6.4 | 新增 WCAG 2.2 |
| 3.4 多語系支援 | 6.5 | 新增時區處理 |
| 4.1~4.3 分層、目錄、依賴注入 | 7.1~7.5 | 新增 ArchUnit 架構測試 |
| 4.4 API 設計規範 | 第 5 章 | 獨立成章;改用 RFC 9457 與 Spring Framework 7 API 版本管理 |
| 5.1 多資料庫支援策略 | 8.7 | |
| 5.2 資料分片與讀寫分離 | 8.4 | 改用 LazyConnectionDataSourceProxy |
| 5.3 資料庫設計範例 | 8.2、資料庫設計指引 | |
| 5.4 資料遷移策略 | 8.5 | 新增 Expand–Contract 零停機變更 |
| 6.1~6.2 快取 | 9.2 | 新增 TTL、擊穿防護、故障降級 |
| 6.3 CDN 配置 | 9.3 | |
| 6.4 非同步處理 | 9.4 | 新增 Virtual Threads 與並行限制 |
| 6.5 負載平衡策略 | 9.5 | 改為 Kubernetes HPA 與優雅關機 |
| 6.6 效能基準測試 | 9.6 | k6 改為開放模型並以品質情境為門檻 |
| 7.1 高可用性架構 | 10.2 | |
| 7.2 容災切換策略 | 10.4 | 新增系統分級與 3-2-1-1-0 備份 |
| 7.3 健康檢查配置 | 10.3 | 分離 liveness 與 readiness |
| 7.4 業務連續性規劃(v1.x 目錄有、本文缺) | 10.5 | 新增,依 ISO 22301 |
| 8.1 OWASP Top 10 防護措施 | 11.5 | 更新為 2025 版 |
| 8.2 身分驗證與授權 | 11.3、11.4 | 改為 OIDC 資源伺服器;新增物件層級授權 |
| 8.3 API 安全防護 | 5.7、11.4 | |
| 8.4 資料加密與遮蔽 | 11.6、8.6 | |
| 9.1~9.4 監控、日誌、指標、告警 | 第 12 章 | 改以 OpenTelemetry 與 SLO 燃燒率告警 |
| 10.1 CI/CD 流程設計 | 14.1 | |
| 10.2 GitHub Actions 配置 | 14.2、11.8 | Actions 以 SHA 釘選;新增 SBOM 與簽章 |
| 10.3 Dockerfile 範例 | 13.1 | |
| 10.4 Kubernetes 部署配置 | 13.3 | |
| 10.5 測試策略 | 14.3 | |
| 總結(v1.x 位於第 10 與 11 章之間) | 結語 | 移至文末 |
| 11.1 容器化策略 | 13.1、13.2 | |
| 11.2 Kubernetes 進階配置 | 13.3~13.6 | |
| 11.3 雲端服務整合 | 11.2、11.6、12.1 | |
| 12.1 服務註冊與發現 | 15.1 | 改以 Kubernetes 原生機制為預設 |
| 12.2 配置管理 | 15.2 | |
| 12.3 服務間協調 | 15.3、4.4 | 修正分散式鎖與事件發布的正確性問題 |
E.3 v1.x 主要更正
| # | v1.x 內容 | 問題 | v2.0 修正 | 規則 |
|---|---|---|---|---|
| 1 | 目錄列出「7.4 業務連續性規劃」 | 本文沒有這一節 | 新增 10.5 業務連續性規劃 | RES-018~RES-020 |
| 2 | 「總結」位於第 10 與 11 章之間;第 11、12 章的子節不在目錄中 | 文件結構與目錄不一致 | 依 Hugo 實際錨點重建目錄;總結移至結語 | — |
| 3 | 品質屬性「API 平均回應 < 200ms」「CPU 使用率 < 80%」 | 平均值掩蓋長尾延遲;CPU 是原因指標,不是品質目標 | 以六段式品質情境與百分位數表示 | NFR-001、NFR-002 |
| 4 | 所有系統預設微服務,服務發現用 Eureka/Consul、負載平衡用 Ribbon | 未依規模選擇;Ribbon 已停止維護;Kubernetes 中不需要註冊中心 | 架構風格決策流程,預設模組化單體;Kubernetes 原生服務發現 | STY-002、MS-001、MS-002 |
| 5 | ApiResponse<T>{success, code, message, data} 包裝 | 錯誤也回 200,監控與重試失效 | RFC 9457 ProblemDetail 與正確狀態碼 | API-009、API-012 |
| 6 | API 版本以 /api/v1、/api/v2 複製 Controller | 重複程式;沒有棄用通知 | Spring Framework 7 API 版本管理,Deprecation/Sunset 標頭 | API-019、API-020 |
| 7 | Swagger 設定使用 Springfox 的 @EnableOpenApi 搭配 springdoc 的 OpenAPI 模型 | Springfox 已停止維護且不相容 Spring Boot 3 以上;兩者混用無法編譯 | API 優先的 OpenAPI 3.1 規格;springdoc 3.x,正式環境關閉 UI | API-001、API-026 |
| 8 | 「OWASP Top 10」未標示版本,對照內容為 2021 版分類 | 2025 版已發布,新增供應鏈與例外處理 | 更新為 OWASP Top 10:2025 與 API Security Top 10:2023 對照 | SEC-016~SEC-020 |
| 9 | 自行以 jjwt 簽發 HS512 權杖,金鑰寫成字串常數 "${app.jwt.secret}",有效期 24 小時 | 常數字串不會被 Spring 解析,金鑰實際上就是該字面值;自行實作身分驗證;權杖有效期過長;使用已棄用的 jjwt API | OIDC 資源伺服器驗證 iss、aud,存取權杖 ≤ 15 分鐘 | SEC-007、SEC-009 |
| 10 | 監控架構使用 Spring Cloud Sleuth | Sleuth 已停止開發,Spring Boot 3 起不支援 | Micrometer Tracing+OpenTelemetry | OBS-001、OBS-003 |
| 11 | logback-spring.xml 以檔案 appender 寫日誌 | 容器中應輸出到 stdout;格式非結構化 | Spring Boot 結構化日誌(ECS) | OBS-005 |
| 12 | GitHub Actions 使用 actions/checkout@v3、setup-java@v3、trivy-action@master、ubuntu-latest,映像標記 latest | 舊版本、可變標籤、執行環境不固定 | 以 commit SHA 釘選最新版本、固定 ubuntu-24.04、以 digest 部署 | SEC-018、CICD-006、SEC-017 |
| 13 | Dockerfile 使用 openjdk:21-jdk-slim、openjdk:21-jre-slim、maven:3.9-openjdk-21-slim | Docker 官方 openjdk 映像已棄用;查證當日三個標籤在 Docker Hub 皆回 404,v1.x 的 Dockerfile 無法建置 | eclipse-temurin:25-jre-noble 並以 digest 釘選 | PLT-001、PLT-002 |
| 14 | Deployment 的 liveness 探針指向 /actuator/health,映像使用 latest | 資料庫故障時所有 Pod 被重啟;部署內容不可重現 | liveness 只檢查 livenessState;映像以 digest 部署 | RES-010、PLT-002 |
| 15 | Secret 以 base64 寫在 YAML 並附明文註解 | base64 不是加密,且提交到版本庫 | External Secrets Operator 從 Vault 同步 | SEC-011 |
| 16 | external-secrets.io/v1beta1;SecretStore 以 AWS 存取金鑰驗證 | API 版本已被 v1 取代;長期金鑰 | external-secrets.io/v1;Workload Identity | SEC-006、SEC-011 |
| 17 | Ingress 使用 kubernetes.io/ingress.class 註解與 NGINX 專屬註解 | 註解已被 ingressClassName 取代;Ingress NGINX 已停止維護 | Kubernetes Gateway API | INT-006 |
| 18 | Consul 服務註冊、bootstrap.yml 連線 Config Server | Kubernetes 中不必要;bootstrap.yml 自 Spring Boot 2.4 起預設不再載入 | Kubernetes 原生服務發現;GitOps 管理組態 | MS-001、MS-003 |
| 19 | Redis setIfAbsent 分散式鎖搭配 AOP,用於保護業務操作 | 鎖過期後舊持有者仍可能寫入,無法保證正確性 | 排程以 ShedLock;正確性以防護權杖或唯一限制保證 | MS-005、MS-007 |
| 20 | 領域事件發布器同時呼叫 ApplicationEventPublisher 與 kafkaTemplate.send() | 雙寫問題:交易回滾時事件已送出、Kafka 失敗時事件遺失 | Spring Modulith Event Publication Registry(Transactional Outbox)、冪等消費者 | INT-012、INT-013 |
| 21 | 容錯設計只列為原則,沒有任何熔斷、逾時、重試的設定 | 原則無法落實 | Resilience4j 與 Spring Framework 7 韌性功能的完整設定 | INT-001、RES-001~RES-004 |
| 22 | k6 腳本以 vus 階段(封閉模型)壓測,門檻使用不存在的 http_req_rate 指標,網址寫死正式環境 | 封閉模型掩蓋吞吐量問題;k6 遇到不存在的指標門檻會直接報錯;可能誤壓正式環境 | 開放模型(ramping-arrival-rate)、以品質情境為門檻、網址由環境變數提供 | PERF-019 |
| 23 | nginx 設定標記為 yaml 程式碼區塊,監聽 80 埠、逾時 30 秒 | 語言標記錯誤;未加密;逾時過長 | 標記為 nginx;HTTPS 由 Gateway 終止;逾時預算 | INT-002、INT-007 |
E.4 查證紀錄
v2.0 的範例與宣稱於 2026-10-07 以下列工具實際執行驗證。「片段」範例(標示「(片段:…)」者,共 23 個)只用於示意,不在編譯範圍內。
| # | 項目 | 工具與版本 | 範圍 | 結果 |
|---|---|---|---|---|
| 1 | Java 編譯 | OpenJDK 25.0.4.1、Maven 3.9.9;Spring Boot 4.1.1、Spring Modulith 2.1.1、Resilience4j 2.4.0、ArchUnit 1.5.1、ShedLock 7.10.1、springdoc 3.1.1 | 44 個完整 Java 範例 | 編譯成功,-Xlint:all 零警告 |
| 2 | 架構與單元測試 | JUnit 5、ArchUnit、Spring Modulith | LayeringArchTest、PackageStructureArchTest、TransactionBoundaryArchTest、ModuleCycleArchTest、LegacyFreezeArchTest、ModularityTests、OrderTest | 全部通過 |
| 3 | 架構測試負向驗證 | 同上 | 故意加入 7 種違規:存取其他模組內部套件、領域層依賴 Spring、Controller 宣告交易、技術名詞套件、模組循環依賴、違反 allowedDependencies、新增欄位注入 | 7 種違規都讓測試失敗;Modulith 的錯誤訊息與 3.2 範例註解一致 |
| 4 | API 版本與棄用標頭 | MockMvc(Spring Framework 7.0.9) | 5.6 | 5.6 的回應標頭為實測輸出;發現 Sunset 依傳入時區輸出,範例改以 UTC 設定 |
| 5 | 結構化日誌 | Spring Boot 4.1.1 實際輸出 | 12.3 | 範例 JSON 的欄位結構與實際輸出一致;發現未設定 service.version 時會帶入無關版本號 |
| 6 | Spring 設定鍵 | Boot 4.1.1、Modulith 2.1.1、springdoc 3.1.1 的設定中繼資料;Resilience4j 屬性類別 | 所有 YAML/properties 範例中的 100 個鍵 | 全部存在且未棄用;唯一的棄用鍵位於 ❌ 範例 |
| 7 | Kubernetes 資源 | kubeconform 0.8.0(-strict、Kubernetes 1.37.1 schema、datreeio CRDs-catalog、Chaos Mesh 2.8.4 CRD) | 31 個資源:核心 API、Gateway API、Istio、Envoy Gateway、CloudNativePG、External Secrets、Argo CD、Argo Rollouts、ValidatingAdmissionPolicy、Chaos Mesh | 全部通過;負向測試確認拼錯的欄位會失敗 |
| 8 | Prometheus 規則 | promtool 3.15.0 | 12.4 | 11 條規則通過 |
| 9 | OpenTelemetry Collector | otelcol-contrib 0.162.0 validate | 12.1 | 通過,無棄用元件名稱警告 |
| 10 | GitHub Actions | actionlint 1.7.12 | 5.1、8.7、11.8、14.2 的 4 個工作流程 | 通過;❌ 範例如預期失敗 |
| 11 | OpenAPI | Redocly CLI 2.x;Spectral 6 搭配 5.2 的企業規則集 | 5.1 規格 | 有效;僅剩 example.com 伺服器的預期警告;企業規則集對 ❌ 路徑回報 error |
| 12 | AsyncAPI | AsyncAPI CLI | 4.6 | 3.1.0 有效,無治理問題 |
| 13 | SQL | PostgreSQL 18.6(podman) | 11 個 SQL 範例依序執行 | 全部成功;防護權杖、讀取模型冪等、應用程式帳號無 DDL 權限的斷言成立 |
| 14 | Dockerfile | hadolint 2.15.1 | 13.1 | ✅ 範例無發現;❌ 範例回報 DL3007、DL3064 |
| 15 | k6 | k6 2.3.0 | 9.6 | k6 inspect 通過;crypto.randomUUID() 可用;確認 v1.x 的 http_req_rate 門檻會讓 k6 報錯 |
| 16 | nginx | nginx stable-alpine nginx -t | 9.3、11.7 | 通過 |
| 17 | TypeScript | Node.js 24.16.0、zod 4.6.5 | 5.6、6.5 | 實際輸出與註解一致 |
| 18 | Shell、JSON、XML | bash -n、Python 解析 | 6 個腳本、7 個 JSON、2 個 XML | 通過 |
| 19 | Mermaid | @mermaid-js/mermaid-cli(實際渲染)、本站 test-mermaid-syntax.ps1 | 20 張圖 | mermaid-cli 12.0.0 全部渲染成功;過程中發現 2 張循序圖的訊息文字含半形分號 ;,Mermaid 會將其視為敘述分隔而解析失敗(本站腳本未偵測到),已修正 |
| 20 | 版本與識別值 | GitHub Releases API、Maven Central、Docker Hub API、Kubernetes KEP | 0.2 基準版本、Actions commit SHA、基底映像 digest、v1.x 映像標籤 | 範例中的版本、SHA、digest 為查證當日的實際值(13.3 的應用程式映像 digest 為示意值) |
| 21 | 目錄與連結 | Hugo 實際渲染後比對 | 243 個標題、724 個頁內連結、12 個 relref | 除主題內建的 #top 外全部可對應;relref 目標頁皆存在 |
| 22 | Markdown 格式 | 本站 check-md.ps1、check-toc.ps1;建置腳本 | 全文 | 0 問題;266 條規則全部有範例 |
E.5 待查項目
| # | 項目 | 說明 | 預計處理 |
|---|---|---|---|
| 1 | OpenAPI 3.2 | 3.2 已發布,但程式碼產生器與部分檢查工具尚未完整支援;工具鏈支援後再把撰寫基準改為 3.2(API-002) | 下次改版 |
| 2 | RateLimit 標頭 | IETF 草案已獲 IESG 核准,正式 RFC 發布後更新 5.7 的格式與 API-025 的等級 | RFC 發布時 |
| 3 | OAuth 2.1 | 仍為草案;成為 RFC 後更新 11.3 的引用 | RFC 發布時 |
| 4 | Spring Boot 4.2/Framework 7.1 | 4.2.0-M2、7.1.0-M2 已釋出;正式版發布後重新驗證 API 版本管理、HTTP Service Client 與 OpenTelemetry 屬性 | 正式版發布後 |
| 5 | Backstage 與 EncryptionConfiguration | Backstage 的 Component、Template 與 API Server 的 EncryptionConfiguration 沒有可供 kubeconform 使用的 schema,只以官方文件人工比對 | 找到可用 schema 時 |
| 6 | 整合測試未實際啟動 | TestcontainersConfig 只編譯;JdbcOrderRepository 的 SQL 以 psql 個別驗證,未以 Spring 整合測試執行 | 下次改版 |
| 7 | 服務網格與閘道行為 | Istio AuthorizationPolicy、Envoy Gateway 限流只做 schema 驗證,未在實際叢集驗證行為 | 有測試叢集時 |
| 8 | 片段範例 | 23 個片段(Pact 契約測試、微前端 Vite 設定等)未編譯 | 依需要補成完整範例 |
| 9 | 法規條文 | 2.2 的個資法、資通安全管理法只列出原則性要求,未引用條號 | 與法務確認後補充 |
結語
架構不是一次性的設計成果,而是一連串持續被驗證的決策。本指引希望達成三件事:
- 決策有依據:每個重要決策都能追溯到品質情境與 ADR,而不是「大家都這樣做」。
- 規則可驗證:每條規則都附有範例與驗證方式;能自動化的規則由 CI 與准入政策守住,不能自動化的規則由「🔍 審查與驗證」的問題引導人工審查。
- AI 產出可審查:AI 可以加速草稿與樣板的產生,但版本、設定鍵、數字與取捨必須由人查證與負責(第 16 章)。
本指引會隨技術基準(0.2)與國際標準更新。發現規則不合時宜、範例錯誤或有新的需求時,請以 PR 提出修改,並在附錄 E 記錄變更與查證結果。