6.1 代码规范与测试
6.1 代码规范与测试
本节摘要：从一次真实评审冲突出发，建立三套可执行的规范——命名与结构、幂等审问、变量纪律——并把 lint 与测试嵌进流水线，让机器守住底线、人只审设计。规范的价值不在条文本身，而在它消灭了哪类争论与事故。
一次评审冲突暴露的问题
规范最有说服力的起点是一次失败的评审。"星尘在线"团队曾经的一次发布评审持续了两个小时，争论集中在三件事：任务名写没写动词；一段用 shell 实现的配置修改该不该打回；环境变量写在 vars 里还是清单里。两小时里没有一个议题涉及"这次发布本身的风险"，因为代码本身的可争议空间太大了。冲突的解药不是更强势的评审人，而是把可机械判断的事交给机器、把约定写成人人可查的条文——评审从此只讨论设计取舍。
规范一：命名与结构
三条硬规矩。规矩一，每个任务必须有 name，且 name 描述意图不描述动作——"确保 nginx 处于运行状态"是意图，"systemctl start nginx"是动作复读。意图名让 dry-run 输出变成一份可读的变更预告，这直接提升 5.2 节流水线干跑阶段的价值。规矩二，一个剧本文件一件事：site.yml 只做编排声明，具体动作用 import 拆到能力文件，单文件超过三百行就该拆。规矩三，目录布局遵循 5.1 节的参考结构，个人创新目录等于给新人埋坑。
# 规范示例：意图化命名 + 声明式实现 - name: 确保应用配置目录属主正确 ansible.builtin.file: path: "{{ app_base_dir }}/conf" owner: "{{ app_user }}" mode: "0750" state: directory
规范二：幂等审问
3.6 节的三层模型在这里转变成评审 checklist。每个新增任务过三问：第一问，用的是资源模块还是逃生舱口？用逃生舱口则必须出示 changed_when 或 creates 的补齐写法。第二问，连跑两遍第二遍 changed 是否归零？无法回答的，评审意见就是"去跑两遍"。第三问，check 干跑下这个任务的行为是否可信？依赖 register 结果的条件任务在干跑下失真，需要书面标注。三问的执行成本极低（两遍运行加一次干跑），拦下的事故却都是高危类型——"每次发布都重启全部服务"这类隐性破坏，全靠第二问拦截。
规范三：变量纪律
3.4 节的优先级阶梯浓缩成四条纪律。纪律一，默认值只出现在角色 defaults，环境差异只出现在清单变量，禁止在剧本里写环境值（"prod 专用剧本"是坏味道，环境差异该由清单承载）。纪律二，额外变量只用于救火，用完必须落回仓库——流水线里 -e 的使用要留审计记录。纪律三，敏感值走 4.3 节的 Vault 体系，明文秘密零容忍，这条由 grep 级扫描兜底。纪律四，变量命名带域前缀（nginx_、app_、db_），无前缀的裸名（port、user）在多角色协作时必然冲突。
机器守门：lint 与测试进流水线
规范写成文档只完成一半，另一半是让机器执行。流水线的第一阶段就是 lint（5.2 节的骨架里已见），这里给 lint 配置的定制示例——把团队约定写进配置，违反即红：
# .ansible-lint —— 团队定制规则（节选） warn_list: - experimental # 实验性规则只警告不拦 skip_list: - name[casing] # 团队允许任务名小写开头 kinds: - playbook: playbooks/**/*.yml - role: roles/*
molecule 的位置在 lint 之后（4.5 节和 5.1 节都给过用法），这里补它在流水线里的触发策略：角色变更触发对应角色的 molecule 场景，剧本级变更触发全量 lint 加目标环境干跑。全量 molecule 每次都跑的成本在角色多了之后不可接受，按变更路径触发是标准解法。
图 6-1：从提交到生产的守门流水线
规范的维护节奏
一份最小规范的落地模板
给尚未成文的团队一个起点模板，全部条文不超过一页，却能覆盖三类高频纠纷。结构两条：任务必须有意图化的 name；单剧本文件超过三百行必须拆分。幂等两条：逃生舱口任务必须带 changed_when 或 creates；发布类剧本必须通过"连跑两遍第二遍归零"验证。变量两条：环境值只准出现在清单层；新增敏感值必须走加密通道。这六条的全部价值在于可机械执行——前四条能写进 lint 与评审 checklist，后两条能用扫描与流程兜住。规范成文的常见失败是贪多：三十条没人记的条文不如六条有牙齿的条文，先让最小集跑三个月，根据实际拦截记录再决定扩充方向。
测试策略的成本分层
lint 与 molecule 的组合也有成本，聪明的做法是按变更风险分层触发，而不是一刀切全量。第一层，所有提交全量 lint：成本秒级，收益是写法纪律的持续守门。第二层，角色变更触发对应 molecule 场景：成本分钟级，按变更路径映射触发，改哪个角色跑哪个。第三层，环境级干跑：合并到主干后对 staging 全量执行 check 加 diff，输出归档进评审单——它拦截的是"角色级测试发现不了的环境级冲突"（两个角色同时管理一份文件的拼接冲突是典型）。第四层，生产级守门：人工卡点加 serial 滚动。四层的成本从秒到小时递增，触发面从全量递减到按需——测试策略设计与性能调优同构：先测后调，分层投入。
规范推行期的两个现实问题
推行规范最难的从来不是写条文，而是处理两个现实问题。问题一，存量怎么办：历史代码不符合新规范，全量整改的工时没有人批。务实解法是"增量严、存量宽"——新提交必须全绿，存量文件谁改谁顺手治，配合一个季度一次的专项清理窗口，一年下来存量自然消化。问题二，规范与进度的冲突：紧急修复时没人想等 molecule 跑完。预案是写进规范的紧急通道——允许跳过第三、四层测试热修，但必须二十四小时内补跑并归档输出。没有预案的规范会被紧急情况第一次击穿后就形同虚设，有预案的规范把例外也纳入了轨道。规范的生命力不在条文严格，而在例外可控。