lijiaoqiao/docs/test_plan_go_aligned_v1_2026-03-18.md

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. 测试目录与命名规范

立交桥/
  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 测试示例（最小可执行）

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版）

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：提交覆盖率与门禁报告。