proxy-pool/docs/development/guide.md

开发指南

1. 环境

• Go 1.26 或 go.mod 指定版本。
• PostgreSQL 与 Redis 仅用于适配器集成测试，领域单测不依赖外部服务。
• 运行 go test -race 需要 CGO 和 C 编译器。
• Docker Compose 用于本地完整拓扑，Docker 不应成为普通单测前置条件。
• Protobuf descriptor 验证需要 protoc；非标准安装可通过 PROTOC_INCLUDE 指定 Google well-known types 的 include 目录。

2. 开发循环

1. 在 traceability.md 中找到需求 ID。
2. 先写会失败的单测或契约测试，确认失败原因与需求一致。
3. 实现最小完整行为，不增加空接口或预留目录。
4. 运行目标包测试，再运行全仓库测试和静态检查。
5. 更新需求证据、相关文档和配置示例。

go test ./internal/domain/proxy
go test ./...
go vet ./...
go build ./...

3. 包设计规则

• 领域包使用业务语言，不使用 Controller、HTTP 或数据库 DTO。
• 模块接口应隐藏内部策略步骤，避免把 filter/scorer/picker 拆成浅接口链。
• 时间逻辑注入 now 或 Clock，测试禁止依赖真实睡眠。
• Provider 调度使用有界信号、singleflight、超时和抖动退避。
• 后台队列必须有容量、溢出策略、关闭语义和指标。
• 并发计数必须以不变量测试证明，不只检查最终值。

4. 配置变更

新增字段时同时修改：

1. internal/config 类型、默认值与校验。
2. configs/default.yaml。
3. docs/configuration/reference.md。
4. 至少一个有效示例和一个无效测试。
5. 配置版本兼容说明；不静默忽略未知字段。

5. API 变更

• OpenAPI 是 REST 契约源，Protobuf 是 Controller/Worker 契约源。
• 先更新契约和兼容性测试，再修改 handler。
• Distribution 不得出现 lease、release、renew、return 等资源归还语义。
• 错误响应包含稳定 code 和 requestId，不向调用方暴露 Secret 或内部栈。

6. 并发与性能

• Gateway 请求路径不得出现远程存储访问和无界 goroutine 创建。
• Snapshot 构建在后台完成，发布后只读；请求只做一次原子指针读取。
• Proxy 容量由同一个打包原子值保存 Active/Reserved，避免分开检查再写入。
• 性能优化必须附基准；100k QPS 结论必须附完整环境和负载模型。

7. 提交前检查

./scripts/verify.ps1
./scripts/verify-proto.ps1

审查还要确认：无 Secret 日志、无 Proxy IP 高基数标签、无默认 direct、无 Extraction Lease API、无把重复结果误计为 Empty 的逻辑。