5分钟上手redux-little-router:Redux 路由快速入门完整指南
5分钟上手redux-little-router:Redux 路由快速入门完整指南
🚀 redux-little-router 是一个专为 Redux 应用设计的轻量级路由方案,核心理念是"让 URL 开口说话"(let the URL do the talking)。本文将带你 5分钟完成安装、配置和接入,轻松掌握 Redux 路由的状态管理、页面导航与 React 组件用法,适合刚接触 React + Redux 技术栈的新手阅读。
一、什么是 redux-little-router?
在 React 应用里,路由(决定"当前显示哪个页面")通常由 React Router 这类视图层库接管,URL 状态被"锁"在组件树里,Redux 的 store 想读取当前 URL 却十分困难。
redux-little-router 用三条基本原则解决这个问题:
| 原则 | 含义 |
|---|---|
| URL 是状态树的一员 | 当前路由状态存放在 state.router,任何 reducer、selector 都能直接读取 |
| URL 变化就是普通 action | 导航操作通过 dispatch action 完成,天然支持 redux-devtools 时间旅行调试 |
| 路由匹配简单可扩展 | 用 :param 占位符声明式定义路由,支持嵌套 |
它的核心不依赖任何视图库,同时提供灵活的 React 绑定组件(<Link>、<Fragment>),是 Redux 生态中把 URL 提升为"一等公民"的经典方案。
💡 项目状态说明:该项目自 2018 年 12 月起停止活跃维护(官方建议在 React Router 场景下考虑
connected-react-router),但作为理解"URL 状态进 Redux"的设计范例,它依然是学习 Redux 路由机制的绝佳教材。详见 README.md。
二、最快安装步骤:30秒完成配置
1. 安装依赖
在你的项目中执行:
npm install redux-little-router
如需源码研读,可克隆仓库(Node 版本需 >= 4):
git clone https://gitcode.com/gh_mirrors/re/redux-little-router
cd redux-little-router
yarn install
运行 yarn run demo 即可在 3000 端口启动官方演示应用,演示代码位于 demo/client/ 目录,其中的 demo/client/app.js 就是一份完整的最小接入示例。
2. 定义路由表
路由用"路由路径 → 任意数据"的哈希对象声明,支持嵌套:
const routes = {
'/messages': { title: 'Message' },
'/messages/:user': { title: 'Message History' },
'/': {
title: 'Home',
'/bio': {
'/:name': { title: 'Biography for:' }
}
}
};
匹配规则基于 url-pattern,:user、:name 就是参数占位符。每个路由值可以是任意可序列化数据(常用来存放页面标题等路由级数据)。
三、5分钟接入 Redux Store:核心三件套
redux-little-router 通过一个store enhancer(包装 history、监听 URL 变化)+ 一个middleware(拦截导航 action 并调用 history API)接入 Redux。三步搞定:
import { combineReducers, compose, createStore, applyMiddleware } from 'redux';
import { routerForBrowser, initializeCurrentLocation } from 'redux-little-router';
// ① 工厂方法生成 reducer / middleware / enhancer
const { reducer, middleware, enhancer } = routerForBrowser({ routes, basename: '/example' });
// ② 把 router 合并进全局 store
const store = createStore(
combineReducers({ router: reducer }),
initialState,
compose(enhancer, applyMiddleware(middleware))
);
// ③ 客户端初始化当前 URL,触发首次路由匹配
const initialLocation = store.getState().router;
if (initialLocation) {
store.dispatch(initializeCurrentLocation(initialLocation));
}
📌 步骤③是官方要求的客户端初始化动作,保证与
redux-thunk、redux-saga等副作用类 enhancer 兼容。
不同环境使用不同的工厂方法,源码中都有对应实现:
| 工厂方法 | 适用场景 | 源码位置 |
|---|---|---|
routerForBrowser |
纯浏览器 SPA | src/environment/browser-router.js |
routerForHash |
hash 路由(#/path 风格) |
src/environment/hash-router.js |
routerForExpress |
Node.js 服务端渲染(Express) | src/environment/express-router.js |
routerForHapi |
Node.js 服务端渲染(Hapi) | src/environment/hapi-router.js |
所有导出集中在 src/index.js,类型定义见 index.d.ts。
四、Redux 路由状态速览:读懂 state.router
每次 URL 变化,enhancer 都会 dispatch 一个 LOCATION_CHANGED action,reducer 把结果写入 state.router,结构如下:
state.router = {
pathname: '/messages/a-user', // 当前路径
route: '/messages/:user', // 命中的路由模板
params: { user: 'a-user' }, // 解析出的路径参数
query: { some: 'thing' }, // 解析后的查询参数
search: '?some=thing', // 原始查询字符串
result: { title: '...' }, // 路由表中你定义的数据
previous: { /* 上一个 location 的完整快照 */ }
};
这意味着:
- selector 直接取参:
state.router.params.user比在组件 props 里层层传递更直接; - 对比前后路由:
router.previous让你轻松做"进入页面时加载数据"的逻辑; - 路由级数据:
result字段承载你在路由表里配置的任意数据,适合管理页面标题。
reducer 的合并逻辑(query 持久化、basename 处理、previous 记录)可参考 src/reducer.js。
五、导航 API 清单:一行代码切换页面
库内置了一组公开的 action creator(定义于 src/actions.js),在任意能拿到 dispatch 的地方调用即可:
| API | 作用 | 类比 History API |
|---|---|---|
push(href) |
跳转并新增历史记录 | pushState |
replace(href) |
跳转但不新增历史记录 | replaceState |
go(n) / goBack() / goForward() |
前进 / 后退 n 步 | history.go |
block(fn) / unblock() |
离开页面时弹窗拦截确认 | history blocking |
replaceRoutes(routes) |
运行时动态替换整个路由表 | 用于代码分割 |
常用技巧:
- 传对象:
push({ pathname: '/messages', query: { filter: 'business' } }),query 对象会被序列化进 URL; - 保留查询参数:第二个参数传
{ persistQuery: true },跳转后沿用上一页面的 query; - 配合 thunk 做重定向:
dispatch(push('/login'))一行完成,无需任何视图层 API。
六、React 绑定: 与 组件
核心与 React 解耦,但库内置了两个"自带 connect()"的组件,让视图层同样省心(源码见 src/components/):
:可点击的导航链接
<Link href="/messages" activeProps={{ className: 'active' }}>
消息
</Link>
- 点击即 dispatch 导航 action,自动尊重右键/修饰键默认行为;
activeProps在链接命中当前路由时附加样式,轻松实现"高亮当前页";- 兄弟组件
<PersistentQueryLink>会在跳转时保留现有 query string。
:按条件渲染当前页面
<Fragment> 可理解为"轻量版 <Route>",能放在组件树的任何位置:
<Fragment forRoute="/messages/:team">
<TeamMessages />
</Fragment>
<Fragment withConditions={loc => loc.query.superuser}>
<SuperUserBadge />
</Fragment>
<Fragment forNoMatch /> {/* 404 页面:所有路由都未命中时渲染 */}
嵌套 <Fragment> 可以与嵌套路由表一一对应,非常适合做"页中页"的分栏布局。
七、进阶玩法:SSR、immutable 与代码分割
- 服务端渲染:用
routerForExpress/routerForHapi把请求传进工厂方法,客户端再用routerForBrowser恢复状态,完整流程见 ADVANCED.md(演示服务代码在 demo/server/); - immutable 支持:配合
redux-immutable使用时,从redux-little-router/es/immutable导入immutableRouterForBrowser等对应版本,源码位于 src/immutable/; - 代码分割:动态加载组件后用
replaceRoutes注册新路由,建议配合lodash.merge合并旧路由表,避免"一刀切"清空; - 运行时路由校验:src/util/validate-routes.js 会在配置错误时给出明确报错,路由匹配缓存逻辑见 src/util/match-cache.js。
八、常见问题 FAQ
Q:和 React Router 冲突吗?
不冲突,但官方建议:若你更看重 React Router 的组件 API 生态,可优先考虑 connected-react-router;若希望"URL 完全由 Redux 驱动",本库的设计更纯粹。
Q:最低环境要求是什么?
ES5 兼容环境即可(不支持 IE8),React 0.14 / 15 / 16、redux 3+ 均支持(见 package.json 的 peerDependencies)。
Q:项目版本迭代频繁是为什么? 项目遵循严格 semver,任何破坏性变更(无论多小)都会升主版本号,高版本号不代表方向性转变。
九、写在最后
回顾一下本文的 5 分钟路线:安装依赖 → 声明路由表 → routerForBrowser 生成三件套 → 合并进 store 并初始化 URL → 用 push 等 API 和 <Link>/<Fragment> 组件完成导航。掌握"URL 即状态"这一心智模型后,你会发现 Redux 时间旅行调试、路由级数据驱动、前后端同构等场景都变得顺理成章。
📂 想深入源码?推荐阅读顺序:src/index.js(全部导出)→ src/enhancer.js(URL 监听)→ src/middleware.js(导航拦截)→ src/reducer.js(状态合并)。祝上手愉快!