# 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`。