task-166: HTTP 客户端契约表盘点（45 项超时/重试配置、198 个调用点扫描器 + 8 条测试 + 报告快照，不改生产代码）

backend-java/scripts/http_client_audit.py

@@ -0,0 +1,117 @@
+"""task-166 HTTP 客户端契约盘点工具。
+
+盘点 backend-java 各 HTTP 客户端（OSS/RustFS/图片下载/紫鸟/LLM）的现状：
+超时（connect/read/write/call）、重试、幂等性，产出机器可读契约表供审计文档使用。
+本工具只读，不改代码。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CONFIG_ROOT = REPO_ROOT / "src/main/java/com/nanri/aiimage/config"
+MAIN_ROOT = REPO_ROOT / "src/main/java"
+
+# 超时/重试配置字段（config 包）
+TIMEOUT_FIELD_RE = re.compile(
+    r"private\s+\w+\s+(\w*(?:Timeout|Retries|Retry|MaxRetries)\w*)\s*=\s*([^;]+);",
+    re.IGNORECASE,
+)
+# 代码中 HttpClient/Client 构建的超时/重试配置
+CLIENT_CONF_RE = re.compile(
+    r"(connectTimeout|readTimeout|writeTimeout|callTimeout|operationTimeout|"
+    r"maxRetries|retry|setConnectTimeout|setReadTimeout|HttpClient\.newBuilder)",
+    re.IGNORECASE,
+)
+# 客户端类识别
+CLIENT_CLASS_RE = re.compile(
+    r"(OssStorageService|RustfsObjectStorageService|ZiniaoShopSwitchService|"
+    r"SimilarAsinLlmService|AppearancePatentLlmClient|ImageDownloader|ImageDownload|"
+    r"imageDownload|HttpClient|WebClient|RestTemplate)",
+)
+
+
+def extract_timeout_configs() -> list[dict]:
+    """从 config 包提取超时/重试配置字段。"""
+    entries: list[dict] = []
+    for java_file in sorted(CONFIG_ROOT.rglob("*.java")):
+        text = java_file.read_text(encoding="utf-8")
+        for match in TIMEOUT_FIELD_RE.finditer(text):
+            entries.append(
+                {
+                    "config_class": java_file.stem,
+                    "field": match.group(1),
+                    "default": match.group(2).strip(),
+                    "source": str(java_file.relative_to(REPO_ROOT)).replace("\\", "/"),
+                }
+            )
+    return entries
+
+
+def extract_client_sites() -> list[dict]:
+    """扫描 main 源码中客户端构建/配置调用点。"""
+    sites: list[dict] = []
+    for java_file in sorted(MAIN_ROOT.rglob("*.java")):
+        text = java_file.read_text(encoding="utf-8")
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            if not CLIENT_CONF_RE.search(line) or "import " in line:
+                continue
+            if CLIENT_CLASS_RE.search(line) or "Timeout" in line or "Retry" in line:
+                sites.append(
+                    {
+                        "file": str(java_file.relative_to(REPO_ROOT)).replace(
+                            "\\", "/"
+                        ),
+                        "line": line_no,
+                        "snippet": line.strip()[:110],
+                    }
+                )
+    return sites
+
+
+@dataclass
+class Report:
+    timeout_configs: list[dict] = field(default_factory=list)
+    client_sites: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "timeout_configs": self.timeout_configs,
+            "client_sites": self.client_sites,
+        }
+
+
+def scan() -> Report:
+    return Report(
+        timeout_configs=extract_timeout_configs(), client_sites=extract_client_sites()
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="HTTP 客户端契约盘点")
+    parser.add_argument("--json", help="输出 JSON 报告路径（默认 stdout）")
+    args = parser.parse_args()
+
+    report = scan()
+    payload = report.to_dict()
+    if args.json:
+        Path(args.json).write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    print(
+        f"timeout configs: {len(payload['timeout_configs'])}, "
+        f"client sites: {len(payload['client_sites'])}",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()

backend-java/scripts/test_http_client_audit.py

@@ -0,0 +1,93 @@
+"""task-166 HTTP 客户端契约盘点测试。
+
+对应 plan 10 任务 166 的 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                  可复查
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import unittest
+
+from http_client_audit import (
+    REPO_ROOT,
+    extract_client_sites,
+    extract_timeout_configs,
+    scan,
+)
+
+DOC_PATH = REPO_ROOT / "docs" / "http-client-contract-audit.md"
+
+
+class HttpClientAuditTest(unittest.TestCase):
+    def test_contract_table_all_clients(self):
+        configs = extract_timeout_configs()
+        self.assertGreaterEqual(len(configs), 4, "超时/重试配置字段必须齐全")
+        classes = {c["config_class"] for c in configs}
+        self.assertTrue(
+            any("Transient" in name or "Storage" in name for name in classes),
+            "存储客户端配置存在",
+        )
+        self.assertTrue(
+            any("SimilarAsin" in name or "ImageVideo" in name for name in classes),
+            "LLM/图片客户端配置存在",
+        )
+
+    def test_timeouts_listed(self):
+        fields = {c["field"] for c in extract_timeout_configs()}
+        self.assertTrue(any("connectTimeout" in f for f in fields), "connect 超时缺失")
+        self.assertTrue(any("readTimeout" in f for f in fields), "read 超时缺失")
+        self.assertTrue(any("writeTimeout" in f for f in fields), "write 超时缺失")
+        self.assertTrue(any("callTimeout" in f for f in fields), "call 超时缺失")
+
+    def test_retry_listed(self):
+        fields = {c["field"] for c in extract_timeout_configs()}
+        self.assertTrue(any("Retry" in f for f in fields), "重试配置缺失")
+
+    def test_idempotency_listed(self):
+        sites = extract_client_sites()
+        self.assertGreater(len(sites), 0, "客户端配置调用点必须记录")
+
+    def test_jdk_limits_noted(self):
+        sites = extract_client_sites()
+        self.assertTrue(
+            any(
+                "HttpClient" in s["snippet"] or "newBuilder" in s["snippet"]
+                for s in sites
+            ),
+            "JDK HttpClient 使用点必须记录",
+        )
+
+    def test_doc_committed(self):
+        self.assertTrue(DOC_PATH.is_file(), f"契约表文档缺失: {DOC_PATH}")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        self.assertIn("超时", text)
+        self.assertIn("重试", text)
+        self.assertIn("幂等", text)
+
+    def test_no_code_change(self):
+        changed = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
+            cwd=REPO_ROOT,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        self.assertEqual(changed, "", f"生产代码被改动: {changed}")
+
+    def test_repeatable(self):
+        first = json.dumps(scan().to_dict(), sort_keys=True)
+        second = json.dumps(scan().to_dict(), sort_keys=True)
+        self.assertEqual(first, second, "盘点可复查")
+
+
+if __name__ == "__main__":
+    unittest.main()