redux-toolkit

Redux Toolkit 核心知识

深入了解：使用 mcp__documentation__fetch_docs 并指定 technology：redux-toolkit，获取完整文档。

Slice

import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface CounterState {
  value: number;
}

const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 } as CounterState,
  reducers: {
    increment: (state) => { state.value += 1; },
    decrement: (state) => { state.value -= 1; },
    incrementByAmount: (state, action: PayloadAction<number>) => {
      state.value += action.payload;
    },
  },
});

export const { increment, decrement, incrementByAmount } = counterSlice.actions;
export default counterSlice.reducer;

Store 设置

import { configureStore } from '@reduxjs/toolkit';

export const store = configureStore({
  reducer: {
    counter: counterReducer,
    users: usersReducer,
  },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

异步 Thunk

import { createAsyncThunk } from '@reduxjs/toolkit';

export const fetchUsers = createAsyncThunk(
  'users/fetchUsers',
  async (_, { rejectWithValue }) => {
    try {
      const response = await api.getUsers();
      return response.data;
    } catch (err) {
      return rejectWithValue(err.message);
    }
  }
);

// In slice
extraReducers: (builder) => {
  builder
    .addCase(fetchUsers.pending, (state) => { state.loading = true; })
    .addCase(fetchUsers.fulfilled, (state, action) => {
      state.loading = false;
      state.users = action.payload;
    })
    .addCase(fetchUsers.rejected, (state, action) => {
      state.loading = false;
      state.error = action.payload;
    });
}

Hooks

import { useSelector, useDispatch } from 'react-redux';
import { RootState, AppDispatch } from './store';

export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
export const useAppSelector = useSelector.withTypes<RootState>();

// Usage
const count = useAppSelector((state) => state.counter.value);
const dispatch = useAppDispatch();
dispatch(increment());

何时不应使用此技能

场景	改用
简单的全局状态（用户偏好、主题）	使用 zustand，减少样板代码
服务端状态管理	仅使用 tanstack-query 或 RTK Query
Vue 3 应用	pinia
小型项目或原型	React Context + hooks 或 Zustand
组件本地状态	React useState/useReducer

反模式

反模式	不好的原因	正确做法
使用原生 Redux，而不是 RTK	样板代码过多，容易出错	始终使用 Redux Toolkit
不借助 Immer 修改状态	破坏不可变性，导致错误	使用内置 Immer 的 createSlice
将所有内容都存入 Redux	造成不必要的复杂性	尽可能将组件状态保留在本地
不使用类型化 hooks	丧失类型安全性	导出类型化的 useAppDispatch/useAppSelector
在组件中使用 thunk 获取数据	请求逻辑重复	使用 RTK Query 获取数据
不使用 createAsyncThunk	需要手动处理加载和错误	使用 createAsyncThunk 执行异步操作
持久化整个状态	localStorage 体积大，水合速度慢	仅持久化 auth/关键 slice
thunk 中没有错误处理	错误被静默忽略	在 thunk 中使用 rejectWithValue
slice 之间存在循环依赖	难以维护，容易出错	使用中间件或单独的选择器
不规范化嵌套数据	更新缓慢，reducer 复杂	使用 @reduxjs/toolkit/normalizr 规范化

快速故障排查

问题	原因	解决方案
“Cannot read property of undefined”	状态水合竞态条件	添加加载检查或使用 skipHydration
Action 未触发重新渲染	未使用类型化选择器	使用类型正确的 useAppSelector
Redux 中出现 “Invariant violation”	在 Immer 外部修改了状态	仅在 createSlice reducer 中修改状态
状态较大时性能缓慢	选择器未记忆化	使用 Reselect 中的 createSelector
DevTools 未显示 action	生产环境中已禁用 DevTools	设置 devTools: process.env.NODE_ENV !== 'production'
RTK Query 缓存未失效	缺少标签或标签错误	添加 providesTags 和 invalidatesTags
使用 persist 时出现序列化错误	状态中存在不可序列化的数据	将其添加到 serializableCheck.ignoredActions
Thunk 错误未捕获	没有错误边界	用错误边界封装，或在组件中处理

生产就绪

Store 配置

// store/index.ts - Production-ready store
import { configureStore, combineReducers } from '@reduxjs/toolkit';
import { setupListeners } from '@reduxjs/toolkit/query';
import {
  persistStore,
  persistReducer,
  FLUSH,
  REHYDRATE,
  PAUSE,
  PERSIST,
  PURGE,
  REGISTER,
} from 'redux-persist';
import storage from 'redux-persist/lib/storage';

const rootReducer = combineReducers({
  auth: authReducer,
  users: usersReducer,
  [api.reducerPath]: api.reducer,
});

const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['auth'], // Only persist auth
  blacklist: [api.reducerPath], // Don't persist API cache
};

const persistedReducer = persistReducer(persistConfig, rootReducer);

export const store = configureStore({
  reducer: persistedReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: {
        ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
      },
    }).concat(api.middleware),
  devTools: process.env.NODE_ENV !== 'production',
});

setupListeners(store.dispatch);

export const persistor = persistStore(store);
export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

RTK Query 最佳实践

// services/api.ts
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

const baseQuery = fetchBaseQuery({
  baseUrl: '/api',
  prepareHeaders: (headers, { getState }) => {
    const token = (getState() as RootState).auth.token;
    if (token) {
      headers.set('Authorization', `Bearer ${token}`);
    }
    return headers;
  },
});

const baseQueryWithReauth = async (args, api, extraOptions) => {
  let result = await baseQuery(args, api, extraOptions);

  if (result.error?.status === 401) {
    const refreshResult = await baseQuery('/auth/refresh', api, extraOptions);
    if (refreshResult.data) {
      api.dispatch(setToken(refreshResult.data.token));
      result = await baseQuery(args, api, extraOptions);
    } else {
      api.dispatch(logout());
    }
  }

  return result;
};

export const api = createApi({
  reducerPath: 'api',
  baseQuery: baseQueryWithReauth,
  tagTypes: ['User', 'Post'],
  endpoints: (builder) => ({
    getUsers: builder.query<User[], void>({
      query: () => '/users',
      providesTags: (result) =>
        result
          ? [...result.map(({ id }) => ({ type: 'User' as const, id })), 'User']
          : ['User'],
    }),
    createUser: builder.mutation<User, CreateUserDto>({
      query: (body) => ({
        url: '/users',
        method: 'POST',
        body,
      }),
      invalidatesTags: ['User'],
    }),
  }),
});

export const { useGetUsersQuery, useCreateUserMutation } = api;

Redux 测试

// test-utils.tsx
import { configureStore } from '@reduxjs/toolkit';
import { render, RenderOptions } from '@testing-library/react';
import { Provider } from 'react-redux';

interface ExtendedRenderOptions extends Omit<RenderOptions, 'queries'> {
  preloadedState?: Partial<RootState>;
  store?: ReturnType<typeof configureStore>;
}

export function renderWithProviders(
  ui: React.ReactElement,
  {
    preloadedState = {},
    store = configureStore({
      reducer: rootReducer,
      preloadedState,
    }),
    ...renderOptions
  }: ExtendedRenderOptions = {}
) {
  function Wrapper({ children }: { children: React.ReactNode }) {
    return <Provider store={store}>{children}</Provider>;
  }
  return { store, ...render(ui, { wrapper: Wrapper, ...renderOptions }) };
}

// Usage
test('displays user list', async () => {
  renderWithProviders(<UserList />, {
    preloadedState: {
      users: { items: [{ id: '1', name: 'John' }], loading: false },
    },
  });

  expect(screen.getByText('John')).toBeInTheDocument();
});

错误处理

// Centralized error handling middleware
const errorMiddleware: Middleware = () => (next) => (action) => {
  if (isRejectedWithValue(action)) {
    const error = action.payload;

    if (error.status === 401) {
      // Handle unauthorized
      store.dispatch(logout());
    }

    // Log to monitoring service
    logError({
      action: action.type,
      error: error.data?.message || 'Unknown error',
    });
  }

  return next(action);
};

监控指标

指标	目标
状态序列化时间	< 50ms
Action 分发时间	< 16ms
缓存命中率	> 80%
测试覆盖率	> 85%

检查清单

• 类型化 hooks（useAppDispatch、useAppSelector）
• 使用 RTK Query 获取数据
• 自动缓存失效
• 令牌刷新处理
• 使用 Redux Persist 持久化 auth 状态
• 在生产环境中禁用 DevTools
• 错误处理中间件
• 使用预加载状态的测试工具
• 对派生数据使用记忆化选择器
• Redux DevTools 中不包含敏感数据

参考文档

• RTK Query
• 中间件