Redux 的 combineReducers 完全指南切片 Reducer 组合、状态形状设计与源码级原理剖析【免费下载链接】reduxA JS library for predictable global state management项目地址: https://gitcode.com/gh_mirrors/re/reduxcombineReducers是 Redux 提供的最常用的高阶 reducer 工具函数用于把多个切片 reducerslice reducer合并成一个根 reducer从而把庞大的状态树按领域拆分为独立管理的切片slice。本篇文章以官方文档 Using combineReducers 为核心骨架结合仓库源码 src/combineReducers.ts 与其测试用例 test/combineReducers.spec.ts系统讲解它的核心概念、状态形状定义方式、内置规则约束以及它不擅长处理的场景与替代方案。读完本文你将理解 combineReducers 的完整调用语义、初始化行为、引用相等性referential equality优化并能在自己的项目中正确组织切片 reducer、规避常见陷阱。Core Concepts为什么需要 combineReducers在大多数 Redux 应用中最典型的状态形状是一个普通 JavaScript 对象每个顶层键top-level key对应一块领域数据如todos、filter、posts。与之配套最主流的 reducer 编写方式是维护一组切片 reducer函数每个切片 reducer 具有完全相同的(state, action)签名各自负责管理自己那一小块状态的更新。多个切片 reducer 可以同时响应同一个 action——每个切片独立决定是否需要更新自己最终由外层把这些切片组合成新的状态对象。由于这种模式极其普遍Redux 直接内置了combineReducers工具来落地这一行为。从代码结构看combineReducers是典型的高阶 reducerhigher-order reducer它接收一个以 reducer 函数为值的对象ReducersMapObject返回一个新的 reducer 函数这一点在其源码注释中有明确定义见 src/combineReducers.tsTurns an object whose values are different reducer functions, into a single reducer function. It will call every child reducer, and gather their results into a single state object, whose keys correspond to the keys of the passed reducer functions.使用 combineReducers 前必须明确的四个要点官方文档 Using combineReducers 开篇就强调了几条重要认知它只是一个简化常见场景的工具函数并非强制要求。你不必在自己的应用中使用它它也无法覆盖所有可能的场景。对于它处理不了的用例完全需要自己编写自定义 reducer 逻辑详见 Beyond combineReducers。Redux 本身对状态如何组织不持意见但 combineReducers 强制执行若干规则以帮助用户避免常见错误。具体规则清单见 combineReducers API 文档。Redux 分发 action 时是否会调用所有 reducer由于整个 store 只有一个根 reducer默认答案是不会。但combineReducers的行为恰恰是会为了组装出新的状态树它会把当前切片状态和当前 action 分别传给每一个切片 reducer给每个切片响应并更新自己的机会。因此使用combineReducers在某种意义上确实调用了所有 reducer——至少是它所包裹的全部切片 reducer。可以在 reducer 结构的任意层级使用它而不只是创建根 reducer。把多个 combined reducer 在不同位置组合起来再拼成根 reducer是极其常见的做法。定义 State Shape状态形状由谁决定初始化 store 状态有两条途径一是createStore的第二个参数preloadedState主要用于从 localStorage 等服务端/持久化来源恢复旧状态二是根 reducer 在state参数为undefined时返回初始状态。这两者如何配合的详细机制见 Initializing State但使用combineReducers时还有额外需要注意的点combineReducers接收一个以切片 reducer 为值的对象并生成一个输出状态对象的函数输出对象的键与输入对象完全一致。这意味着如果没有向createStore传入preloadedState那么传入combineReducers的键名就直接决定了输出状态对象的键名。而这种键名即状态形状的关联在使用默认导出default export和对象字面量简写object literal shorthand等 ES Module 特性时并不那么显而易见容易造成困惑。简写语法如何意外定义状态形状文档给出了一个非常典型的例子——使用对象字面量简写时状态键名会等于导入的变量名// reducers.js export default theDefaultReducer (state 0, action) state export const firstNamedReducer (state 1, action) state export const secondNamedReducer (state 2, action) state // rootReducer.js import { combineReducers, createStore } from redux import theDefaultReducer, { firstNamedReducer, secondNamedReducer } from ./reducers // 使用对象字面量简写语法定义对象形状 const rootReducer combineReducers({ theDefaultReducer, firstNamedReducer, secondNamedReducer }) const store createStore(rootReducer) console.log(store.getState()) // {theDefaultReducer : 0, firstNamedReducer : 1, secondNamedReducer : 2}注意因为使用了对象字面量简写结果状态中的键名与 import 的变量名完全相同。这未必是你想要的行为也常常是初学者对现代 JS 语法不熟悉时产生困惑的根源。更重要的是theDefaultReducer这类名字作为状态键名也很别扭——状态键应该反映它承载的数据领域或类型而不是把 reducer 这个词写进键名。文档因此给出两个修正建议要么在切片 reducer 对象中显式指定键名要么在 import 时小心地重命名变量以配合简写语法。更好的写法显式控制键名import { combineReducers, createStore } from redux // 把默认导入重命名为我们想要的任何名字也可以重命名具名导入 import defaultState, { firstNamedReducer, secondNamedReducer as secondState } from ./reducers const rootReducer combineReducers({ defaultState, // 键名与仔细重命名过的默认导出一致 firstState: firstNamedReducer, // 用明确的键名替代变量名 secondState // 键名与仔细重命名过的具名导出一致 }) const reducerInitializedStore createStore(rootReducer) console.log(reducerInitializedStore.getState()) // {defaultState : 0, firstState : 1, secondState : 2}这个状态形状更贴切地反映了数据本身因为我们特意为传给combineReducers的键设置了清晰的名字。底层实现combineReducers 到底做了什么要真正理解combineReducers的语义最好的方式是阅读它的实现源码 src/combineReducers.ts。整个实现可以分为构造阶段与调用阶段两部分。构造阶段过滤、告警与形状校验在调用combineReducers(reducers)的那一刻源码会依次执行过滤非函数值遍历传入对象的键只保留typeof reducers[key] function的条目进入finalReducerssrc/combineReducers.ts。这对应测试用例ignores all props which are not a function——传入布尔值、字符串、嵌套对象都会被忽略最终状态只包含真正的 reducer 函数见 test/combineReducers.spec.ts。对缺失的 reducer 发出告警开发环境下若某个键对应的值为undefined会输出No reducer provided for key ...的警告src/combineReducers.ts对应测试warns if a reducer prop is undefined。形状断言assertReducerShape对每个切片 reducer 执行两次探测调用src/combineReducers.ts用{ type: ActionTypes.INIT }调用reducer(undefined, ...)若返回undefined则抛出初始化时返回 undefined的错误用ActionTypes.PROBE_UNKNOWN_ACTION()一个随机生成的私有 action 类型再次探测若返回undefined则抛出错误提示不要处理redux/*命名空间下的私有 action未知 action 必须返回当前状态。这一步与 src/utils/actionTypes.ts 中定义的私有 action 类型机制密切相关INIT、REPLACE、PROBE_UNKNOWN_ACTION都是带随机后缀的字符串应用程序不应直接引用它们。缓存形状断言错误如果断言阶段抛错错误会被暂存shapeAssertionError等到组合函数第一次被实际调用时再抛出src/combineReducers.ts。测试throws an error on first call if a reducer returns undefined initializing验证的正是这一行为test/combineReducers.spec.ts。调用阶段逐切片分发与引用相等性优化组合函数combination(state {}, action)是每次分发 action 时真正执行的逻辑src/combineReducers.ts开发环境下通过getUnexpectedStateShapeWarningMessage检查输入状态形状若状态不是普通对象、或包含未知键会给出精确的警告信息如Unexpected key bar found in preloadedState argument passed to createStore。并且unexpectedKeyCache保证同一个未知键只告警一次对应测试only warns for unexpected keys oncetest/combineReducers.spec.ts。遍历每个切片 reducer取出当前切片状态previousStateForKey调用reducer(previousStateForKey, action)得到nextStateForKey。若某个切片返回undefined立即抛出包含 action 类型与切片键名的详细错误对应测试throws an error if a reducer returns undefined handling an action。引用相等性优化只有任一切片的新状态与旧状态引用不同nextStateForKey ! previousStateForKey或者状态键的数量发生变化时才返回新建的nextState对象否则直接返回原state引用src/combineReducers.ts。这正是两个测试的核心断言所有子 reducer 都保持引用相等时组合结果也保持相等reducer(initialState, { type: FOO })严格等于initialState只要有一个切片变化整体就返回新对象见 test/combineReducers.spec.ts。这个返回原引用还是新对象的行为对性能至关重要它让 Redux 能够廉价地判断状态是否真的发生了变化从而避免无谓的重渲染。理解这一点也就理解了为什么每个切片 reducer 都必须遵循未识别 action 返回原状态的约定——只有这样才能保住引用相等性带来的优化。传给 combineReducers 的 reducer 必须满足的规则正如 API 文档 combineReducers 所强调的combineReducers是轻度固执mildly opinionated的它倾向于帮助初学者避免常见陷阱因此强制约束了传入 reducer 的行为。任何传给它的 reducer 都必须满足三条规则对任何未识别的 action必须原样返回传入的第一个参数state测试maintains referential equality if the reducers it is combining do正是对该约定的验证。永远不能返回undefined。通过早期的return语句很容易误写出这种 bug所以combineReducers会选择直接抛错而不是让错误在别处慢慢显现。如果确实不想让某个切片持有值可以返回null而不是undefined。当传入的state为undefined时必须返回该 reducer 自己的初始状态根据上一条规则初始状态同样不能是undefined。推荐用参数默认值语法state 初始值实现也可以显式检查第一个参数是否为undefined。需要特别警惕的是即使你给createStore(combineReducers(...), initialState)传了初始状态combineReducers依然会用undefined去探测每个切片 reducer这正是上面提到的assertReducerShape阶段。因此你必须确保自己的 reducer 在收到undefined时也能正常工作哪怕你在自己的代码里从不打算让它真的收到undefined。规则背后的错误信息结合源码可以看到这些规则对应的完整错误文案src/combineReducers.ts 与 src/combineReducers.ts初始化时返回undefinedThe slice reducer for key counter returned undefined during initialization. ...探测到处理了私有 actionThe slice reducer for key counter returned undefined when probed with a random type. Dont try to handle redux/INIT... or other actions in redux/* namespace. ...处理某个 action 时返回undefinedWhen called with an action of type whatever, the slice reducer for key counter returned undefined. To ignore an action, you must explicitly return the previous state. ...这些信息量极大的报错信息正是combineReducers帮助初学者避免常见陷阱的设计意图的直接体现。实战示例从切片 reducer 到完整 store完整可运行的示例以下示例完整改编自 API 文档 combineReducers 的 Example 章节演示切片 reducer、组合与分发的完整链路// reducers/todos.js export default function todos(state [], action) { switch (action.type) { case ADD_TODO: return state.concat([action.text]) default: return state } } // reducers/counter.js export default function counter(state 0, action) { switch (action.type) { case INCREMENT: return state 1 case DECREMENT: return state - 1 default: return state } } // reducers/index.js import { combineReducers } from redux import todos from ./todos import counter from ./counter export default combineReducers({ todos, counter }) // App.js import { createStore } from redux import reducer from ./reducers/index const store createStore(reducer) console.log(store.getState()) // { // counter: 0, // todos: [] // } store.dispatch({ type: ADD_TODO, text: Use Redux }) console.log(store.getState()) // { // counter: 0, // todos: [ Use Redux ] // }可以看到分发ADD_TODO时todos切片响应并更新counter切片由于不识别该 action 而原样返回自己的状态——两者互不干扰且counter的引用被保留这正是前面讲的逐切片分发语义。仓库示例项目中的真实用法在本仓库的多个示例项目中combineReducers都是组装根 reducer 的标准方式。例如 examples/todos/src/reducers/index.js 和 examples/todomvc/src/reducers/index.js 的结构完全一致import { combineReducers } from redux import todos from ./todos import visibilityFilter from ./visibilityFilter export default combineReducers({ todos, visibilityFilter })同样的模式还出现在 examples/async/src/reducers/index.js、examples/shopping-cart/src/reducers/index.js、examples/real-world/src/reducers/index.js、examples/universal/common/reducers/index.js 与 examples/todos-with-undo/src/reducers/index.js 中。你可以直接阅读这些示例观察真实应用中状态形状如何被组织、切片之间如何协作。combineReducers 与 preloadedState 的初始化博弈在没有 combineReducers 的简单 reducer场景下preloadedState永远赢过state ...默认值因为传给 reducer 的state就是preloadedState它不是undefined默认参数语法不会生效。而使用combineReducers时行为更微妙详见 Initializing State在preloadedState中指明了对应切片的 reducer会收到那份状态未被指明的切片 reducer 会收到undefined正因如此才回退到各自state ...指定的默认值。function a(state lol, action) { return state } function b(state wat, action) { return state } const combined combineReducers({ a, b }) import { createStore } from redux // 不传 preloadedState两个切片都回退到默认值 const store createStore(combined) console.log(store.getState()) // { a: lol, b: wat } // 传部分 preloadedStatea 用指定值b 回退默认值 const store2 createStore(combined, { a: horse }) console.log(store2.getState()) // { a: horse, b: wat }总体结论preloadedState优先于 reducer 内部的默认值。这让 reducer 可以用默认参数声明对自己有意义的初始数据同时允许在从持久化存储或服务端水合hydratestore 时载入已有数据可整体载入也可部分载入。这里还有一个常被忽略的细节那些用preloadedState填充初始状态的 reducer仍然必须提供默认值因为所有 reducer 在初始化时都会被传入undefined。所以它们应被写成收到undefined就返回某个非undefined的值且无需在默认值里重复preloadedState的那部分内容。何时不该用 combineReducers越界场景与自定义方案combineReducers被刻意设计为只覆盖一个常见用例把纯 JavaScript 对象组成的状态树按切片委托给各个切片 reducer。它不处理以下场景详见 Beyond combineReducers状态树由 Immutable.js 的 Map 等非常规结构构成需要把状态树的其他部分作为额外参数传给某个切片 reducer需要对切片 reducer 的调用顺序做特殊排序它也不关心某个切片 reducer 内部如何完成工作。对这些场景答案很简单别用combineReducers——你需要自定义 reducer 逻辑。 一旦超出combineReducers的核心用例就进入了自定义 reducer 的领域。跨切片共享数据三种思路思路一父级 reducer 显式传参。当sliceReducerA需要sliceReducerB的数据时写一个自定义组合函数在特定 action 下把需要的数据作为额外参数传入function combinedReducer(state, action) { switch (action.type) { case A_TYPICAL_ACTION: { return { a: sliceReducerA(state.a, action), b: sliceReducerB(state.b, action) } } case SOME_SPECIAL_ACTION: { return { // 显式把 state.b 作为额外参数传入 a: sliceReducerA(state.a, action, state.b), b: sliceReducerB(state.b, action) } } default: return state } }思路二把共享数据放进 action。用 thunk 之类的方案在 dispatch 前把另一切片的数据塞进 action payload父 reducer 就无需做任何特殊处理function someSpecialActionCreator() { return (dispatch, getState) { const state getState() const dataFromB selectImportantDataFromB(state) dispatch({ type: SOME_SPECIAL_ACTION, payload: { dataFromB } }) } }思路三组合两个 reducer。用combineReducers处理简单场景另写一个crossSliceReducer处理特殊场景再由外层rootReducer依次调用const combinedReducer combineReducers({ a: sliceReducerA, b: sliceReducerB }) function crossSliceReducer(state, action) { switch (action.type) { case SOME_SPECIAL_ACTION: { return { a: handleSpecialCaseForA(state.a, action, state.b), b: sliceReducerB(state.b, action) } } default: return state } } function rootReducer(state, action) { const intermediateState combinedReducer(state, action) const finalState crossSliceReducer(intermediateState, action) return finalState }高阶组合给切片套上可复用逻辑Redux 的 reducer 说到底只是函数而combineReducers只是工具箱里的一件工具。函数可以包含 switch 之外的任意条件逻辑可以被组合、包裹、互相调用。例如想让某个切片支持撤销且只响应特定 action可以这样组合const undoableFilteredSliceA compose( undoReducer, filterReducer(ACTION_1, ACTION_2), sliceReducerA ) const rootReducer combineReducers({ a: undoableFilteredSliceA, b: normalSliceReducerB })combineReducers完全不知道也不关心管理a的 reducer 内部有什么特殊之处——你不需要为了支持撤销而修改combineReducers只需把需要的零件组装成一个新的组合函数即可。TypeScript 视角类型推断带来的状态形状保证在本仓库的 src/types/reducers.ts 中combineReducers的类型签名展现了强大的类型推导能力。它的泛型重载src/combineReducers.ts基于ReducersMapObject并通过以下工具类型精确还原状态形状StateFromReducersMapObjectM从 reducer 映射对象推导合并后的状态类型ActionFromReducersMapObjectM推导整个组合 reducer 能处理的 action 联合类型PreloadedStateShapeFromReducersMapObjectM推导可接受的preloadedState形状允许部分键缺失。也就是说在 TypeScript 项目中const rootReducer combineReducers({ posts: postsReducer, comments: commentsReducer }) // rootReducer 的 state 参数类型被精确推导为 // { posts: PostsState; comments: CommentsState }组合结果状态、action 类型与preloadedState三者都由切片 reducer 的声明自动推导类型错误会在编译期暴露而非等到运行时。这与状态键名由传入对象的键决定的运行时语义完全一致从类型层面再次印证了键名即状态形状这一核心规律。总结与最佳实践清单combineReducers是 Redux 中最常见的高阶 reducer其设计目标明确、行为可预期。综合本文所述使用时的最佳实践可以归纳为始终为每个切片 reducer 提供非undefined的默认状态推荐state 初始值语法即使你计划用preloadedState初始化——因为combineReducers在构造阶段会用undefined探测所有切片。对未识别的 action 原样返回state既满足规则约束也保住引用相等性带来的性能优化。状态键名应反映数据领域而不是变量名或 reducer 字样需要时在 import 阶段重命名或显式指定combineReducers对象的键。充分利用键名即状态形状的语义combineReducers可以在 reducer 树任意层级嵌套使用把大型状态树逐步拆分到粒度合适的切片。认识到它的边界跨切片共享数据、非常规状态容器、调用顺序控制等场景应当走向自定义 reducer 或第三方 reducer 工具本仓库文档 Beyond combineReducers 提供了完整思路而不是试图把combineReducers改造成万能方案。延伸阅读combineReducers API 参考参数、返回值与三条规则约束的官方定义Beyond combineReducerscombineReducers 之外的更高级 reducer 组织方式Initializing StatepreloadedState 与 reducer 默认值之间的完整博弈关系structuring-reducers 目录总览Reducer 结构化的系列文档入口createStore API根 reducer 与 preloadedState 的完整调用约定【免费下载链接】reduxA JS library for predictable global state management项目地址: https://gitcode.com/gh_mirrors/re/redux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考