882 lines
34 KiB
Python
882 lines
34 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""ETL 架构分析脚本。
|
||
|
||
通过静态分析（AST 解析、import 扫描、文件统计）评估 ETL 代码结构，
|
||
生成架构优化报告（Markdown）。
|
||
|
||
分析维度：
|
||
1. 模块依赖关系 — 扫描 import，构建依赖图，识别循环依赖
|
||
2. 文件大小分析 — 统计行数，识别过大文件（>500 行）
|
||
3. 函数复杂度 — AST 分析圈复杂度（分支/嵌套深度）
|
||
4. 重复代码检测 — 比较函数签名和结构相似度
|
||
5. 耦合度评估 — 模块间导入关系密度
|
||
6. 任务分类分析 — 从 TaskRegistry 读取元数据，评估分类合理性
|
||
|
||
用法:
|
||
cd apps/etl/connectors/feiqiu
|
||
python -m scripts.debug.analyze_architecture
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
import ast
|
||
import argparse
|
||
import logging
|
||
import os
|
||
import sys
|
||
from collections import Counter, defaultdict
|
||
from dataclasses import dataclass, field
|
||
from datetime import datetime
|
||
from pathlib import Path
|
||
from typing import Iterator
|
||
|
||
# ── 确保项目根目录在 sys.path ──
|
||
_FEIQIU_ROOT = Path(__file__).resolve().parents[2]
|
||
if str(_FEIQIU_ROOT) not in sys.path:
|
||
sys.path.insert(0, str(_FEIQIU_ROOT))
|
||
|
||
# ── 分析范围：ETL 核心模块 ──
|
||
_CORE_MODULES = [
|
||
"api", "cli", "config", "database", "loaders", "models",
|
||
"orchestration", "quality", "scd", "tasks", "utils",
|
||
]
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 数据结构
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
@dataclass
|
||
class FileInfo:
|
||
"""单个 .py 文件的统计信息"""
|
||
path: Path
|
||
rel_path: str
|
||
lines: int = 0
|
||
code_lines: int = 0 # 非空非注释行
|
||
blank_lines: int = 0
|
||
comment_lines: int = 0
|
||
module: str = "" # 所属模块（api/cli/...）
|
||
|
||
|
||
@dataclass
|
||
class FunctionInfo:
|
||
"""函数/方法的分析信息"""
|
||
name: str
|
||
file: str
|
||
line: int
|
||
complexity: int = 1 # 圈复杂度
|
||
max_nesting: int = 0 # 最大嵌套深度
|
||
param_count: int = 0
|
||
lines: int = 0 # 函数体行数
|
||
is_method: bool = False
|
||
class_name: str = ""
|
||
|
||
|
||
@dataclass
|
||
class ImportEdge:
|
||
"""模块间的导入关系"""
|
||
source_module: str # 导入方
|
||
target_module: str # 被导入方
|
||
source_file: str
|
||
import_name: str # 具体导入的名称
|
||
|
||
|
||
@dataclass
|
||
class ArchitectureReport:
|
||
"""架构分析报告的完整数据"""
|
||
generated_at: datetime = field(default_factory=datetime.now)
|
||
# 文件统计
|
||
files: list[FileInfo] = field(default_factory=list)
|
||
# 函数分析
|
||
functions: list[FunctionInfo] = field(default_factory=list)
|
||
# 依赖关系
|
||
import_edges: list[ImportEdge] = field(default_factory=list)
|
||
circular_deps: list[tuple[str, str]] = field(default_factory=list)
|
||
# 任务分类
|
||
task_classification: dict = field(default_factory=dict)
|
||
# 重复代码
|
||
similar_functions: list[tuple[str, str, float]] = field(default_factory=list)
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 日志
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def _setup_logging() -> logging.Logger:
|
||
logger = logging.getLogger("analyze_architecture")
|
||
logger.setLevel(logging.INFO)
|
||
if not logger.handlers:
|
||
handler = logging.StreamHandler(sys.stdout)
|
||
handler.setFormatter(logging.Formatter(
|
||
"%(asctime)s [%(levelname)s] %(message)s", datefmt="%H:%M:%S"
|
||
))
|
||
logger.addHandler(handler)
|
||
return logger
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 1. 文件扫描与行数统计
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def _iter_py_files(root: Path) -> Iterator[Path]:
|
||
"""递归遍历核心模块下的 .py 文件，跳过 __pycache__ / .hypothesis 等。"""
|
||
skip_dirs = {"__pycache__", ".hypothesis", ".pytest_cache", "export", "Asia"}
|
||
for dirpath, dirnames, filenames in os.walk(root):
|
||
dirnames[:] = [d for d in dirnames if d not in skip_dirs]
|
||
for fn in filenames:
|
||
if fn.endswith(".py"):
|
||
yield Path(dirpath) / fn
|
||
|
||
|
||
def _classify_module(rel_path: str) -> str:
|
||
"""从相对路径提取所属模块名。"""
|
||
parts = Path(rel_path).parts
|
||
if parts:
|
||
top = parts[0]
|
||
if top in _CORE_MODULES:
|
||
return top
|
||
if top == "scripts":
|
||
return "scripts"
|
||
if top == "tests":
|
||
return "tests"
|
||
return "root"
|
||
|
||
|
||
def _count_lines(filepath: Path) -> FileInfo:
|
||
"""统计单个文件的行数分布。"""
|
||
info = FileInfo(path=filepath, rel_path="")
|
||
try:
|
||
text = filepath.read_text(encoding="utf-8", errors="replace")
|
||
except Exception:
|
||
return info
|
||
raw_lines = text.splitlines()
|
||
info.lines = len(raw_lines)
|
||
for line in raw_lines:
|
||
stripped = line.strip()
|
||
if not stripped:
|
||
info.blank_lines += 1
|
||
elif stripped.startswith("#"):
|
||
info.comment_lines += 1
|
||
else:
|
||
info.code_lines += 1
|
||
return info
|
||
|
||
|
||
def scan_files(root: Path, logger: logging.Logger) -> list[FileInfo]:
|
||
"""扫描所有 .py 文件并统计行数。"""
|
||
results: list[FileInfo] = []
|
||
for fp in _iter_py_files(root):
|
||
info = _count_lines(fp)
|
||
info.path = fp
|
||
info.rel_path = str(fp.relative_to(root)).replace("\\", "/")
|
||
info.module = _classify_module(info.rel_path)
|
||
results.append(info)
|
||
logger.info("扫描完成：共 %d 个 .py 文件", len(results))
|
||
return results
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 2. AST 分析：函数复杂度
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
# 增加圈复杂度的 AST 节点类型
|
||
_COMPLEXITY_NODES = (
|
||
ast.If, ast.For, ast.While, ast.ExceptHandler,
|
||
ast.With, ast.Assert, ast.BoolOp,
|
||
)
|
||
# 仅 comprehension 内的 if 子句
|
||
_COMP_NODES = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
|
||
|
||
|
||
def _calc_complexity(node: ast.AST) -> int:
|
||
"""计算函数体的圈复杂度（McCabe）。"""
|
||
complexity = 1
|
||
for child in ast.walk(node):
|
||
if isinstance(child, _COMPLEXITY_NODES):
|
||
complexity += 1
|
||
# BoolOp 中每个额外的 and/or 加 1
|
||
if isinstance(child, ast.BoolOp):
|
||
complexity += len(child.values) - 2 if len(child.values) > 2 else 0
|
||
elif isinstance(child, _COMP_NODES):
|
||
for gen in child.generators:
|
||
complexity += len(gen.ifs)
|
||
return complexity
|
||
|
||
|
||
def _calc_max_nesting(node: ast.AST, depth: int = 0) -> int:
|
||
"""计算最大嵌套深度。"""
|
||
nesting_types = (ast.If, ast.For, ast.While, ast.With, ast.Try, ast.ExceptHandler)
|
||
max_depth = depth
|
||
for child in ast.iter_child_nodes(node):
|
||
if isinstance(child, nesting_types):
|
||
child_depth = _calc_max_nesting(child, depth + 1)
|
||
max_depth = max(max_depth, child_depth)
|
||
else:
|
||
child_depth = _calc_max_nesting(child, depth)
|
||
max_depth = max(max_depth, child_depth)
|
||
return max_depth
|
||
|
||
|
||
def _func_body_lines(node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
|
||
"""计算函数体行数。"""
|
||
if not node.body:
|
||
return 0
|
||
first_line = node.body[0].lineno
|
||
last_line = node.body[-1].end_lineno or node.body[-1].lineno
|
||
return last_line - first_line + 1
|
||
|
||
|
||
def _walk_with_parent(tree: ast.AST):
|
||
"""遍历 AST 并记录每个节点的父节点（避免 O(n²) 嵌套 walk）。"""
|
||
# 先给所有节点标记 parent
|
||
for node in ast.walk(tree):
|
||
for child in ast.iter_child_nodes(node):
|
||
child._parent = node # type: ignore[attr-defined]
|
||
|
||
|
||
def analyze_functions(files: list[FileInfo], logger: logging.Logger) -> list[FunctionInfo]:
|
||
"""对所有文件做 AST 分析，提取函数/方法信息。"""
|
||
results: list[FunctionInfo] = []
|
||
for fi in files:
|
||
try:
|
||
source = fi.path.read_text(encoding="utf-8", errors="replace")
|
||
tree = ast.parse(source, filename=fi.rel_path)
|
||
except (SyntaxError, UnicodeDecodeError):
|
||
continue
|
||
|
||
_walk_with_parent(tree)
|
||
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
||
# 通过 _parent 属性判断是否为方法
|
||
parent = getattr(node, "_parent", None)
|
||
class_name = ""
|
||
is_method = False
|
||
if isinstance(parent, ast.ClassDef):
|
||
class_name = parent.name
|
||
is_method = True
|
||
|
||
param_count = len(node.args.args)
|
||
if is_method and param_count > 0:
|
||
param_count -= 1 # 去掉 self/cls
|
||
|
||
info = FunctionInfo(
|
||
name=node.name,
|
||
file=fi.rel_path,
|
||
line=node.lineno,
|
||
complexity=_calc_complexity(node),
|
||
max_nesting=_calc_max_nesting(node),
|
||
param_count=param_count,
|
||
lines=_func_body_lines(node),
|
||
is_method=is_method,
|
||
class_name=class_name,
|
||
)
|
||
results.append(info)
|
||
|
||
logger.info("函数分析完成：共 %d 个函数/方法", len(results))
|
||
return results
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 3. 依赖关系分析
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def _extract_imports(filepath: Path, rel_path: str) -> list[ImportEdge]:
|
||
"""从单个文件提取 import 语句，映射到模块级别。"""
|
||
edges: list[ImportEdge] = []
|
||
try:
|
||
source = filepath.read_text(encoding="utf-8", errors="replace")
|
||
tree = ast.parse(source, filename=rel_path)
|
||
except (SyntaxError, UnicodeDecodeError):
|
||
return edges
|
||
|
||
source_module = _classify_module(rel_path)
|
||
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, ast.Import):
|
||
for alias in node.names:
|
||
target = _resolve_import_module(alias.name)
|
||
if target and target != source_module:
|
||
edges.append(ImportEdge(
|
||
source_module=source_module,
|
||
target_module=target,
|
||
source_file=rel_path,
|
||
import_name=alias.name,
|
||
))
|
||
elif isinstance(node, ast.ImportFrom):
|
||
if node.module:
|
||
target = _resolve_import_module(node.module)
|
||
if target and target != source_module:
|
||
names = ", ".join(a.name for a in (node.names or []))
|
||
edges.append(ImportEdge(
|
||
source_module=source_module,
|
||
target_module=target,
|
||
source_file=rel_path,
|
||
import_name=f"{node.module}.{{{names}}}",
|
||
))
|
||
return edges
|
||
|
||
|
||
def _resolve_import_module(import_path: str) -> str | None:
|
||
"""将 import 路径映射到核心模块名。"""
|
||
parts = import_path.split(".")
|
||
top = parts[0]
|
||
if top in _CORE_MODULES:
|
||
return top
|
||
return None
|
||
|
||
|
||
def analyze_dependencies(files: list[FileInfo], logger: logging.Logger) -> tuple[list[ImportEdge], list[tuple[str, str]]]:
|
||
"""分析模块间依赖关系，检测循环依赖。"""
|
||
all_edges: list[ImportEdge] = []
|
||
for fi in files:
|
||
all_edges.extend(_extract_imports(fi.path, fi.rel_path))
|
||
|
||
# 构建有向图检测循环
|
||
graph: dict[str, set[str]] = defaultdict(set)
|
||
for edge in all_edges:
|
||
graph[edge.source_module].add(edge.target_module)
|
||
|
||
circular: list[tuple[str, str]] = []
|
||
for src, targets in graph.items():
|
||
for tgt in targets:
|
||
if src in graph.get(tgt, set()):
|
||
pair = tuple(sorted([src, tgt]))
|
||
if pair not in circular:
|
||
circular.append(pair)
|
||
|
||
logger.info("依赖分析完成：%d 条导入边，%d 对循环依赖", len(all_edges), len(circular))
|
||
return all_edges, circular
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 4. 重复代码检测（基于函数签名相似度）
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def _func_signature_key(fn: FunctionInfo) -> str:
|
||
"""生成函数签名指纹：参数数量 + 行数范围 + 复杂度。"""
|
||
line_bucket = fn.lines // 10 * 10 # 按 10 行分桶
|
||
return f"p{fn.param_count}_l{line_bucket}_c{fn.complexity}"
|
||
|
||
|
||
def detect_similar_functions(
|
||
functions: list[FunctionInfo],
|
||
logger: logging.Logger,
|
||
min_lines: int = 15,
|
||
) -> list[tuple[str, str, float]]:
|
||
"""检测签名相似的函数对（可能是重复代码）。
|
||
|
||
只比较行数 >= min_lines 的函数，避免噪声。
|
||
"""
|
||
# 按签名分桶
|
||
buckets: dict[str, list[FunctionInfo]] = defaultdict(list)
|
||
for fn in functions:
|
||
if fn.lines >= min_lines:
|
||
key = _func_signature_key(fn)
|
||
buckets[key].append(fn)
|
||
|
||
similar: list[tuple[str, str, float]] = []
|
||
for key, group in buckets.items():
|
||
if len(group) < 2:
|
||
continue
|
||
# 同一桶内两两配对
|
||
for i in range(len(group)):
|
||
for j in range(i + 1, len(group)):
|
||
a, b = group[i], group[j]
|
||
# 跳过同文件内的重载/变体
|
||
if a.file == b.file:
|
||
continue
|
||
# 简单相似度：行数差异越小越相似
|
||
line_ratio = 1 - abs(a.lines - b.lines) / max(a.lines, b.lines)
|
||
if line_ratio >= 0.7:
|
||
label_a = f"{a.file}:{a.class_name}.{a.name}" if a.class_name else f"{a.file}:{a.name}"
|
||
label_b = f"{b.file}:{b.class_name}.{b.name}" if b.class_name else f"{b.file}:{b.name}"
|
||
similar.append((label_a, label_b, round(line_ratio, 2)))
|
||
|
||
logger.info("重复检测完成：%d 对相似函数", len(similar))
|
||
return similar
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 5. 任务分类分析
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def analyze_task_classification(logger: logging.Logger) -> dict:
|
||
"""从 TaskRegistry 读取 52 个任务的元数据，分析分类合理性。"""
|
||
try:
|
||
from orchestration.task_registry import default_registry, TaskMeta
|
||
except ImportError:
|
||
logger.warning("无法导入 TaskRegistry，跳过任务分类分析")
|
||
return {}
|
||
|
||
all_codes = default_registry.get_all_task_codes()
|
||
by_layer: dict[str, list[str]] = defaultdict(list)
|
||
by_type: dict[str, list[str]] = defaultdict(list)
|
||
anomalies: list[str] = []
|
||
|
||
for code in all_codes:
|
||
meta: TaskMeta | None = default_registry.get_metadata(code)
|
||
if not meta:
|
||
continue
|
||
layer = meta.layer or "NONE"
|
||
by_layer[layer].append(code)
|
||
by_type[meta.task_type].append(code)
|
||
|
||
# 检测命名与分类不一致
|
||
if code.startswith("DWS_") and layer not in ("DWS", "INDEX"):
|
||
anomalies.append(f"{code}: 前缀 DWS_ 但分类为 {layer}")
|
||
if code.startswith("ODS_") and layer != "ODS":
|
||
anomalies.append(f"{code}: 前缀 ODS_ 但分类为 {layer}")
|
||
if code.startswith("DWD_") and layer != "DWD":
|
||
anomalies.append(f"{code}: 前缀 DWD_ 但分类为 {layer}")
|
||
|
||
# 检测 INDEX 层任务命名
|
||
if layer == "INDEX" and not code.startswith("DWS_"):
|
||
anomalies.append(f"{code}: INDEX 层但不以 DWS_ 开头，可能造成混淆")
|
||
|
||
# INDEX 层任务以 DWS_ 开头的命名问题
|
||
index_tasks = by_layer.get("INDEX", [])
|
||
if index_tasks and all(c.startswith("DWS_") for c in index_tasks):
|
||
anomalies.append(
|
||
f"INDEX 层全部 {len(index_tasks)} 个任务以 DWS_ 开头，"
|
||
"建议改为 IDX_ 前缀以区分 DWS 汇总任务"
|
||
)
|
||
|
||
result = {
|
||
"total": len(all_codes),
|
||
"by_layer": {k: {"count": len(v), "tasks": sorted(v)} for k, v in sorted(by_layer.items())},
|
||
"by_type": {k: {"count": len(v), "tasks": sorted(v)} for k, v in sorted(by_type.items())},
|
||
"anomalies": anomalies,
|
||
}
|
||
logger.info("任务分类分析完成：共 %d 个任务，%d 个异常", len(all_codes), len(anomalies))
|
||
return result
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 6. 耦合度评估
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def evaluate_coupling(
|
||
edges: list[ImportEdge],
|
||
files: list[FileInfo],
|
||
) -> dict:
|
||
"""评估模块间耦合度。
|
||
|
||
指标：
|
||
- 传入耦合（Ca）：有多少模块依赖本模块
|
||
- 传出耦合（Ce）：本模块依赖多少其他模块
|
||
- 不稳定度 I = Ce / (Ca + Ce)，越接近 1 越不稳定
|
||
"""
|
||
# 只统计核心模块
|
||
modules = set(m for m in _CORE_MODULES if any(f.module == m for f in files))
|
||
|
||
ca: Counter = Counter() # 传入
|
||
ce: Counter = Counter() # 传出
|
||
|
||
# 去重：同一 source_module → target_module 只计一次
|
||
seen = set()
|
||
for edge in edges:
|
||
pair = (edge.source_module, edge.target_module)
|
||
if pair in seen:
|
||
continue
|
||
seen.add(pair)
|
||
if edge.source_module in modules:
|
||
ce[edge.source_module] += 1
|
||
if edge.target_module in modules:
|
||
ca[edge.target_module] += 1
|
||
|
||
coupling: dict[str, dict] = {}
|
||
for m in sorted(modules):
|
||
ca_val = ca.get(m, 0)
|
||
ce_val = ce.get(m, 0)
|
||
total = ca_val + ce_val
|
||
instability = round(ce_val / total, 2) if total > 0 else 0.0
|
||
coupling[m] = {
|
||
"afferent_coupling": ca_val,
|
||
"efferent_coupling": ce_val,
|
||
"instability": instability,
|
||
}
|
||
return coupling
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 7. Markdown 报告生成
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def generate_report(report: ArchitectureReport, coupling: dict) -> str:
|
||
"""生成 Markdown 格式的架构优化报告。"""
|
||
lines: list[str] = []
|
||
_a = lines.append
|
||
|
||
_a(f"# ETL 架构分析报告")
|
||
_a(f"")
|
||
_a(f"> 生成时间：{report.generated_at.strftime('%Y-%m-%d %H:%M:%S')}")
|
||
_a(f"> 分析范围：`apps/etl/connectors/feiqiu/` 核心模块")
|
||
_a("")
|
||
|
||
# ── 概览 ──
|
||
total_files = len(report.files)
|
||
total_lines = sum(f.lines for f in report.files)
|
||
total_code = sum(f.code_lines for f in report.files)
|
||
_a("## 1. 概览")
|
||
_a("")
|
||
_a(f"| 指标 | 值 |")
|
||
_a(f"|------|-----|")
|
||
_a(f"| Python 文件数 | {total_files} |")
|
||
_a(f"| 总行数 | {total_lines:,} |")
|
||
_a(f"| 代码行数 | {total_code:,} |")
|
||
_a(f"| 函数/方法数 | {len(report.functions):,} |")
|
||
_a(f"| 注册任务数 | {report.task_classification.get('total', 'N/A')} |")
|
||
_a(f"| 循环依赖数 | {len(report.circular_deps)} |")
|
||
_a(f"| 相似函数对数 | {len(report.similar_functions)} |")
|
||
_a("")
|
||
|
||
# ── 模块规模 ──
|
||
_a("## 2. 模块规模分析")
|
||
_a("")
|
||
module_stats: dict[str, dict] = defaultdict(lambda: {"files": 0, "lines": 0, "code_lines": 0})
|
||
for f in report.files:
|
||
ms = module_stats[f.module]
|
||
ms["files"] += 1
|
||
ms["lines"] += f.lines
|
||
ms["code_lines"] += f.code_lines
|
||
|
||
_a("| 模块 | 文件数 | 总行数 | 代码行数 |")
|
||
_a("|------|--------|--------|----------|")
|
||
for mod in sorted(module_stats, key=lambda m: module_stats[m]["lines"], reverse=True):
|
||
s = module_stats[mod]
|
||
_a(f"| `{mod}` | {s['files']} | {s['lines']:,} | {s['code_lines']:,} |")
|
||
_a("")
|
||
|
||
# ── 大文件 ──
|
||
large_files = [f for f in report.files if f.lines > 500]
|
||
large_files.sort(key=lambda f: f.lines, reverse=True)
|
||
_a("## 3. 大文件识别（>500 行）")
|
||
_a("")
|
||
if large_files:
|
||
_a("| 文件 | 行数 | 代码行 | 模块 |")
|
||
_a("|------|------|--------|------|")
|
||
for f in large_files:
|
||
_a(f"| `{f.rel_path}` | {f.lines:,} | {f.code_lines:,} | {f.module} |")
|
||
_a("")
|
||
_a(f"> ⚠️ 共 {len(large_files)} 个文件超过 500 行，建议拆分以降低维护成本。")
|
||
else:
|
||
_a("所有文件均在 500 行以内。✅")
|
||
_a("")
|
||
|
||
# ── 函数复杂度 ──
|
||
_a("## 4. 函数复杂度分析")
|
||
_a("")
|
||
high_complexity = [fn for fn in report.functions if fn.complexity >= 10]
|
||
high_complexity.sort(key=lambda fn: fn.complexity, reverse=True)
|
||
_a(f"### 4.1 高复杂度函数（圈复杂度 ≥ 10）")
|
||
_a("")
|
||
if high_complexity:
|
||
_a("| 函数 | 文件 | 行号 | 复杂度 | 嵌套深度 | 函数行数 |")
|
||
_a("|------|------|------|--------|----------|----------|")
|
||
for fn in high_complexity[:20]:
|
||
name = f"{fn.class_name}.{fn.name}" if fn.class_name else fn.name
|
||
_a(f"| `{name}` | `{fn.file}` | {fn.line} | {fn.complexity} | {fn.max_nesting} | {fn.lines} |")
|
||
if len(high_complexity) > 20:
|
||
_a(f"| ... | 共 {len(high_complexity)} 个 | | | | |")
|
||
else:
|
||
_a("所有函数复杂度均在合理范围内。✅")
|
||
_a("")
|
||
|
||
# 长函数
|
||
long_funcs = [fn for fn in report.functions if fn.lines >= 80]
|
||
long_funcs.sort(key=lambda fn: fn.lines, reverse=True)
|
||
_a("### 4.2 长函数（≥ 80 行）")
|
||
_a("")
|
||
if long_funcs:
|
||
_a("| 函数 | 文件 | 行号 | 函数行数 | 复杂度 |")
|
||
_a("|------|------|------|----------|--------|")
|
||
for fn in long_funcs[:15]:
|
||
name = f"{fn.class_name}.{fn.name}" if fn.class_name else fn.name
|
||
_a(f"| `{name}` | `{fn.file}` | {fn.line} | {fn.lines} | {fn.complexity} |")
|
||
if len(long_funcs) > 15:
|
||
_a(f"| ... | 共 {len(long_funcs)} 个 | | | |")
|
||
else:
|
||
_a("所有函数行数均在合理范围内。✅")
|
||
_a("")
|
||
|
||
# ── 依赖关系 ──
|
||
_a("## 5. 模块依赖关系")
|
||
_a("")
|
||
|
||
# 依赖矩阵
|
||
dep_matrix: dict[str, Counter] = defaultdict(Counter)
|
||
for edge in report.import_edges:
|
||
dep_matrix[edge.source_module][edge.target_module] += 1
|
||
|
||
all_modules = sorted(set(
|
||
list(dep_matrix.keys()) +
|
||
[t for counts in dep_matrix.values() for t in counts]
|
||
))
|
||
# 只保留核心模块
|
||
all_modules = [m for m in all_modules if m in _CORE_MODULES]
|
||
|
||
if all_modules:
|
||
_a("### 5.1 依赖矩阵（行→列 = 导入次数）")
|
||
_a("")
|
||
header = "| 模块 | " + " | ".join(f"`{m}`" for m in all_modules) + " |"
|
||
_a(header)
|
||
_a("|" + "------|" * (len(all_modules) + 1))
|
||
for src in all_modules:
|
||
row = f"| `{src}` |"
|
||
for tgt in all_modules:
|
||
count = dep_matrix.get(src, {}).get(tgt, 0)
|
||
row += f" {count or '·'} |"
|
||
_a(row)
|
||
_a("")
|
||
|
||
# 循环依赖
|
||
_a("### 5.2 循环依赖")
|
||
_a("")
|
||
if report.circular_deps:
|
||
for a, b in report.circular_deps:
|
||
_a(f"- ⚠️ `{a}` ↔ `{b}`")
|
||
_a("")
|
||
_a("> 循环依赖增加模块间耦合，建议通过接口抽象或依赖注入解耦。")
|
||
else:
|
||
_a("未检测到模块级循环依赖。✅")
|
||
_a("")
|
||
|
||
# ── 耦合度 ──
|
||
_a("## 6. 耦合度评估")
|
||
_a("")
|
||
_a("| 模块 | 传入耦合 Ca | 传出耦合 Ce | 不稳定度 I |")
|
||
_a("|------|-----------|-----------|-----------|")
|
||
for mod, vals in sorted(coupling.items(), key=lambda x: x[1]["instability"], reverse=True):
|
||
flag = " ⚠️" if vals["instability"] > 0.8 else ""
|
||
_a(f"| `{mod}` | {vals['afferent_coupling']} | {vals['efferent_coupling']} | {vals['instability']}{flag} |")
|
||
_a("")
|
||
_a("> 不稳定度 I = Ce/(Ca+Ce)。I 接近 1 表示模块高度依赖外部，变更风险大。")
|
||
_a("> I 接近 0 表示模块被广泛依赖，是稳定基础设施。")
|
||
_a("")
|
||
|
||
# ── 重复代码 ──
|
||
_a("## 7. 重复代码检测")
|
||
_a("")
|
||
if report.similar_functions:
|
||
_a("以下函数对具有相似的签名特征（参数数量、行数、复杂度），可能存在重复逻辑：")
|
||
_a("")
|
||
_a("| 函数 A | 函数 B | 相似度 |")
|
||
_a("|--------|--------|--------|")
|
||
for a, b, sim in report.similar_functions[:20]:
|
||
_a(f"| `{a}` | `{b}` | {sim:.0%} |")
|
||
if len(report.similar_functions) > 20:
|
||
_a(f"| ... | 共 {len(report.similar_functions)} 对 | |")
|
||
_a("")
|
||
_a("> 建议人工审查上述函数对，确认是否可提取公共逻辑。")
|
||
else:
|
||
_a("未检测到明显的重复函数。✅")
|
||
_a("")
|
||
|
||
# ── 任务分类 ──
|
||
tc = report.task_classification
|
||
_a("## 8. 任务分类分析")
|
||
_a("")
|
||
if tc:
|
||
_a(f"### 8.1 按层分布（共 {tc['total']} 个任务）")
|
||
_a("")
|
||
_a("| 层 | 数量 | 任务列表 |")
|
||
_a("|-----|------|----------|")
|
||
for layer, info in tc.get("by_layer", {}).items():
|
||
tasks_str = ", ".join(f"`{t}`" for t in info["tasks"][:8])
|
||
if info["count"] > 8:
|
||
tasks_str += f" ... 共 {info['count']} 个"
|
||
_a(f"| {layer} | {info['count']} | {tasks_str} |")
|
||
_a("")
|
||
|
||
_a("### 8.2 按类型分布")
|
||
_a("")
|
||
_a("| 类型 | 数量 |")
|
||
_a("|------|------|")
|
||
for ttype, info in tc.get("by_type", {}).items():
|
||
_a(f"| {ttype} | {info['count']} |")
|
||
_a("")
|
||
|
||
anomalies = tc.get("anomalies", [])
|
||
_a("### 8.3 分类异常")
|
||
_a("")
|
||
if anomalies:
|
||
for a in anomalies:
|
||
_a(f"- ⚠️ {a}")
|
||
else:
|
||
_a("未发现分类异常。✅")
|
||
else:
|
||
_a("任务分类分析未执行（TaskRegistry 导入失败）。")
|
||
_a("")
|
||
|
||
# ── 优化建议 ──
|
||
_a("## 9. 架构优化建议")
|
||
_a("")
|
||
suggestions = _generate_suggestions(report, coupling)
|
||
for i, s in enumerate(suggestions, 1):
|
||
_a(f"{i}. {s}")
|
||
_a("")
|
||
|
||
return "\n".join(lines)
|
||
|
||
|
||
def _generate_suggestions(report: ArchitectureReport, coupling: dict) -> list[str]:
|
||
"""基于分析结果生成具体优化建议。"""
|
||
suggestions: list[str] = []
|
||
|
||
# 大文件建议
|
||
large_files = [f for f in report.files if f.lines > 500]
|
||
if large_files:
|
||
biggest = max(large_files, key=lambda f: f.lines)
|
||
suggestions.append(
|
||
f"**拆分大文件**：`{biggest.rel_path}`（{biggest.lines:,} 行）是最大文件，"
|
||
"建议按职责拆分为多个子模块。"
|
||
)
|
||
|
||
# 高复杂度建议
|
||
high_cx = [fn for fn in report.functions if fn.complexity >= 15]
|
||
if high_cx:
|
||
worst = max(high_cx, key=lambda fn: fn.complexity)
|
||
name = f"{worst.class_name}.{worst.name}" if worst.class_name else worst.name
|
||
suggestions.append(
|
||
f"**降低函数复杂度**：`{name}`（复杂度 {worst.complexity}）建议提取子函数或使用策略模式。"
|
||
)
|
||
|
||
# 循环依赖建议
|
||
if report.circular_deps:
|
||
pairs = ", ".join(f"`{a}`↔`{b}`" for a, b in report.circular_deps)
|
||
suggestions.append(
|
||
f"**消除循环依赖**：{pairs}。可通过引入接口层或依赖注入解耦。"
|
||
)
|
||
|
||
# 高不稳定模块
|
||
unstable = [m for m, v in coupling.items() if v["instability"] > 0.8]
|
||
if unstable:
|
||
suggestions.append(
|
||
f"**稳定化高不稳定模块**：{', '.join(f'`{m}`' for m in unstable)} "
|
||
"的不稳定度 > 0.8，建议减少对外部模块的依赖。"
|
||
)
|
||
|
||
# 任务命名建议
|
||
tc = report.task_classification
|
||
if tc:
|
||
anomalies = tc.get("anomalies", [])
|
||
if any("INDEX" in a for a in anomalies):
|
||
suggestions.append(
|
||
"**统一 INDEX 层任务命名**：当前 INDEX 层任务以 `DWS_` 开头，"
|
||
"建议改为 `IDX_` 前缀以避免与 DWS 汇总任务混淆。"
|
||
)
|
||
|
||
# 重复代码建议
|
||
if len(report.similar_functions) > 5:
|
||
suggestions.append(
|
||
f"**消除重复代码**：检测到 {len(report.similar_functions)} 对相似函数，"
|
||
"建议提取公共基类或工具函数。"
|
||
)
|
||
|
||
if not suggestions:
|
||
suggestions.append("当前架构整体健康，未发现需要立即优化的问题。")
|
||
|
||
return suggestions
|
||
|
||
|
||
# ═══════════════════════════════════════════════════════════════
|
||
# 主流程
|
||
# ═══════════════════════════════════════════════════════════════
|
||
|
||
def run_analysis(root: Path, logger: logging.Logger) -> tuple[ArchitectureReport, dict]:
|
||
"""执行完整架构分析，返回报告数据和耦合度评估。"""
|
||
report = ArchitectureReport()
|
||
|
||
logger.info("=" * 60)
|
||
logger.info("ETL 架构分析开始")
|
||
logger.info("分析根目录: %s", root)
|
||
logger.info("=" * 60)
|
||
|
||
# 1. 文件扫描
|
||
logger.info("── 阶段 1/6：文件扫描 ──")
|
||
report.files = scan_files(root, logger)
|
||
|
||
# 2. 函数复杂度
|
||
logger.info("── 阶段 2/6：函数复杂度分析 ──")
|
||
report.functions = analyze_functions(report.files, logger)
|
||
|
||
# 3. 依赖关系
|
||
logger.info("── 阶段 3/6：依赖关系分析 ──")
|
||
report.import_edges, report.circular_deps = analyze_dependencies(report.files, logger)
|
||
|
||
# 4. 重复代码
|
||
logger.info("── 阶段 4/6：重复代码检测 ──")
|
||
report.similar_functions = detect_similar_functions(report.functions, logger)
|
||
|
||
# 5. 任务分类
|
||
logger.info("── 阶段 5/6：任务分类分析 ──")
|
||
report.task_classification = analyze_task_classification(logger)
|
||
|
||
# 6. 耦合度
|
||
logger.info("── 阶段 6/6：耦合度评估 ──")
|
||
coupling = evaluate_coupling(report.import_edges, report.files)
|
||
|
||
logger.info("=" * 60)
|
||
logger.info("分析完成")
|
||
logger.info("=" * 60)
|
||
|
||
return report, coupling
|
||
|
||
|
||
def parse_args() -> argparse.Namespace:
|
||
parser = argparse.ArgumentParser(description="ETL 架构分析")
|
||
parser.add_argument(
|
||
"--output", "-o",
|
||
help="报告输出路径（默认自动生成带日期的文件名）",
|
||
default=None,
|
||
)
|
||
return parser.parse_args()
|
||
|
||
|
||
def main():
|
||
logger = _setup_logging()
|
||
args = parse_args()
|
||
|
||
root = _FEIQIU_ROOT
|
||
|
||
report, coupling = run_analysis(root, logger)
|
||
|
||
# 生成 Markdown 报告
|
||
md_content = generate_report(report, coupling)
|
||
|
||
# 确定输出路径
|
||
_report_root = os.environ.get("ETL_REPORT_ROOT")
|
||
if not _report_root:
|
||
raise KeyError("环境变量 ETL_REPORT_ROOT 未定义。请在根 .env 中配置。")
|
||
reports_dir = Path(_report_root)
|
||
reports_dir.mkdir(parents=True, exist_ok=True)
|
||
|
||
if args.output:
|
||
output_path = Path(args.output)
|
||
else:
|
||
date_str = datetime.now().strftime("%Y%m%d")
|
||
output_path = reports_dir / f"architecture_report_{date_str}.md"
|
||
|
||
output_path.write_text(md_content, encoding="utf-8")
|
||
logger.info("报告已保存: %s", output_path)
|
||
|
||
# 打印摘要
|
||
total_files = len(report.files)
|
||
total_lines = sum(f.lines for f in report.files)
|
||
large_count = sum(1 for f in report.files if f.lines > 500)
|
||
high_cx = sum(1 for fn in report.functions if fn.complexity >= 10)
|
||
|
||
logger.info("")
|
||
logger.info("═══ 分析摘要 ═══")
|
||
logger.info(" 文件数: %d", total_files)
|
||
logger.info(" 总行数: %s", f"{total_lines:,}")
|
||
logger.info(" 大文件(>500行): %d", large_count)
|
||
logger.info(" 高复杂度函数(≥10): %d", high_cx)
|
||
logger.info(" 循环依赖: %d", len(report.circular_deps))
|
||
logger.info(" 相似函数对: %d", len(report.similar_functions))
|
||
logger.info(" 注册任务: %s", report.task_classification.get("total", "N/A"))
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|