附錄：完整內容和源代碼下載請參照

https://doc.janettr.com/

一、前序章節回憶

我們在前面章節拆解了 Collector 的啟動過程，并定位了控制器 TimelineWebServices。
本節聚焦 Collector 對外暴露的 REST 服務，搭建「接口全景圖」。

二、接口請求梳理

2.1 接口總覽表

分類	方法	路徑	功能	主要參數
基礎	GET	/ws/v1/timeline	服務探活	-
寫入	POST	/ws/v1/timeline/metrics	寫入普通指標	TimelineMetrics JSON
寫入	POST	/ws/v1/timeline/metrics/aggregated	寫入聚合指標	AggregationResult JSON
寫入	POST	/ws/v1/timeline/containermetrics	寫入容器指標	List<ContainerMetric>
查詢	GET	/ws/v1/timeline/metrics	核心查詢接口	metricNames, appId, hostname, startTime, endTime, precision, topN
查詢	GET	/ws/v1/timeline/metrics/{instanceId}	按實例查詢	instanceId PathParam
查詢	GET	/ws/v1/timeline/metrics/summary	獲取服務摘要	-
元數據	GET	/ws/v1/timeline/metrics/metadata	查詢指標元數據	appId, metricName, includeAll
元數據	GET	/ws/v1/timeline/metrics/{instanceId}/metadata	實例元數據（實現未完整）	instanceId PathParam
拓撲	GET	/ws/v1/timeline/metrics/hosts	主機→應用映射	-
拓撲	GET	/ws/v1/timeline/metrics/instance	主機→應用→實例映射	appId, instanceId
拓撲	GET	/ws/v1/timeline/metrics/{instanceId}/instance	等價實例查詢	instanceId PathParam
診斷	GET	/ws/v1/timeline/metrics/uuid	獲取指標 UUID	metricName, appId, hostname, instanceId
存活	GET	/ws/v1/timeline/metrics/livenodes	當前活躍節點	-

2.2 基礎類接口

:::danger 枯燥提醒
不想看可以看后面的導入操作，我們把openapi.json文件放到了 github 和 gitee 中供大家自行體驗
:::

2.2.1 /ws/v1/timeline

• 方法：GET
• 功能：探活，確認 Collector 是否在線。
• 參數：無

2.3 寫入類接口

2.3.1 /ws/v1/timeline/metrics

• 方法：POST
• 功能：寫入普通時序指標。
• 參數：TimelineMetrics JSON

2.3.2 /ws/v1/timeline/metrics/aggregated

• 方法：POST
• 功能：寫入主機級聚合指標。
• 參數：AggregationResult JSON

2.3.3 /ws/v1/timeline/containermetrics

• 方法：POST
• 功能：寫入容器級指標。
• 參數：List<ContainerMetric> JSON

2.4 查詢類接口

2.4.1 /ws/v1/timeline/metrics

• 方法：GET
• 功能：核心查詢接口。
• 主要參數：metricNames, appId, hostname, startTime, endTime, precision, topN

2.4.2 /ws/v1/timeline/metrics/{instanceId}

• 方法：GET
• 功能：與 2.4.1 類似，支持 PathParam instanceId。

2.4.3 /ws/v1/timeline/metrics/summary

• 方法：GET
• 功能：返回 Collector 服務摘要。
• 參數：無

2.5 元數據接口

2.5.1 /ws/v1/timeline/metrics/metadata

• 方法：GET
• 功能：查詢指標元數據。
• 主要參數：appId, metricName, includeAll

2.5.2 /ws/v1/timeline/metrics/{instanceId}/metadata

• 方法：GET
• 功能：實例元數據查詢（當前實現未完整使用 PathParam）。

2.6 拓撲類接口

2.6.1 /ws/v1/timeline/metrics/hosts

• 方法：GET
• 功能：返回主機與應用映射。

2.6.2 /ws/v1/timeline/metrics/instance

• 方法：GET
• 功能：返回主機→應用→實例映射。
• 參數：appId, instanceId

2.6.3 /ws/v1/timeline/metrics/{instanceId}/instance

• 方法：GET
• 功能：與 2.6.2 類似，支持 PathParam instanceId。

2.7 診斷與存活接口

2.7.1 /ws/v1/timeline/metrics/uuid

• 方法：GET
• 功能：返回指標的 UUID。
• 主要參數：metricName, appId, hostname, instanceId

2.7.2 /ws/v1/timeline/metrics/livenodes

• 方法：GET
• 功能：返回當前活躍的 Collector 節點列表。

三、Apifox 導入與調試

我們將接口定義整理為 OpenAPI 規范文件，可以直接導入 Apifox：

👉 openapi.json 文件地址

導入效果如下：

所有接口自動分組，支持調試和測試：