billing-service/docs/reference/exporter.md

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 中完成。