你有没有遇到过在看各种 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 结构中，让你的系统设计更加专业且具有扩充性！