# npm
npm install @reduxjs/toolkit react-redux
 
# pnpm
pnpm add @reduxjs/toolkit react-redux
 
# yarn
yarn add @reduxjs/toolkit react-redux

// app/store.ts
import { configureStore } from '@reduxjs/toolkit'
import counterReducer from '../features/counter/counterSlice'
import todosReducer from '../features/todos/todosSlice'
import apiReducer from '../services/api/apiSlice'
 
export const store = configureStore({
  reducer: {
    counter: counterReducer,
    todos: todosReducer,
    // RTK Query 自动生成的 reducer
    [apiReducer.reducerPath]: apiReducer,
  },
  // RTK Query 自动生成的中间件
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(apiReducer.middleware),
  // 可选：自定义 DevTools 配置
  devTools: process.env.NODE_ENV !== 'production'
    ? { trace: true, traceLimit: 25 }
    : false,
})
 
// 推导 RootState 和 AppDispatch 类型
export type RootState = ReturnType<typeof store.getState>
export type AppDispatch = typeof store.dispatch

// app/hooks.ts — 类型安全的 hooks
import { useDispatch, useSelector, TypedUseSelectorHook } from 'react-redux'
import type { RootState, AppDispatch } from './store'
 
export const useAppDispatch: () => AppDispatch = useDispatch
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector

// main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { Provider } from 'react-redux'
import { store } from './app/store'
import App from './App'
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Provider store={store}>
      <App />
    </Provider>
  </React.StrictMode>
)

// features/counter/counterSlice.ts
import { createSlice, PayloadAction } from '@reduxjs/toolkit'
 
interface CounterState {
  value: number
  status: 'idle' | 'loading' | 'failed'
}
 
const initialState: CounterState = {
  value: 0,
  status: 'idle',
}
 
export const counterSlice = createSlice({
  name: 'counter',
  initialState,
  reducers: {
    increment: (state) => {
      // Immer 允许直接修改 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

// features/counter/Counter.tsx
import { useAppSelector, useAppDispatch } from '../../app/hooks'
import { increment, decrement, incrementByAmount } from './counterSlice'
 
export function Counter() {
  const count = useAppSelector((state) => state.counter.value)
  const dispatch = useAppDispatch()
 
  return (
    <div>
      <h2>计数器: {count}</h2>
      <button onClick={() => dispatch(decrement())}>减少</button>
      <button onClick={() => dispatch(increment())}>增加</button>
      <button onClick={() => dispatch(incrementByAmount(5))}>增加 5</button>
    </div>
  )
}

// features/todos/todosSlice.ts — 异步操作示例
import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit'
 
interface Todo {
  id: number
  title: string
  completed: boolean
}
 
interface TodosState {
  items: Todo[]
  loading: boolean
  error: string | null
}
 
// 创建异步 thunk
export const fetchTodos = createAsyncThunk(
  'todos/fetchTodos',
  async () => {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos?_limit=10')
    if (!response.ok) throw new Error('网络请求失败')
    return response.json() as Promise<Todo[]>
  }
)
 
const todosSlice = createSlice({
  name: 'todos',
  initialState: { items: [], loading: false, error: null } as TodosState,
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(fetchTodos.pending, (state) => {
        state.loading = true
        state.error = null
      })
      .addCase(fetchTodos.fulfilled, (state, action: PayloadAction<Todo[]>) => {
        state.loading = false
        state.items = action.payload
      })
      .addCase(fetchTodos.rejected, (state, action) => {
        state.loading = false
        state.error = action.error.message ?? '未知错误'
      })
  },
})
 
export default todosSlice.reducer

const userSlice = createSlice({
  name: 'user',
  initialState: { name: '', email: '', status: 'idle' } as UserState,
  reducers: {
    logout: (state) => { state.name = ''; state.email = '' },
  },
  extraReducers: (builder) => {
    builder
      .addCase(loginUser.fulfilled, (state, action) => {
        state.name = action.payload.name
        state.email = action.payload.email
        state.status = 'authenticated'
      })
  },
})

export const fetchUserById = createAsyncThunk(
  'users/fetchById',
  async (userId: string, { rejectWithValue }) => {
    try {
      const response = await fetch(`/api/users/${userId}`)
      if (!response.ok) throw new Error('用户不存在')
      return await response.json()
    } catch (err) {
      return rejectWithValue(err.message)
    }
  }
)

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
 
export const pokemonApi = createApi({
  reducerPath: 'pokemonApi',
  baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
  tagTypes: ['Pokemon'],
  endpoints: (builder) => ({
    getPokemonByName: builder.query<Pokemon, string>({
      query: (name) => `pokemon/${name}`,
      providesTags: (result, error, name) => [{ type: 'Pokemon', id: name }],
    }),
    updatePokemon: builder.mutation<Pokemon, Partial<Pokemon> & Pick<Pokemon, 'id'>>({
      query: ({ id, ...patch }) => ({
        url: `pokemon/${id}`,
        method: 'PATCH',
        body: patch,
      }),
      invalidatesTags: (result, error, { id }) => [{ type: 'Pokemon', id }],
    }),
  }),
})
 
export const { useGetPokemonByNameQuery, useUpdatePokemonMutation } = pokemonApi

import { createEntityAdapter, createSlice } from '@reduxjs/toolkit'
 
interface User { id: string; name: string; age: number }
 
const usersAdapter = createEntityAdapter<User>({
  selectId: (user) => user.id,
  sortComparer: (a, b) => a.name.localeCompare(b.name),
})
 
const usersSlice = createSlice({
  name: 'users',
  initialState: usersAdapter.getInitialState(),
  reducers: {
    userAdded: usersAdapter.addOne,
    userUpdated: usersAdapter.updateOne,
    userRemoved: usersAdapter.removeOne,
    usersReceived: usersAdapter.setAll,
  },
})
 
// 自动生成的选择器
const { selectAll: selectAllUsers, selectById: selectUserById } = usersAdapter.getSelectors<RootState>(state => state.users)

import { combineSlices } from '@reduxjs/toolkit'
 
// 支持动态注入的 rootReducer
const rootReducer = combineSlices({
  auth: authSlice,
  ui: uiSlice,
})
 
// 在路由组件中按需注入
function AdminPage() {
  const adminReducer = useSelector(
    () => rootReducer.inject({ reducerPath: 'admin', reducer: adminSlice })
  )
  // ...
}

import { createListenerMiddleware, isAnyOf } from '@reduxjs/toolkit'
 
const listenerMiddleware = createListenerMiddleware()
 
// 监听特定 action 并执行副作用
listenerMiddleware.startListening({
  actionCreator: userLoggedIn,
  effect: async (action, listenerApi) => {
    // 监听后续的 action
    const result = await listenerApi.condition(
      (action) => isAnyOf(orderPlaced, orderFailed)(action),
      30000 // 30 秒超时
    )
    if (result) {
      // 处理结果
    }
  },
})

// 类型安全的 action payload
interface User {
  id: string
  name: string
  role: 'admin' | 'user'
}
 
const userSlice = createSlice({
  name: 'user',
  initialState: { data: null as User | null, loading: false },
  reducers: {
    // PayloadAction<T> 自动推导 payload 类型
    setUser: (state, action: PayloadAction<User>) => {
      state.data = action.payload // action.payload 类型为 User
    },
    setRole: (state, action: PayloadAction<'admin' | 'user'>) => {
      if (state.data) state.data.role = action.payload
    },
  },
})
 
// 类型安全的 selector
const selectUser = (state: RootState) => state.user.data
const selectUserRole = (state: RootState) => state.user.data?.role

pnpm add -D eslint-plugin-react-redux

{
  "plugins": ["react-redux"],
  "rules": {
    "react-redux/use-selector-in-extra-callbacks": "warn",
    "react-redux/map-state-props": "warn"
  }
}

// features/counter/counterSlice.test.ts
import counterReducer, { increment, decrement, incrementByAmount } from './counterSlice'
 
describe('counterSlice', () => {
  const initialState: CounterState = { value: 0, status: 'idle' }
 
  it('应处理初始状态', () => {
    expect(counterReducer(undefined, { type: 'unknown' })).toEqual(initialState)
  })
 
  it('应处理 increment', () => {
    const actual = counterReducer(initialState, increment())
    expect(actual.value).toBe(1)
  })
 
  it('应处理 decrement', () => {
    const actual = counterReducer({ value: 3, status: 'idle' }, decrement())
    expect(actual.value).toBe(2)
  })
 
  it('应处理 incrementByAmount', () => {
    const actual = counterReducer(initialState, incrementByAmount(5))
    expect(actual.value).toBe(5)
  })
})

// 异步 thunk 测试
import { fetchTodos } from './todosSlice'
import { store } from '../../app/store'
 
test('fetchTodos 应更新 todos 列表', async () => {
  await store.dispatch(fetchTodos())
  const state = store.getState()
  expect(state.todos.loading).toBe(false)
  expect(state.todos.items.length).toBeGreaterThan(0)
})

export const store = configureStore({
  reducer: rootReducer,
  middleware: (getDefaultMiddleware) => {
    const middleware = getDefaultMiddleware({
      // 生产环境关闭序列化检查以提升性能
      serializableCheck: process.env.NODE_ENV !== 'production',
      // 保留 thunk 中间件
      thunk: true,
    })
    return middleware.concat(api.middleware)
  },
  devTools: process.env.NODE_ENV !== 'production'
    ? {
        name: 'My App',
        trace: true,
        traceLimit: 25,
      }
    : false,
  // 自动批处理，减少低优先级更新
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers({ autoBatch: { type: 'tick' } }),
})

import { createSelector } from 'reselect'
 
const selectUsers = (state: RootState) => state.users.items
const selectFilter = (state: RootState) => state.ui.filter
 
const selectFilteredUsers = createSelector(
  [selectUsers, selectFilter],
  (users, filter) => users.filter(user => user.status === filter)
)

// 推荐：只订阅需要的值，避免不必要的重渲染
const userName = useAppSelector((state) => state.user.data?.name)
 
// 或使用 shallowEqual 防止对象引用变化导致的重渲染
import { shallowEqual } from 'react-redux'
const user = useAppSelector((state) => state.user, shallowEqual)

// 推荐：每个功能域一个 slice，保持职责单一
// features/auth/authSlice.ts
const authSlice = createSlice({
  name: 'auth',
  initialState: { user: null, token: null, status: 'idle' },
  reducers: { /* 同步操作 */ },
  extraReducers: (builder) => { /* 异步操作 */ },
})
 
// 避免：将所有逻辑塞进一个巨型 slice
// ❌ features/globalSlice.ts — 数百个 reducer，难以维护

// 推荐：使用 createSelector 避免重复计算
const selectFilteredTodos = createSelector(
  [(state: RootState) => state.todos.items, (state: RootState) => state.filter.value],
  (todos, filter) => todos.filter(todo =>
    filter === 'all' ? true : todo.completed === (filter === 'completed')
  )
)
 
// 在组件中使用
const filteredTodos = useAppSelector(selectFilteredTodos)

// 推荐：使用 tagTypes 管理缓存失效关系
const api = createApi({
  // ...
  tagTypes: ['User', 'Post'],
  endpoints: (builder) => ({
    getUsers: builder.query({
      query: () => '/users',
      providesTags: (result) =>
        result ? result.map(({ id }) => ({ type: 'User', id })) : ['User'],
    }),
    updateUser: builder.mutation({
      query: (user) => ({ url: `/users/${user.id}`, method: 'PUT', body: user }),
      // 精确失效：只失效被更新的用户
      invalidatesTags: (result, error, { id }) => [{ type: 'User', id }],
    }),
  }),
})

// 推荐：按职责分离状态层
// - RTK / Zustand：客户端全局状态（用户会话、权限、UI 配置）
// - RTK Query / TanStack Query：服务端状态（API 数据缓存）
// - useState / useReducer：局部组件状态（表单、弹窗开关）
// - URL state（React Router）：路由参数、筛选条件、分页

// ❌ 避免：每次调用都创建新数组引用
const selectCompleted = (state: RootState) =>
  state.todos.items.filter(t => t.completed)
 
// ✅ 推荐：使用 createSelector 记忆化结果
const selectCompleted = createSelector(
  [(state: RootState) => state.todos.items],
  (items) => items.filter(t => t.completed)
)