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