# 重构对比

> 本项目各模块重构前后的差异对比。每个模块一节：对比维度表 + 关键差异展开说明。
> 目的：为 review / 回归 / 将来 ADR 归档提供"看得见的差异"镜头；入职新人也可以从这里快速把握项目的演进脉络。

## 1. DataX 入口重构（2026-04-23 完成）

### 1.1 对比表（22 项）

| # | 维度 | 新入口 | 老入口 |
|---|---|---|---|
| 1 | 入口文件数 | 2 `.py` + `cli.py` = 3（bin 层已无 .sh 壳） | 5 `.sh` + 3 `.py` 调试壳 + 1 `config-generator.py` = 9（不含独立保留的 `gc-generator.py`）|
| 2 | 入口组织 | 门面模式：`datax-hive-import-starter.py` / `datax-hdfs-export-starter.py` 两条独立入口 | 三层堆叠：`multiple-hive` → `multiple` → `single` |
| 3 | 核心语言 | 纯 Python 入口；env 由 `dw_base/__init__.py` 的 `bootstrap_env()` 从 conf/env.sh 注入（单源，Python/Bash 不双解析） | bash 脚本为主，Python 做 ini→json 翻译 |
| 4 | 参数形态 | `-ini <file>` / `-inis <dir>` 两种输入 + 8 个选项 | `-c/-cd/-gc/-gcd/-jc/-jcd` 6 种输入 + `--override` + 脚本内 5 个硬编码数组 |
| 5 | 能力边界 | json 是内部中间产物，`conf/datax-json/{job_name}.json` 扁平化，调用方不感知 | json 路径暴露给调用方（`-c` / `-jc`），用户可能手动管 json |
| 6 | 核心抽象 | Python 分层：`entry`（门面）→ `batch`（调度）→ `runner`（执行）+ `worker` / `partition` / `path_utils` / `mask` / `cli` 旁支 | shell for 循环 + 函数 |
| 7 | 优雅与否 | `in` / ConfigParser / os.path 标准用法；NamedTuple / 纯函数 / 闭包分层；类型注解；异常抛堆栈 | `set -e` + command-substitution 静默退出坑；`parse_ddl` 用 `grep "path =" ` 字面子串（多空格对齐就漏）；5 个硬编码数组 + `--override` 从未激活；`__contains__(k)` 反 Pythonic |
| 8 | 死代码 | 无（单测 47 条覆盖） | `plugin.py: import pwd` 无引用、`mysql_reader` 顶层 import 已删的 `dw_base.database.mysql_utils`、5 个 `xxx_array=()` 空壳、`--override` case 无作用对象、`conf/datax/config/` 前缀剥离（目录已归档 bak）、`conf/datax/generated` 路径默认值 |
| 9 | Hive 分区管理 | `partition.parse_ini_partition` 走 `ConfigParser.get('writer', 'path')` 正规读；`.db` 段抽取逻辑同语义但容错更好 | `parse_ddl` 依赖 ini `path = ` 单空格字面子串、从 path 按 `/` 切段找 `.db` 段 |
| 10 | 分区 dt 计算 | `start_date`（业务日），partition + writer 双方对齐；分区内允许含次日漂移（配套 ADR-03 raw 48h 宽窗） | `START_DATE` 但 writer 用 `stop-1` → 不一致（单日范围歧义掩盖、多日范围错位） |
| 11 | 字段脱敏 | `[mask]` 声明式段自动生成 querySql；PG 5 种脱敏（3 静态 `month_trunc` / `md5` / `mask_middle` + 2 动态 `keep_first_{n}` / `keep_last_{n}`），列名白名单防 SQL 注入 | 不支持；需要在 ini 里自己手写 querySql 用 SQL 表达式脱敏 |
| 12 | Workers 配置 | 外配 `conf/workers.ini`（新 cdhmaster02/cdhnode01-03） | 硬编码在 `init.sh:13-28`（老 m3/d1-d4 列表 + 权重 map） |
| 13 | 日志路径 | 扁平化：`${LOG_ROOT_DIR}/datax/${dt}/${job_name}.log`（对齐 kb/90 §7.2.1） | 多维派生：`${LOG_ROOT_DIR}/datax/${SRC_DST}/${PROJECT_LAYER_ENV}/${DB_ENV}/${GROUP}/${START_DATE}/${JOB_NAME}.log`，路径含老 `conf/datax/config/` 残留语义 |
| 14 | 日志内容（stdout）| Python 原生 `print` **无颜色**（颜色丢失仍未补）；**关键阶段 print 已补齐**（worker 选中 / gen 起止 / exec 起止 / 任务起止，2026-04-24 落地）；DataX JVM 自身日志输出不变；异常改用 `raise RuntimeError` 携堆栈 | `pretty_print` **带 ANSI 颜色**：`NORM_MGT`（紫）+ `NORM_GRN`（绿）+ `NORM_RED`（红）+ `NORM_YEL`（黄）分区；驱动常量来自 `bin/common/print-constants.sh` + `dw_base/__init__.py` |
| 15 | Tee / 独立日志文件 | Python 层 `runner._run_with_tee` Popen + 行循环 tee（串行 `tee_to=fh` 写文件 + 父 stdout；并行 `stdout=fh` 只写文件）。**2026-04-24 补齐串行独立 log 文件**，行为对齐老 `\| tee LOG_FILE` | bash 层 `\| tee LOG`（串行）/ `> LOG 2>&1 &`（并行），shell pipe 天然做到 |
| 16 | 错误处理 | Python Exception + `subprocess.returncode`，抛 `RuntimeError` 含上下文（ini 名 / 阶段） | `set -e` + exit code 透传、出错位置信息含糊 |
| 17 | 分布式 | 同（待 kb/93 ADR-02 拍板后可砍 ssh 分发，DS worker group 接管） | `-random` + `workers.ini` 加权随机 + ssh 分发到 worker |
| 18 | 字段变换 | ini `[mask]` 声明式 + `mask.py` 翻译为 PG `querySql` 内 SQL 表达式，源库端脱敏（合规硬约束：敏感不出业务库） | 无（需源库做或下游 Spark SQL 做） |
| 19 | 环境依赖 | 环境全从 `conf/env.sh` + `conf/workers.ini` 读；`bootstrap_env()` 通过 bash 子进程解析 env.sh 注入 `os.environ`（Python / Bash 单源） | `init.sh` 硬编码 USER=bigdata / RELEASE_HOST=m3 / DATAX_WORKERS / PYTHON3_PATH / DATAX_HOME 老路径 |
| 20 | 测试覆盖 | 47 条单测（path_utils 5 + worker 6 + partition 7 + runner 5 + batch 7 + entry 5 + cli 3 + mask 9） | 0 单测 |
| 21 | 可维护性 | Python 分层模块职责单一；类型注解 + docstring；47 单测兜底；异常含上下文 | bash 脚本 + 内嵌数组 + 多文件分散，新人上手须看 3+ 脚本理解 `multiple-hive → multiple → single` 调用链；改动易漏同步；无类型注解；错误信息模糊 |
| 22 | 可扩展性 | 加新脱敏类型只改 `mask.py` 静态字典一行 / 动态正则一条；加新 ssh 命令子命令只在 `cli.py` 加 subparser；`plugin_factory` eager import 未变动（见 kb/90 §2.6 后延 ADR 的"plugin_factory 解耦"低优先级项） | 加新 reader 要改 `plugin_factory.py` 顶层 import 并扩 registry；加新脱敏类型要手写 querySql 或改 `plugins/reader/*.py` 代码 |
| 23 | speed 调参 | 三级注入：L1 `conf/datax-tuning.conf` 默认 + L2 ini `[speed]` 段 + L3 CLI `-channel/-byte/-record`，逐字段合并 + 审计日志（详见 kb/93 ADR-04） | `job_config_generator.py:60-67` 硬编码两档时段 + 两档 speed 三参，调优要改代码发布 |

### 1.2 行为退化说明

对比表里**新不如老**的项：

- ~~**#14 日志颜色退化**~~ / ~~**关键阶段 print 缺失**~~ —— 2026-04-24 **阶段 print 已补齐**（worker 选中 / gen 起止 / exec 起止 / 任务起止）；颜色仍退化（仅单色文本），如要恢复用 `colorama` 或自写 ANSI escape helper，当前不做
- ~~**#15 串行模式日志文件缺失**~~ —— 2026-04-24 **已补齐**，`runner.run_job(tee_to=fh)` Popen 行循环 tee 到文件 + 父 stdout，行为对齐老 `| tee LOG_FILE`
- **HDFS 源路径存在性 check 未搬迁** —— 2026-04-24 **已补齐，且默认语义反转**：`runner._hdfs_src_check` 对 `reader.dataSource` 是 `hdfs/...` 的 ini 在 gen json 前跑 `hadoop fs -test -e` + `hadoop fs -du -s`；**missing / empty → `return 1` 任务失败**（老 sh 是 silent skip `return 0`）。反转理由：T+1 ads 导出"源没数据=上游异常"，应显式失败由 DS 告警触发通知。手动跑批已知有空分区场景可加 `-skip-check` 恢复老 silent skip 语义
- **默认日期未做** —— 2026-04-24 **已补齐**，入口层 `-start-date` / `-stop-date` 不传时默认昨天/今天（对齐老 sh 的 YESTERDAY/TODAY 默认）

**仍未做**：hdfs-kafka 特殊 writer 说明（老 sh `datax-single-job-starter.sh:232-245` 10 行 columnType/columnMapping 业务说明），本项目用 kafka 概率低，用到再补

### 1.3 行为升级说明

**`-parallel` 语义变化**：老 sh `-parallel` 用 `&` 后台 fire-and-forget，主脚本启动完立即退出，rc 恒为 0（只计启动数，不等完成；查证老 `datax-multiple-job-starter.sh:232-252`）；新 Python 用 `threading.Thread + join`（`dw_base/datax/batch.py:70-89`），等所有 ini 完成后汇总真实 rc（= 失败任务数）。

- 实际并行度 / 多核利用**完全等价**：两者都 fork 独立 OS 进程跑 DataX JVM，OS 内核调度到不同 core
- Python GIL **不影响**：线程 95% 时间卡在 `subprocess.wait()` 上，此时 GIL 释放；CPU 密集活全在 JVM 子进程里
- 行为差异只在主进程退出时机：老立即退、新等齐
- 更适合 DS 调度：DS 拿 rc=0 时作业确实全跑完；老行为下 DS 收到 rc=0 作业可能还在后台跑
- 老的"非 release 用户/主机自动降级串行"兜底未搬（ADR-02 草案砍 worker 分发，该兜底自然过时）

### 1.4 收益点概述

- **入口数 9 → 5**，调用方学习曲线陡降
- **测试覆盖 0 → 47**，回归有护栏
- **代码量**：bin/ 层 shell 脚本 1200+ 行减到 bin/ 层 ≤ 200 行，其余逻辑搬到 `dw_base/datax/` Python 分层共 ~800 行 + 单测 ~600 行
- **配置外化**：`workers.ini` / `env.sh` / `[mask]` 段替代原先散在 shell 脚本 / plugin 代码里的硬编码
- **合规加强**：`[mask]` 声明式脱敏保证敏感字段源库端处理、敏感原值不出业务库
- **坑修复**：老 `parse_ddl` 多日范围分区错位、`querySql` 模式 `column` 非 list 的 `ClassCastException`、`plugin_factory` eager import 链里死 import 破整条链路等

### 1.5 待讨论 / 未收尾

- kb/93 ADR-02 草案（分布式归 DS worker group）正式拍板后，`worker.py` / `runner.py` 里 ssh 远端分发逻辑可砍
- kb/93 ADR-03 草案（零点漂移决策）实施时迁 kb/12
- kb/90 §2.6 后延 ADR 低优先级三项（日期范围展开 / plugin_factory 解耦 / 日志颜色恢复可能也要补）
- **Python 入口 / runner 阶段 print 彩色化（低优先级）**：当前 entry.py / runner.py 的 `[datax] ...` print 为单色文本，可用 `colorama`（Windows/Unix 跨平台）或手写 ANSI escape helper 给不同阶段标色（worker 选中=紫 / gen=绿 / exec=绿 / 失败=红）。独立于 dw_base/__init__.py banner 彩色（那套自带）；此处补的是运行时 log 彩色

---

## 2. （待补）

---

## 3. （待补）