系統架構設計指引

企業標準技術白皮書|版本 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. 文件資訊

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 LTS21 LTS25 起 Virtual Threads 不再因 synchronized 釘住載體執行緒(JEP 491,Java 24)
框架Spring Boot4.1.13.5.x3.5 的開源支援至 2026-06 結束,新專案一律用 4.x
框架Spring Framework7.0.96.2.x7.0 起內建 @Retryable、@ConcurrencyLimit
框架Spring Cloud2025.1.32025.0.x對應 Boot 4.0/4.1
框架Spring Modulith2.1.11.4.x模組化單體的邊界驗證
韌性Resilience4j2.4.02.3.0Boot 4 使用 resilience4j-spring-boot4
測試ArchUnit1.5.11.3.x架構規則自動化測試
資料庫遷移Flyway13.910.x
容器平台Kubernetes1.37.11.351.37 的 API 版本見第 13 章
網路Gateway API1.6.31.2取代 Ingress 的新一代 API
服務網格Istio1.31.11.29Ambient 模式已 GA
可觀測性OpenTelemetry Collector0.162.0—Java Agent 2.32.0
監控Prometheus3.15.03.13 LTS
API 規格OpenAPI3.1.1(撰寫)/3.2.1(已發布)3.0.3工具鏈支援 3.2 前仍以 3.1 撰寫,見 5.1
事件規格AsyncAPI/CloudEvents3.1.0/1.0.23.0/1.0
安全標準OWASP Top 10/ASVS2025/5.0.0—
供應鏈SLSA1.21.01.2 新增 Source Track

0.3 規範等級與規則格式

本文規則採用 RFC 2119 與 RFC 8174 的語意:

等級英文意義架構審查處理
必須MUST不遵守會造成重大風險(資安、資料遺失、無法維運)不通過審查;如需例外必須走 0.6 豁免流程
應該SHOULD業界共識的最佳實務,除非有充分理由不遵守時必須在 ADR 中記錄理由
可以MAY建議做法,依系統規模與情境選用不阻擋
不應該SHOULD NOT通常是錯誤的做法,除非有充分理由採用時必須在 ADR 中記錄理由

每條規則都有編號,格式為 <領域>-<三位數序號>,方便在架構審查、ADR 與豁免單中引用。編號一經發布不會重編,新增規則使用該領域尚未使用的號碼。

前綴領域章前綴領域章
GOV架構治理1PERF效能與擴展性9
NFR品質屬性與非功能需求2RES韌性與災難復原10
STY架構風格與拆分3SEC安全架構11
INT整合與通訊4OBS可觀測性12
APIAPI 設計5PLT容器與部署平台13
FE前端架構6CICD持續整合與交付14
BE後端分層架構7MS微服務治理15
DATA資料架構8AIAI 輔助架構設計16

驗證方式欄位: 每張規則表的最後一欄說明「怎麼確認設計符合這條規則」。審查者應先看這一欄,再決定要花多少心力人工檢查。

圖示意義範例審查者該做什麼
🤖工具可自動檢查🤖 ArchUnit、🤖 kubeconform、🤖 Spectral確認 CI 有執行該工具且沒有被停用或略過
🧪需要以測試或演練證明🧪 Testcontainers 整合測試、🧪 故障演練確認有對應的測試或演練紀錄,而且規則被違反時測試會失敗
👁只能由人判斷👁 架構審查依該節「🔍 審查與驗證」的問題逐項確認

範例標記: 範例中以 ✅ <規則編號> 標示符合規則的寫法,以 ❌ <規則編號> 標示違規寫法。所有規則都至少出現在一個範例中(統計見 附錄 A)。

0.4 與其他指引的關係

本指引處理「系統層級」的決策。下列主題另有專門指引,本文只列出與架構相關的要求並連結過去:

主題指引本文的分工
程式碼寫法、命名、例外處理程式寫作指引本文只定義分層與模組邊界,第 7 章
系統設計文件、物件導向設計系統設計指引本文提供架構決策的規則與檢核
安全程式碼安全程式碼指引本文處理安全架構,第 11 章
資料庫實體設計資料庫設計指引本文處理資料架構,第 8 章
測試方法測試與品質保證指引本文只定義架構測試與測試分層,第 7、14 章
開發流程與文件範本軟體開發標準程序教學手冊本文的 ADR/SAD 範本與該手冊的範本共用,附錄 C

0.5 如何閱讀本指引

每一節都依相同的結構撰寫,閱讀與審查時可以直接跳到需要的部分:

  1. 概念說明:為什麼需要這個設計、有哪些選項。
  2. 規則表:編號、等級、規則內容、驗證方式。
  3. 範例:✅ 正確寫法與 ❌ 常見錯誤,範例中標註規則編號。
  4. 🔍 審查與驗證:自動檢查指令、人工審查問題、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 例外與豁免流程

規則不可能涵蓋所有情境。專案無法遵守某條「必須」規則時,依下列流程申請豁免,不得直接忽略:

  1. 撰寫一份 ADR(格式見 1.4),標題寫明豁免的規則編號,說明原因、替代控制措施與到期日。
  2. 由架構審查委員會(或指定的架構師)核准,並記錄核准人與日期。
  3. 到期前重新評估;到期未處理的豁免,在下一次架構審查視為不通過。
# ADR-0042 豁免 RES-006:報表服務以單一副本執行

- 狀態:accepted(有效至 2027-03-31)
- 豁免規則:RES-006(正式環境線上服務至少 3 個副本並跨 AZ)
- 原因:報表服務為單一副本的批次工作,夜間執行,白天不提供服務。
- 替代控制:批次工作可重跑(冪等),失敗時由排程系統告警並自動重試。
- 核准:架構審查委員會,2026-10-07

1. 架構治理與國際標準

架構治理的目的不是產生文件,而是讓「重要的決策」被看見、被討論、被記錄、被驗證。本章定義企業採用的國際標準、架構原則、決策紀錄方式,以及如何用自動化測試守住架構。

1.1 國際標準與參考框架

本指引參考下列標準與框架。它們的定位不同,不需要「全部導入」,但團隊應該知道每一項解決什麼問題:

標準/框架版本解決的問題本指引的對應
ISO/IEC/IEEE 420102022架構描述(Architecture Description)應包含哪些元素1.5 架構文件
ISO/IEC/IEEE 420202019架構相關流程(治理、管理、概念化、評估、精化)1.6 架構審查流程
ISO/IEC/IEEE 420302019架構評估的框架1.6、2.3
ISO/IEC 250102023產品品質模型(9 項品質特性)第 2 章
TOGAF Standard第 10 版企業架構方法(ADM)與架構內容框架企業層級;本指引聚焦解決方案架構
AWS Well-Architected2026 更新雲端工作負載的 6 大支柱(卓越營運、安全、可靠性、效能效率、成本最佳化、永續性)附錄 B 檢核表
Azure Well-Architected持續更新5 大支柱(可靠性、安全、成本最佳化、卓越營運、效能效率)附錄 B 檢核表
SEI ATAM—以品質屬性情境評估架構取捨2.3
arc42第 9 版範本架構文件的 12 個章節結構1.5
C4 Model—以 4 個抽象層級繪製架構圖1.5
MADR4.0.0ADR 的 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 DecisionsADR 清單(連結到 docs/adr/)必須1.4
10. Quality Requirements品質樹與品質情境必須2.3
11. Risks and Technical Debts已知風險與技術債應該1.6
12. Glossary業務與技術名詞應該3.3 通用語言

C4 模型的四個層級:

層級名稱回答的問題讀者必要程度
1System Context系統和誰互動?所有人,包括非技術人員必須
2Container系統由哪些可部署/可執行的單元組成?用什麼技術?如何通訊?開發、維運、資安必須
3Component一個容器內部由哪些元件組成?開發選用(複雜容器才畫)
4Code類別層級的結構開發不建議手繪,由 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" --> idp

C4 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)資源用量低、升級不需重啟應用 PodL7 功能需要部署 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-bff

Ambient 模式下,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 契約

服務之間的介面就是契約。契約變更若破壞相容性,會讓其他服務在執行時失敗。

契約類型規格標準相容性檢查工具
同步 APIOpenAPI 3.1(第 5 章)oasdiff、Spectral
非同步事件AsyncAPI 3.x、CloudEvents 1.0Schema Registry 相容性檢查
事件資料結構JSON Schema、Avro、ProtobufSchema 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.x2017仍被廣泛支援
3.1.x2021(3.1.1 於 2024-10)與 JSON Schema 2020-12 完全相容;主流工具已支援,本指引的撰寫基準
3.2.x2025-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-reference

CI 檢查(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 /ordersPOST /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}/cancellationPOST /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 固定)庫存不足
statusHTTP 狀態碼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)。

人工審查問題:

  • 錯誤類型清單(type URI)是否寫在 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_idv2是
4. 切換讀取—v3 讀寫 buyer_id,仍寫 customer_id是
5. 收縮移除 customer_id、buyer_id 設為 NOT NULLv4 只用 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 Threads
package 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: 0
package 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)可接受遺失的最大資料量(以時間表示)「最多可以遺失多少分鐘的資料?」

系統依業務影響分級,每一級對應不同的災難復原策略與成本:

等級範例RTORPO策略相對成本
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:2025Broken Access Control(含 SSRF)預設拒絕、物件層級授權、Egress 白名單SEC-003、SEC-008、SEC-005
A02:2025Security Misconfiguration設定即程式碼、准入政策、關閉不必要端點RES-013、API-026、PLT-013、PLT-011
A03:2025Software Supply Chain FailuresSBOM、相依掃描、簽章與來源證明、釘選版本SEC-016~SEC-018
A04:2025Cryptographic FailuresTLS、靜態加密、金鑰管理SEC-012~SEC-014
A05:2025Injection參數化查詢、輸入驗證、輸出編碼DATA-004、API-024
A06:2025Insecure Design威脅建模、品質情境、ADRSEC-001、NFR-001、GOV-006
A07:2025Authentication FailuresOIDC、PKCE、權杖驗證SEC-007、SEC-009
A08:2025Software or Data Integrity Failures映像簽章驗證、事件結構相容性SEC-017、INT-020
A09:2025Logging & Alerting Failures稽核日誌、安全事件告警SEC-019、OBS-008
A10:2025Mishandling of Exceptional Conditions失效時安全(fail closed)、統一錯誤處理SEC-020、API-014

OWASP API Security Top 10:2023 中與架構最相關的項目:

編號風險架構控制
API1Broken Object Level AuthorizationSEC-008
API2Broken AuthenticationSEC-007、SEC-009
API3Broken Object Property Level Authorization回應 DTO 只包含允許的欄位、輸入 DTO 白名單(大量指派)
API4Unrestricted Resource ConsumptionAPI-016、API-023、API-024
API5Broken Function Level AuthorizationSEC-010
API6Unrestricted Access to Sensitive Business Flows業務流程限流(每使用者下單上限)、機器人防護
API7Server Side Request ForgeryEgress 白名單(SEC-005)、禁止使用者提供任意網址
API8Security MisconfigurationRES-013、API-026
API9Improper Inventory Management服務目錄(STY-014)、API 版本與棄用(API-021)
API10Unsafe 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-Securitymax-age=31536000; includeSubDomains強制 HTTPS,防止降級攻擊
Content-Security-Policy依應用程式設定,至少 default-src 'self'; frame-ancestors 'none'; object-src 'none'XSS、點擊劫持
X-Content-Type-OptionsnosniffMIME 類型混淆
Referrer-Policystrict-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)定義了兩條軌道:

軌道等級要求重點
BuildL1產生建置來源證明(provenance)
BuildL2由代管的建置平台產生並簽署來源證明
BuildL3建置平台強化:建置之間互相隔離,簽章金鑰無法被建置流程存取
SourceL1–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 ContextSpring Boot 4 Micrometer Tracing → OTLP → Collector → 追蹤後端
指標(Metrics)系統整體的趨勢與健康狀態?Prometheus、OpenMetrics、OTLPMicrometer → /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_balancing exporter(以 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 天的預算:

嚴重度長視窗短視窗燃燒率錯誤率門檻意義
page1 小時5 分鐘14.41.44%1 小時內耗用 2% 的預算
page6 小時30 分鐘60.6%6 小時內耗用 5% 的預算
ticket1 天2 小時30.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 AdmissionKubernetes 內建,以命名空間標籤套用 privileged/baseline/restricted 三個等級所有叢集的基本安全設定
ValidatingAdmissionPolicyKubernetes 內建(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,不需要額外的註冊中心。

環境建議的服務發現說明
全部在 KubernetesKubernetes 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 Dockerfile

Spring 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
架構風格所有服務共用一個資料庫每個服務擁有自己的 schemaSTY-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
APIApiResponse<T> 包裝並一律回 200RFC 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 存在 localStorageBFF 保管權杖、HttpOnly CookieFE-003
資料以 ddl-auto=update 管理結構、修改已套用的遷移腳本Flyway 版本化遷移、Expand–ContractDATA-011、DATA-012
分散式鎖SETNX 保證正確性資料層的防護權杖或唯一限制MS-007
Kubernetes舊 API 版本、沒有 securityContext、latest 標籤1.37 API、restricted、digestPLT-006、PLT-015
CI/CDActions 以標籤引用、沒有 permissionscommit 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架構治理11811700
NFR品質屬性與非功能需求2138500
STY架構風格與拆分3168701
INT整合與通訊42212901
APIAPI 設計52718810
FE前端架構6138500
BE後端分層架構7139301
DATA資料架構82014600
PERF效能與擴展性92115501
RES韌性與災難復原102218400
SEC安全架構112019100
OBS可觀測性121311200
PLT容器與部署平台131613300
CICD持續整合與交付14138500
MS微服務治理15117301
AIAI 輔助架構設計1686200
合計2661857515

A.2 驗證方式與範例覆蓋

依各規則表的「驗證方式」欄統計(圖示定義見 0.3)。一條規則可同時有多種驗證方式;「僅人工」表示沒有工具或測試可以替代人工判斷,審查時請特別依照各節「🔍 審查與驗證」的問題確認。

前綴規則數🤖 工具檢查🧪 測試或演練👁 僅人工有範例
GOV18701118
NFR1331913
STY1646616
INT2287722
API271014627
FE1352613
BE1391313
DATA2067820
PERF21413721
RES22410822
SEC2088420
OBS1374413
PLT16102416
CICD1391413
MS1132611
AI83058
合計2661007898266

「有範例」指規則編號出現在至少一個範例(程式碼區塊)的 ✅/❌ 標記中,由建置腳本自動檢查。

A.3 規則清單

編號等級規則所在章節
GOV-001必須每項架構原則都必須附上「如何判斷有沒有做到」的可觀察標準;不接受只有口號的原則1.2
GOV-002應該引入複雜機制(分散式交易、分片、CQRS、Service Mesh、多區域部署)前,必須以 ADR 說明當下的需求與更簡單的替代方案為何不足1.2
GOV-003必須新專案只能使用技術雷達 Adopt 或 Trial 環的技術;使用 Trial 環技術必須有 ADR1.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-NNNN1.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必須每個服務在服務目錄中登錄唯一的擁有團隊、聯絡方式與 SLO3.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 不得包含業務邏輯(業務規則判斷、資料彙整、資料格式轉換);需要為特定前端彙整資料時使用 BFF4.2
INT-006應該新的 Kubernetes 叢集以 Gateway API 取代 Ingress;平台團隊管理 Gateway,應用團隊只管理自己命名空間的 HTTPRoute4.2
INT-007必須對外的 Gateway 只接受 HTTPS;HTTP 只用於導向 HTTPS4.2
INT-008應該每個 HTTPRoute 規則設定請求逾時,與 4.1 的逾時預算一致4.2
INT-009應該只有在需要「所有服務間 mTLS」或「跨多個服務一致的 L7 流量/授權政策」時才導入服務網格,並以 ADR 記錄;服務少於 10 個時優先考慮應用層函式庫與 NetworkPolicy4.3
INT-010必須導入服務網格時,mTLS 必須設為 STRICT,不得長期停留在 PERMISSIVE4.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 而不是 4035.3
API-012必須所有錯誤回應採用 RFC 9457 格式(application/problem+json),並啟用 spring.mvc.problemdetails.enabled5.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 時間不得早於 Deprecation5.6
API-021應該對外 API 的棄用期至少 6 個月,內部 API 至少一個發布週期;期間監控舊版本的呼叫量,歸零或屆期才下線5.6
API-022應該用戶端必須忽略不認得的回應欄位(容錯讀取,Tolerant Reader)5.6
API-023必須對外 API 必須設定速率限制(依用戶端或使用者),超過時回 429 並附 Retry-After5.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 或 SSG6.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,只有需要被其他套件使用的類別才宣告為 public7.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.getProperty7.5
BE-011必須交易邊界設在應用層的 Use Case 方法;Controller 與領域層不得宣告 @Transactional7.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-migrate8.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/RPO10.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 不得大於依賴它的系統的 RTO10.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 311.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.311.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.name12.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 等於 limits13.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: true13.3
PLT-007必須優雅關機:preStop 先等待數秒讓負載平衡器移除端點,terminationGracePeriodSeconds 大於 preStop 等待加上應用程式的關機等待時間(PERF-016)13.3
PLT-008必須不需要呼叫 Kubernetes API 的工作負載設定 automountServiceAccountToken: false,並使用專屬的 ServiceAccount13.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-002arc42 第 10 章
2品質目標是否排序,前 3–5 項寫入 arc42 第 1 章?NFR-003arc42 第 1 章
3法規要求是否列為品質需求?NFR-004合規需求表
4每個品質情境是否追溯到架構決策與驗證方式?NFR-006追溯表
5SLO 是否定義,並考慮相依元件的串聯可用性?NFR-007、NFR-008SLO 檔、可用性計算
6架構風格的選擇是否有 ADR,並符合 3.1 的決策流程?STY-001、STY-002ADR
7是否有 C4 Context 與 Container 圖,連線有協定與同步/非同步說明?GOV-011、GOV-013架構圖
8每個複雜機制(Kafka、CQRS、Service Mesh、分片、多區域)是否有 ADR?GOV-002ADR 清單
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-019BIA、DR 計畫
15單點故障清單是否完整?RES-009單點故障清單
16技術選型是否只使用技術雷達 Adopt/Trial 環的技術,且沒有 EOL 版本?GOV-003、GOV-004SBOM、技術雷達

B.2 實作審查(抽查)

#檢核項目規則證據
1架構測試(ArchUnit、Modulith)是否存在並在 CI 執行?GOV-017、BE-007、STY-004CI 測試報告
2領域層是否沒有框架相依?BE-002LayeringArchTest
3交易內是否沒有遠端呼叫?BE-012程式碼審查、連線持有時間指標
4API 錯誤是否使用 ProblemDetail、正確狀態碼?API-009、API-012API 測試
5OpenAPI 規格是否先行、lint 與破壞性變更檢查是否在 CI?API-001、API-003CI 設定
6遠端呼叫是否有熔斷、重試只用於冪等操作?RES-001、RES-002設定、故障注入測試
7消費者是否冪等?INT-013重複投遞測試
8遷移腳本是否向後相容?DATA-011、DATA-012遷移腳本 PR
9日誌是否結構化、含 traceId、沒有個資?OBS-005日誌樣本
10機密是否沒有出現在版本庫與映像中?SEC-011gitleaks、Trivy 報告

B.3 上線審查

#檢核項目規則證據
1負載測試是否以品質情境作為門檻並通過?PERF-019、PERF-020、GOV-015k6/Gatling 報告
2故障演練(熔斷、AZ 失效、資料庫容錯移轉)是否執行並達標?RES-016、RES-021演練紀錄
3還原演練是否在最近一季內執行,實際 RTO/RPO 是否達標?RES-015、RES-016還原測試報告
4健康檢查是否正確分離 liveness 與 readiness?RES-010、RES-011Deployment 設定、故障注入結果
5副本數、跨 AZ 分散與 PDB 是否設定?RES-006、RES-007Deployment、PDB
6安全設定是否符合 restricted?NetworkPolicy 是否預設拒絕?PLT-006、PLT-013、SEC-005命名空間標籤、政策
7映像是否簽章並以 digest 部署?SBOM 與弱點掃描是否通過?SEC-016、SEC-017簽章驗證、掃描報告
8SLO 告警與 runbook 是否就緒?安全事件是否有告警?OBS-008、OBS-009、OBS-011告警規則、runbook
9回退方案是否驗證過?CICD-012回退演練紀錄
10正式環境部署是否透過 GitOps?PLT-011Argo 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.4NFR-007、RES-001~RES-022
效能效率 Performance Efficiency第 9 章PERF-001~PERF-021
成本最佳化 Cost Optimization2.5NFR-011~NFR-013
永續性 Sustainability2.5、9.5NFR-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:2022Software, systems and enterprise — Architecture description1.1、1.5
ISO/IEC/IEEE 42020:2019Software, systems and enterprise — Architecture processes1.6
ISO/IEC/IEEE 42030:2019Software, systems and enterprise — Architecture evaluation framework1.6、2.3
ISO/IEC 25010:2023Systems and software Quality Requirements and Evaluation (SQuaRE) — Product quality model2.1
ISO 22301:2019Security and resilience — Business continuity management systems — Requirements10.5
NIST SP 800-207Zero Trust Architecture11.2
NIST SP 800-207AA Zero Trust Architecture Model for Access Control in Cloud-Native Applications in Multi-Location Environments11.2
WCAG 2.2Web Content Accessibility Guidelines 2.26.4
W3C Trace Context分散式追蹤內容傳遞12.2

D.2 IETF 規格

規格名稱狀態(2026-10)本指引章節
RFC 9457Problem Details for HTTP APIs標準(取代 RFC 7807)5.4
RFC 9745The Deprecation HTTP Response Header Field標準(2025-03)5.6
RFC 8594The Sunset HTTP Header Field資訊性5.6
RFC 9700Best Current Practice for OAuth 2.0 SecurityBCP(2025-01)11.3
draft-ietf-oauth-v2-1The OAuth 2.1 Authorization Framework草案11.3
draft-ietf-oauth-browser-based-appsOAuth 2.0 for Browser-Based Applications草案6.2
draft-ietf-httpapi-ratelimit-headersRateLimit header fields for HTTPIESG 已核准,待發布5.7
draft-ietf-httpapi-idempotency-key-headerThe Idempotency-Key HTTP Header Field草案4.4

D.3 安全標準

標準版本本指引章節
OWASP Top 10202511.5
OWASP API Security Top 10202311.4、11.5
OWASP ASVS5.0.011.1
SLSA1.211.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
MADRADR 格式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.05.1
AsyncAPI 3.14.6
CloudEvents4.6
Spring Modulith Reference3.2、4.4
Spring Framework Resilience Features9.4、10.1
Resilience4j10.1
ArchUnit User Guide1.7、7.2
OpenTelemetry Documentation12.1
Kubernetes Pod Security Standards13.3、13.6
Kubernetes Gateway API4.2
Istio Ambient Mode4.3
ShedLock15.3

D.6 企業內部相關指引

指引關係
程式寫作指引程式碼層級規範
系統設計指引系統設計文件
安全程式碼指引程式碼層級的安全寫法
資料庫設計指引資料庫實體設計
前端開發指引前端元件與程式寫法
測試與品質保證指引測試方法
12-Factor App 說明與對應解決方案雲原生應用程式原則

附錄 E 修訂紀錄與查證紀錄

E.1 版本紀錄

版本日期說明
v1.x2025-10-31初版:12 章,以微服務架構為預設,涵蓋分層、資料庫、效能、高可用、安全、監控、部署與治理
v2.02026-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.6k6 改為開放模型並以品質情境為門檻
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.8Actions 以 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
5ApiResponse<T>{success, code, message, data} 包裝錯誤也回 200,監控與重試失效RFC 9457 ProblemDetail 與正確狀態碼API-009、API-012
6API 版本以 /api/v1、/api/v2 複製 Controller重複程式;沒有棄用通知Spring Framework 7 API 版本管理,Deprecation/Sunset 標頭API-019、API-020
7Swagger 設定使用 Springfox 的 @EnableOpenApi 搭配 springdoc 的 OpenAPI 模型Springfox 已停止維護且不相容 Spring Boot 3 以上;兩者混用無法編譯API 優先的 OpenAPI 3.1 規格;springdoc 3.x,正式環境關閉 UIAPI-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 APIOIDC 資源伺服器驗證 iss、aud,存取權杖 ≤ 15 分鐘SEC-007、SEC-009
10監控架構使用 Spring Cloud SleuthSleuth 已停止開發,Spring Boot 3 起不支援Micrometer Tracing+OpenTelemetryOBS-001、OBS-003
11logback-spring.xml 以檔案 appender 寫日誌容器中應輸出到 stdout;格式非結構化Spring Boot 結構化日誌(ECS)OBS-005
12GitHub 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
13Dockerfile 使用 openjdk:21-jdk-slim、openjdk:21-jre-slim、maven:3.9-openjdk-21-slimDocker 官方 openjdk 映像已棄用;查證當日三個標籤在 Docker Hub 皆回 404,v1.x 的 Dockerfile 無法建置eclipse-temurin:25-jre-noble 並以 digest 釘選PLT-001、PLT-002
14Deployment 的 liveness 探針指向 /actuator/health,映像使用 latest資料庫故障時所有 Pod 被重啟;部署內容不可重現liveness 只檢查 livenessState;映像以 digest 部署RES-010、PLT-002
15Secret 以 base64 寫在 YAML 並附明文註解base64 不是加密,且提交到版本庫External Secrets Operator 從 Vault 同步SEC-011
16external-secrets.io/v1beta1;SecretStore 以 AWS 存取金鑰驗證API 版本已被 v1 取代;長期金鑰external-secrets.io/v1;Workload IdentitySEC-006、SEC-011
17Ingress 使用 kubernetes.io/ingress.class 註解與 NGINX 專屬註解註解已被 ingressClassName 取代;Ingress NGINX 已停止維護Kubernetes Gateway APIINT-006
18Consul 服務註冊、bootstrap.yml 連線 Config ServerKubernetes 中不必要;bootstrap.yml 自 Spring Boot 2.4 起預設不再載入Kubernetes 原生服務發現;GitOps 管理組態MS-001、MS-003
19Redis 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
22k6 腳本以 vus 階段(封閉模型)壓測,門檻使用不存在的 http_req_rate 指標,網址寫死正式環境封閉模型掩蓋吞吐量問題;k6 遇到不存在的指標門檻會直接報錯;可能誤壓正式環境開放模型(ramping-arrival-rate)、以品質情境為門檻、網址由環境變數提供PERF-019
23nginx 設定標記為 yaml 程式碼區塊,監聽 80 埠、逾時 30 秒語言標記錯誤;未加密;逾時過長標記為 nginx;HTTPS 由 Gateway 終止;逾時預算INT-002、INT-007

E.4 查證紀錄

v2.0 的範例與宣稱於 2026-10-07 以下列工具實際執行驗證。「片段」範例(標示「(片段:…)」者,共 23 個)只用於示意,不在編譯範圍內。

#項目工具與版本範圍結果
1Java 編譯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.144 個完整 Java 範例編譯成功,-Xlint:all 零警告
2架構與單元測試JUnit 5、ArchUnit、Spring ModulithLayeringArchTest、PackageStructureArchTest、TransactionBoundaryArchTest、ModuleCycleArchTest、LegacyFreezeArchTest、ModularityTests、OrderTest全部通過
3架構測試負向驗證同上故意加入 7 種違規:存取其他模組內部套件、領域層依賴 Spring、Controller 宣告交易、技術名詞套件、模組循環依賴、違反 allowedDependencies、新增欄位注入7 種違規都讓測試失敗;Modulith 的錯誤訊息與 3.2 範例註解一致
4API 版本與棄用標頭MockMvc(Spring Framework 7.0.9)5.65.6 的回應標頭為實測輸出;發現 Sunset 依傳入時區輸出,範例改以 UTC 設定
5結構化日誌Spring Boot 4.1.1 實際輸出12.3範例 JSON 的欄位結構與實際輸出一致;發現未設定 service.version 時會帶入無關版本號
6Spring 設定鍵Boot 4.1.1、Modulith 2.1.1、springdoc 3.1.1 的設定中繼資料;Resilience4j 屬性類別所有 YAML/properties 範例中的 100 個鍵全部存在且未棄用;唯一的棄用鍵位於 ❌ 範例
7Kubernetes 資源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全部通過;負向測試確認拼錯的欄位會失敗
8Prometheus 規則promtool 3.15.012.411 條規則通過
9OpenTelemetry Collectorotelcol-contrib 0.162.0 validate12.1通過,無棄用元件名稱警告
10GitHub Actionsactionlint 1.7.125.1、8.7、11.8、14.2 的 4 個工作流程通過;❌ 範例如預期失敗
11OpenAPIRedocly CLI 2.x;Spectral 6 搭配 5.2 的企業規則集5.1 規格有效;僅剩 example.com 伺服器的預期警告;企業規則集對 ❌ 路徑回報 error
12AsyncAPIAsyncAPI CLI4.63.1.0 有效,無治理問題
13SQLPostgreSQL 18.6(podman)11 個 SQL 範例依序執行全部成功;防護權杖、讀取模型冪等、應用程式帳號無 DDL 權限的斷言成立
14Dockerfilehadolint 2.15.113.1✅ 範例無發現;❌ 範例回報 DL3007、DL3064
15k6k6 2.3.09.6k6 inspect 通過;crypto.randomUUID() 可用;確認 v1.x 的 http_req_rate 門檻會讓 k6 報錯
16nginxnginx stable-alpine nginx -t9.3、11.7通過
17TypeScriptNode.js 24.16.0、zod 4.6.55.6、6.5實際輸出與註解一致
18Shell、JSON、XMLbash -n、Python 解析6 個腳本、7 個 JSON、2 個 XML通過
19Mermaid@mermaid-js/mermaid-cli(實際渲染)、本站 test-mermaid-syntax.ps120 張圖mermaid-cli 12.0.0 全部渲染成功;過程中發現 2 張循序圖的訊息文字含半形分號 ;,Mermaid 會將其視為敘述分隔而解析失敗(本站腳本未偵測到),已修正
20版本與識別值GitHub Releases API、Maven Central、Docker Hub API、Kubernetes KEP0.2 基準版本、Actions commit SHA、基底映像 digest、v1.x 映像標籤範例中的版本、SHA、digest 為查證當日的實際值(13.3 的應用程式映像 digest 為示意值)
21目錄與連結Hugo 實際渲染後比對243 個標題、724 個頁內連結、12 個 relref除主題內建的 #top 外全部可對應;relref 目標頁皆存在
22Markdown 格式本站 check-md.ps1、check-toc.ps1;建置腳本全文0 問題;266 條規則全部有範例

E.5 待查項目

#項目說明預計處理
1OpenAPI 3.23.2 已發布,但程式碼產生器與部分檢查工具尚未完整支援;工具鏈支援後再把撰寫基準改為 3.2(API-002)下次改版
2RateLimit 標頭IETF 草案已獲 IESG 核准,正式 RFC 發布後更新 5.7 的格式與 API-025 的等級RFC 發布時
3OAuth 2.1仍為草案;成為 RFC 後更新 11.3 的引用RFC 發布時
4Spring Boot 4.2/Framework 7.14.2.0-M2、7.1.0-M2 已釋出;正式版發布後重新驗證 API 版本管理、HTTP Service Client 與 OpenTelemetry 屬性正式版發布後
5Backstage 與 EncryptionConfigurationBackstage 的 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 的個資法、資通安全管理法只列出原則性要求,未引用條號與法務確認後補充

結語

架構不是一次性的設計成果,而是一連串持續被驗證的決策。本指引希望達成三件事:

  1. 決策有依據:每個重要決策都能追溯到品質情境與 ADR,而不是「大家都這樣做」。
  2. 規則可驗證:每條規則都附有範例與驗證方式;能自動化的規則由 CI 與准入政策守住,不能自動化的規則由「🔍 審查與驗證」的問題引導人工審查。
  3. AI 產出可審查:AI 可以加速草稿與樣板的產生,但版本、設定鍵、數字與取捨必須由人查證與負責(第 16 章)。

本指引會隨技術基準(0.2)與國際標準更新。發現規則不合時宜、範例錯誤或有新的需求時,請以 PR 提出修改,並在附錄 E 記錄變更與查證結果。