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

6.8 KiB
Raw Blame History

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。