billing-service/docs/reference/httpapi.md

# httpapi 包参考

本文档覆盖 `internal/httpapi/handler.go`，说明 HTTP 路由注册和各处理函数与服务层的映射关系。

## 包职责

`internal/httpapi` 负责把 `service.Service` 暴露成 HTTP 接口。当前只承担：

- 健康检查
- 运行状态查询
- 立即触发任务
- 运行镜像身份查询

它不包含业务逻辑，所有计费行为都委托给 `service.Service`。

## 类型

### `Handler`

签名：`type Handler struct`

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `service` | `*service.Service` | 业务服务实例 |

## 函数与方法

### `New`

- 签名：`func New(svc *service.Service) *Handler`
- 参数：
  - `svc`：业务服务实例
- 返回：
  - `*Handler`
- 职责：
  - 构造 HTTP handler
- 调用位置：
  - `cmd/billing-service/main.go`
- 主要副作用：无
- 错误/边界条件：
  - 不校验 `svc` 是否为 `nil`

### `Routes`

- 签名：`func (h *Handler) Routes() http.Handler`
- 参数：无
- 返回：
  - `http.Handler`：注册好全部路由的 `*http.ServeMux`
- 职责：
  - 注册当前服务支持的全部 HTTP 路径
- 调用位置：
  - `cmd/billing-service/main.go`
- 主要副作用：
  - 构造新的 `ServeMux`
- 错误/边界条件：
  - 当前路由集合固定，不包含版本协商或中间件

当前注册的路由：

| 路径 | 处理函数 | 说明 |
| --- | --- | --- |
| `/api/ping` | `ping` | 返回运行镜像身份 |
| `/healthz` | `healthz` | 返回最近一次任务健康状态 |
| `/v1/status` | `status` | 返回最近一次任务结果快照 |
| `/v1/jobs/collect-and-rate` | `collectAndRate` | 触发立即采集与计费 |
| `/v1/jobs/reconcile` | `reconcile` | 触发同一执行路径，但 job 名不同 |

### `ping`

- 签名：`func (h *Handler) ping(w http.ResponseWriter, r *http.Request)`
- 参数：`w`、`r`
- 返回：无
- 职责：
  - 返回 `service.Ping()` 的结果
- 调用位置：
  - `Routes`
- 主要副作用：
  - 写 HTTP 响应
- 错误/边界条件：
  - 当前不限制 HTTP 方法，任何方法都会返回 `200`

### `healthz`

- 签名：`func (h *Handler) healthz(w http.ResponseWriter, r *http.Request)`
- 参数：`w`、`r`
- 返回：无
- 职责：
  - 调用 `service.Health()`
  - 将布尔健康值映射为 HTTP 状态码与 `status` 文本
- 调用位置：
  - `Routes`
- 主要副作用：
  - 写 HTTP 响应
- 错误/边界条件：
  - `ok == false` 时返回 `503`
  - 当前不限制 HTTP 方法

### `status`

- 签名：`func (h *Handler) status(w http.ResponseWriter, r *http.Request)`
- 参数：`w`、`r`
- 返回：无
- 职责：
  - 返回最近一次 `service.Status()`
- 调用位置：
  - `Routes`
- 主要副作用：
  - 写 HTTP 响应
- 错误/边界条件：
  - 当前不限制 HTTP 方法

### `collectAndRate`

- 签名：`func (h *Handler) collectAndRate(w http.ResponseWriter, r *http.Request)`
- 参数：`w`、`r`
- 返回：无
- 职责：
  - 只接受 `POST`
  - 调用 `service.RunCollectAndRate(r.Context(), "collect-and-rate")`
  - 根据是否返回错误决定 `200` 或 `503`
- 调用位置：
  - `Routes`
- 主要副作用：
  - 触发一次完整计费执行
  - 写 HTTP 响应
- 错误/边界条件：
  - 非 `POST` 返回 `405 method not allowed`
  - 服务层返回错误时仍返回 `JobResult`，但状态码为 `503`

### `reconcile`

- 签名：`func (h *Handler) reconcile(w http.ResponseWriter, r *http.Request)`
- 参数：`w`、`r`
- 返回：无
- 职责：
  - 只接受 `POST`
  - 调用 `service.RunCollectAndRate(r.Context(), "reconcile")`
  - 与 `collectAndRate` 共用同一业务路径，仅 job 名不同
- 调用位置：
  - `Routes`
- 主要副作用：
  - 触发一次完整计费执行
  - 写 HTTP 响应
- 错误/边界条件：
  - 非 `POST` 返回 `405`
  - 服务层返回错误时状态码为 `503`

### `writeJSON`

- 签名：`func writeJSON(w http.ResponseWriter, status int, payload any)`
- 参数：
  - `w`：响应写入器
  - `status`：HTTP 状态码
  - `payload`：任意可 JSON 编码的对象
- 返回：无
- 职责：
  - 统一设置 `Content-Type: application/json`
  - 写入状态码和 JSON 响应体
- 调用位置：
  - `ping`
  - `healthz`
  - `status`
  - `collectAndRate`
  - `reconcile`
- 主要副作用：
  - 写 HTTP Header 和 Body
- 错误/边界条件：
  - JSON 编码错误被忽略，调用方不会收到显式错误

## 接口设计说明

- `collect-and-rate` 和 `reconcile` 在当前实现中只有作业名不同，没有独立 reconciliation 流程
- `/healthz` 反映的是最近一次作业的结果，不是即时数据库探活
- `/api/ping` 用于发布追踪，不依赖数据库或 exporter