Acasă Explorează Ajutor
Autentificare
tianyu.chu
/
poyee-data-warehouse
1
0
Bifurcare 0
Fisiere Probleme 0 Trageți solicitările 0 Wiki
Arbore: b0ddc02c14
Ramuri Etichete
poyee-data-ware...
/
kb
/
93-架构决策.md

93-架构决策.md 17 KB
Istoric Crud

架构决策

重构完成后沉淀的关键架构决策（ADR），给自己看的备忘。

说明

  • 本文档是重构完成态的沉淀：90-重构路线.md / 91-重构备忘.md / 92-重构进度.md 三份过程文档会在重构收尾时删除，关键决策、权衡、反悔条件压到这里留档。
  • 当前仍在重构中，本文档先留骨架，内容待重构收尾时填入。
  • 单条 ADR 格式按业界主流（Michael Nygard 版精简）：背景 / 决策 / 后果 / 候选方案 / 反悔条件 五段；不套公司标准模板的多余字段。

模板

新增一条决策时，复制以下模板到 §2 列表内。编号连续，不复用已弃用编号。

### ADR-NN 决策标题

- **状态**：已采纳 / 被 ADR-MM 取代 / 已弃用
- **背景**：当时面对的问题、约束、触发决策的场景。
- **决策**：最终选了什么方案，一句话。
- **后果**：带来的好处、新增的代价、影响到的模块。
- **候选方案**：考察过但否决的方案，以及否决理由。
- **反悔条件**：什么条件下会重新评估或反悔。

决策清单

ADR-01 DataX 入口默认单日，显式 -backfill 开日循环用于存量回填

  • 状态：草案 老 spark-sql-starter 的 get_date_range 支持 20260401-20260410 范围格式自动展开；DataX 入口从未用过。本项目调度用 DolphinScheduler，DS 原生支持业务日期补数（时间区间选定后，按调度周期逐日实例化 task）。用户老 DS 配置即 -start-date=${dt} -stop-date=${cdt} 单日传参。2026-04-24 出现场景：接入新源表需一次性回填 N 年历史存量数据——这类一次性手工批量 DS 的日历补数组件实例化太慢，走外部工具更合适。

  • 决策：DataX 入口默认单日语义（start_date / stop_date 对应一个 dt 分区），T+1 增量补数仍归 DS；hive-import 入口 2026-04-24 补 -backfill flag，显式开启后 -start-date / -stop-date 作外层回填范围，按日循环调用单日逻辑，用于存量回填。

  • 后果：

    • 正面：DataX 层默认职责单一（单日），T+1 增量 / 补数 / 回溯在 DS 层统一可视化；一次性存量回填通过 -backfill 内置支持，不再需要外部 bash 循环 / 临时 dispatcher
    • 负面：参数语义轻度重载（-start-date / -stop-date 在 -backfill 模式下含义不同）；DS 任务模板规范上不得加 -backfill（团队约定）

  • 候选方案：

    • DataX 入口层实现"日期范围自动展开 + 多 json 分发多 worker"作为默认行为——否决（重复 DS 职责 + 增入口常态复杂度）
    • 独立 bin/datax-backfill.py 工具文件——否决（和 hive-import 共享 100% 参数，独立文件冗余；单 flag 切换更简洁）

  • 反悔条件：出现必须在 DataX 层做日期展开的默认场景（如 DS 彻底换掉）；或 -backfill 被误用频繁到需物理隔离

ADR-02 分布式分发归 DolphinScheduler worker group，DataX 不重复随机

  • 状态：草案 DataX 老入口 single-job-starter.sh 内置 -random + workers.ini 权重加权随机选 worker + ssh 分发。DS 自身亦有 worker group 机制（group 绑定机器列表、task 落到 group 内一台 worker）。两层叠加：DS 选 node01 → node01 上 DataX 再 random 到 node03。【查证 kb/91 §4.4】：用户老 DS 配置不传 -random，说明 DS 层已完成分发，DataX 只在本机跑——两层分发在实际运营中就没被"同时启用"过

  • 决策：DataX 入口不做 worker 分发；分布式执行在 task 粒度靠 DS worker group 承担。DataX 入口的 select_worker 等同"返回 current_host"，ssh 分支可删，workers.ini 可移除

  • 后果：

    • 正面：消除两层独立随机叠加打乱 DS 负载均衡；DataX 链路大幅简化（worker.py / ssh 远端执行 / workers.ini 可裁）；维护成本下降
    • 负面：单 DS 任务节点内部的批量（多 ini + -parallel）场景无法在 DataX 层散到多 worker，要分布式必须在 DS 层拆成多 task

  • 候选方案：保留 DataX 两层分发——否决，"两层独立随机"破坏 DS worker group 语义

  • 反悔条件：DS 换成无 worker group 支持的调度器；或单 task 内批量规模大到 DS 拆分成本过高

ADR-03 零点漂移决策

  • 状态：草案 T+1 按 update_time 过滤单日窗口 [day-start, day-stop) 同步时，源库在同步执行期间持续写入——跨零点的记录 update_time 会从 N 号"漂到" N+1 号，单日窗口无法捕获漂移记录。

漂移概率和漂移数据量的相关变量：

  • 漂移窗口 = 执行时刻距零点的小时数。越晚跑漂移窗口越大
  • 漂移窗口越大，单条记录的漂移概率越高
  • 漂移窗口内用户越活跃（业务写入高峰落在漂移窗口内），漂移数据量越多

业界一般做法：小数据量、用户低活跃度的场景下，通常凌晨 0:30 前后跑 T+1，漂移窗口 30 分钟、活跃度低，单日固定窗口 [day-start, day-stop) 即可，忽略极少量漂移数据是可接受的工程权衡。

本项目特殊性：业务高峰在凌晨 6 点前，同步定时必须避开高峰定在 6 点后，漂移窗口 6 小时；且若干用户行为集中在 0-6 点，漂移窗口和活跃度两个放大因子都踩中，漂移不能忽略——需要单独设计。

极端场景佐证：某用户习惯 0-6 点更新自己的数据，若走业界做法的单日固定窗口，数仓永远只能看到该用户最早的 create_time 版本，最新状态永远抓不到。

  • 决策：

    • raw 层 where 右界扩展为次日同期：where update_time >= '{day-start} 00:00' AND update_time < '{day+1-stop} 00:00'，在关闭侧加 1 天 buffer 覆盖漂移
    • buffer 取 1 天而非 N 小时：定时可变更（同步执行时刻从 6 点调到 3 点或 8 点都不影响窗口语义）+ 可维护（固定区间可复跑、可回刷）
    • raw 层不纠正分区漂移：所有抓到的记录（含"漂到次日"的）按 ini dt = start_date（业务日）统一落当日分区，分区内允许含次日漂移数据
    • ods 层 Spark SQL 用动态分区 PARTITION (dt)，按每行 update_time 真实日期归位
    • ods 写入模式：INSERT OVERWRITE 覆盖式 + 双源 union raw dt=T-1 + raw dt=T-2，按 WHERE DATE(update_time) = T-1 过滤，dedupe by (pk, max(update_time))。覆盖式写入支持重跑；双源 union 完整捕获 update_time ∈ [T-1, T) 范围的所有版本（含跨 raw 任务时段被业务覆盖更新跨日的早期版本）
    • 为什么双源 union 必要（具体例子）：

    设定：业务日 04-27，跑批日 04-28，raw 任务凌晨 03:00 跑批，业务库覆盖式更新会推 update_time 字段。

    订单 X 的 update 时间线（业务库视角）：

    • 04-27 02:00：update，update_time = 04-27 02:00（状态 A）
    • 04-28 02:00：再 update，update_time = 04-28 02:00（状态 B，跨日）

    raw 抓取过程：

    • raw dt=04-26 任务（04-27 03:00 跑批，窗口 [04-26, 04-28)）：业务库 X 是状态 A，抓到 update_time = 04-27 02:00 → 落 raw dt=04-26 / update_dt=04-27
    • raw dt=04-27 任务（04-28 03:00 跑批，窗口 [04-27, 04-29)）：业务库 X 已变成状态 B（04-27 02:00 那条 update_time 字段被覆盖到 04-28 02:00），抓到 update_time = 04-28 02:00 → 落 raw dt=04-27 / update_dt=04-28

    ods 04-28 跑批写 dt=04-27 分区（WHERE DATE(update_time)='04-27'）：

    • 单源 raw dt=04-27：X update_time = 04-28 02:00，DATE=04-28，不入 → ods dt=04-27 漏 X 的 04-27 状态 ❌
    • 双源 union raw dt=04-27 + raw dt=04-26：raw dt=04-26 里 X update_time = 04-27 02:00（DATE=04-27，入），raw dt=04-27 里 X update_time = 04-28 02:00（不入）→ ods dt=04-27 完整包含 X 的 04-27 状态 A ✓

    X 的 04-28 状态 B 第二天 ods 04-29 跑批时落 ods dt=04-28 分区，拉链表轨迹完整无断节。

    业务高峰跨零点（如本项目订单 0-6 点高峰）下，跨日漂移是常态，双源 union 是必要机制不是 defensive。

    • ods 层跨 dt 不去重：同一业务 id 允许在多个 dt 分区并存（每条代表一个"时间段状态快照"）——上层拉链表（SCD Type 2）的必要基础

  • 后果：

    • 正面：不漏漂移记录；raw 简单（只管多抓、不管分对）；ods 动态分区自动归位；同 id 多 dt 并存作为拉链表底层
    • 负面：raw 每日抓量约翻倍；ods SQL 必须统一动态分区写法 + 双源 union，开发规范需明文约束

  • 候选方案：

    • 单日窗口 [day-start, day-stop) 固定区间（无 buffer）：业界小公司通用做法，本项目因漂移窗口 + 活跃度双放大否决
    • 动态 now 右界 [day-start, now)：可复现性、复跑、补数场景难处理，否决
    • 精确匹配漂移的半天 buffer [day-start, day+6h-stop)：和具体同步时刻耦合，调定时就得改窗口，否决
    • ods 跨 dt 按 (pk, max(update_time)) 去重：破坏拉链表基础，否决
    • ods 单源 raw dt=T-1（不 union raw dt=T-2）：业务覆盖式更新跨日漂移场景下，漏 update_time=T-1 的早期版本（业务库该记录 update_time 已被推到 T 范围，raw dt=T-1 抓到的 DATE=T 不入），拉链表轨迹断一节，否决（具体例子见 §决策"为什么双源 union 必要"）
    • ods INSERT INTO 追加 + 分区内去重（早先并列方案 B）：意图保留"每日 ods 跑时刻"的中间快照轨迹。但与"支持重跑"语义冲突（追加模式重跑会重复入数据），且方案 A 双源 union 已能完整捕获跨日漂移版本，方案 B 的"中间快照"价值不抵复杂度代价，否决
    • 源库 REPEATABLE READ snapshot isolation：业务库长事务风险，否决
    • CDC（PG 逻辑复制 / MySQL binlog 流读）：架构正路，需独立立项，本阶段不取（见 kb/12 CDC 演进节）

  • 反悔条件：迁 CDC

ADR-04 DataX speed 三级注入（L1 conf / L2 ini / L3 CLI）

  • 状态：草案 老代码 job_config_generator.py:60-67 把 speed 三参（channel / byte / record）按工作时段硬编码：07:50-19:00 走 channel=10 / byte=10MB / record=40k（保护业务 DB），其余时段走 channel=6 / byte=256MB / record=100k。时段边界和各档值完全写死在 Python 代码里，调优需要改代码 + 发布。压测 / 回填场景下 speed 是高频调参项，需要运行时覆盖能力。

  • 决策：speed 三参走三级合并，优先级 L1 < L2 < L3。

    • L1 conf/datax-tuning.conf：项目级默认，承载宽松时段 relaxed_period.{start,stop} 边界 + strict/relaxed 两档各 3 个 speed 参值，共 8 个 key；时段配置用 HH:MM 字符串，代码解析为 HHMM 整数比较
    • L2 DataX ini 新增可选 [speed] 段：单 ini 级覆盖 channel / byte / record；一旦在 L2 显式写了，忽略时段判断直接使用
    • L3 CLI -channel / -byte / -record：本次运行级覆盖，bin/datax-{hive-import,hdfs-export}-starter.py 暴露，逐层透传到 dw_base.datax.cli gen-json 子进程，最终到 JobConfigGenerator
    • 合并发生在 JobConfigGenerator.assemble() 内存里，结果写进生成的 json（job.setting.speed + core.transport.channel.speed）；ini / conf 文件本身不动
    • 时段判断采用左闭右开 [start, stop)；每 key 的来源打印到 stdout 便于审计
    • schema 以宽松时段为基准（区间内 relaxed、区间外 strict）：原计划 strict_period 不工作——本项目业务高峰跨午夜（12:00 至次日 06:00），HHMM 整数比较 1200 ≤ x < 0600 为空集；宽松时段在低峰期（如 06:00-12:00）天然连续不跨日

  • 后果：

    • 正面：压测 / 回填 speed 调参不用改代码；时段分档逻辑可配，业务高峰期调整不用发布；单 ini 特殊场景可用 L2 覆盖；ADR 级改动只加约 350 行代码 + 10 条单测
    • 负面：参数语义复杂度上升（3 层合并规则）——通过 [tuning] log 逐层打印缓解；conf/datax-tuning.conf 是新文件需同步到所有 worker（sync-all.sh 已覆盖）

  • 候选方案：

    • 只做 L1（conf 外配，不要 L2 L3）——否决，压测高频调 speed 不想改 conf 再部署
    • 参数全外配（speed + reader.fetchSize + writer.batchSize）——否决，fetchSize/batchSize 低频调，现有 ini 覆盖硬编码 够用，外配反而复杂
    • CLI 用合成 flag --datax-conf key=value,...——否决，speed 高频用独立 flag 更直观，Spark 入口风格参考

  • 反悔条件：三级注入使用场景长期 <5%（即 L2 L3 基本不用），退回单层 conf；或者 DataX 被替换

ADR-05 DWD 事实表设计：默认"事件 vs 状态"拆派组合，acc 累积快照仅留例外口子

  • 状态：已采纳

老 kb/20 §5.5 走"合 vs 拆"二分法（粒度相同则合粒度不同则拆），举例订单履约 / 拼团生命周期均"合到 acc 累积快照"——一行一实体，每个里程碑一列时间戳，状态单向推进。该写法属 Kimball 维度建模理论里的 Accumulating Snapshot Fact Table，在传统数仓（Teradata / Oracle / Greenplum）里是经典模式。

2026-04-26 启动埋点 + 业务库接入业务建模时重新审视，发现两个核心问题：

  1. Hive 技术栈不友好：Hive ORC 普通表不支持原生 UPDATE，acc 模式（每经过里程碑回写时间戳列）只能"INSERT OVERWRITE 整张表 / 整个分区"实现，每天扫近 N 天 ODS 重算，写入开销大、性能粗暴。要解此约束需开 Hive ACID（CDH 6 支持但少用 + 性能折损）或上 Iceberg / Hudi / Delta Lake，本项目都不具备
  2. 业务流程多有循环：拼团有审核机制（提交 → 拒绝 → 重新提交 → 再审核），订单亦有退款 / 重派单等循环。Kimball 对 acc 的前提是"每个状态只经过一次"——循环场景 acc 的时间戳列会丢失历史，不适用

期间在 inbox 收了一篇分层分区语义草稿，主张"事实表只承载事件、状态归 DIM 拉链"。讨论后认为该结论方向正确，但论证过度（直接否定 Kimball 三类事实表的全部）；最终采纳折中表述：默认拆派 + 留 acc 例外口子。

  • 决策：默认采用"事件 vs 状态"拆派组合：

    • DWD 事实表只承载业务事件（不可变事实），命名 dwd_{域}_{业务过程}_apd_d，append-only，业务时间分区
    • 实体当前状态进 DIM 拉链表，命名 dim_{域}_{实体}_zip_d，SCD Type 2 每次状态变更生成新行
    • 循环状态机天然支持：事件流水任意次重复追加，DIM 拉链每次变更生成新行可完整回溯
    • acc 不一刀切禁用：极少数严格不循环、固定线性里程碑场景（如不可逆的合同审批流程）按需评估，新建 acc 表时在 PR / 设计稿里说明选型理由

  • 后果：

    • 正面：
    • 与 Hive 列存"只追加 + 分区"模型天然契合，不需要 UPDATE
    • 状态查询走拉链表 is_current 切片或按 dt 切片，直观
    • 循环 / 单向状态机统一同一套建模，降低团队心智负担
    • 与阿里 OneData / 字节 / 美团 Hive 数仓主流做法对齐
    • 负面：
    • 跨表 JOIN（"下单数 - 退单数 = 实际下单数"）成为常态，但维度建模本就支持
    • DIM 拉链表实现复杂度高于 acc 单表（每日变更 pk 检测 + 原行 end_date 置昨天 + 新行 insert）
    • 状态查询需要 join dim 拉链而非读单表，少量查询复杂度

  • 候选方案：

    • 保留老 §5.5 合派 acc：经典 Kimball 但不适合 Hive 技术栈 + 不支持循环——否决
    • 完全禁用 acc：inbox 草稿原版主张"事实表出现需要更新状态就是建模错"——过度扩大化，放弃了 Kimball 三类事实表的理论丰富性，未来引擎栈升级（Iceberg / Hudi）想用 acc 又得反悔——否决，留例外口子
    • inc 主表 + apd 流水表 fallback（kb/21 §2.2 老循环 fallback 方案）：inc 只保留最新状态，状态历史靠 apd 流水还原，但状态查询要 join 流水表算最新值，远不如拉链表 is_current 直接——否决

  • 反悔条件：

    • 引擎栈升级到支持高效 UPDATE 的存储（Iceberg / Hudi / Delta Lake），acc 实现成本 / 性能不再是问题，可重新评估
    • DIM 拉链表实现复杂度成为团队瓶颈（开发提效需要）
    • 实际场景中跨表 JOIN 性能 / 维护成本超出预期