React 状态管理完全指南：Context、Zustand、Jotai、Redux Toolkit、TanStack Query 深度选型与生产级实践

// useState：简单值或对象
const [count, setCount] = useState(0);

// useReducer：复杂状态转换逻辑
const [state, dispatch] = useReducer(reducer, initialState);
// dispatch({ type: 'increment', payload: 5 }) —— 类似 Redux 但局限在单个组件

// ❌ 反模式：把整个 store 放进一个 Context
function App() {
  const [state, setState] = useState({ user, theme, sidebar, notifications });
  return (
    <AppContext.Provider value={{ state, setState }}>
      <Layout />  {/* theme 变了，整个 Layout 会重渲染 */}
    </AppContext.Provider>
  );
}

// ✅ 垂直拆分 Context，减少重渲染范围
function App() {
  const user = useUserState();
  const theme = useThemeState();
  return (
    <UserContext.Provider value={user}>
      <ThemeContext.Provider value={theme}>
        <Layout />
      </ThemeContext.Provider>
    </UserContext.Provider>
  );
}

import { create } from 'zustand';

interface BearStore {
  bears: number;
  increase: () => void;
  decrease: () => void;
  reset: () => void;
}

const useBearStore = create<BearStore>((set, get) => ({
  bears: 0,
  increase: () => set((state) => ({ bears: state.bears + 1 })),
  decrease: () => set((state) => ({ bears: Math.max(0, state.bears - 1) })),
  reset: () => set({ bears: 0 }),
}));

// 组件中使用
function BearCounter() {
  const bears = useBearStore((state) => state.bears);
  return <h1>{bears} bears</h1>; // 只有 bears 变化时才重渲染
}

import { create } from 'zustand';

// 用户 slice
const createUserSlice = (set: any, get: any) => ({
  user: null as User | null,
  isLoggedIn: false,
  login: (user: User) => set({ user, isLoggedIn: true }),
  logout: () => set({ user: null, isLoggedIn: false }),
});

// 购物车 slice
const createCartSlice = (set: any, get: any) => ({
  items: [] as CartItem[],
  addItem: (item: CartItem) => {
    const { items } = get();
    set({ items: [...items, item] });
  },
  total: () => {
    const { items } = get();
    return items.reduce((sum, item) => sum + item.price * item.qty, 0);
  },
});

// 组合 store
const useStore = create((...args) => ({
  ...createUserSlice(...args),
  ...createCartSlice(...args),
}));

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

const useUserStore = create(
  persist<UserState>(
    (set) => ({
      theme: 'dark',
      sidebarOpen: true,
      setTheme: (theme: string) => set({ theme }),
    }),
    {
      name: 'user-preferences',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({ theme: state.theme }), // 只持久化 theme
    }
  )
);

import { atom, useAtom } from 'jotai';

// Primitive atoms：基础原子
const countAtom = atom(0);

// Derived atoms：派生原子（自动追踪依赖）
const doubleAtom = atom((get) => get(countAtom) * 2);

// Writable derived atoms
const tripleAtom = atom(
  (get) => get(countAtom) * 3,
  (get, set, newValue: number) => set(countAtom, newValue / 3)
);

function Counter() {
  const [count, setCount] = useAtom(countAtom);
  const [double] = useAtom(doubleAtom); // 只读
  return (
    <div>
      <p>Count: {count}, Double: {double}</p>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  );
}

// 异步原子（数据获取）
const postsAtom = atom(async () => {
  const res = await fetch('/api/posts');
  return res.json();
});

// 带有 write 的原子
const updatePostAtom = atom(
  null,
  async (get, set, { id, data }: { id: string; data: PostData }) => {
    const res = await fetch(`/api/posts/${id}`, {
      method: 'PATCH',
      body: JSON.stringify(data),
    });
    const updated = await res.json();
    set(postsAtom, (prev) => prev.map((p) => (p.id === id ? updated : p)));
  }
);

// Provider scope（隔离状态，用于测试或 SSR）
function PostEditor({ id }: { id: string }) {
  return (
    <Provider>
      <EditorContent id={id} />
    </Provider>
  );
}

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

// 异步 thunk
const fetchUser = createAsyncThunk('user/fetch', async (userId: string) => {
  const res = await fetch(`/api/users/${userId}`);
  return res.json();
});

const userSlice = createSlice({
  name: 'user',
  initialState: { user: null, loading: false, error: null } as UserState,
  reducers: {
    clearUser: (state) => { state.user = null; },
  },
  extraReducers: (builder) => {
    builder
      .addCase(fetchUser.pending, (state) => { state.loading = true; })
      .addCase(fetchUser.fulfilled, (state, action) => {
        state.user = action.payload;
        state.loading = false;
      })
      .addCase(fetchUser.rejected, (state, action) => {
        state.error = action.error.message;
        state.loading = false;
      });
  },
});

const store = configureStore({
  reducer: { user: userSlice.reducer },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;
export { fetchUser, clearUser };

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  endpoints: (builder) => ({
    getPosts: builder.query<Post[], void>({ query: () => '/posts' }),
    getPost: builder.query<Post, string>({ query: (id) => `/posts/${id}` }),
    updatePost: builder.mutation<Post, { id: string; body: PostData }>({
      query: ({ id, body }) => ({
        url: `/posts/${id}`,
        method: 'PATCH',
        body,
      }),
    }),
  }),
});

export const { useGetPostsQuery, useGetPostQuery, useUpdatePostMutation } = api;

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// 查询
const { data, isLoading, error, isFetching } = useQuery({
  queryKey: ['posts', postId],
  queryFn: () => fetchPost(postId),
  staleTime: 1000 * 60 * 5,      // 5分钟内数据不会重新获取
  gcTime: 1000 * 60 * 30,        // 缓存保留30分钟（v5 参数名）
  retry: 3,                       // 失败后重试3次
  refetchOnWindowFocus: true,     // 窗口聚焦时自动重取
});

const queryClient = useQueryClient();

const mutation = useMutation({
  mutationFn: updatePost,
  onMutate: async (newPost) => {
    // 1. 取消正在进行的重新获取
    await queryClient.cancelQueries({ queryKey: ['posts', newPost.id] });

    // 2. 保存之前的状态用于回滚
    const previousPost = queryClient.getQueryData(['posts', newPost.id]);

    // 3. 乐观更新 UI
    queryClient.setQueryData(['posts', newPost.id], newPost);

    return { previousPost };
  },
  onError: (err, newPost, context) => {
    // 4. 发生错误时回滚
    queryClient.setQueryData(['posts', newPost.id], context?.previousPost);
  },
  onSettled: (newPost) => {
    // 5. 最终数据同步
    queryClient.invalidateQueries({ queryKey: ['posts', newPost?.id] });
  },
});

// ✅ 推荐：分离策略
// 服务端状态：只用 TanStack Query
const { data: user } = useQuery({ queryKey: ['user'], queryFn: fetchUser });
const { mutate: updateUser } = useMutation({ mutationFn: updateUserApi });

// 客户端状态：Zustand 或 Context
const theme = useStore((state) => state.theme);
const toggleSidebar = useStore((state) => state.toggleSidebar);

// ✅ 使用语义化命名，避免简写
interface UserState {
  isLoading: boolean;        // 异步操作进行中
  isAuthenticated: boolean;  // 认证状态
  currentUser: User | null;  // 当前用户信息
  error: Error | null;       // 错误对象
}

// ❌ 避免
interface BadState {
  loading: boolean;          // 语义弱
  errorMessage: string;      // 应该统一用 error: Error
  data: any;                 // 具体类型不明
}

// ❌ 反模式：把 Form 状态塞进全局 Store
const useBadStore = create(() => ({
  loginForm: { username: '', password: '' },  // 只在 Login 页使用
}));

// ✅ 正确：Form 状态留在组件内
function LoginPage() {
  const [form, setForm] = useState({ username: '', password: '' });
  // 只在需要提交时才与全局状态交互
}