7.4 混合范式团队约定：一页纸的边界协议
7.4 混合范式团队约定：一页纸的边界协议
本节摘要：函数式落地的最后一公里不在代码在人：风格偏好不同的人共用一个代码库，没有清晰的边界协议就会演变成"评审互拒"的风格内战。本节给出一页纸约定的完整模板——边界条款、握手协议、评审清单、升级机制——并拆解三个真实冲突场景的处理。目标不是让所有人写同一种代码，是让不同风格在明确的地界上合作。
内战是怎么打起来的
还原一个典型冲突现场：评审里，函数式倾向的工程师给同事的合并请求提意见"这段应该用不可变模型"，同事反驳"业务这么急，别搞形式主义"。三轮讨论后升级到组长，裁决随意（通常偏向资历），输的一方记仇，下轮评审反向报复。冲突的根源不是品味，是规则缺位——没有约定哪块地界用哪种范式，每个合并请求都变成范式公投。本节的一页纸约定就是要在项目启动（或内战爆发）前，把公投变成条款。
一、一页纸约定模板
模板分四段，全部是可执行条款，禁用"尽量""鼓励"这类不可判定的措辞：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 《代码风格边界约定》v1 · 生效日期 · 修订需全员评审 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 一、地界划分 1. 业务规则层（规则、计算、校验）：强制纯函数，禁读全局与时钟 2. 模型层：新类型一律不可变（record / frozen / readonly） 3. 外壳层（IO、框架、ORM）：范式不限，但不允许夹带业务规则 4. 存量代码：不追溯，改动到哪行，哪行遵守新约定（童子军军规） 二、握手协议（两种风格交界处的固定形态） - 纯核心对世界暴露：数据进、数据出，禁传可变对象进核心 - 外壳对核心的供数：在边界处完成快照（拷贝/冻结），核心内视为恒定 - 错误出核心：一律结果类型，异常只许出现在外壳 三、评审清单（合并请求必过五问） 1. 新增模型可变吗？ 2. 规则层读了全局状态、时钟或随机源吗？ 3. 核心函数的入参有可变类型吗？ 4. IO 是否只在外壳层？ 5. 新增规则的测试是表驱动或属性式吗？ 四、升级与修订 - 评审争议两次未决 → 按本约定裁决，不按资历 - 约定本身的修订 → 提案加全员评审，季度一次窗口 - 豁免 → 需书面理由并附带偿还计划（如临时性能热点） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
模板的用词刻意"可机判"：每一款都能在对具体代码 diff 时回答"是或否"。"地界划分"把第 2 章的管制架构翻译成治理语言；"握手协议"把不可变数据跨边界传递的细节（边界处快照）写死——这是实践中最高频的踩坑点；"童子军军规"条款让存量代码零压力演进，避免"旧代码不合规就整库抵触"的死锁。
二、三个真实冲突的裁决示范
冲突一：性能热点要不要豁免不可变。 消息队列消费的热循环里，每条消息构造不可变模型，剖析显示分配占比过高。裁决路径：按豁免条款给该热点局部许可（mutable 局部缓存、边界不可变），条件是突变封在单函数内、注释标注豁免编号与偿还计划。条款给出口，纪律防滥用——豁免不是破例，是另一条受管的路。
冲突二：老模块改一行，要不要顺手合规。 修一个 bug 的提交，改动行落在存量过程式模块。按童子军军规条款：改动到的函数按新约定执行（提纯该函数），但禁止扩大范围重构整个模块。裁决关键句：**"改动之内的合规是义务，改动之外的改造是新任务。"**这一条把大量潜在争执消解在事前。
冲突三：结果类型与既有异常体系并存。 团队一半人开始返回 Result，另一半继续抛异常，调用方两头写处理。裁决路径：按握手协议划定分工——业务拒绝（可预期的失败）走结果类型，基础设施故障（不可预期的崩溃）走异常；过渡期在外壳提供适配器把旧异常翻译成结果类型。两套机制并存不可怕，没有分工的并存才致命。
三、约定生效的第一周：落地排期
条款写得再好，落地排期没跟上，约定就会在两周内变成文档库里的陈列品。给一个验证过的排期表。第一天，全员会宣读约定，重点讲地界划分与握手协议，宣读时间控制在三十分钟内——超时的宣读会稀释条款的严肃性。第二天，把五问清单配置进合并请求模板，评审流程多出的这一步必须在第一周内跑通。第三、四天，把可机判的条款落进静态检查（规则层的时钟与随机引用检测、核心入参的可变类型检测、IO 调用混入规则层的检测），先以警告模式运行，跑完一周再切强制模式——直接强制会在第一周制造大量误报抵触。第五天，第一次按新约定完成的合并请求合入，在团队频道里做一次"示范案例"点评：哪几问是机器查的、哪几问是人审的，让所有人看到流程真实运转。
一周结束的验收标准只有一条：随便抽一个本周的合并请求，能明确说出它经过了哪几道约定关卡、每道关卡由谁执行。说不出来，说明流程没有闭环，下周重跑。
四、让约定活过第一年的三件事
约定夭折的头号原因是"发了没人查"。三件维持机制。其一，清单进工具：五问评审清单做成合并请求模板的检查项，人工记忆不可靠，流程卡片才可靠。其二，静态检查兜底：把可机判的条款自动化（检测规则层的时钟随机引用、检测核心入参的可变类型、检测 IO 类调用混入规则层），机器兜住底线，人只审机器判不了的。其三，季度修订窗口：约定随团队成长修订（比如第一年只有三条规矩，第二年加属性测试条款），每次修订走全员评审——约定的权威性来自它被严肃对待的历史，一次走过场的修订会透支全部条款的效力。
💡 关键直觉：混合范式团队的目标不是统一品味，是划清地界让两种风格各司其职。函数式管规则与状态安全，传统范式管框架交互与生态衔接——争的不是谁对谁错，是哪块代码归哪种风格管。地界清了，风格之争自然熄火。
五、评审争议的判例库雏形
约定要被信任，最好的方式是积累自己的判例库：每一次按条款裁决的争议都留档，下次同类问题直接引用判例编号。给三个常见的争议类型与预期裁决方向，作为判例库的种子。争议类型一："这段逻辑看不出副作用，能不能进规则层？"裁决方向：以签名与静态检查为准，不靠口头承诺——读了时钟或全局变量的函数过不了检查，"看不出"不是证据。争议类型二："新框架的惯例是可变模型，跟随框架还是遵守约定？"裁决方向：跟随框架的部分留在壳层，壳层对核心的供数在边界处快照；框架惯例不自动豁免核心层条款。争议类型三："临时活动的代码活不过三个月，能不能不写测试？"裁决方向：按豁免条款走，但必须写明预计删除日期；到期未删的，自动恢复全套标准——"临时"代码在工程界以长寿著称，这条判例几乎每个团队最终都验证过。
判例库放团队可见的位置，每季度修订约定窗口时顺带整理。两年下来你会得到一本只属于自己团队的小型裁判手册，其价值远超任何外来的风格指南。
本节要点回顾
- 冲突根源是规则缺位：没有地界条款，每次评审都变成范式公投，输赢都伤团队。
- 约定必须可机判：禁用"尽量鼓励"，每款条款都要能在具体 diff 上回答是或否。
- 握手协议是高频踩坑点：边界处快照、结果类型出核心、异常只留外壳，三句写死。
- 豁免与童子军条款是安全阀：性能热点有受管的出口，存量代码零压力演进。
- 三件事维持效力：清单进工具、静态检查兜底、季度修订走真评审。
到此，技术与管理两线的工程实践都交了底。最后一章走出当前项目，看函数式思想正在往哪里扩张——语言演化、新领域、以及那道尚未填平的理论与工程鸿沟。