69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# 开发指南
|
||
|
||
## 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 的逻辑。
|