内容
# coverage-api
[](https://github.com/arxdsilva/opencoverage/actions/workflows/ci.yml)
## 仪表盘预览
用于摄取测试覆盖率、比较差异和跟踪项目、分支和团队趋势的自托管Go代码覆盖率API和仪表盘。
`coverage-api`是`opencoverage`项目的一部分，专为希望在其自身基础设施中实现覆盖率可见性的开发团队而设计。
## 为什么选择coverage-api
- 摄取本地运行或CI管道中的Go覆盖率结果
- 计算确定性的基准比较和差异
- 跟踪项目和包级别的覆盖率历史
- 分组项目（用于团队级报告）
- 与GitHub Actions和其他CI系统集成
- 自托管API + 前端与PostgreSQL
## 主要功能
- 具有`/v1`端点的REST API，用于摄取、历史记录和最新比较
- Coverage CLI，用于将`coverage.out`转换为API-ready JSON有效载荷
- 用于项目、多分支趋势、比较和热图可视化的仪表盘前端
- 集成测试结果摄取和热图可视化
- 受保护端点的API密钥身份验证
- 六边形架构（端口和适配器）
## 快速入门（Docker Compose）
运行完整的本地堆栈（PostgreSQL + API + seed + frontend + MCP）：
```bash
make compose-up
```
如果本地端口`5432`已被占用：
```bash
DB_PORT=5433 make compose-up
```
访问服务：
- API：`http://localhost:8080`
- 前端仪表盘：`http://localhost:8090`
- 健康检查：`http://localhost:8080/healthz`
Compose启动行为：
1. `db`首先启动并必须通过其健康检查。
2. `api`启动后，在启动期间运行所有数据库迁移。
3. `api`仅在启动完成后公开`/healthz`。
4. `seed`仅在`api`健康后运行。
5. `mcp`在`seed`成功完成后启动。
停止堆栈：
```bash
make compose-down
```
## 本地开发
要求：
- Go 1.23+
- PostgreSQL 14+
核心环境变量：
- `DATABASE_URL`（必填）
- `MIGRATIONS_DIR`（默认为`./migrations`，由API启动迁移使用）
- `API_KEY_SECRET`（必填）
- `SERVER_ADDR`（默认为`:8080`）
- `API_KEY_HEADER`（默认为`X-API-Key`）
- `SHUTDOWN_TIMEOUT_SECONDS`（默认为`10`）
本地运行API：
```bash
export DATABASE_URL="postgres://coverage:coverage@localhost:5432/coverage?sslmode=disable"
export API_KEY_SECRET="dev-local-key"
go run ./cmd/api
```
`cmd/api`在提供HTTP流量之前会在启动时运行迁移。
本地运行MCP服务器：
```bash
export DATABASE_URL="postgres://coverage:coverage@localhost:5432/coverage?sslmode=disable"
export MCP_SERVER_NAME="opencoverage"
export MCP_SERVER_VERSION="dev"
go run ./cmd/mcp
```
`cmd/mcp`不运行迁移。在启动MCP之前，首先启动API（或运行`make migrate-up`）。
可选的MCP设置：
- `MCP_TRANSPORT`（默认为`stdio`）
- `MCP_ENABLE_PROMPTS`（默认为`true`）
- `MCP_LOG_LEVEL`（默认为`info`）- MCP服务器日志详细程度（例如：`debug`、`info`、`warn`、`error`）。
- `MCP_ENABLE_WRITE_TOOLS`（默认为`false`）- 启用`ingest_coverage_run`和`ingest_integration_run`；写入工具需要一个可以携带请求头部的传输器和一个非空的`API_KEY_SECRET`在shell或部署环境中（例如`export API_KEY_SECRET="dev-local-key"`），然后再启动`go run ./cmd/mcp`。
- `MCP_MAX_PAGE_SIZE`（默认为`100`）
- `MCP_DEFAULT_RUNS_LIMIT`（默认为`20`）
本地运行前端：
```bash
make frontend-run
```
有用的开发人员命令：
```bash
make deps
make fmt
make test
make migrate-status
make migrate-up
```
## API概述
主要端点：
- `GET /v1/projects`
- `POST /v1/coverage-runs`
- `GET /v1/projects/{projectId}`
- `GET /v1/projects/{projectId}/coverage-runs`
- `GET /v1/projects/{projectId}/coverage-runs/latest-comparison`
- `GET /v1/projects/{projectId}/branches`
- `GET /v1/projects/{projectId}/contributors`
- `POST /v1/integration-test-runs`
- `GET /v1/integration-test-runs/heatmap`
- `GET /v1/projects/{projectId}/integration-test-runs`
- `GET /v1/projects/{projectId}/integration-test-runs/latest-comparison`
- `GET /v1/projects/{projectId}/integration-test-runs/{runId}`
有关完整的API合约详细信息，请参见[SPEC.md](SPEC.md)。
## 使用cURL摄取覆盖率
设置变量：
```bash
export BASE_URL="http://localhost:8080"
export API_KEY="dev-local-key"
```
发送覆盖率运行：
```bash
curl -i -X POST "$BASE_URL/v1/coverage-runs" \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d '{
"projectKey": "org/repo-service",
"projectName": "repo-service",
"projectGroup": "platform-team",
"defaultBranch": "main",
"branch": "main",
"commitSha": "a1b2c3d4",
"author": "alice",
"triggerType": "push",
"runTimestamp": "2026-03-28T12:00:00Z",
"totalCoveragePercent": 83.42,
"packages": [
{"importPath": "github.com/acme/repo-service/internal/api", "coveragePercent": 85.10},
{"importPath": "github.com/acme/repo-service/internal/service", "coveragePercent": 80.70}
]
}'
```
## 覆盖率CLI工作流程
从Go覆盖率配置文件生成有效载荷：
```bash
go run ./cmd/coveragecli \
-coverprofile coverage.out \
-out coverage-upload.json \
-project-key "github.com/example/repo" \
-project-name "repo" \
-project-group "platform" \
-default-branch "main" \
-branch "main" \
-commit-sha "abc123" \
-author "alice"
```
生成并上传一步到位：
```bash
make coverage-upload API_URL="http://localhost:8080/v1/coverage-runs" API_KEY="dev-local-key"
```
从GitHub安装CLI：
```bash
go install github.com/arxdsilva/opencoverage/cmd/coveragecli@latest
```
### 上传Vitest覆盖率摘要（npm）
生成Vitest覆盖率摘要：
```bash
npx vitest run --coverage --coverage.reporter=lcov --coverage.reporter=json-summary
```
使用CLI上传`coverage/coverage-summary.json`:
```bash
go run ./cmd/coveragecli npm-upload \
-vitest-summary coverage/coverage-summary.json \
-api-url http://localhost:8080/v1/coverage-runs \
-api-key dev-local-key \
-project-key github.com/example/frontend-repo \
-project-name frontend-repo \
-project-group frontend \
-default-branch main \
-branch main \
-commit-sha abc123 \
-author alice \
-trigger-type push
```
有用的选项：
- `-metric lines|statements|functions|branches`（默认为`lines`）
- `-group-by dir|file`（默认为`dir`）
- `-include-glob`和`-exclude-glob`（可重复）
- `-path-strip-prefix`用于确定性路径规范化
- `-dry-run`和`-out <payload.json>`检查有效载荷而不上传
## 架构
该项目遵循六边形架构（端口和适配器）：
- `cmd/api` - 引导和依赖关系绑定
- `internal/domain` - 实体、不变性和确定性领域逻辑
- `internal/application` - 用例和端口
- `internal/adapters/http` - 处理程序、DTO和中间件
- `internal/adapters/postgres` - 存储库实现
- `internal/adapters/auth` - API密钥身份验证适配器
- `internal/platform` - 配置和基础设施实用程序
## 数据库和迁移
迁移文件位于`migrations/`。
迁移所有权：
1. API进程拥有启动时的自动迁移执行。
2. MCP和前端进程从不运行迁移。
3. 在Docker Compose中，`seed`等待API健康状况，以便在迁移后进行播种。
常用命令：
```bash
make migrate-status
make migrate-up
make migrate-down
make migrate-create name=add_new_table
```
播种本地数据库：
```bash
make seed
```
## CI/CD和GitHub Actions
有关完整的CI示例（单元测试、`coverage.out`、CLI有效载荷生成、上传到自托管API），请参见[GITHUB_ACTIONS_INTEGRATION.md](GITHUB_ACTIONS_INTEGRATION.md)。
示例包括：
- 可配置的项目元数据（`project key`、`name`、`group`）
- 推送和拉取请求工作流程
- 用于monorepos的多项目矩阵工作流程
- PR注释和基于阈值的质量门控
## 前端和产品文档
- 前端行为和UI说明：[frontend.md](frontend.md)
- API合约和响应模型：[SPEC.md](SPEC.md)
- 贡献/PR工作流程：[making-a-PR.md](making-a-PR.md)
前端亮点：
- 项目概览包括多分支覆盖率趋势图。
- 趋势视图将默认分支与所选项目的所有已发现分支叠加显示。
- 分支选择器用于最新比较详细信息，而不是用于筛选趋势图。
- 热图叠加层显示所有项目按团队分组，瓷砖颜色编码在-3%至+3%增量范围内（绿色=改进，红色=回归）。比例图例在叠加层标题中显示。
- 顶部贡献者叠加层显示每个项目在所有团队中的主要提交贡献者，按热图相同的方式分组。
- 集成测试屏幕提供每个项目的集成测试运行历史和失败规范详细信息。
- 集成运行链从旧到新渲染（最新运行在右侧），最多显示5次运行。
- 集成通过率卡显示运行成功率百分比，计算为`passed runs / failed runs * 100`，在返回的运行列表窗口内（最多20次运行）。
- 集成热图显示所有项目按团队分组，但仅显示默认分支运行，带有`✅`/`❌`运行标记和最新运行状态色调，每个项目行。
## 典型集成流程
1. 运行测试并生成`coverage.out`。
2. 使用`coveragecli`将覆盖率配置文件转换为JSON有效载荷。
3. 将有效载荷上传到`POST /v1/coverage-runs`。
4. 在CI中读取比较元数据（`thresholdStatus`、`deltaPercent`）。
5. 在仪表盘中可视化趋势和项目组。
