Files
crawler-plugin/backend-java/docs/plans/10-plan-http-client-governance.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

185 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`。