9.3 开发规范与命名约定

9.3 开发规范与命名约定

规范不是束缚，是给未来的自己留便条

本篇是第 9 章第 3 节，讲可维护性，团队越大规范越值钱，是降低接手成本的核心。

命名上，我们规定转换按「域_动作」命名（如 order_sync），步骤按职责命名（表输入叫「读订单」而非默认「表输入」）。默认名一堆「表输入1/2/3」时，排错要逐个点开，改名后一眼知意。

单个转换步骤数控制在二十以内，超出拆子转换由作业串。前面 1.1 提过我们吃过巨型图的亏，规范把它量化：超二十就必须拆，评审一票否决。图小才好读好测。

参数命名统一前缀：运行日 p_day、批次 p_batch、环境 p_env。我们有一份参数字典，新转换照抄，避免同一含义多种写法导致变量接不上。一致性比聪明更重要。

注释与文档：复杂步骤在「备注」里写为什么这么设计，而不是只写做了什么。我们评审时重点看备注是否讲因果，因为半年后改它的人只信备注。

文件结构：连接、转换、作业分目录；共享子转换放 common。我们仓库树固定，新人clone 即懂全局，不用问「转换该放哪」。结构即文档。

关键代码与配置

下面这段 text 给出了可直接落地的配置，输入来自上一步、输出写入目标端：

# 参数命名字典（节选，团队强制遵守）
p_day    运行日期 格式 2026-08-25
p_batch 批次号   格式 B20260825
p_env   环境     dev/test/prod
# 禁止同义不同名：不要再用 dt / day / run_day
​

参数字典消灭「同名不同义、同义不同名」。我们 CI 会扫变量名是否在字典，野名直接拦下。

目录约定：
  /connections   共享连接
  /trans/{domain}  各域转换
  /jobs           作业
  /trans/common   可复用子转换
# 评审看目录即知归属，无需口头约定
​

固定仓库树让结构自解释。我们新成员第一天就能定位文件，省下大量询问成本。

背景

一个转换有七个「表输入」「表输入2」…排错时只能逐个点开看 SQL，定位慢出两倍。

操作

按职责统一改名（读订单/读用户/写宽表），并把参数名对齐字典。

<step><name>读订单</name><type>TableInput</type>...</step>
<step><name>写宽表</name><type>TableOutput</type>...</step>
​

结果

排错时一眼知每一步用途，定位时间从两小时降到十分钟。

解读

根因是命名缺失抬高认知成本。规范里最便宜、收益最高的一条就是「步骤起有意义名字」。

变式

更进一步的团队会把命名规则写进 CI 自动检查，缺语义名直接标红，把规范从自觉变成强制。

常见误区与工程取舍

误区：用默认步骤名。必须按职责改名，排错省时。

误区：单转换无限堆。超二十必拆，图小才好测。

取舍：参数字典+固定目录树；备注讲因果而非只讲做了啥。

深入：规范落地的三道闸

规范写进文档没人看，要落地成三道闸。第一道是命名闸：步骤名必须语义化、转换按「域_动作」、参数走字典，这在第一时间降低认知成本。第二道是结构闸：单转换步骤超二十必拆、连接/转换/作业分目录，让仓库结构自解释。第三道是评审闸：复杂步骤的备注必须讲因果，评审重点看「为什么这么设计」而非「做了什么」。三道闸层层把关，新成员第一天就能安全改动，老成员离职不留下黑盒。

# 评审自检清单（节选，提交前过一遍）
[ ] 步骤名是否语义化（无「表输入1/2/3」）
[ ] 单转换步骤数是否 ≤ 20（超出已拆子转换）
[ ] 参数是否全在字典（无野名 dt/day/run_day）
[ ] 复杂步骤备注是否讲因果
[ ] 文件是否落在正确目录（connections/trans/jobs/common）
# 任一项不达标，PR 被打回；规范从「自觉」变「强制」
​

⚠️ 常见坑（开发规范）

• 规范只写在 wiki：不进流程就等于没有，要落到 PR 检查。
• 备注只写做了啥：半年后没人懂为什么，应写因果。
• 目录随意：转换满天飞，新人找不到文件，结构即文档被破坏。

💡 关键直觉

• 规范最便宜、收益最高的一条就是「步骤起有意义名字」，零成本却救回无数排错工时。
• 把规范编进 CI 与评审，它才真正生效；靠自觉的规范会在第一次赶工时崩塌。

工程实录：规范进 PR 检查

规范写 wiki 没人看，步骤名仍是一堆「表输入1/2/3」。

提交前过评审自检清单，任一项不达标 PR 打回。

[ ] 步骤名语义化（无表输入1/2/3）
[ ] 单转换步骤数 ≤ 20
[ ] 参数全在字典
[ ] 复杂步骤备注讲因果
[ ] 文件落正确目录
​

规范从自觉变强制，排错工时大降。

步骤起有意义名字是零成本高收益的一条。

命名规则写进 CI 自动检查，缺语义名标红。

参数与阈值速查

现场口诀与示例

规范最便宜、收益最高的一条就是「步骤起有意义名字」：把默认的「表输入1/2/3」改成「读订单/读用户/写宽表」，排错定位时间可从两小时降到十分钟。再把命名规则写进 CI 自动检查，缺语义名直接标红，规范就从自觉变成强制，新人第一天就能安全改动。

# 命中即打回，强制改成语义名；这一步零运行时成本，却救回无数排错工时
​

补充一条常被忽视的规范：复杂步骤的「备注」要写因果而非只写做了什么。半年后改它的人只信备注，写「为什么这么设计」比写「做了字段映射」有价值十倍。评审时我们重点看备注是否讲因果，这是规范里最便宜却最救命的一条。

现场口诀

命名与目录是最便宜的高收益规范：步骤起语义名（读订单/写宽表）让排错从两小时降到十分钟；单转换超二十步必拆；参数走字典消灭同义不同名；备注讲因果而非只讲做了啥。把这些写进 PR 检查，规范就真正生效，而不是躺在 wiki 里无人看。