195 lines
4.8 KiB
Markdown
195 lines
4.8 KiB
Markdown
# Go 主测试链路对齐方案
|
||
|
||
- 版本：v1.0
|
||
- 日期：2026-03-18
|
||
- 目标：将测试体系与主技术栈（Go + PostgreSQL）对齐，替代 Python 工程骨架为主的测试设计。
|
||
|
||
---
|
||
|
||
## 1. 适用范围
|
||
|
||
1. 适用于网关主链路：路由、鉴权、计费、适配器、风控、审计。
|
||
2. 覆盖阶段：S0-S2（优先保障 S1/S2 的上线与替换门禁）。
|
||
3. 本文档作为测试实施主方案，历史 Python 示例仅保留参考。
|
||
|
||
---
|
||
|
||
## 2. 测试金字塔（Go版）
|
||
|
||
| 层级 | 占比 | 工具 | 目标 |
|
||
|---|---:|---|---|
|
||
| 单元测试 | 70% | `go test` + `testing` + `testify` | 逻辑正确性、异常分支、边界条件 |
|
||
| 集成测试 | 20% | `go test` + `testcontainers-go` + `httptest` | DB/Redis/网关链路联通与一致性 |
|
||
| E2E/门禁测试 | 10% | `playwright` + `k6` + 契约回归脚本 | 用户旅程、性能门禁、兼容门禁 |
|
||
|
||
覆盖率目标：
|
||
1. 核心包总覆盖率 >= 80%。
|
||
2. Router/Billing/Adapter 覆盖率 >= 85%。
|
||
3. 关键门禁用例（S2 Gate）通过率 = 100%。
|
||
|
||
---
|
||
|
||
## 3. 测试目录与命名规范
|
||
|
||
```text
|
||
立交桥/
|
||
gateway/
|
||
internal/
|
||
pkg/
|
||
tests/
|
||
unit/
|
||
router/
|
||
billing/
|
||
auth/
|
||
integration/
|
||
api/
|
||
db/
|
||
adapter/
|
||
contract/
|
||
compat/
|
||
e2e/
|
||
user_journey/
|
||
performance/
|
||
k6/
|
||
```
|
||
|
||
命名规则：
|
||
1. 单元测试文件：`*_test.go`。
|
||
2. 集成测试标签：`//go:build integration`。
|
||
3. 门禁测试标签：`//go:build gate`。
|
||
|
||
---
|
||
|
||
## 4. 工具链基线（Go）
|
||
|
||
| 能力 | 工具 | 说明 |
|
||
|---|---|---|
|
||
| 单元测试 | `testing`, `testify/require` | 断言与失败信息可读性 |
|
||
| Mock | `gomock` 或 `testify/mock` | 仅在外部依赖边界处使用 |
|
||
| HTTP测试 | `httptest` | Handler/中间件测试 |
|
||
| DB集成 | `testcontainers-go` + PostgreSQL 15 | 与生产数据库方言一致 |
|
||
| Redis集成 | `testcontainers-go` + Redis 7 | 限流/并发门控验证 |
|
||
| 覆盖率 | `go test -coverprofile` | CI 门禁 |
|
||
| 性能 | `k6` | P95/P99 与错误率门禁 |
|
||
| 前端E2E | `playwright` | 注册、Key、调用、账单旅程 |
|
||
|
||
---
|
||
|
||
## 5. 关键测试套件（必须落地）
|
||
|
||
### 5.1 Router Core 套件
|
||
|
||
1. 主路径端点归一：`/responses` -> `/v1/responses`。
|
||
2. 路由决策正确性：模型映射、租户策略、fallback。
|
||
3. 接管率标记：`router_engine` 写入一致性。
|
||
|
||
### 5.2 Billing 套件
|
||
|
||
1. 幂等扣费：重复 `request_id` 不重复扣费。
|
||
2. 冲突检测：`billing_conflict_rate_pct` 监测与告警。
|
||
3. 对账一致性：usage 与 billing 差异 <= 0.1%。
|
||
|
||
### 5.3 兼容契约套件
|
||
|
||
1. Schema Gate：请求/响应字段与类型。
|
||
2. Behavior Gate：stream/no-replay/错误码语义。
|
||
3. Performance Gate：P95/P99/5xx/账务指标。
|
||
|
||
### 5.4 安全套件
|
||
|
||
1. query key 外拒内转边界。
|
||
2. subapi 内网隔离与 mTLS。
|
||
3. RLS/租户越权访问防护。
|
||
|
||
---
|
||
|
||
## 6. Go 测试示例（最小可执行）
|
||
|
||
```go
|
||
package billing_test
|
||
|
||
import (
|
||
"testing"
|
||
"github.com/stretchr/testify/require"
|
||
)
|
||
|
||
func TestCharge_IdempotentByRequestID(t *testing.T) {
|
||
svc := newTestBillingService(t)
|
||
|
||
reqID := "req-123"
|
||
err1 := svc.Charge("u1", reqID, 100)
|
||
err2 := svc.Charge("u1", reqID, 100)
|
||
|
||
require.NoError(t, err1)
|
||
require.NoError(t, err2)
|
||
|
||
cnt, err := svc.CountTransactionsByRequestID(reqID)
|
||
require.NoError(t, err)
|
||
require.Equal(t, 1, cnt)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. CI 门禁流水线（Go版）
|
||
|
||
```yaml
|
||
name: go-test-pipeline
|
||
on:
|
||
pull_request:
|
||
branches: [main]
|
||
push:
|
||
branches: [main]
|
||
|
||
jobs:
|
||
unit:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-go@v5
|
||
with:
|
||
go-version: '1.21.x'
|
||
- run: go test ./... -coverprofile=coverage.out
|
||
- run: go tool cover -func=coverage.out
|
||
|
||
integration:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-go@v5
|
||
with:
|
||
go-version: '1.21.x'
|
||
- run: go test -tags=integration ./tests/integration/...
|
||
|
||
gate:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-go@v5
|
||
with:
|
||
go-version: '1.21.x'
|
||
- run: go test -tags=gate ./tests/contract/...
|
||
- run: ./scripts/gate/perf_gate_check.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 历史 Python 测试迁移映射
|
||
|
||
| 历史做法 | 对齐后做法 |
|
||
|---|---|
|
||
| `pytest` 单测 | `go test` + `testify` |
|
||
| Python `AsyncClient` API 测试 | Go `httptest` + 集成容器 |
|
||
| sqlite 内存库 | PostgreSQL 容器（与生产一致） |
|
||
| Python 契约脚本 | Go 契约测试 + CI gate 标签 |
|
||
|
||
---
|
||
|
||
## 9. 实施排期（首周）
|
||
|
||
1. D1-D2：迁移 Router/Billing 单测到 Go 主链路。
|
||
2. D3：补齐 integration（PostgreSQL/Redis）。
|
||
3. D4：接入 gate 标签与性能门禁脚本。
|
||
4. D5：提交覆盖率与门禁报告。
|
||
|