Manifest、Report、Finding 差在哪？軟體架構中的資料層級名詞是什麼意思？為什麼 API 設計要這樣分層？Metadata、Artifact 與 Payload 又有什麼不同！

你有沒有遇過在看各種 API 文件、資安掃描工具或是 CI/CD 流程時，常常看到 Manifest、Report、Finding、Evidence 這些名詞？它們其實不是哪個特定程式語言的語法，而是業界約定俗成的 資料層級代名詞。到底這些名詞代表什麼意思？

核心概念：從「健康檢查」理解資料階層

其實我們可以把它們想像成去醫院做 健康檢查 的流程，這四個名詞剛好對應了從高層級到最底層的資料階層。

名詞	健檢比喻	軟體架構對應說明
`Manifest`	健檢報到單	宣告有哪些項目要執行、版本與環境配置，屬於描述性資料。
`Report`	完整健檢報告書	執行完成後的完整總結，包含整體狀態與審計結果。
`Finding`	報告中的紅字註記	報告中被圈出來的具體發現，例如「發現高血壓」或資安漏洞。
`Evidence`	血壓計數據紙條	支持發現的原始客觀證據，例如日誌記錄或數據測量值。

這些名詞不是程式語言的保留字，而是業界約定俗成的共同資料模型。

我們可以使用 Mermaid 圖表來呈現這四者在資料結構上的上下游與包含關係：

  graph TD
    A["Manifest (執行清單/元資料)"] -->|定義範疇與執行| B["Report (完整總結報告)"]
    B -->|包含多筆| C["Finding (具體發現/觀察)"]
    C -->|關聯多筆| D["Evidence (客觀原始證據)"]

為什麼要這樣分層設計？資料層級的三大優勢

那為什麼系統要把資料拆得這麼細，不全部塞進一個大 JSON 就好呢？其實這樣的設計有幾個極大的好處：

優秀的 API 架構設計，能讓前端介面載入更順暢、數據更具可信度與擴充性。

優勢	說明
職責分離	前端介面可以先載入 `Finding` 讓用戶看概況，有需要深究時才調用龐大的 `Evidence`。
高可信度	提供 `Evidence` 能證明 `Finding` 不是誤報，顯著增加系統的可審計性。
彈性擴充性	一筆 `Finding` 可以彈性關聯多筆 `Evidence`，不會破壞原有資料格式。

其他常見名詞補充：Metadata、Artifact 與 Payload

除了上述四個核心階層，你在設計 API、構建流水線或定義傳輸格式時，一定還會常看到這三個名詞 Metadata、Artifact 與 Payload，它們分別扮演著不同的角色：

名詞	核心定義	生活比喻	軟體架構實際應用範例
`Metadata`	描述資料本身的資料（中繼資料）	包裹外面的寄件貼紙、相片資訊	`HTTP Header`、請求時間戳記 `timestamp`、分頁資訊 `page`。
`Artifact`	流程執行後產生的實體產出物	工廠生產的汽車、健檢光碟	打包好的 `.apk` 檔、`Docker Image`、審計 `PDF` 報告。
`Payload`	傳輸中真正要傳遞的核心業務資料	包裹盒子裡真正裝的智慧型手機	`HTTP POST Body` 中的 `JSON` 業務主體內容。

Payload 就像郵件包裹裡的物品，而 Metadata 則是貼在包裹外面的寄件標籤。

為了讓大家更清楚這三者的協同運作方式，我們可以用一個典型的 API Request 資料結構來觀察：

{
  "metadata": {
    "version": "v1.2.0",
    "timestamp": "2026-08-02T15:08:41Z",
    "request_id": "req-98765"
  },
  "payload": {
    "report_id": "REP-2026-001",
    "status": "COMPLETED",
    "artifact_url": "https://example.com/artifacts/build-report.pdf"
  }
}

在這個 JSON 範例中：

metadata 提供了傳輸與環境的上下文（版本、時間戳記、請求 ID）。
payload 包含了真正傳輸的業務邏輯資料（報告 ID、狀態）。
artifact_url 則指向了這次構建任務真正產生的實體檔案（Artifact）。

共同語彙的力量：跨系統溝通的橋樑

當不同工具、不同團隊都採用這套相近的資料模型（例如 Report -> Findings -> Evidence），彼此之間的溝通成本就會大幅降低。

想像一下，你的 CI/CD 工具產生的 Report，可以直接無痛傳輸給資安系統做分析，這就是共同語彙帶來的整合威力。

  sequenceDiagram
    autonumber
    actor CI as CI/CD Pipeline
    participant Scanner as 資安掃描器
    participant Dashboard as 管理儀表板
    
    CI->>Scanner: 提供 Manifest 執行掃描
    Scanner->>Scanner: 產生 Report 與 Findings
    Scanner->>Dashboard: 傳送結構化 Payload (Finding + Evidence)
    Dashboard-->>CI: 顯示審計結果

總結

其實，這些名詞的出發點都是為了解決大型系統間 資料溝通與結構化 的問題。

在串接系統或設計 API 時，可以試著把這些概念融入你的 Payload 結構中，讓你的系統設計更加專業且具有擴充性！