# https://github.com/reduxjs/redux-toolkit 项目说明书 生成时间：2026-06-17 18:44:05 UTC ## 目录 - [Redux Toolkit 概述与整体架构](#page-1) - [核心 API：Slices、Reducers、Async Thunk 与副作用](#page-2) - [RTK Query：数据获取、缓存与 React Hooks](#page-3) - [迁移、Codemods、TypeScript 与社区高频问题](#page-4) ## Redux Toolkit 概述与整体架构 ### 相关页面 相关主题：[核心 API：Slices、Reducers、Async Thunk 与副作用](#page-2), [RTK Query：数据获取、缓存与 React Hooks](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [packages/toolkit/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json) - [packages/toolkit/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/README.md) - [package.json](https://github.com/reduxjs/redux-toolkit/blob/main/package.json) - [packages/rtk-codemods/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/rtk-codemods/README.md) - [examples/type-portability/nodenext-esm/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/type-portability/nodenext-esm/package.json) - [examples/query/react/advanced/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/advanced/package.json) - [packages/toolkit/scripts/issue-triage/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md) - [examples/publish-ci/cra5/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra5/README.md)
# Redux Toolkit 概述与整体架构 ## 一、项目定位与设计目标 Redux Toolkit（包名 `@reduxjs/toolkit`）是 Redux 官方维护的"开箱即用"工具集，旨在以**一套约定优于配置**的 API 降低 Redux 的使用门槛。其设计动机在仓库根目录的 `README.md` 中明确指出：解决"配置 Redux store 过于复杂"、"必须额外安装大量包"、"样板代码过多"这三大痛点([packages/toolkit/README.md:8-22](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/README.md))。 当前发布版本为 **v2.12.0**，作者 Mark Erikson，遵循 MIT 协议([packages/toolkit/package.json:1-10](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json))。该包刻意保持"有限范围"——它不解决"可复用的 Redux 模块封装"、"目录/文件结构"或"实体关系管理"等更上层的问题([packages/toolkit/README.md:18-22](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/README.md))。`react` 与 `react-redux` 被声明为**可选 peerDependency**，意味着核心包既可在纯 Node 环境、也可在 React Native、浏览器环境中使用([packages/toolkit/package.json:30-39](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json))。 社区长期关注的演进方向——例如 RTK 2.0 路线图(issue #958)以及 RTK Query 对 React Suspense 的支持(issue #1574)——都已纳入或正在纳入后续里程碑；v2.12.0 也引入了 TanStack Intent 的 skills 文件、修复了无限查询的状态标志与批处理问题，体现了"持续吸收社区反馈"的产品节奏。 ## 二、Monorepo 工作区与分发形态 整个仓库采用 **Yarn Workspaces Monorepo** 结构，根 `package.json` 通过 `workspaces` 字段声明子包目录([package.json:13-21](https://github.com/reduxjs/redux-toolkit/blob/main/package.json))： ```mermaid graph TD Root["rtk-monorepo (根)"] --> Pkg["packages/*
(toolkit, rtk-codemods, ...)"] Root --> Docs["docs / website"] Root --> ExQ["examples/query/react/*"] Root --> ExAL["examples/action-listener/*"] Root --> ExTP["examples/type-portability/*"] Pkg --> RTK["@reduxjs/toolkit
(v2.12.0)"] Pkg --> CMs["@reduxjs/rtk-codemods"] RTK -->|ESM/CJS 多产物| Dist["dist/
redux-toolkit.modern.mjs
redux-toolkit.legacy-esm.js
redux-toolkit.browser.mjs"] RTK -->|类型| Types["dist/index.d.ts
dist/index.d.mts"] ``` `@reduxjs/toolkit` 的 `package.json` 暴露了**多入口、多格式**的产物：`main` 指向 CJS，`module`/`module-sync` 指向现代 ESM，`react-native` 单独指向 legacy ESM，`unpkg` 指向浏览器 ESM，从而覆盖 Web、Node、React Native、CDN 等多种消费场景([packages/toolkit/package.json:14-29](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json))。`sideEffects: false` 的声明则让打包器（如 Vite、Webpack）能更激进地进行 tree-shaking。 `examples/` 目录提供了多种运行示例：用 `react-scripts` 5.x 驱动的 `examples/query/react/advanced` 与 `examples/query/react/basic` 验证 RTK Query 在 Create React App 中的集成([examples/query/react/advanced/package.json:6-20](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/advanced/package.json))；`examples/type-portability/nodenext-esm` 则使用 Vite + `moduleResolution: NodeNext` 验证 ESM 类型可移植性([examples/type-portability/nodenext-esm/package.json:6-22](https://github.com/reduxjs/redux-toolkit/blob/main/examples/type-portability/nodenext-esm/package.json))。 ## 三、核心 API 体系 仓库 `README.md` 列出了 Redux Toolkit 提供的核心 API([packages/toolkit/README.md:26-35](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/README.md))，可概括为以下几类： | 类别 | 代表 API | 解决的问题 | |------|----------|-----------| | Store 装配 | `configureStore()` | 自动合并 slice reducer、默认注入 `redux-thunk`、启用 DevTools Extension | | Reducer 简化 | `createReducer()` | 以"查表"形式定义 reducer，配合 Immer 支持可变写法 | | Slice 聚合 | `createSlice()` | 一次性生成 action creators + reducer，降低样板代码 | | 异步逻辑 | `createAsyncThunk()` | 自动派发 `pending` / `fulfilled` / `rejected` 三种状态 | | 副作用 | `createListenerMiddleware()` | 在 store 之外以订阅风格处理副作用 | | 实体建模 | `createEntityAdapter()` | 提供 CRUD 与选择器原语 | | 数据获取 | **RTK Query**（独立入口） | 内置缓存、订阅、轮询的数据获取层 | 围绕 `createSlice` 的 `extraReducers` 一直是社区高频问题来源：issue #478 反映出"在 `extraReducers` 中使用计算属性名"的 TypeScript 报错；而 issue #429 中提到的 `combineActions` 风格则体现了"同一 reducer 匹配多个 action"的需求。这些反馈塑造了 RTK 1.x 引入 builder API、2.x 进一步收紧类型推断的演进路径。RTK Query 方面，issue #1676 中"generated hooks 类型推断要求 1-2 个参数"的问题，则促使 v2.12.0 **导出可复用的 hook options 类型** 以便用户显式标注。 ## 四、配套工具与生态 除主包外，仓库还维护一组辅助工程： - **RTK Codemods**：`@reduxjs/rtk-codemods` 提供 `createReducerBuilder`、`createSliceBuilder`、`createSliceReducerBuilder` 等代码转换，帮助用户从老式 `createReducer` / `createSlice` 写法迁移到 builder API([packages/rtk-codemods/README.md:1-39](https://github.com/reduxjs/redux-toolkit/blob/main/packages/rtk-codemods/README.md))。 - **GitHub Issues Triage 工具**：`packages/toolkit/scripts/issue-triage/` 提供基于 TypeScript 的 issue 自动分类脚本，匹配关键词/标签生成统计报告，并支持 `--use-cache` 复用本地缓存以避免 GitHub API 限流([packages/toolkit/scripts/issue-triage/README.md:1-42](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md))。 - **发布与 CI 样例**：`examples/publish-ci/cra4` 与 `cra5` 演示如何在 CRA 4 / 5 项目中接入 RTK Query 并跑通 Playwright 端到端测试([examples/publish-ci/cra5/README.md:1-30](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra5/README.md))。 ## See Also - RTK Query 数据获取与缓存 - `createSlice` 与 `extraReducers` 深入指南 - 从 Redux 1.x / 2.x 旧版迁移到 builder API - `createListenerMiddleware` 副作用模式 - `createEntityAdapter` 规范化数据建模 --- ## 核心 API：Slices、Reducers、Async Thunk 与副作用 ### 相关页面 相关主题：[Redux Toolkit 概述与整体架构](#page-1), [RTK Query：数据获取、缓存与 React Hooks](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [packages/toolkit/src/createSlice.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/createSlice.ts) - [packages/toolkit/src/createReducer.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/createReducer.ts) - [packages/toolkit/src/createAsyncThunk.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/createAsyncThunk.ts) - [packages/toolkit/src/configureStore.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/configureStore.ts) - [packages/toolkit/src/listenerMiddleware/index.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/listenerMiddleware/index.ts) - [packages/toolkit/src/entities/create_adapter.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/entities/create_adapter.ts) - [packages/toolkit/src/query/utils/getOrInsert.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/query/utils/getOrInsert.ts) - [packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts) - [packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts)
# 核心 API：Slices、Reducers、Async Thunk 与副作用 ## 概述 Redux Toolkit（RTK）的核心 API 围绕四个支柱构建：`createSlice`、`createReducer`、`createAsyncThunk`，以及用于副作用处理的中间件（Middleware）体系。仓库内部的 issue 分类器明确将 `createSlice`、`configureStore`、`createAsyncThunk` 列入 "Core Redux Toolkit" 类目，并把它们视为该类目下的高权重关键词 [资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts)]。这些 API 的设计目标是减少传统 Redux 模板代码、内置 Immer 提供"看似可变"的不可变更新、默认集成 Redux DevTools 与 `redux-thunk`，并通过 `createListenerMiddleware` 提供可替代 `redux-saga` 的轻量副作用机制。 ## Slice 与 Reducer 模式 `createSlice` 接受一个 slice 名称、初始 state 与一组 reducer 函数，自动生成对应的 action creator 与 action type 字符串。reducer 内部默认由 Immer 代理，使开发者可以直接对 draft state 进行赋值而无需手动展开/合并。 ```ts const counterSlice = createSlice({ name: 'counter', initialState: { value: 0 }, reducers: { increment: (state) => { state.value += 1 }, incrementBy: (state, action: PayloadAction) => { state.value += action.payload }, }, }) ``` 当 slice 需要响应自身之外派发的 action（例如 `createAsyncThunk` 的 `pending` / `fulfilled` / `rejected`）时，使用 `extraReducers` 字段。社区 issue #478 报告了一个常见痛点：在 `extraReducers` 内通过 TypeScript 计算属性名引用 async thunk 的 action creator 时，会触发错误 *"A computed property name must be of type 'string', 'number', 'symbol', or 'any'"* [社区讨论：#478]。该问题长期与 builder callback 的类型推断相关，是用户迁移到 RTK 时的高频踩点。 ## Async Thunk 与副作用 `createAsyncThunk` 封装异步逻辑，并自动派发三个生命周期 action。其状态机可表示为： ```mermaid stateDiagram-v2 [*] --> pending: dispatch(thunk()) pending --> fulfilled: payload 解析成功 pending --> rejected: 抛错 / rejectWithValue fulfilled --> [*] rejected --> [*] ``` 仓库的 categorizer 工具在短语匹配中显式收录了 `createasyncthunk`、`.pending`、`.fulfilled` 等模式，并把它们归入 `core` 子分类的 `createAsyncThunk` 条目 [资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts)]，反映了这套生命周期在仓库维护者认知中的基础地位。 对于希望"以同一个 reducer 响应多个不同 action 类型"的场景，社区 issue #429 提议引入类似 `redux-actions` 中 `combineActions` 的辅助函数，从而避免在 `extraReducers` 中重复书写 [社区讨论：#429]。截至 v2.12.0，该提议并未在 RTK 核心中以一等 API 形式落地。 ## 中间件、Store 与工具方法 `configureStore` 自动装配 `redux-thunk`、序列化检查、不可变检查与 Redux DevTools 增强，是 RTK 的"开箱即用"入口。对于非 thunk 风格的副作用，issue triage 的分类器将 `createlistenermiddleware` 单独列为核心子分类，表明它在官方体系中享有与 `createAsyncThunk` 同等的关注度 [资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts)]。 `packages/toolkit/src/query/utils/getOrInsert.ts` 顶部注释指出，文件中故意复制了 `src/utils` 的同名工具，目的是避免将大块 RTK core 打入 RTKQ bundle [资料来源：[packages/toolkit/src/query/utils/getOrInsert.ts:1-3](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/src/query/utils/getOrInsert.ts#L1-L3)]。这种"打包边界隔离"的做法也说明 RTK 在内部严格区分 core 与 RTKQ 两个包边界：core 负责 Slice / Thunk / Store，RTKQ 在其上提供数据获取层。 ## 已知限制与社区反馈 | Issue | 主题 | 影响范围 | | --- | --- | --- | | #478 | `extraReducers` 内使用计算属性名的 TS 错误 | core | | #429 | 缺少 `combineActions` 风格的辅助函数 | core | | #1574 | RTK Query 对 React Suspense 的支持请求 | RTKQ | | #1676 | 生成 hook 在 0 参调用时的 TS 推断缺陷 | RTKQ | | #958 | RTK 2.0 路线图（已于 2023-12-05 发布 v2.0.0） | 仓库级 | 其中 #1574 与 #1676 严格意义上属于 RTK Query，但用户常把它们与 core 的 `createAsyncThunk` 行为混淆 [社区讨论：#1574] [社区讨论：#1676]。 ## 参见 - [RTK Query 数据获取与缓存]() - [Entities 适配器与规范化状态]() - [Listener Middleware 副作用模型]() - [从 Redux 迁移到 Redux Toolkit]() --- ## RTK Query：数据获取、缓存与 React Hooks ### 相关页面 相关主题：[Redux Toolkit 概述与整体架构](#page-1), [核心 API：Slices、Reducers、Async Thunk 与副作用](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [packages/toolkit/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json) - [packages/toolkit/scripts/issue-triage/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md) - [packages/toolkit/scripts/issue-triage/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/package.json) - [packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts) - [examples/query/react/basic/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/basic/package.json) - [examples/query/react/advanced/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/advanced/package.json) - [examples/query/react/authentication/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/authentication/package.json) - [examples/query/react/authentication-with-extrareducers/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/authentication-with-extrareducers/package.json) - [examples/query/react/optimistic-update/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/optimistic-update/package.json) - [examples/query/react/pagination/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/pagination/package.json) - [examples/query/react/prefetching/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/prefetching/package.json) - [examples/query/react/prefetching-automatic/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/prefetching-automatic/package.json) - [examples/query/react/prefetching-automatic-waterfall/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/prefetching-automatic-waterfall/package.json) - [examples/query/react/mutations/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/mutations/package.json) - [examples/publish-ci/cra4/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra4/README.md) - [examples/publish-ci/cra5/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra5/README.md)
# RTK Query：数据获取、缓存与 React Hooks ## 一、模块定位与设计目的 RTK Query 是 Redux Toolkit 内置的数据获取与缓存层，旨在为 Redux 应用提供"开箱即用"的异步数据管理能力，避免重复手写 reducer、middleware 和缓存逻辑。从仓库的 `package.json` 导出条件可以看到，RTK Query 以独立的子路径进行分发： - `@reduxjs/toolkit/query` —— 框架无关的核心 API - `@reduxjs/toolkit/query/react` —— 绑定 React 的 Hooks 与组件接口 资料来源：[packages/toolkit/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json) 这种分层导出结构意味着用户可以仅引入核心能力（如在非 React 环境使用 `initiate` thunk），也可以按需加载 React 绑定。从 `examples/query/react/` 目录下的多个示例工程可以观察到该模块涵盖了以下典型场景：基础 CRUD、认证、变更（mutations）、乐观更新、分页、预取与自动预取水合。资料来源：[examples/query/react/basic/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/basic/package.json)、[examples/query/react/optimistic-update/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/optimistic-update/package.json)、[examples/query/react/pagination/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/pagination/package.json)、[examples/query/react/prefetching-automatic-waterfall/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/prefetching-automatic-waterfall/package.json) ## 二、核心架构与运行机制 基于仓库内示例与导出约定，RTK Query 在运行时可拆解为三层： ```mermaid graph TD A[UI 组件/React Hooks] --> B[createApi 生成的 apiSlice] B --> C[Endpoint 集合
query / mutation / infiniteQuery] C --> D[Thunk Action
initiate / updateInitiated] D --> E[fetchBaseQuery / 自定义 baseQuery] E --> F[(外部 HTTP 接口)] D --> G[(Redux Store
内建缓存切片)] G --> A ``` 各层职责说明： 1. **createApi 入口**：通过 `createApi` 声明 baseQuery、reducerPath、tagTypes、endpoints，并返回包含 reducer、middleware、Hooks 的对象。该层是整个缓存体系的"装配工厂"。 2. **Endpoint 定义**：使用 `builder.query()` 与 `builder.mutation()` 声明端点，可在 `examples/query/react/advanced/package.json` 等示例中看到对应依赖。资料来源：[examples/query/react/advanced/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/advanced/package.json) 3. **Thunk 与缓存切片**：`initiate` action 触发请求生命周期，状态写入由 RTK Query 内部切片管理，订阅引用计数决定缓存项的活跃程度。 4. **baseQuery**：`fetchBaseQuery` 是默认实现，可在 `prepareHeaders` 中注入认证 Token，这正是 `authentication-with-extrareducers` 示例所演示的能力。资料来源：[examples/query/react/authentication-with-extrareducers/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/authentication-with-extrareducers/package.json) ## 三、React 集成与常用 Hooks React 绑定子包导出的 Hooks 主要包括： | Hook 类别 | 典型用途 | 示例工程 | | --- | --- | --- | | `useQuery` / `useLazyQuery` | 同步或按需触发查询、订阅缓存 | basic、pagination | | `useMutation` | 触发变更并接收 `{ data, error, isLoading }` | mutations | | `useInfiniteQuery` | 无限滚动与分页 | pagination | | `usePrefetch` | 路由切换前的预取 | prefetching、prefetching-automatic | | `selectFromResult` | 在 Hook 中裁剪订阅数据以减少重渲染 | （公共 API，详见 `advanced` 示例） | 资料来源：[examples/query/react/basic/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/basic/package.json)、[examples/query/react/mutations/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/mutations/package.json)、[examples/query/react/prefetching/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/prefetching/package.json) 通过 `selectFromResult`，组件可以仅订阅自己关心的字段，从而避免大对象比较造成的无效重渲染。 ## 四、缓存、失效与发布版本要点 ### 4.1 缓存标签（Tags）与失效 `createApi` 的 `tagTypes` 与端点中 `providesTags` / `invalidatesTags` 共同组成"发布-订阅式"缓存失效机制。当 mutation 命中某个 tag，所有提供该 tag 的 query 会被自动重新获取或标记为失效。 ### 4.2 常见问题与社区关注点 仓库的 issue triage 工具对社区反馈进行了分类，其中与 RTK Query 直接相关的高频话题包括： - **Suspense 集成**（对应 #1574）：用户希望直接用 React Suspense 渲染 loading 状态；目前 RTK Query 主要通过 `isLoading` / `isFetching` 标志手动控制。资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts) - **生成 Hooks 的 TypeScript 入参**（对应 #1676）：在使用 `useQuery` 等 Hook 时，TypeScript 要求显式传入 `arg`；典型解法是确认端点定义中 `query: (arg: SomeType) => ...` 的参数化形式。 - **`extraReducers` 与 `createAsyncThunk` 联合使用**（对应 #478）：建议在 slice 中通过 builder 匹配 thunk 的 `pending/fulfilled/rejected` 三态动作。 社区问题分类的具体规则可参考 issue triage 配置中关于 "rtk-query" 的关键词与正则模式。资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts)、[packages/toolkit/scripts/issue-triage/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md) ### 4.3 发布与工具链 `triage` 工具使用 Bun + TypeScript 编写，支持通过 `--use-cache` 复用本地缓存以避免 GitHub API 限流，适用于本地迭代分类规则。资料来源：[packages/toolkit/scripts/issue-triage/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md)、[packages/toolkit/scripts/issue-triage/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/package.json) 仓库同时在 `examples/publish-ci/cra4` 与 `examples/publish-ci/cra5` 中验证了 RTK 2.0 在不同 Create React App 版本下的 ESM/CJS 兼容性。资料来源：[examples/publish-ci/cra4/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra4/README.md)、[examples/publish-ci/cra5/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/examples/publish-ci/cra5/README.md) ## 五、典型使用流程 1. 在 store 配置中注入 apiSlice 的 reducer 与 middleware（`api.reducerPath` 与 `api.middleware`）。 2. 使用 `createApi` 定义 baseQuery、tagTypes、endpoints。 3. 在 React 组件中通过 `useGetXQuery`、`useXMutation` 等生成的 Hooks 访问数据。 4. 通过 `tagTypes` 配合 `providesTags` / `invalidatesTags` 维护缓存一致性。 5. 在测试环境使用 MSW 拦截请求（参见 `examples/query/react/*` 中的 `msw` 配置）。 ## See Also - RTK Query 官方文档与 v2.x 更新说明（仓库根 `docs/` 目录及发布说明） - [examples/query/react/optimistic-update](https://github.com/reduxjs/redux-toolkit/blob/main/examples/query/react/optimistic-update) —— 乐观更新模式参考 - [packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts) —— issue 分类配置，可定位 RTK Query 相关的历史讨论模式 --- ## 迁移、Codemods、TypeScript 与社区高频问题 ### 相关页面 相关主题：[核心 API：Slices、Reducers、Async Thunk 与副作用](#page-2), [RTK Query：数据获取、缓存与 React Hooks](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [packages/toolkit/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/package.json) - [packages/rtk-query-codegen-openapi/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/packages/rtk-query-codegen-openapi/package.json) - [packages/rtk-query-codegen-openapi/src/index.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/rtk-query-codegen-openapi/src/index.ts) - [packages/rtk-query-codegen-openapi/src/generators/react-hooks.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/rtk-query-codegen-openapi/src/generators/react-hooks.ts) - [packages/toolkit/scripts/issue-triage/README.md](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/README.md) - [packages/toolkit/scripts/issue-triage/src/categorize/config.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/config.ts) - [packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorizer.ts) - [packages/toolkit/scripts/issue-triage/src/categorize/types.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/categorize/types.ts) - [packages/toolkit/scripts/issue-triage/src/similarity/types.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/similarity/types.ts) - [packages/toolkit/scripts/issue-triage/src/reports/utils.ts](https://github.com/reduxjs/redux-toolkit/blob/main/packages/toolkit/scripts/issue-triage/src/reports/utils.md) - [website/package.json](https://github.com/reduxjs/redux-toolkit/blob/main/website/package.json)
# 迁移、Codemods、TypeScript 与社区高频问题 本页面面向需要把项目从经典 Redux / RTK 1.x 升级到当前主线版本、接入 OpenAPI 代码生成、或排查常见 TypeScript 错误的开发者。围绕社区讨论度最高的几个主题（#1574、#478、#1676、#429、#958），结合仓库内嵌的维护工具进行说明。 ## RTK 2.x 版本与升级路径 当前主线 feature 发布为 RTK 2.12.0，配套的 OpenAPI 代码生成包 `@rtk-query/codegen-openapi` 已迭代到 2.2.0。`packages/toolkit/package.json` 固定的核心依赖包括 `immer ^11.0.0`、`redux ^5.0.1`、`redux-thunk ^3.1.0`、`reselect ^5.1.0`，并新增了 `@standard-schema/spec ^1.0.0` 与 `@standard-schema/utils ^0.3.0` 以提供统一的运行时校验接口；React 与 `react-redux` 仅作为可选 peer 依赖声明（`peerDependenciesMeta`）。资料来源：[packages/toolkit/package.json]() 社区 issue #958 "Future planning: RTK 2.0?" 长期跟踪了从 v1 到 v2 的破坏性变更讨论。配套的 codemod 工具（`packages/rtk-codemods/transforms/createReducerBuilder/` 与 `createSliceBuilder/`）用于把旧式 `createReducer` / `createSlice` 调用自动改写为 v2 推荐写法，文档位于 `docs/api/codemods.mdx`。升级时应优先运行 codemod，再手动检查剩余差异。 ## TypeScript 集成与典型问题 RTK 2.12.0 强化了类型推断能力，并随包附带 `skills/` 目录供 AI 代理使用。文档站 `website/package.json` 将 TypeScript 固定为 `^5.9.3`，渲染层使用 Docusaurus 3.9+。资料来源：[website/package.json]() 社区高频 TS 问题主要集中于两类： - **`extraReducers` 计算属性名错误**（issue #478，6 条评论）：当 `createAsyncThunk` 派生的 action 与 `builder.addCase` 配合时，TS 要求计算属性名必须是 `string | number | symbol`，否则编译失败。常见解法是改用 `addMatcher`，或为 action 类型显式标注 `as const`。 - **生成式 Hooks 缺少参数**（issue #1676，28 条评论）：调用 `useGetXxxQuery()` 时 TS 报 `Expected 1-2 arguments, but got 0`，根因是端点定义在泛型中未声明 `arg`。`packages/rtk-query-codegen-openapi/src/generators/react-hooks.ts` 中的 `getReactHookName` 会在每个 `operationDefinition` 上展开参数签名——若 endpoint 需要 `arg`，对应 `useQuery` 必须显式承载该参数。资料来源：[packages/rtk-query-codegen-openapi/src/generators/react-hooks.ts]() ## OpenAPI Codegen 与代码生成流程 `@rtk-query/codegen-openapi` 提供 `generateEndpoints` 入口（见 `packages/rtk-query-codegen-openapi/src/index.ts`），支持传入 `schemaFile`（本地路径或 URL）、`outputFile`、`prettierConfigFile` 等选项。生成的代码通过 `oazapfts` 解析 OpenAPI 文档，再由 React Hooks 生成器输出 `useQuery` / `useMutation` 绑定，最终经 `prettify` 写入磁盘。资料来源：[packages/rtk-query-codegen-openapi/src/index.ts]() ```mermaid flowchart LR A[OpenAPI Schema] --> B[generateApi] B --> C[oazapfts 解析] C --> D[React Hooks 生成器] D --> E[useQuery/useMutation] B --> F[prettify] F --> G[outputFile 写入] G --> H[业务侧 import] ``` 典型用法： ```ts import { generateEndpoints } from '@rtk-query/codegen-openapi'; await generateEndpoints({ schemaFile: './openapi.yaml', apiFile: './src/store/emptyApi.ts', outputFile: './src/store/api.ts', }); ``` ## 社区高频问题与维护工具 为系统性管理 issue，仓库内嵌了 `packages/toolkit/scripts/issue-triage/` 工具。`scripts/issue-triage/README.md` 描述其能力：拉取 GitHub issue、按标签/标题/正文分类、生成 Markdown 报告，并支持 `--use-cache` 离线模式。资料来源：[packages/toolkit/scripts/issue-triage/README.md]() 分类器（`scripts/issue-triage/src/categorize/categorizer.ts`）采用多级策略： - **Tier 1**：基于 GitHub 标签（置信度最高，约 95%）。 - **Tier 2**：关键词 + 正则匹配（`scripts/issue-triage/src/categorize/config.ts` 定义了 `createslice`、`createasyncthunk`、`middleware`、`devtools`、`future-planning` 等分类，权重 `weight` 越高越优先）。 - **Tier 3**：内容启发式（`bug` / `feature` / `question` / `docs` 推断）。资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/categorizer.ts]() 每条 issue 会被赋予 `urgency`、`complexity`、`engagement` 三维评分（见 `scripts/issue-triage/src/categorize/types.ts` 的 `Scores` 接口），并打上 `isUrgent`、`isEasyFix`、`needsTriage`、`hasBreakingChange` 等 flag。`scripts/issue-triage/src/similarity/types.ts` 还定义了一组相似度信号（标题 Jaccard、关键词重合、类别匹配、错误模式匹配、时间邻近度），用于发现重复 issue 并形成 `WorkCluster`。资料来源：[packages/toolkit/scripts/issue-triage/src/categorize/types.ts]()、[packages/toolkit/scripts/issue-triage/src/similarity/types.ts]() 社区高频主题在分类器中的命中情况： - **#1574 RTK Query Suspense 支持**：命中 `rtk-query` 分类、`feature` 类型。 - **#478 extraReducers 类型错误**：命中 `createSlice` 子分类、`bug` 类型。 - **#1676 生成 Hooks TS 错误**：命中 `rtk-query` 分类、`bug` 类型。 - **#429 `.addCase` 多 action 合并**：命中 `createSlice` 子分类、`feature` 类型。 - **#958 RTK 2.0 路线图**：命中 `future-planning` 分类。 报告生成侧（`scripts/issue-triage/src/reports/utils.ts`）提供 `formatIssueLink` / `formatRelativeDate` / `formatScoreBar` 等工具函数，把分类结果渲染为可视化的 Markdown 报告。 ## See Also - [Redux Toolkit 官方文档](https://redux-toolkit.js.org/) - [迁移到现代 Redux](https://redux-toolkit.js.org/usage/migrating-to-modern-redux) - [RTK 2.0 迁移指南](https://redux-toolkit.js.org/usage/migrating-rtk-2) - [TypeScript 使用指南](https://redux-toolkit.js.org/usage/usage-with-typescript) - [Codemods 文档](https://redux-toolkit.js.org/api/codemods) --- --- ## Doramagic 踩坑日志 项目：reduxjs/redux-toolkit 摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：build(toolkit): migrate build setup to `tsdown`。 ## 1. 安装坑 · 来源证据：build(toolkit): migrate build setup to `tsdown` - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build(toolkit): migrate build setup to `tsdown` - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5191 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 2. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `redux-toolkit` 与安装入口 `@reduxjs/toolkit` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`npm install @reduxjs/toolkit` - 证据：identity.distribution | https://www.npmjs.com/package/@reduxjs/toolkit | repo=redux-toolkit; install=@reduxjs/toolkit ## 3. 安装坑 · 来源证据：build(codegen): migrate build setup to `tsdown` - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build(codegen): migrate build setup to `tsdown` - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5196 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安装坑 · 来源证据：ci: publish preview packages via `pkg.pr.new` - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ci: publish preview packages via `pkg.pr.new` - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5313 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 来源证据：Best practice for constantly-drifting time-range params (e.g., "last N hours") - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Best practice for constantly-drifting time-range params (e.g., "last N hours") - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5316 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://www.npmjs.com/package/@reduxjs/toolkit | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 来源证据：Discussion: Migration strategy for oazapfts v6 → v7 in `@rtk-query/codegen-openapi` - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Discussion: Migration strategy for oazapfts v6 → v7 in `@rtk-query/codegen-openapi` - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5225 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 维护坑 · 来源证据：chore: update TypeScript to v6.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：chore: update TypeScript to v6.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/reduxjs/redux-toolkit/issues/5292 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@reduxjs/toolkit | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://www.npmjs.com/package/@reduxjs/toolkit | no_demo; severity=medium ## 11. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://www.npmjs.com/package/@reduxjs/toolkit | no_demo; severity=medium ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@reduxjs/toolkit | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@reduxjs/toolkit | release_recency=unknown