niuniu/lijiaoqiao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新项目文档，添加测试验证规范和经验总结

Browse Source 
新增内容：
1. CLAUDE.md - 添加测试验证规范
   - 数据库连接配置
   - 测试运行命令
   - 性能基准参考值
   - 覆盖率目标
   - 常见问题与解决方案

2. project_experience_summary.md - 添加测试验证经验
   - 集成测试环境配置
   - 测试覆盖率要求
   - 性能基准测试
   - E2E测试常见问题
   - 数据库表验证步骤
   - 中间件鲁棒性验证
This commit is contained in:
Your Name
2026-04-09 14:32:36 +08:00
parent e6ac812a0a
commit cdb3a453bb
2 changed files with 217 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
supply-api/CLAUDE.md
View File

@@ -353,6 +353,81 @@ database:
--- ---
## 测试验证规范（2026-04-09）
### 1. 数据库连接配置
```bash
# Unix socket 连接（推荐开发环境）
export SUPPLY_API_DB_HOST="/var/run/postgresql"
export SUPPLY_API_DB_USER="long"
export SUPPLY_API_DB_PASSWORD=""
export SUPPLY_API_DB_NAME="supply_test"
# TCP 连接
export SUPPLY_API_DB_HOST="localhost"
export SUPPLY_API_DB_PORT="5432"
```
### 2. 测试运行命令
```bash
# 单元测试（跳过集成测试）
go test -short ./...
# 集成测试（需真实数据库）
go test -tags=integration ./...
# 性能基准测试
go test -tags=slow -bench=. -benchmem ./internal/benchmark/...
# 完整测试（含集成）
go test -tags=integration,benchmark ./...
# E2E 测试
go test -tags=e2e ./e2e/...
# 覆盖率报告
go test -cover ./...
```
### 3. 服务启动
```bash
# 使用配置文件
/tmp/supply-api -env=dev
# 服务运行端口
# http://localhost:18082
```
### 4. 健康检查端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/actuator/health` | GET | 综合健康检查 |
| `/actuator/health/live` | GET | 存活探针 |
| `/actuator/health/ready` | GET | 就绪探针 |
### 5. 性能基准（参考值）
| 操作 | 性能 |
|------|------|
| AccountService_Create | ~680 ns/op |
| AccountService_Verify | ~3.6 ns/op |
| PackageService_CreateDraft | ~510 ns/op |
| SettlementService_Withdraw | ~630 ns/op |
| LoggingMiddleware | ~1.8 μs/op |
| TracingMiddleware | ~1.9 μs/op |
### 6. 测试覆盖率目标
| 模块 | 当前覆盖率 | 目标覆盖率 |
|------|-----------|-----------|
| audit/events | 97.6% | 95%+ |
| audit/model | 93.8% | 90%+ |
| audit/service | 83.0% | 80%+ |
| audit/sanitizer | 84.3% | 80%+ |
| security | 88.8% | 80%+ |
| domain | 61.2% | 70%+ |
| middleware | 53.9% | 70%+ |
---
## 文件结构 ## 文件结构
``` ```
@@ -374,5 +449,31 @@ supply-api/
│ ├── config/ # 配置管理 │ ├── config/ # 配置管理
│ └── pkg/ # 公共包 │ └── pkg/ # 公共包
├── sql/postgresql/ # 数据库 DDL 脚本 ├── sql/postgresql/ # 数据库 DDL 脚本
└── docs/ # 设计文档 ├── e2e/ # E2E 测试
├── docs/ # 设计文档
└── deploy/ # 部署配置
``` ```
---
## 常见问题与解决方案
### Q1: 如何处理跨模块命名不一致？
**A**: 建立字段命名标准文档，所有模块遵循 W3C 和行业通用命名。
### Q2: 何时使用乐观锁 vs 悲观锁？
**A**:
- 乐观锁：读多写少，低冲突场景
- 悲观锁：高并发写，财务类敏感操作
### Q3: 如何避免中间件代码重复？
**A**: 使用统一的 Handler 模式，集中管理公共逻辑。
### Q4: 审计日志的性能影响如何控制？
**A**: 采样策略 + 异步写入 + 批量处理。
### Q5: E2E 测试编译失败如何处理？
**A**: 检查未使用的导入和变量，确保 `ctx` 变量被正确使用或声明为 `_`。
### Q6: 基准测试无法运行？
**A**: 基准测试需要 `-tags=slow` 标记，且 `testing.Short()` 返回 false 时才运行。

122
supply-api/docs/project_experience_summary.md
View File

@@ -372,19 +372,127 @@ git rm $(git status --short | grep "^ D " | sed 's/^ D //')
--- ---
## 八、改进建议 ## 八、测试验证经验（2026-04-09）
### 8.1 短期改进 ### 8.1 集成测试环境配置
1. [ ] 完善单元测试覆盖率（当前 75% → 目标 85%）
2. [ ] 补充集成测试
3. [ ] 添加 API 文档（OpenAPI/Swagger）
### 8.2 中期改进 **Unix Socket vs TCP 连接**：
```bash
# Unix socket（开发环境推荐）
export SUPPLY_API_DB_HOST="/var/run/postgresql"
dsn = "postgres://user:password@/dbname?host=/var/run/postgresql&sslmode=disable"
# TCP 连接（生产环境）
dsn = "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
**常见错误**：
- `password authentication failed` - 检查 pg_hba.conf 或使用 Unix socket
- `database does not exist` - DSN 路径解析错误
- `server error (FATAL)` - 主机名解析问题
### 8.2 测试覆盖率要求
| 模块 | 当前覆盖率 | 最低要求 | 优秀 |
|------|-----------|---------|------|
| audit/events | 97.6% | 80% | 95%+ |
| audit/handler | 79.6% | 75% | 85%+ |
| audit/model | 93.8% | 80% | 90%+ |
| audit/sanitizer | 84.3% | 80% | 90%+ |
| audit/service | 83.0% | 80% | 85%+ |
| security | 88.8% | 80% | 90%+ |
| domain | 61.2% | 70% | 80%+ |
| middleware | 53.9% | 70% | 80%+ |
### 8.3 性能基准测试
**运行方式**：
```bash
go test -tags=slow -bench=. -benchmem -run=^$ ./internal/benchmark/...
```
**参考性能数据**：
| 操作 | 性能 | Allocation |
|------|------|-----------|
| AccountService_Create | 678.7 ns/op | 601 B/op, 5 allocs |
| AccountService_Verify | 3.6 ns/op | 0 B/op, 0 allocs |
| PackageService_CreateDraft | 508.8 ns/op | 462 B/op, 1 allocs |
| SettlementService_Withdraw | 625.7 ns/op | 463 B/op, 2 allocs |
| ConcurrentAccountAccess | 3.5 ns/op | 0 B/op, 0 allocs |
| LoggingMiddleware | 1.8 μs/op | 5.4 KB/op, 18 allocs |
| TracingMiddleware | 1.9 μs/op | 5.7 KB/op, 19 allocs |
### 8.4 E2E 测试常见问题
**编译错误**：
```go
// 错误：导入但未使用
import (
"context" // ❌ 未使用
"github.com/stretchr/testify/assert" // ❌ 未使用
)
// 修复
import (
_ "context" // 使用空白导入或删除
)
```
**变量声明未使用**：
```go
// 错误
ctx, cancel := context.WithTimeout(context.Background(), cfg.Timeout)
defer cancel()
// 修复
_, cancel := context.WithTimeout(context.Background(), cfg.Timeout)
defer cancel()
_ = ctx // 如果确实需要 ctx
```
### 8.5 数据库表验证
**验证步骤**：
1. 连接数据库：`psql` 或 `pg_isready`
2. 列出所有表：`SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'`
3. 验证字段：`SELECT column_name FROM information_schema.columns WHERE table_name = 'xxx'`
4. 验证索引：`SELECT indexname FROM pg_indexes WHERE tablename = 'xxx'`
**核心表结构验证通过**：
- `supply_accounts` - 包含 `version` 字段（乐观锁）
- `supply_packages` - 包含 `available_quota`、`version` 字段
- `supply_settlements` - 支持 `FOR UPDATE SKIP LOCKED`、`NOWAIT`
### 8.6 中间件鲁棒性验证
**TimeoutMiddleware 并发问题**：
- 主 goroutine 和 handler goroutine 不能同时持有锁
- 使用 `sync.Once` 或互斥锁 + 标志位确保响应只发送一次
- 超时设置必须足够长（建议 >100ms）
**性能测试注意**：
- 基准测试在 short mode 下会被跳过
- `testing.Short()` 返回 true 时不运行基准测试
- 使用 `-short=false` 覆盖默认行为
---
## 九、改进建议
### 9.1 短期改进
1. [x] 补充集成测试（43个测试已通过）
2. [x] 修复 E2E 测试编译错误
3. [x] 建立基准测试套件
4. [ ] 完善 API 文档（OpenAPI/Swagger）
5. [ ] 补充 middleware 模块测试覆盖率（当前 53.9%）
### 9.2 中期改进
1. [ ] 实现数据库连接池监控 1. [ ] 实现数据库连接池监控
2. [ ] 添加 Redis 缓存命中率指标 2. [ ] 添加 Redis 缓存命中率指标
3. [ ] 完善错误码体系文档 3. [ ] 完善错误码体系文档
4. [ ] 补充 domain 模块测试覆盖率（当前 61.2%）
### 8.3 长期改进 ### 9.3 长期改进
1. [ ] 迁移到 gRPC 1. [ ] 迁移到 gRPC
2. [ ] 实现服务网格 2. [ ] 实现服务网格
3. [ ] 添加 A/B 测试框架 3. [ ] 添加 A/B 测试框架