98 lines
2.9 KiB
Markdown
98 lines
2.9 KiB
Markdown
# exporter 包参考
|
||
|
||
本文档覆盖 `internal/exporter/client.go`，说明与 `xray-exporter` 的 HTTP 调用约定。
|
||
|
||
## 包职责
|
||
|
||
`internal/exporter` 目前只提供一个客户端类型 `Client`。它不负责业务校验，也不负责窗口推进，只负责：
|
||
|
||
- 拼接窗口拉取 URL
|
||
- 注入查询参数和认证头
|
||
- 发送 HTTP 请求
|
||
- 反序列化为 `model.SnapshotWindowPage`
|
||
|
||
## 类型
|
||
|
||
### `Client`
|
||
|
||
签名：`type Client struct`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| `serviceToken` | `string` | 写入 `Authorization: Bearer ...` 的内部服务令牌 |
|
||
|
||
## 函数
|
||
|
||
### `NewClient`
|
||
|
||
- 签名：`func NewClient(serviceToken string) *Client`
|
||
- 参数：
|
||
- `serviceToken`：调用 exporter 时使用的内部服务令牌
|
||
- 返回：
|
||
- `*Client`：已去掉首尾空白的客户端实例
|
||
- 职责：
|
||
- 构造 exporter 客户端
|
||
- 调用位置：
|
||
- `cmd/billing-service/main.go`
|
||
- 主要副作用：无
|
||
- 错误/边界条件：
|
||
- 不做空令牌校验；必填校验在 `config.Load()` 中完成
|
||
|
||
### `FetchWindow`
|
||
|
||
- 签名：`func (c *Client) FetchWindow(ctx context.Context, source config.ExporterSource, since, until time.Time, limit int, cursor *time.Time) (model.SnapshotWindowPage, error)`
|
||
- 参数：
|
||
- `ctx`：请求上下文
|
||
- `source`：来源配置，提供 `BaseURL`、`SourceID`、`TimeoutSeconds`
|
||
- `since`：窗口起始时间
|
||
- `until`：窗口结束时间
|
||
- `limit`：分页大小
|
||
- `cursor`：可选游标，非空时加入查询参数
|
||
- 返回：
|
||
- `model.SnapshotWindowPage`：窗口分页结果
|
||
- `error`：构造请求、发送请求、状态码异常、JSON 解码失败时返回
|
||
- 职责：
|
||
- 将 `source.BaseURL` 与 `/v1/snapshots/window` 拼接成请求地址
|
||
- 设置 `since`、`until`、`limit`、`cursor` 查询参数
|
||
- 设置 `Accept: application/json` 和 `Authorization: Bearer <token>` 请求头
|
||
- 基于来源超时时间构造 `http.Client`
|
||
- 调用位置：
|
||
- `service.collectSource`
|
||
- 主要副作用：
|
||
- 发起外部 HTTP 请求
|
||
- 错误/边界条件：
|
||
- `source.TimeoutSeconds <= 0` 时使用 15 秒默认超时
|
||
- 响应状态码不是 `200 OK` 时返回错误
|
||
- 返回体不是合法 JSON 时返回错误
|
||
|
||
## 请求契约
|
||
|
||
### URL
|
||
|
||
- 路径：`/v1/snapshots/window`
|
||
- 拼接方式：`url.JoinPath(strings.TrimRight(source.BaseURL, "/"), "/v1/snapshots/window")`
|
||
|
||
### 查询参数
|
||
|
||
| 参数 | 含义 |
|
||
| --- | --- |
|
||
| `since` | RFC3339 格式的窗口起始时间 |
|
||
| `until` | RFC3339 格式的窗口结束时间 |
|
||
| `limit` | 本页最大快照数量 |
|
||
| `cursor` | 非空时追加，用于翻页 |
|
||
|
||
### 请求头
|
||
|
||
| Header | 值 |
|
||
| --- | --- |
|
||
| `Accept` | `application/json` |
|
||
| `Authorization` | `Bearer <serviceToken>` |
|
||
|
||
## 与 service 层的边界
|
||
|
||
- `Client` 不校验 `snapshot.node_id` / `snapshot.env`
|
||
- `Client` 不处理窗口重叠或完成位置推进
|
||
- `Client` 不判断 `NextCursor` 是否为空或是否合法
|
||
|
||
这些行为都在 `service.collectSource` 中完成。
|