RTK Query

相关源文件

• docs/components/_FundamentalsWarning.mdx
• docs/introduction/why-rtk-is-redux-today.md
• docs/style-guide/style-guide.md
• docs/tutorials/essentials/part-1-overview-concepts.md
• docs/tutorials/essentials/part-2-app-structure.md
• docs/tutorials/essentials/part-3-data-flow.md
• docs/tutorials/essentials/part-4-using-data.md
• docs/tutorials/essentials/part-5-async-logic.md
• docs/tutorials/essentials/part-6-performance-normalization.md
• docs/tutorials/essentials/part-7-rtk-query-basics.md
• docs/tutorials/essentials/part-8-rtk-query-advanced.md
• docs/tutorials/quick-start.md
• docs/tutorials/typescript.md
• docs/tutorials/videos.md
• docs/understanding/history-and-design/PriorArt.md
• docs/understanding/history-and-design/history-of-redux.md
• docs/usage/ServerRendering.md
• docs/usage/UsageWithTypescript.md
• docs/usage/WritingCustomMiddleware.md
• docs/usage/WritingTests.mdx
• docs/usage/deriving-data-selectors.md
• docs/usage/migrating-to-modern-redux.mdx
• docs/usage/nextjs.mdx
• docs/usage/side-effects-approaches.mdx
• examples/counter-ts/src/app/hooks.ts
• website/sidebars.js

RTK Query 是一个强大的数据获取和缓存解决方案，内置于 Redux Toolkit。它提供了一种简化的方法来处理 Redux 应用程序中的 API 请求，无需手动编写 reducer、action creator 和 thunk 来执行数据获取操作。本页介绍了 RTK Query 的核心概念、架构和使用模式。

有关使用 thunk 进行基本 Redux 数据获取的信息，请参阅 基本 Redux 数据流。有关使用 Redux Toolkit 的 createSlice 的信息，请参阅 createSlice 和 Reducers。

核心概念

RTK Query 围绕几个关键概念设计，这些概念协同工作以提供完整的数据获取解决方案

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md165-184 docs/tutorials/essentials/part-7-rtk-query-basics.md118-140

主要功能

功能	描述
自动 Hook 生成	为每个端点创建自定义的 React hook
缓存管理	处理响应数据的缓存并自动重新获取
请求生命周期管理	跟踪加载中、成功和错误状态
请求去重	自动避免对相同数据发出重复请求
基于标签的缓存失效	允许在数据更改时进行有针对性的缓存更新
轮询和重新获取	支持按设定间隔自动刷新数据
TypeScript 支持	内置类型定义，实现卓越的 TypeScript 集成
分页/无限滚动	处理分页数据的实用工具

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md89-99 docs/tutorials/essentials/part-7-rtk-query-basics.md124-136

设置 RTK Query

创建 API Slice

RTK Query 的核心是 createApi 函数，它定义了一组用于与服务器 API 交互的端点

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md156-184 docs/tutorials/essentials/part-7-rtk-query-basics.md235-273

基本设置示例

1. 定义 API slice

2. 将 API slice 添加到 Redux store

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md156-184 docs/tutorials/essentials/part-7-rtk-query-basics.md275-325

在组件中使用 RTK Query

RTK Query 会自动为每个端点生成 React hook。这些 hook 处理数据获取、缓存和订阅管理

查询 Hook

对于查询端点，RTK Query 会生成一个 hook，返回当前的请求状态

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md327-385 docs/tutorials/essentials/part-7-rtk-query-basics.md449-491

Mutation Hook

对于 mutation 端点，RTK Query 会生成一个 hook，返回一个触发函数和请求状态

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md731-775 docs/tutorials/essentials/part-7-rtk-query-basics.md812-844

RTK Query 中的数据流

下图说明了数据如何通过使用 RTK Query 的 Redux 应用程序流动

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md118-152 docs/tutorials/essentials/part-7-rtk-query-basics.md449-491

缓存管理

RTK Query 的缓存系统负责存储响应数据并跟踪 API 请求的生命周期。

缓存条目生命周期

1. 当组件调用查询 hook 时，它会创建一个到该缓存条目的订阅
2. 如果数据不在缓存中或已过期，RTK Query 会获取它
3. 当组件卸载时，其订阅将被移除
4. 如果缓存条目没有活动订阅，则计时器开始
5. 如果计时器过期，缓存条目将被移除
6. 如果在计时器过期前添加了新订阅，则计时器将被取消

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md144-156 docs/tutorials/essentials/part-8-rtk-query-advanced.md77-82

基于标签的失效

RTK Query 使用基于标签的系统进行缓存失效，允许对何时需要重新获取数据进行细粒度控制

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md158-222 docs/tutorials/essentials/part-8-rtk-query-advanced.md235-238

基于标签的失效示例

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md177-215

高级特性

操作响应数据

您可以使用 transformResponse 在 API 响应数据存储到缓存之前对其进行转换

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md387-390

与 TypeScript 结合使用

RTK Query 基于 TypeScript 构建，提供出色的类型安全

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md255-273

乐观更新

您可以实现乐观更新以提供更好的用户体验

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md505-525

在 React 之外使用 RTK Query

虽然 RTK Query 通常通过其生成的 hook 与 React 一起使用，但您可以将其与任何 UI 框架或不使用 UI 框架一起使用

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md286-298 docs/tutorials/essentials/part-8-rtk-query-advanced.md371-375

与传统 Redux 数据获取的比较

以下是 RTK Query 与传统 Redux 数据获取方法的比较

功能	传统 Redux 方法	RTK Query
设置	需要手动设置 store、action creator、reducer 和 selector	通过 createApi 和自动生成的 hook 进行简化
加载状态	需要手动管理 loading、error 等	通过 hook 自动跟踪和提供
缓存	需要手动实现	内置智能默认值
去重	需要自定义逻辑	自动请求去重
重新获取	需要手动实现	内置基于标签的失效
类型定义	额外的工作以正确进行类型定义	一流的 TypeScript 集成
代码大小	更多样板代码	代码显著减少

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md32-40 docs/tutorials/essentials/part-5-async-logic.md32-39

最佳实践

1. 有效使用缓存标签：设计您的标签系统以匹配您的数据关系
2. 考虑缓存生命周期：根据数据的波动性调整 keepUnusedDataFor 设置
3. 使用 transformResponse：在获取数据后立即格式化数据，而不是在组件中
4. 选择特定的缓存数据：使用 selectFromResult 仅提取您需要的数据
5. 优先使用 RTK Query 的缓存操作实用工具：使用内置实用工具而不是手动更新 Redux 状态
6. 实现错误处理：始终处理 mutation 可能出现的错误

Sources: docs/tutorials/essentials/part-8-rtk-query-advanced.md235-242 docs/tutorials/essentials/part-7-rtk-query-basics.md634-636

用例和限制

最佳用例

• REST API 交互
• CRUD 操作
• 具有复杂数据获取需求的应用程序
• 需要缓存、去重和自动重新获取的应用程序
• 希望减少样板代码的项目

局限性

• GraphQL 的设置更复杂（尽管支持）
• 对于非常简单的应用程序可能会增加不必要的开销
• 缓存管理增加了服务器渲染应用程序的复杂性

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md65-99 docs/tutorials/essentials/part-7-rtk-query-basics.md118-140

RTK Query 包大小

RTK Query 确实会增加您的应用程序大小

• 如果已在使用 Redux Toolkit：RTK Query 约为 9kb min+gzip + hook 约为 2kb
• 如果尚未在使用 Redux Toolkit
  • 不使用 React：约 17kb（RTK + 依赖项 + RTK Query）
  • 使用 React：约 19kb + React-Redux（对等依赖）

添加额外的端点定义通常对包大小的影响很小。

Sources: docs/tutorials/essentials/part-7-rtk-query-basics.md122-129