1. 项目概述：Composition 不是“合成”，而是现代软件架构的底层呼吸方式
Composition 这个词在中文技术圈里常被直译为“组合”，但如果你真把它当成 Photoshop 里的图层叠加，或者简单理解成“把几个函数拼在一起”，那接下来的路会越走越窄。我做前端架构十年，带过七支不同规模的技术团队，从电商大促系统到工业物联网控制台，踩过最深的坑，几乎都源于对 Composition 的误读——它不是一种技巧，而是一种思维方式，一种让代码具备生命力、可演进性与抗腐烂能力的底层设计哲学。核心关键词Composition、组合优于继承、函数式思维、可组合性、声明式抽象，它们共同指向一个事实：现代复杂系统的稳定性，不再靠层层封装的“黑盒继承”来维系，而是靠原子化、高内聚、低耦合的“白盒组合”来编织。这个项目标题看似极简，实则覆盖了从 React 的 Hooks 设计、Vue 的 Composition API、Svelte 的逻辑复用机制，到后端微服务编排、配置驱动型业务引擎、甚至硬件固件模块化设计的共通底层逻辑。它适合三类人：一是正在被“祖传代码”拖垮、想重构却无从下手的中高级开发者；二是刚学完 class 继承就一头扎进 React 函数组件、被 useEffect 用法绕晕的新手；三是负责技术选型的架构师，需要判断一个框架或工具是否真正支持“可组合”的底层能力。它解决的不是“怎么写个按钮”，而是“当业务需求以月为单位高频变更时，你的代码结构能否像乐高一样快速拆解、重组、验证，而不引发雪崩式回归？”——这才是 Composition 真正要回答的问题。
2. 内容整体设计与思路拆解：为什么放弃继承，选择组合？一次真实故障的倒推分析
2.1 从一场线上事故说起：继承链断裂如何让支付成功率暴跌 17%
去年双十二前夜，我们一个金融级支付中台突然出现支付成功率断崖式下跌。监控显示，95% 的失败请求都卡在“风控校验”环节。排查日志发现，所有失败请求都触发了同一个异常：TypeError: this.validateCardNumber is not a function。这个方法本该定义在BasePaymentService基类里，被WechatPayService和AlipayService继承。但问题在于，WechatPayService在上个月新增了一个validateCardNumberForMiniProgram方法，并在内部重写了validateCardNumber的调用逻辑——它没有调用super.validateCardNumber()，而是直接复制粘贴了基类代码并做了修改。更致命的是，基类BasePaymentService在本周发布前，因合规要求将validateCardNumber重命名为validateCardNumberV2，并废弃了旧方法。结果就是：WechatPayService的实例在运行时试图调用一个已不存在的方法，整个支付流程中断。这不是个例。我们回溯过去半年的 P0 级故障，有 63% 直接源于继承关系的隐式依赖被破坏。继承强制建立了一种“父子血缘”，但现实中的业务演化是网状的、非线性的。一个支付渠道可能同时需要“国际卡风控”、“小程序特有校验”、“灰度流量标记”三个维度的能力，它们彼此正交，强行塞进一条继承链，就像给一个人硬安上鱼鳃、翅膀和机械臂——表面功能齐全，实则处处冲突。
2.2 Composition 的设计原点：把系统看作“能力网络”，而非“家族族谱”
Composition 的核心思想，是彻底抛弃“谁是谁的子类”这种静态血缘关系，转而关注“谁拥有什么能力”。它不问“WechatPayService是不是BasePaymentService的儿子”，而是问“WechatPayService需要哪些能力模块？这些模块是否可以独立存在、独立测试、独立升级？” 我们重构后的支付服务结构如下：
// 能力模块（纯函数或轻量类，无状态或状态明确隔离） const cardValidation = { validate: (cardNo) => { /* 国际卡号 Luhn 算法校验 */ } }; const miniProgramRules = { apply: (order) => { /* 小程序订单专属风控规则 */ } }; const grayScaleMarker = { mark: (order) => { /* 根据用户 ID 哈希决定是否打灰度标 */ } }; // 组合服务（声明式组装能力） const WechatPayService = compose( withValidation(cardValidation), // 注入校验能力 withRules(miniProgramRules), // 注入规则能力 withGrayScale(grayScaleMarker) // 注入灰度能力 )(basePaymentLogic); // basePaymentLogic 是纯业务逻辑函数，不包含任何具体实现细节 // 关键：每个能力模块可单独替换 // 替换校验模块，无需动其他代码 const newCardValidation = { validate: (cardNo) => { /* 新增 BIN 表匹配校验 */ } }; const WechatPayServiceV2 = compose( withValidation(newCardValidation), // 仅此处变更 withRules(miniProgramRules), withGrayScale(grayScaleMarker) )(basePaymentLogic);这个设计背后有三层关键考量：第一，可测试性。cardValidation.validate可以脱离整个支付系统，用 3 行 Jest 代码完成全路径测试；第二，可替换性。当监管要求更换风控引擎时，只需提供一个符合validate接口的新模块，WechatPayService的组装代码一行不动；第三，可追溯性。compose函数的执行顺序就是能力注入顺序，调试时一眼看清“校验 -> 规则 -> 灰度”这条数据流，而不是在 5 层继承链里逐级super()查找。这正是 Composition 解决“代码腐烂”的根本路径：它把变化点（change point）显式地暴露出来，而不是隐藏在extends关键字之后。
2.3 为什么不是 Mixin 或 Decorator？Composition 的不可替代性
有人会说：“Mixin 不也是一堆功能混入吗？Decorator 不也能装饰类？” 这是个关键误区。Mixin 的本质仍是继承的变体，它把多个父类的属性“拷贝”到子类原型上，依然存在命名冲突、执行顺序不明确、无法动态卸载等问题。Decorator（如 TypeScript 的@语法）则过度依赖运行时元编程，调试困难，且与框架强绑定。而真正的 Composition，其灵魂在于函数式组合（Function Composition）和依赖注入（Dependency Injection）的结合。compose(f, g, h)的数学定义是f(g(h(x)))，它保证了严格的、可预测的执行顺序；而withValidation(module)这样的高阶函数，则实现了依赖的显式声明与解耦。我们曾对比过三种方案在 10 万次压测下的性能损耗：纯 Composition 方案平均耗时 2.1ms，Mixin 方案因原型链查找增加至 3.8ms，Decorator 方案因反射操作飙升至 7.4ms。性能差异背后，是设计哲学的分野：Composition 追求的是编译期/构建期的确定性，而 Mixin/Decorator 往往把决策推迟到运行时，牺牲了可预测性来换取灵活性——这在基础设施层是得不偿失的。
3. 核心细节解析与实操要点：从概念到落地的五个关键断层
3.1 断层一：混淆“组合对象”与“组合逻辑”——90% 的初学者卡在这里
很多开发者写的“组合”代码，其实是这样的：
// ❌ 错误示范：这只是对象拼接，不是 Composition class UserService { constructor() { this.db = new Database(); this.cache = new RedisCache(); this.logger = new Logger(); } getUser(id) { return this.db.find(id); // 没有利用 cache，没有记录日志 } }这仅仅是把几个对象塞进一个类里，各模块之间没有形成协同的数据流。真正的 Composition，必须体现数据流的声明式编排。正确做法是：
// ✅ 正确示范：数据流即组合逻辑 const getUser = pipe( // pipe 是组合函数：f(g(h(x))) fetchFromDB, // 第一步：从 DB 获取原始数据 memoizeWithRedis(cacheClient), // 第二步：用 Redis 缓存结果（自动处理缓存穿透） logOperation(logger, 'getUser') // 第三步：记录操作日志（自动捕获错误） ); // 使用时，getUser(id) 自动完成“查库 -> 缓存 -> 日志”整条链路 // 每个环节都是可插拔的：换缓存方案？只改 memoizeWithRedis 的参数 // 去掉日志？删掉 logOperation 这一行即可这里的关键洞察是：Composition 的最小单元不是“类”，而是“函数”；组合的目标不是“拥有对象”，而是“编排行为”。pipe函数本身不关心fetchFromDB是从 MySQL 还是 MongoDB 查，也不关心cacheClient是 Redis 还是 Memcached，它只认准一个契约：输入一个id，输出一个Promise<User>。这个契约（接口）就是组合得以成立的基石。我在带新人时，会让他们先用纸笔画出业务流程图，然后强制要求：图上的每一个箭头，必须对应一个独立的、可测试的函数。画不出来，说明逻辑还没拆解到位。
3.2 断层二：忽略状态管理的组合——当“可组合”遇上“有状态”
Composition 最常被质疑的一点是：“函数是无状态的，但现实业务哪有不维护状态的？” 这个质疑非常有力。我们的解决方案不是回避状态，而是将状态管理本身也作为可组合的能力模块。以一个电商购物车为例，传统写法是：
// ❌ 状态与逻辑强耦合 class Cart { items = []; total = 0; addItem(item) { this.items.push(item); this.total += item.price; // 状态更新逻辑散落在各处 } removeItem(id) { this.items = this.items.filter(i => i.id !== id); this.total = this.items.reduce((sum, i) => sum + i.price, 0); // 重复计算 } }这导致total的计算逻辑与items的操作逻辑紧耦合，无法单独测试total计算的正确性。Composition 方案是：
// ✅ 状态管理作为独立模块 const cartState = { initialState: { items: [], total: 0 }, reducers: { ADD_ITEM: (state, item) => ({ ...state, items: [...state.items, item] }), REMOVE_ITEM: (state, id) => ({ ...state, items: state.items.filter(i => i.id !== id) }) } }; // 计算逻辑作为独立模块（纯函数） const calculateTotal = (items) => items.reduce((sum, i) => sum + i.price, 0); // 组合：状态 + 计算 + 副作用（如持久化） const CartService = compose( withState(cartState), // 提供状态管理能力 withSelector('items', calculateTotal), // 提供派生状态能力（total） withPersistence(localStorage, 'cart') // 提供持久化能力 )(baseCartLogic); // baseCartLogic 只处理业务规则，如库存校验、限购检查withSelector模块的核心是：它监听items状态的变化，一旦变化，自动调用calculateTotal重新计算total，并将新值注入到服务的上下文中。这样，total的计算逻辑完全独立，可以单独用calculateTotal([{price: 10}, {price: 20}])测试，结果永远是30。状态管理不再是“谁来改this.total”，而是“谁来响应items的变化并触发计算”。这就是 Composition 处理状态的精髓：把状态变更视为事件，把计算逻辑视为对事件的响应，两者通过明确的接口（selector）连接。
3.3 断层三：组合粒度失控——太粗失去灵活性，太细则丧失可读性
组合不是越细越好。我见过一个团队把 HTTP 请求拆成buildUrl、buildHeaders、buildBody、sendRequest、parseResponse、handleError六个函数，再用compose串起来。结果是：一个简单的GET /users调用，代码长达 20 行，阅读成本远超一个axios.get()。组合粒度的黄金法则是：一个组合单元，应该对应一个完整的、有明确业务语义的“能力闭环”。对于 HTTP 请求，apiClient就是一个合理的闭环——它封装了 URL 构建、认证头、重试、错误分类等所有细节，对外只暴露get,post,put等语义清晰的方法。而buildUrl这类函数，只应在apiClient内部使用，不应暴露给上层组合。我们制定了一套粒度判断标准：
- 如果一个函数的输入/输出类型，在业务领域中没有公认的名称（如
User,Order,PaymentResult），它大概率粒度太细； - 如果一个函数的职责，可以用“动词+名词”准确概括（如
fetchUserProfile,validatePaymentMethod），它就是一个合格的组合单元； - 如果两个函数总是被一起调用（如
startTransaction和commitTransaction），它们应该被合并为一个transactional能力模块。
在实际项目中，我们通常将组合粒度控制在 3-5 层：最底层是通用工具（如debounce,throttle），中间层是领域能力（如authManager,notificationService），顶层是业务场景（如checkoutFlow,onboardingWizard）。每一层都只与相邻层交互，形成清晰的“能力金字塔”。
3.4 断层四：缺乏组合契约（Contract）——当模块间开始“猜接口”
没有契约的组合，就像没有图纸的乐高。我曾接手一个遗留项目，其中userProfileLoader模块的文档写着“返回用户基本信息”，但实际返回的是{name, email, avatar}；而依赖它的dashboardRenderer模块，却期望字段是{fullName, emailAddress, profilePic}。结果是渲染时大量undefined。Composition 要求每个可组合模块，必须明确定义其输入契约（Input Contract）和输出契约（Output Contract）。我们采用 TypeScript 接口 + JSDoc 的双重保障：
/** * 用户资料加载器 * @inputContract { userId: string } - 必须提供用户唯一标识 * @outputContract { * id: string; * name: string; * email: string; * avatar: string; * createdAt: Date; * } - 严格返回此结构，字段名、类型、必选性均不可变 */ interface UserProfileLoader { load: (input: { userId: string }) => Promise<{ id: string; name: string; email: string; avatar: string; createdAt: Date; }>; } // 使用时，TypeScript 会强制校验 const loader: UserProfileLoader = createLoader(); // 类型安全更重要的是，我们要求所有契约必须经过契约测试（Contract Test）。即：为UserProfileLoader编写一个独立的测试套件，只验证它是否满足上述契约，不涉及任何具体实现（如数据库连接、API 调用）。这个测试套件会被所有依赖方（如dashboardRenderer）在 CI 中运行。一旦loader的实现违反契约，所有依赖方的构建立即失败。这从根本上杜绝了“模块间猜接口”的混乱。契约不是文档，而是可执行的、自动化的质量门禁。
3.5 断层五：忽视组合的副作用管理——当“纯函数”撞上“发邮件”
Composition 崇尚纯函数，但现实世界充满副作用：发邮件、写数据库、调用第三方 API。如果把这些副作用直接塞进组合链，整个链条就失去了可预测性和可测试性。我们的解决方案是副作用分离（Side Effect Separation）和延迟执行（Lazy Execution）。以“用户注册成功后发送欢迎邮件”为例：
// ❌ 错误：副作用侵入组合逻辑 const registerUser = (userData) => { const user = createUser(userData); sendWelcomeEmail(user.email); // 副作用！无法测试，无法模拟 return user; }; // ✅ 正确：声明副作用，延迟执行 const registerUser = (userData) => { const user = createUser(userData); // 返回一个“待执行”的副作用描述，而非立即执行 return { user, sideEffects: [ { type: 'SEND_EMAIL', payload: { to: user.email, template: 'welcome' } } ] }; }; // 由专门的副作用处理器统一调度 const effectHandler = { SEND_EMAIL: async (payload) => { await mailer.send(payload.to, payload.template); } }; // 组合时，业务逻辑与副作用处理完全解耦 const registrationFlow = compose( withBusinessLogic(registerUser), // 只负责生成用户和副作用描述 withEffectHandler(effectHandler) // 只负责执行副作用描述 )(baseRegistration);这种模式的好处是爆炸性的：registerUser函数现在可以 100% 纯函数化测试，输入userData，断言输出的user结构和sideEffects数组内容；effectHandler可以针对不同环境（开发/测试/生产）注入不同的实现（开发环境打印日志，测试环境存入内存队列，生产环境调用真实邮件服务）；最关键的是，副作用的执行时机完全可控。我们可以选择在事务提交后执行，也可以在用户确认邮箱后再执行，甚至可以批量发送。Composition 不是消灭副作用，而是把它从“暗处”拉到“明处”，变成可声明、可管理、可审计的一等公民。
4. 实操过程与核心环节实现：一个完整电商搜索服务的 Composition 实战
4.1 需求拆解：从模糊需求到可组合能力清单
客户提出的需求是：“搜索要快，要准，要能按销量排序，还要支持品牌筛选和价格区间，最好能记住用户上次搜的词。” 这听起来很常规，但如果我们直接开干，很容易陷入“先搭个 SearchService 类，再慢慢加功能”的老路。Composition 的第一步，是需求原子化。我带着团队用白板进行了一次“能力风暴”：
- 快→ 需要缓存能力（Cache）、需要查询优化能力（QueryOptimization）
- 准→ 需要分词能力（Tokenizer）、需要相关性打分能力（Scoring）
- 销量排序→ 需要排序能力（Sorting），且排序依据是动态的（销量、价格、新品）
- 品牌筛选→ 需要过滤能力（Filtering），且过滤条件是多维度的（品牌、品类、属性）
- 价格区间→ 同样是 Filtering，但数据类型是数值范围
- 记住上次搜索→ 需要本地存储能力（LocalStorage）、需要历史记录管理能力（HistoryManager）
我们最终提炼出 7 个核心能力模块，每个模块都独立开发、独立测试：
| 模块名称 | 职责 | 输入契约 | 输出契约 | 是否可选 |
|---|---|---|---|---|
queryParser | 将用户输入字符串解析为结构化查询对象 | string(e.g., "iPhone 15") | { keywords: string[], filters: { brand?: string, priceRange?: [number, number] } } | 必选 |
tokenizer | 对关键词进行分词、去停用词、同义词扩展 | string[] | string[](e.g., ["iphone", "15", "apple"]) | 必选 |
searchEngine | 执行实际搜索（对接 ES/Algolia） | { keywords, filters, sort, page } | { results: Product[], total: number, tookMs: number } | 必选 |
scorer | 对搜索结果进行相关性重打分 | Product[] | Product[](按新分数排序) | 可选（默认关闭） |
cacheManager | 缓存搜索结果，设置 TTL | { query, results } | void | 可选（默认开启） |
historyTracker | 记录搜索历史到 localStorage | { query, timestamp } | void | 可选（默认开启） |
resultEnricher | 为结果添加额外信息（如库存状态、促销标签） | Product[] | Product[](增强后) | 可选（默认开启） |
这个清单的价值在于：它把一个模糊的“搜索要好”转化为了 7 个可量化、可替换、可开关的具体能力。产品经理说“下个月要接入新的 AI 打分模型”，我们只需提供一个符合scorer契约的新模块，替换掉旧的scorer，其他 6 个模块完全不受影响。
4.2 模块开发：以searchEngine为例的契约驱动开发
searchEngine是核心模块，我们严格按照契约先行原则开发。首先定义 TypeScript 接口：
/** * 搜索引擎能力契约 * @inputContract { * keywords: string[]; * filters: Record<string, any>; * sort: { field: string; order: 'asc' | 'desc' }; * page: { size: number; from: number }; * } - 查询参数必须结构化，禁止传 raw SQL 或 ES DSL * @outputContract { * results: Product[]; * total: number; * tookMs: number; * facets?: Record<string, { value: string; count: number }[]>; * } - 必须返回标准化结果，facets 为可选聚合数据 */ interface SearchEngine { search: (input: { keywords: string[]; filters: Record<string, any>; sort: { field: string; order: 'asc' | 'desc' }; page: { size: number; from: number }; }) => Promise<{ results: Product[]; total: number; tookMs: number; facets?: Record<string, { value: string; count: number }[]>; }>; }然后编写契约测试（searchEngine.contract.test.ts）：
describe('SearchEngine Contract', () => { let engine: SearchEngine; beforeEach(() => { engine = createElasticsearchEngine(); // 使用真实 ES 实例 }); it('should return results array when keywords provided', async () => { const result = await engine.search({ keywords: ['phone'], filters: {}, sort: { field: 'score', order: 'desc' }, page: { size: 10, from: 0 } }); expect(Array.isArray(result.results)).toBe(true); expect(result.results.length).toBeLessThanOrEqual(10); }); it('should return total count and tookMs', async () => { const result = await engine.search({ /* same input */ }); expect(typeof result.total).toBe('number'); expect(typeof result.tookMs).toBe('number'); }); // 更多契约测试... });只有当所有契约测试通过，searchEngine模块才被视为“可用”。这个过程确保了无论底层是 Elasticsearch、Algolia 还是未来自研的向量搜索引擎，只要它满足这个契约，就能无缝接入整个搜索组合体系。我们在项目中，为每个模块都建立了这样的契约测试套件，它们构成了整个系统的“质量护城河”。
4.3 组装服务：用compose构建可配置的搜索流水线
有了 7 个经过契约验证的模块，组装就变成了“搭积木”。我们创建了一个SearchServiceFactory，它接收模块实例，返回一个可配置的搜索服务：
import { compose, pipe } from 'ramda'; // 高阶函数：为模块添加能力 const withQueryParsing = (parser: QueryParser) => (next: SearchStep) => (input: string) => parser.parse(input).then(next); const withTokenizing = (tokenizer: Tokenizer) => (next: SearchStep) => (input: ParsedQuery) => tokenizer.tokenize(input.keywords).then(keywords => next({ ...input, keywords }) ); const withCaching = (cache: CacheManager) => (next: SearchStep) => async (input: ParsedQuery) => { const cacheKey = generateCacheKey(input); const cached = await cache.get(cacheKey); if (cached) return cached; const result = await next(input); await cache.set(cacheKey, result, { ttl: 300 }); // 5分钟缓存 return result; }; // 组装主搜索流水线 export const createSearchService = ({ queryParser, tokenizer, searchEngine, scorer, cacheManager, historyTracker, resultEnricher, enableScorer = false, enableCache = true }: SearchServiceConfig) => { // 构建核心搜索链 const searchPipeline = pipe( withQueryParsing(queryParser), withTokenizing(tokenizer), ...(enableCache ? [withCaching(cacheManager)] : []), withSearching(searchEngine), ...(enableScorer ? [withScoring(scorer)] : []), withEnriching(resultEnricher) ); // 包装为完整服务 return { search: async (query: string) => { const result = await searchPipeline(query); // 记录历史（副作用） await historyTracker.record({ query, timestamp: Date.now() }); return result; }, // 其他方法... }; };这个工厂函数的关键在于：所有能力模块的启用/禁用，都通过布尔参数控制，而不是修改代码逻辑。当产品经理说“缓存导致新品上架延迟，先关掉”，我们只需将enableCache设为false，重新部署，整个缓存逻辑就从流水线中消失了，其他所有环节照常工作。这种配置驱动的组合，让系统拥有了前所未有的适应性。
4.4 运行时调试：如何看清组合链中每一环的输入输出？
组合链一旦变长，调试就成了噩梦。我们开发了一个轻量级的debugCompose工具，它能在开发环境下，自动打印每一环的输入和输出：
// 开发环境专用的组合器 const debugCompose = (...fns: Function[]) => { return (input: any) => { console.group('🔍 Composition Debug Trace'); let result = input; fns.forEach((fn, index) => { console.log(`Step ${index + 1}: ${fn.name || 'anonymous'} -> Input:`, result); result = fn(result); console.log(`Step ${index + 1}: ${fn.name || 'anonymous'} -> Output:`, result); }); console.groupEnd(); return result; }; }; // 使用 const debugSearchService = createSearchService({ // ... same config // 但在开发环境，用 debugCompose 替代 pipe searchPipeline: debugCompose(/* same functions */) });效果如下：
🔍 Composition Debug Trace Step 1: withQueryParsing -> Input: "iPhone 15" Step 1: withQueryParsing -> Output: { keywords: ["iPhone", "15"], filters: {} } Step 2: withTokenizing -> Input: { keywords: ["iPhone", "15"], filters: {} } Step 2: withTokenizing -> Output: { keywords: ["iphone", "15", "apple"], filters: {} } Step 3: withCaching -> Input: { keywords: ["iphone", "15", "apple"], filters: {} } Step 3: withCaching -> Output: { results: [...], total: 120, tookMs: 42 } ...这个工具让我们在 5 秒内就能定位问题：是queryParser把 “iPhone” 解析错了？还是tokenizer没有做同义词扩展？抑或是cacheManager返回了过期数据？它把原本需要打断点、层层跟进的调试过程，简化为一次 console.log 的扫视。这是 Composition 赋予开发者的“上帝视角”。
4.5 性能监控：组合不是银弹，必须量化每一块的代价
Composition 的最大风险是“看不见的性能损耗”。10 个模块，每个增加 2ms 开销，整条链路就是 20ms。我们必须对每个模块进行性能基线监控。我们在每个能力模块的入口和出口，都注入了性能测量：
const withPerformanceMonitoring = (moduleName: string) => (next: Function) => { return async (input: any) => { const start = performance.now(); try { const result = await next(input); const end = performance.now(); // 上报到监控系统：moduleName, duration, inputSize, outputSize reportMetric(`${moduleName}.duration`, end - start); return result; } catch (error) { const end = performance.now(); reportMetric(`${moduleName}.error`, 1); throw error; } }; }; // 组装时加入监控 const searchPipeline = pipe( withPerformanceMonitoring('queryParser'), withQueryParsing(queryParser), withPerformanceMonitoring('tokenizer'), withTokenizing(tokenizer), // ... );上线后，我们立刻发现了瓶颈：scorer模块在处理 100 条结果时，平均耗时 120ms，远超预期的 20ms。深入分析发现，它在循环中反复调用了未缓存的getBrandPopularityScore()。我们没有去改scorer的实现，而是为它组合了一个新的能力模块：withMemoizedBrandScore(memoizedBrandScoreProvider)。这个新模块拦截了getBrandPopularityScore的调用，用 LRU Cache 缓存结果，将scorer的耗时从 120ms 降至 18ms。整个过程，scorer模块的代码一行未动，我们只是在它的上游，插入了一个“加速器”模块。这就是 Composition 的威力：性能优化不再是“改代码”，而是“加模块”。它把优化行为，也变成了可组合、可复用、可开关的能力。
5. 常见问题与排查技巧实录：来自 12 个真实项目的血泪经验
5.1 问题速查表：高频故障与根因定位
| 现象 | 可能根因 | 快速定位技巧 | 解决方案 |
|---|---|---|---|
| 组合后功能正常，但性能急剧下降 | 某个模块内部存在未优化的 O(n²) 算法，或频繁的同步 I/O | 使用withPerformanceMonitoring查看各模块耗时分布；重点关注耗时 >50ms 的模块 | 为该模块组合一个withOptimizedAlgorithm或withAsyncIO模块，将耗时操作移出主线程 |
| 某个模块在组合链中失效（不执行） | 模块的输入/输出契约与上下游不匹配，导致 Promise 被 reject 或返回 undefined | 在debugCompose输出中，检查失效模块的 Input 和 Output；查看是否有Promise.reject或undefined传递 | 用withFallback模块包裹失效模块，提供默认值或降级逻辑；检查契约测试是否覆盖了边界情况 |
| 状态更新不及时，UI 未刷新 | 状态管理模块（如withState）未正确监听状态变化，或 selector 函数有 bug | 在withState模块中添加console.log('state changed:', newState)；检查 selector 函数是否返回了新引用 | 确保 selector 函数是纯函数；使用immer或solid-js的响应式原语，避免手动setState |
| 组合服务在 SSR（服务端渲染）环境下报错 | 某个模块（如localStorage）在 Node.js 环境下不可用，或依赖浏览器全局对象 | 在模块初始化时，检查typeof window !== 'undefined'；查看错误堆栈定位到具体模块 | 为该模块提供 SSR 安全的替代实现（如memoryStorage），或用withSSRGuard模块包装，服务端跳过执行 |
| A/B 测试分流不生效 | 分流逻辑（如withABTest）被放在了组合链的错误位置，导致在缓存后才执行 | 检查debugCompose输出，确认withABTest是否在withCaching之前 | 将withABTest移动到组合链最前端，确保分流决策基于原始请求，而非缓存结果 |
这张表是我们团队在过去两年中，从 12 个不同项目里总结出来的“故障地图”。它不是教科书式的理论，而是每次凌晨三点被 PagerDuty 叫醒后，我们记下的第一反应。比如“SSR 报错”这个问题，我们曾在一个大型电商项目中栽过跟头：historyTracker模块直接调用了localStorage.setItem，导致整个 Node.js 渲染进程崩溃。后来我们制定了铁律：任何模块在初始化时，必须主动声明其运行时环境依赖。historyTracker的构造函数现在变成了：
class HistoryTracker { constructor(options: { storage: Storage | MemoryStorage; // 显式传入存储实现 isBrowser: boolean; // 显式传入环境标识 }) { this.storage = options.storage; this.isBrowser = options.isBrowser; } record(event) { if (!this.isBrowser) return; // 环境守卫 this.storage.setItem('history', JSON.stringify(event)); } }这种显式声明，比任何文档都管用。
5.2 实操心得：那些文档里不会写的“潜规则”
提示：Composition 的学习曲线是反直觉的。你越想“完美设计”，越容易失败。我的第一条心得是：先组合，再抽象。不要一上来就设计 7 个模块。从一个最核心的、最痛的痛点开始。比如，你的搜索慢，那就先做一个
withCaching模块，把它加到现有SearchService的 `search
