JBoss EAP 07：把 HTTP、DB、MQ 與 log 比對做成可重跑的練習

第六課把 HTTP、DB、MQ 與 log 列成四種證據，實際工作還有下一個問題：資料收齊以後，怎麼避免每次都從頭讀一遍？這一課附一個可在本機執行的比對程式。先用合成案例練習找差異，再把結果帶回原始資料，判斷是哪個行為改變。

這是接在六堂基礎課後的實作。下載包只有 Python 標準函式庫程式與假資料，不需要 EAP 授權、資料庫或 MQ。這次實際驗證的是比對器與教材案例；它不會啟動伺服器，也沒有替企業系統執行升級測試。

先把同一個案例定義清楚

練習情境是 MDB 處理一筆訂單，在 DB 寫入後、流程完成前故意失敗。我們替假案例設定「交易回滾，留下處理失敗事件」的預期。這是手工設計的 fixture，不是對所有 MDB 的保證；實際預期仍由你第五課查到的交易邊界決定。Red Hat 的交易文件說明伺服器的交易與復原配置，不能替這份假資料背書。

舊、新兩份 snapshot 必須有相同 case_id、input、start_state_id 與 observation_rule。前兩者說明跑哪個輸入，後兩者固定起始資料及收集規則。比方說一邊從空 queue 開始，另一邊還留昨天的訊息，即使呼叫同一支程式，也不是同條件比較。工具會拒絕宣告不同的案例；宣告是否符合真正執行過的環境，仍要由人核對。

空陣列與沒有資料，意思不一樣

"db": {
  "state": "captured",
  "evidence_ref": "synthetic:example-only",
  "data": { "orders": [] }
}

"mq": {
  "state": "missing",
  "evidence_ref": null,
  "data": null
}

這是兩段欄位示意，完整 JSON 在 fixtures/baseline.json。第一段宣告已觀察 DB，結果沒有訂單；第二段表示 MQ 證據沒取得。若把未知直接寫成空陣列，就會製造「兩邊都零筆，所以相同」的假象。工具因此要求四個面向都明寫狀態：兩邊同樣 missing 也不能算 match。

MDB 入口沒有 HTTP 呼叫，範例便在 HTTP data 寫下 not-applicable 與原因，仍留下可以審閱的範圍決定。Web 案例則要收集相關狀態碼、header 與 body。data 的內容由案例契約決定；工具不會知道你是否漏掉一個重要 header，或少查了一張資料表。

動手：先猜結果，再跑四次

python3 compare.py fixtures/baseline.json fixtures/match.json
python3 compare.py fixtures/baseline.json fixtures/db-difference.json
python3 compare.py fixtures/baseline.json fixtures/mq-duplicate.json
python3 compare.py fixtures/baseline.json fixtures/mq-missing.json

解壓縮後，在 migration-parity 目錄逐條執行，需要 Python 3.9 以上。不要用 && 串接，因為找到差異會回傳非零 exit code。先不看答案，猜「DB 多一筆」「MQ 多送一次」「MQ 還沒收集」是否應歸在同一種結果。

例如 mq-duplicate 的報告會在 mq 底下列出 path: /deliveries、kind: length_changed。它不替你斷言「一定是 MDB 重送設定錯誤」，而是把你帶回那組訊息記錄。接著核對業務鍵、傳遞次數、交易結果與 log，才有依據分辨正常重送、重複副作用或收集了兩次同一筆資料。

檔案讀不到、JSON 格式不合法、缺必要欄位或案例條件不同，則回 invalid／3。若 DB 有差異而 MQ 同時缺資料，總結果為 different，has_missing_evidence 也會是 true；不能因為找到一個問題，就讓另一個缺口消失。

哪些差異保留，哪些不自動處理

Object 的 key 順序不影響結果；array 的順序、筆數與重複值保留。null 和欄位缺漏不同，true、1、1.0、"1" 也會分開。小數以 Decimal 解析，避免先轉成浮點數而吃掉精度；1.0 與 1.00 仍視為相同小數值。這是語意資料的嚴格比較，不是原始 JSON 字元逐字比較。

工具沒有自動忽略時間戳、刪掉 ID 或把訊息排序。若 log 時間必然不同，先寫明允許的正規化規則，保留事件順序、關聯與原始證據，再產出可比較的 snapshot。DB 查詢也要定義穩定順序或經審閱的排序規則；一開始就全部排序去重，可能把多送一次訊息的問題一起擦掉。

每個面向最多列 50 個差異，超出就標 truncated；結果仍是 different。輸出只列欄位路徑與差異種類，並記錄兩份輸入檔的 SHA-256。hash 能識別這次用了哪兩份檔案，不能證明內容是真的，也不能證明四面向收集完整。evidence_ref 只當參考文字，不會被開啟或驗證。

把比對結果變成一份短交接

下載包的 REVIEW.md 留了改動原因、案例、差異位置、原始證據與下一個驗證。可以請 AI 協助把差異連回程式改動，但要求它指出哪段資料支持判斷、哪裡仍未知。你的閱讀順序就能從「全部重看」改成先看案例與差異，再回查必要的程式；這是工作安排，不是已量測的省時保證。

本機已跑過下載包的 12 項測試，涵蓋差異與缺漏並存、重複訊息、型別、小數精度、錯誤輸入與檔案未被修改。接到公司環境時，下一個驗證是拿一個已知正常案例與一個已知失敗案例，確認收集程序真的保留了要比的行為。match 只代表提交內容一致，不能取代那一步。