49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
185 lines
6.8 KiB
Markdown
185 lines
6.8 KiB
Markdown
# 10-plan — 外部 HTTP 客户端配置治理
|
||
|
||
> 对应 `docs/specs/10-http-client-governance.md`。现状:HttpClientPool 已统一(Coze/品牌/紫鸟共用连接池)。
|
||
> 技术栈:Java 21 + JDK HttpClient + RestClient。
|
||
|
||
## 任务 166:各客户端契约表盘点
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
盘点 Coze/OSS/RustFS/图片下载/紫鸟各客户端现状:connect/read/write/call timeout、重试、幂等性;产出契约表文档;标注 JDK HttpClient 平台限制(无独立 write timeout、连接池上限不可配置);不改代码。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_contract_table_all_clients — 全客户端
|
||
2. test_timeouts_listed — 超时现状
|
||
3. test_retry_listed — 重试现状
|
||
4. test_idempotency_listed — 幂等性
|
||
5. test_jdk_limits_noted — 平台限制
|
||
6. test_doc_committed — 文档存在
|
||
7. test_no_code_change — 零代码
|
||
8. test_repeatable — 可复查
|
||
|
||
### TDD 流程
|
||
1. 断言文档存在 → RED
|
||
2. 产出契约表 → GREEN
|
||
|
||
## 任务 167:aiimage.http-client.* 配置命名空间
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:166 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
application.yml 新增 `aiimage.http-client.*` 命名空间(connect-timeout/read-timeout/call-timeout/retry 默认值);默认值与现状一致;配置类绑定校验。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_config_namespace_exists — 命名空间
|
||
2. test_defaults_match_current — 默认一致
|
||
3. test_connect_timeout_bound — 合法值
|
||
4. test_read_timeout_bound
|
||
5. test_retry_count_bound
|
||
6. test_invalid_values_clamped — 非法钳制
|
||
7. test_config_class_binding — 绑定类
|
||
8. test_env_override — env 覆盖
|
||
|
||
## 任务 168:Coze 客户端配置接入
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
Coze 客户端从配置读取超时/重试(现为硬编码或独立配置);行为不变(默认值等同现状)。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_coze_timeout_from_config — 配置生效
|
||
2. test_coze_default_kept — 默认不变
|
||
3. test_coze_override — 覆盖
|
||
4. test_coze_call_timeout — 总时长
|
||
5. test_coze_retry_config — 重试配置
|
||
6. test_coze_pool_shared — 共用连接池
|
||
7. test_coze_idempotent_post — 幂等标注
|
||
8. test_coze_behavior_same — 行为一致
|
||
|
||
## 任务 169:品牌检查客户端配置接入
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||
|
||
同 168 模式。
|
||
|
||
### 测试用例(≥8)
|
||
同 168(品牌检查)。
|
||
|
||
## 任务 170:紫鸟客户端配置接入
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||
|
||
同 168 模式。
|
||
|
||
### 测试用例(≥8)
|
||
同 168(紫鸟)。
|
||
|
||
## 任务 171:图片下载客户端配置接入
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||
|
||
同 168 模式(图片下载特有:大响应流式读取)。
|
||
|
||
### 测试用例(≥8)
|
||
1-8:配置生效、默认、覆盖、call timeout、重试、池共享、幂等、流式读取。
|
||
|
||
## 任务 172:幂等重试守卫
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:167 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
统一重试守卫:仅幂等请求(GET/HEAD)自动重试;非幂等(POST/PUT)不自动重试;重试次数与退避从配置;防重试风暴。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_get_retried — GET 重试
|
||
2. test_post_not_retried — POST 不重试
|
||
3. test_retry_count_limited — 次数限制
|
||
4. test_retry_backoff — 退避
|
||
5. test_idempotent_header_override — 显式幂等标记
|
||
6. test_retry_success_after_fail — 重试成功
|
||
7. test_retry_exhausted_fail — 耗尽失败
|
||
8. test_no_retry_storm — 不风暴
|
||
|
||
## 任务 173:超时生效测试
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
mock 慢端点(>read timeout):请求在超时内失败;connect timeout 生效;call timeout 生效(RestClient 层)。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_read_timeout_fires — 读超时
|
||
2. test_read_timeout_duration — 时长断言
|
||
3. test_connect_timeout_fires — 连接超时
|
||
4. test_connect_timeout_duration
|
||
5. test_call_timeout_fires — 总时长
|
||
6. test_fast_response_ok — 快响应正常
|
||
7. test_timeout_error_type — 错误类型
|
||
8. test_timeout_after_config — 配置生效
|
||
|
||
## 任务 174:连接复用测试
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:168-171 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
连续 N 请求复用底层连接(共享 HttpClient);不同客户端共用连接池;连接不复用时暴露。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_connection_reused — 复用
|
||
2. test_shared_across_clients — 跨客户端共用
|
||
3. test_sequential_requests — 顺序复用
|
||
4. test_keep_alive_header — keep-alive
|
||
5. test_no_new_connection_burst — 突发不建新连
|
||
6. test_pool_singleton — 单例
|
||
7. test_concurrent_reuse — 并发复用
|
||
8. test_connection_stats — 连接统计
|
||
|
||
## 任务 175:Python 回调超时不变确认
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
只读确认:Java 侧外部客户端改动不影响 Python 回调请求的超时与重试约定(Python 侧 requests 调用不动);写断言测试固化 Python 回调契约不受 Java 配置影响。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_python_callback_contract — 回调契约
|
||
2. test_no_java_config_affects_python — 不受影响
|
||
3. test_python_timeout_doc — 文档一致
|
||
4. test_python_retry_doc
|
||
5. test_python_headers — 头一致
|
||
6. test_python_success_detection — 成功判定
|
||
7. test_python_contract_frozen — 快照
|
||
8. test_no_code_change_python — Python 零改动
|
||
|
||
## 任务 176:重试计数与日志字段
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:172 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
重试时记录日志(客户端/URL/尝试次数/耗时);重试计数指标;不记录敏感信息。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_retry_logged — 日志
|
||
2. test_retry_attempt_field — 尝试次数
|
||
3. test_retry_duration — 耗时
|
||
4. test_retry_metric — 指标
|
||
5. test_no_token_in_log — 无敏感信息
|
||
6. test_success_no_retry_log — 成功不记
|
||
7. test_log_level — 日志级别
|
||
8. test_final_failure_logged — 最终失败
|
||
|
||
## 任务 177:10 全量回归
|
||
|
||
**所属模块**:10 HTTP 客户端 **依赖**:168-176 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
全部客户端配置改造后:现有测试全绿;外部服务 mock 集成测试通过;行为与默认配置下现状一致。
|
||
|
||
### 测试用例(≥8)
|
||
1-8:各客户端测试绿、HttpClientPool 既有测试绿、配置绑定测试、超时测试、复用测试、幂等守卫、日志脱敏、全量单测
|
||
|
||
### 验证方法
|
||
`mvn test` 全量 + `mvn clean package -DskipTests`。
|