task-166: HTTP 客户端契约表盘点（45 项超时/重试配置、198 个调用点扫描器 + 8 条测试 + 报告快照，不改生产代码）
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -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()
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user