# config 包参考

本文档覆盖 `internal/config/config.go`，说明运行配置结构、环境变量来源和全部生产函数。

## 包职责

`internal/config` 负责把环境变量解析成运行时可直接使用的 `Config`，并处理：

- 镜像标识拆解
- exporter 来源列表构造
- 默认值和必填项校验
- 数值型环境变量解析

## 类型

### `ExporterSource`

签名：`type ExporterSource struct`

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `SourceID` | `string` | 来源唯一标识，写入 `billing_source_sync_state` 的主键 |
| `BaseURL` | `string` | exporter 基础地址，`FetchWindow` 会在其后拼接 `/v1/snapshots/window` |
| `ExpectedNodeID` | `string` | 期望上游返回的 `snapshot.node_id`，用于来源校验 |
| `ExpectedEnv` | `string` | 期望上游返回的 `snapshot.env`，用于来源校验 |
| `Enabled` | `bool` | 是否参与当前轮采集 |
| `TimeoutSeconds` | `int` | 单个来源 HTTP 请求超时秒数，<= 0 时使用默认值 15 |

### `Config`

签名：`type Config struct`

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `ImageRef` | `string` | 原始 `IMAGE` 环境变量 |
| `ImageTag` | `string` | 从 `ImageRef` 中解析出的 tag |
| `ImageCommit` | `string` | 从 tag 中解析出的完整 40 位 commit |
| `ImageVersion` | `string` | 当前实现与 `ImageCommit` 相同，用于 `/api/ping` |
| `ExporterBaseURL` | `string` | 旧单来源兼容入口，对应 `EXPORTER_BASE_URL` |
| `ExporterSources` | `[]ExporterSource` | 当前实际启用的来源清单，推荐由 `EXPORTER_SOURCES_JSON` 生成 |
| `InternalServiceToken` | `string` | 调用 exporter 的 Bearer token |
| `DatabaseURL` | `string` | PostgreSQL DSN |
| `ListenAddr` | `string` | HTTP 监听地址，默认 `:8081` |
| `CollectInterval` | `time.Duration` | 后台定时采集间隔，默认 1 分钟 |
| `DefaultRegion` | `string` | 写入分钟桶时的默认地域 |
| `SourceRevision` | `string` | 当前写路径版本标识，默认 `billing-service-v1` |
| `PricePerByte` | `float64` | 默认每字节价格 |
| `InitialIncludedQuotaBytes` | `int64` | 默认初始包含流量 |
| `InitialBalance` | `float64` | 默认初始余额 |

### `rawExporterSource`

签名：`type rawExporterSource struct`

这是 `EXPORTER_SOURCES_JSON` 的中间反序列化结构，不直接暴露给其他包。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `SourceID` | `string` | JSON `source_id` |
| `BaseURL` | `string` | JSON `base_url` |
| `ExpectedNodeID` | `string` | JSON `expected_node_id` |
| `ExpectedEnv` | `string` | JSON `expected_env` |
| `Enabled` | `*bool` | JSON `enabled`，指针用于区分“未传”和“显式 false” |
| `TimeoutSeconds` | `int` | JSON `timeout_seconds` |

## 环境变量映射

| 环境变量 | 是否必填 | 默认值 | 作用 |
| --- | --- | --- | --- |
| `IMAGE` | 否 | 空字符串 | 供 `/api/ping` 返回镜像身份 |
| `EXPORTER_SOURCES_JSON` | 条件必填 | 无 | 推荐的多来源配置入口 |
| `EXPORTER_BASE_URL` | 条件必填 | 无 | 当前兼容路径，仅在未提供 `EXPORTER_SOURCES_JSON` 时使用 |
| `INTERNAL_SERVICE_TOKEN` | 是 | 无 | exporter Bearer token |
| `DATABASE_URL` | 是 | 无 | PostgreSQL 连接串 |
| `LISTEN_ADDR` | 否 | `:8081` | HTTP 监听地址 |
| `COLLECT_INTERVAL` | 否 | `1m` | 后台定时采集间隔 |
| `DEFAULT_REGION` | 否 | 空字符串 | 分钟桶地域字段 |
| `SOURCE_REVISION` | 否 | `billing-service-v1` | 写路径版本号 |
| `PRICE_PER_BYTE` | 否 | `0` | 默认单价 |
| `INITIAL_INCLUDED_QUOTA_BYTES` | 否 | `0` | 默认初始包含流量 |
| `INITIAL_BALANCE` | 否 | `0` | 默认初始余额 |

## 函数

### `Load`

- 签名：`func Load() (Config, error)`
- 参数：无
- 返回：
  - `Config`：已填充默认值和解析结果的配置对象
  - `error`：必填项缺失、时长解析失败、来源 JSON 解析失败时返回
- 职责：
  - 读取全部环境变量
  - 调用 `parseImageRef` 拆解镜像信息
  - 调用 `loadExporterSources` 生成 `ExporterSources`
  - 处理默认值和必填项校验
- 调用位置：
  - `cmd/billing-service/main.go`
- 主要副作用：
  - 读取进程环境变量
- 错误/边界条件：
  - `DATABASE_URL` 为空时报错
  - `INTERNAL_SERVICE_TOKEN` 为空时报错
  - `COLLECT_INTERVAL` 无法解析时报错
  - `EXPORTER_SOURCES_JSON` 非法或为空列表时报错
  - 若 `EXPORTER_SOURCES_JSON` 未设置，则要求 `EXPORTER_BASE_URL` 存在

### `parseImageRef`

- 签名：`func parseImageRef(imageRef string) (tag, commit, version string)`
- 参数：
  - `imageRef`：完整镜像引用，例如 `registry.example.com/billing-service:sha-<40位SHA>`
- 返回：
  - `tag`：冒号后的 tag
  - `commit`：当 tag 为完整 40 位 SHA 或 `sha-<40位SHA>` 时提取出的 commit
  - `version`：当前实现与 `commit` 相同
- 职责：
  - 为 `/api/ping` 提供可校验的运行镜像身份
- 调用位置：
  - `Load`
- 主要副作用：无
- 错误/边界条件：
  - 空字符串、无冒号、无 tag、tag 不是完整 40 位 SHA 时，返回空结果而非报错

### `loadExporterSources`

- 签名：`func loadExporterSources(legacyBaseURL, rawJSON string) ([]ExporterSource, error)`
- 参数：
  - `legacyBaseURL`：旧单来源配置
  - `rawJSON`：`EXPORTER_SOURCES_JSON` 原始内容
- 返回：
  - `[]ExporterSource`：可直接参与采集的来源配置
  - `error`：来源缺失、JSON 非法、必填字段缺失时返回
- 职责：
  - 优先使用 `EXPORTER_SOURCES_JSON`
  - 在未设置 JSON 时退回到单来源兼容模式
  - 为来源填充默认超时和 `enabled=true`
- 调用位置：
  - `Load`
- 主要副作用：无
- 错误/边界条件：
  - 两种来源配置都缺失时报错
  - JSON 为空数组时报错
  - 某个来源缺少 `source_id` 或 `base_url` 时按来源维度报错
  - `timeout_seconds <= 0` 时回填为 15

### `parseFloatEnv`

- 签名：`func parseFloatEnv(key string, fallback float64) float64`
- 参数：
  - `key`：环境变量名
  - `fallback`：解析失败或缺失时返回的默认值
- 返回：
  - 解析成功后的 `float64`，否则返回 `fallback`
- 职责：
  - 解析浮点型环境变量，不把格式错误上抛为配置加载失败
- 调用位置：
  - `Load`
- 主要副作用：
  - 读取指定环境变量
- 错误/边界条件：
  - 缺失或格式错误时静默回退到默认值

### `parseIntEnv`

- 签名：`func parseIntEnv(key string, fallback int64) int64`
- 参数：
  - `key`：环境变量名
  - `fallback`：解析失败或缺失时返回的默认值
- 返回：
  - 解析成功后的 `int64`，否则返回 `fallback`
- 职责：
  - 解析整型环境变量，不把格式错误上抛为配置加载失败
- 调用位置：
  - `Load`
- 主要副作用：
  - 读取指定环境变量
- 错误/边界条件：
  - 缺失或格式错误时静默回退到默认值

## 当前主路径与兼容路径

当前实现仍保留两条来源配置路径：

1. 主路径：`EXPORTER_SOURCES_JSON`
2. 兼容路径：`EXPORTER_BASE_URL`

维护建议：

- 新部署应只使用 `EXPORTER_SOURCES_JSON`
- 阅读代码时不要把 `ExporterBaseURL` 误解为主设计，它只是当前尚未移除的兼容入口