codestable__codestable/asset/programming-paradigm.md

编程通用范式：编排-计算分离与渐进结构化

本文档从具体语言实现中提炼出语言无关的编程范式。 这套范式适用于任何支持函数/模块/接口抽象的语言。 分卷：扩展模型与参数设计 · 编写与重构规则

---

第一部分：核心模型

0. 基础约束：代码是写给人看的

所有规则的根基是一条认知事实：人在单一时刻能处理的信息量是有限的。代码的一切组织方式——函数拆分、文件划分、层次结构——最终都是为了让阅读者在任意时刻只需面对"刚好能理解"的信息量。

单函数：一屏可读

一个函数应该在一屏之内读完，阅读者不需要滚动就能看到全貌。这不是审美偏好，而是认知约束——滚动意味着阅读者必须用记忆力去拼接上下文，记忆力是最不可靠的资源。

经验数字：

• 编排函数：10-30 行最佳，每一行是一个动作名。超过 50 行几乎必然层级混乱。
• 计算函数：不超过 50 行。超了说明它做的事情不止一件，应该继续拆。
• 硬上限：单函数超过 100 行，无论什么理由，都是需要拆分的信号。

单文件：一个文件一个角色

一个文件应该用一句话说清它的职责。说不清 → 文件该拆。

经验数字：

• 编排文件（Workflow / Handler）：50-150 行。它只做编排，超了说明业务逻辑混进来了。
• 计算文件（领域服务 / 工具函数）：100-300 行。一个内聚的计算主题。
• 超过 400 行：几乎必然职责混合。不是"太长了"，是"两件事混在一个文件里了"。

拆文件的判断方法：数一下文件里有几组"不相关的函数"。如果函数 A-D 互相调用但从不调用 E-G，而 E-G 互相调用也从不调用 A-D——它们就是两个文件。

单次可见逻辑量

在任意一个抽象层级上，阅读者一次看到的逻辑分支不应超过 7±2 个（米勒定律）。

• 一个编排函数里，步骤超过 7 个 → 考虑分成"阶段"，每个阶段是一个子编排
• 一个 if/switch 里，分支超过 5 个 → 考虑用注册发现或策略模式替代
• 一个模块的公开接口超过 7 个方法 → 考虑拆成更小的模块
• 一个函数同时操作超过 7 个概念（order、customer、payment...）→ 拆成两步

信息密度的平衡

过疏和过密都有害：

• 过密：一个函数里塞了加载、计算、持久化、异常处理、日志——阅读者被淹没
• 过疏：每个操作都拆成单独的类和文件，3 行逻辑散落在 5 个文件里——阅读者被迫四处跳转拼接

判断标准：阅读者理解一段逻辑需要同时打开几个文件？ 如果超过 3 个，说明拆得太碎了。所有规则（分层、拆文件、抽函数）都要在"单点信息过载"和"跨文件跳转"之间找平衡。

文件内的信息布局

一个文件被打开后，阅读者在前 10 秒应该能回答：

1. 这个文件是干什么的（文件名 + 顶部注释/类名）
2. 核心流程是什么（编排函数在最前面，不要埋在 500 行之后）
3. 依赖了谁（import / 构造参数一目了然）

具体做法：

• 编排函数/主函数放在文件最前面，不要被辅助函数埋没
• 公开接口在前，私有实现在后——阅读者先看"做什么"，有兴趣再往下看"怎么做"
• 命名要承载意图——好的命名让阅读者跳过实现。compute_risk(order, customer) 不需要看函数体就知道它干什么；process(data) 什么都没说

核心判断标准

所有数字（50 行、400 行、7 个概念）都是启发式信号。真正的判断标准只有一个：

一个新加入团队的人，打开这个文件/函数，能否在 30 秒内理解它的意图？

能 → 信息密度合适。 不能 → 要么太长（拆）、要么层级混乱（抽取）、要么命名不好（重命名）。

1. 三段式执行模型

任何有副作用的业务操作，都可以分解为三个阶段：

加载（Load）→ 计算（Compute）→ 持久化（Persist）

• 加载：从外部世界（数据库、文件、网络）读取状态，装入内存结构
• 计算：纯逻辑处理，不接触外部世界，输入决定输出
• 持久化：把计算结果写回外部世界

这三个阶段的代码不应混在同一个函数里。混合是复杂性的第一来源——你无法单独测试计算逻辑，因为它和 IO 纠缠在一起。

不同语言的实现方式不同，但分离原则不变：

• 函数式语言天然做到了（纯函数 + IO Monad）
• 面向对象语言需要显式分层（Loader / Service / Persister）
• 脚本语言需要纪律约束（把 IO 调用集中到函数首尾）

2. 状态是显式的容器，不是隐式的环境

程序中流转的状态应该是一个显式的数据结构，在函数间作为参数传递，而不是藏在全局变量、线程本地存储、闭包捕获、或模块级 mutable state 中。

// 原则
f(state) → state'

// 而不是
f()  // 偷偷读写某个外部的 state

这个显式的数据结构（我们称之为 Context）有三层内容：

层次	性质	示例
不可变输入	请求级标识，全程不变	request_id, tenant_id, trace_id
领域状态	核心业务数据，可变	order, customer, account
过程产物	节点间的中间结果	risk_score, payment_result

Context 的边界判断：一个值该不该进 Context，问一个问题——"这个值在不同请求之间会不一样吗？" 会 → 进 Context；不会 → 它是依赖，通过构造/初始化注入。

框架提供的状态容器是合法的 Context

框架提供的响应式状态容器（Vue ref/reactive、React useState、Redux store）本质上就是 Context——它们是显式的、可追踪的、框架帮你管理的状态。使用它们不违反本原则。

不同技术栈的 Context 形态：

技术栈	状态容器（Context）	编排层	计算层
Vue	ref / reactive	methods / watch	computed / 纯函数
React	useState / store	event handler / useEffect	纯函数 / useMemo
后端 Java	Context 对象	Workflow 类	领域服务
Rust	&mut Context	orchestrator 函数	纯函数

违反本原则的不是"改 ref"，而是绕过显式容器传递可变状态：

• 模块级变量被多个组件/函数隐式共享
• 全局对象/单例被当作垃圾桶随处读写
• 隐式注入（provide/inject、ThreadLocal）传递可变状态而非只读值或修改函数
• 闭包捕获了外层的可变变量，且修改不可追踪

判断标准："这个状态的修改，是否可以从编排层的代码里一眼看出来？" 可以 → 合法；不可以 → 隐式状态，需要招安。

3. 编排与计算分离

这是整套范式的核心原理。

编排（Orchestration）= 决定"做什么、以什么顺序、在什么条件下"。 计算（Computation）= 具体"怎么做"。

两者必须分处不同的代码单元（函数、模块、文件）。

// 编排层：只有流程骨架，每一行是一个动作名
function process_order(ctx):
    validate(ctx)
    check_risk(ctx)
    charge(ctx)
    ship(ctx)

// 计算层：具体逻辑，不知道自己在哪个流程里
function check_risk(order, customer) -> risk_score:
    // 纯计算，无副作用，不依赖 context 容器

关键约束：计算层不应接收 Context 容器。 它只接收自己真正需要的参数。编排层负责从 Context 中取出参数、调用计算、把结果写回 Context。

精确表述：计算层接收值、返回值，不接触状态容器。编排层负责从容器取值、调计算、把结果写回容器。

// ✅ 计算函数：接收值，返回值，不碰容器
function compute_risk(order, customer) -> score:
    score = 0
    if customer.bindDuration < 30: score += 40
    if order.amount > 10000: score += 30
    return score

// ✅ 编排层：从容器取值 → 调计算 → 写回容器
function handle_submit():
    score = compute_risk(order.value, customer.value)  // 取值 + 调计算
    risk_score.value = score                            // 写回容器

// ❌ 计算和编排混在一起
function compute_risk():
    score = 0
    if customer.value.bindDuration < 30: score += 40   // 直接读容器
    risk_score.value = score                            // 直接写容器
    api.charge(order.value.id)                          // 连持久化都混进来了

只读派生不算"接触容器"。 响应式框架中的派生计算（Vue computed、React useMemo）读取容器但不修改状态，数学上是 f(state) → derived_value，属于计算层而非编排层。

这条约束的意义：

• 计算函数的签名暴露了它的真实依赖，可读性极高
• 计算函数可以脱离 Context 独立测试
• Context 的变更不会波及计算层

编排层是一个职责，不是一个固定的架构层

编排的本质是**"组装能力而不实现能力"**。这个职责可以由不同重量级的代码单元承担：

最轻                                                     最重
  │                                                        │
  调用点直接组合          提取组合模块            独立编排模块/类
  (模板里写slot组合)     (CopyableTip)          (OrderWorkflow)
  │                                                        │
  适合：1-2次使用         适合：3+次重复模式      适合：核心业务流程
  不额外建文件            多一个小文件            独立文件，专职编排

三者做的事情完全一样——组装能力。区别只是固化程度。

后端倾向重量级编排（独立 Workflow 类），因为流程涉及事务边界、持久化时机、多入口调用，这些约束迫使编排逻辑必须集中管理。

前端组件组合通常没有这些约束——一个页面模板组合几个组件，不涉及事务、调用点通常就一个——所以调用点直接组合就够了。

前端需要重量级编排的信号：

• 多步表单/向导：步骤之间有依赖和条件跳转
• 复杂状态联动：改 A 要联动更新 B、C、D，不该散落在各个 watch 里
• 同一组合模式重复 3 次以上

选择哪个重量级，问三个问题：

1. 有没有事务/持久化/多入口等约束？ 有 → 独立编排模块
2. 这个组合模式重复出现 3 次以上了吗？ 是 → 提取组合模块
3. 都不是？ → 调用点直接组合，最简方案先行

4. 同层同级原则

基础约束（第 0 节）在代码层面的直接推论：一个函数体内的每一行代码，应该处于同一个抽象层级。

// ✅ 同一层级：都是"做什么"
validate(ctx)
check_risk(ctx)
charge(ctx)
ship(ctx)

// ❌ 层级混乱
validate(ctx)
score = 0
for rule in rules:           // 突然掉到"怎么做"
    score += rule.eval(order)
charge(ctx)
ship(ctx)

判断标准：每一行能不能用一句自然语言概括为"做了什么"——如果需要说"它遍历了一个列表然后累加了分数"，那这段代码属于下一层。

---