Redux Toolkit中RTK Query 2.0迁移：如何正确类型化onQueryStarted生命周期函数

背景介绍

在Redux Toolkit的RTK Query 2.0版本中，开发者经常需要处理缓存更新的场景。一个常见的模式是通过onQueryStarted生命周期函数手动更新缓存。在2.0版本之前，开发者可以使用MutationLifecycleApi和QueryLifecycleApi类型来类型化这些函数，但在2.0版本中这一方式发生了变化。

问题分析

在RTK Query 2.0中，开发者面临的主要挑战是如何正确类型化可复用的onQueryStarted函数。这些函数通常用于多个端点，需要处理查询和变更两种场景。

典型的用例包括：

• 在数据变更后自动更新相关查询的缓存
• 处理乐观更新
• 执行副作用操作

解决方案演进

旧版解决方案

在2.0版本之前，开发者可以使用联合类型来处理查询和变更两种场景：

import {
  MutationLifecycleApi,
  QueryLifecycleApi,
} from "@reduxjs/toolkit/dist/query/endpointDefinitions";

const updateUserOnComplete = async (
  arg: unknown,
  {
    dispatch,
    queryFulfilled,
  }:
    | MutationLifecycleApi<unknown, BaseQueryFn, User>
    | QueryLifecycleApi<unknown, BaseQueryFn, User>
) => {
  // 实现逻辑
};

新版解决方案

在Redux Toolkit 2.4.0版本中，官方引入了新的类型工具来更好地支持这一场景：

const onGetPostStarted: TypedQueryOnQueryStarted<Post, Id, typeof baseQuery, 'postApi'> = 
  (arg, { dispatch, queryFulfilled }) => {
    // 实现逻辑
  };

const onUpdatePostStarted: TypedMutationOnQueryStarted<Post, PostUpdate, typeof baseQuery, 'postApi'> = 
  (arg, { dispatch, queryFulfilled }) => {
    // 实现逻辑
  };

最佳实践

1. 类型分离：对于查询和变更操作，分别使用TypedQueryOnQueryStarted和TypedMutationOnQueryStarted类型。

2. 明确泛型参数：

   • 第一个泛型参数：API返回的数据类型
   • 第二个泛型参数：端点参数类型
   • 第三个泛型参数：基础查询函数类型
   • 第四个泛型参数：API的reducerPath

3. 复用逻辑：将通用逻辑提取为独立函数，通过适当的类型参数使其可复用。

示例实现

// 定义基础查询
const baseQuery = fetchBaseQuery({ baseUrl: '/api' });

// 类型化查询的onQueryStarted
const onGetPostStarted: TypedQueryOnQueryStarted<Post, Id, typeof baseQuery, 'postApi'> = 
  (arg, { dispatch, queryFulfilled }) => {
    // 实现获取文章后的逻辑
  };

// 类型化变更的onQueryStarted
const onUpdatePostStarted: TypedMutationOnQueryStarted<Post, PostUpdate, typeof baseQuery, 'postApi'> = 
  (arg, { dispatch, queryFulfilled }) => {
    // 实现更新文章后的逻辑
  };

// 创建API
const postApi = createApi({
  reducerPath: 'postApi',
  baseQuery: baseQuery,
  endpoints: (build) => ({
    getPost: build.query<Post, Id>({
      query: () => '/posts',
      onQueryStarted: onGetPostStarted
    }),
    updatePost: build.mutation<Post, PostUpdate>({
      query: ({ id, ...patch }) => ({
        url: `/posts/${id}`, 
        body: patch, 
        method: "POST" 
      }),
      onQueryStarted: onUpdatePostStarted
    })
  })
});

总结

RTK Query 2.0通过引入TypedQueryOnQueryStarted和TypedMutationOnQueryStarted类型，为开发者提供了更清晰、更类型安全的方式来处理onQueryStarted生命周期函数。这种方式不仅解决了类型问题，还提高了代码的可维护性和可复用性。

对于从旧版本迁移的开发者，建议逐步替换原有的MutationLifecycleApi和QueryLifecycleApi用法，采用新的类型化方案，以获得更好的类型支持和开发体验。