# 开发指南

## 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. 更新需求证据、相关文档和配置示例。

```powershell
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. 提交前检查

```powershell
./scripts/verify.ps1
./scripts/verify-proto.ps1
```

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