Studio Web (Next.js) 项目结构一览 - Redux + React Query 方案

Studio Web/
├── @types/                 # 📝 TypeScript类型定义
│   ├── api.d.ts           # 🔌 API响应类型定义
│   ├── store.d.ts         # 📦 Redux状态类型定义
│   └── global.d.ts        # 🌐 全局类型声明
├── app/                    # 🚀 Next.js App Router (页面/路由/布局)
├── components/             # 🧩 React组件库
│   ├── features/          # 📋 业务功能组件 (UserProfile/Dashboard)
│   ├── layout/            # 🏗️ 布局组件 (Header/Footer/Sidebar)
│   └── ui/                # 🎨 基础UI组件 (Button/Input/Modal)
├── configs/                # ⚙️ 应用配置 (环境变量/常量配置)
├── hooks/                  # 🎣 自定义Hooks
│   ├── queries/           # 🔍 React Query相关Hooks (服务端状态)
│   └── store/             # 📦 Redux相关Hooks (客户端状态)
├── i18n/                   # 🌍 国际化 (多语言翻译文件)
├── lib/                    # 📚 第三方库配置
│   ├── react-query.ts     # ⚡ React Query客户端配置
│   └── redux.ts           # 📦 Redux Store配置
├── service/                # 🔌 API服务层 (纯HTTP请求函数)
├── providers/              # 🔐 全局Provider组件
├── store/                  # 📦 Redux状态管理 (客户端状态)
│   ├── slices/            # 🔪 Redux切片 (auth/ui/filters等)
│   └── index.ts           # 🏪 Store配置和导出
└── utils/                  # 🛠️ 工具函数 (格式化/验证/通用方法)

用户交互 → Component → Hook (分流) → 不同状态管理
    ↓         ↓         ↓              ↓
  事件触发   UI渲染    状态查询        执行操作
    ↑         ↑         ↑              ↑
  UI更新  ← Component ← Hook ←── 状态更新通知

Component → hooks/queries/useUsers → service/userService → API
    ↓              ↓                      ↓                ↓
  调用Hook       执行查询              HTTP请求          后端处理
    ↑              ↑                      ↑                ↑
  自动更新   ← React Query缓存 ← userService ← API Response

Component → hooks/store/useAuth → store/slices/authSlice → Redux Store
    ↓             ↓                    ↓                      ↓
  触发Action   调用dispatch        执行Reducer           状态更新
    ↑             ↑                    ↑                      ↑
  重新渲染   ← useSelector ← store/index.ts ← 状态变更通知

// service/userService.ts
export const userService = {
  // 纯粹的HTTP请求，无状态逻辑
  getUsers: () => fetch('/api/users').then(res => res.json()),
  createUser: (data) => fetch('/api/users', { method: 'POST', body: JSON.stringify(data) })
}

// hooks/queries/useUsers.ts
export const useUsers = (filters) => {
  return useQuery({
    queryKey: ['users', filters],
    queryFn: () => userService.getUsers(filters),
    staleTime: 5 * 60 * 1000, // 缓存策略
  })
}

export const useCreateUser = () => {
  return useMutation({
    mutationFn: userService.createUser,
    onSuccess: () => queryClient.invalidateQueries(['users'])
  })
}

// hooks/store/useAuth.ts
export const useAuth = () => {
  const dispatch = useDispatch()
  return {
    ...useSelector(state => state.auth),
    login: (credentials) => dispatch(login(credentials)),
    logout: () => dispatch(logout())
  }
}

// store/slices/authSlice.ts - 认证状态
const authSlice = createSlice({
  name: 'auth',
  initialState: { user: null, isAuthenticated: false },
  reducers: { login, logout }
})

// store/slices/uiSlice.ts - UI状态
const uiSlice = createSlice({
  name: 'ui',
  initialState: { sidebarOpen: false, theme: 'light' },
  reducers: { toggleSidebar, setTheme }
})

// lib/react-query.ts
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 60 * 1000, cacheTime: 5 * 60 * 1000 }
  }
})

// lib/redux.ts
export const store = configureStore({
  reducer: {
    auth: authSlice.reducer,
    ui: uiSlice.reducer
  }
})

// app/dashboard/page.tsx
'use client'
export default function DashboardPage() {
  // 服务端状态 (React Query)
  const { data: users, isLoading } = useUsers()
  const { data: orders } = useOrders()
  const createUserMutation = useCreateUser()
  
  // 客户端状态 (Redux)  
  const { isAuthenticated } = useAuth()
  const { sidebarOpen, filters } = useUI()
  
  return <Dashboard {...props} />
}

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Component     │    │      Hooks       │    │  State Manager  │
│                 │    │                  │    │                 │
│  ┌─────────────┐│    │ ┌──────────────┐ │    │ ┌─────────────┐ │
│  │ 用户交互    ││───→│ │queries/      │ │───→│ │React Query  │ │
│  │            ││    │ │useUsers()    │ │    │ │   Cache     │ │
│  └─────────────┘│    │ └──────────────┘ │    │ └─────────────┘ │
│                 │    │                  │    │                 │
│  ┌─────────────┐│    │ ┌──────────────┐ │    │ ┌─────────────┐ │
│  │ UI状态切换  ││───→│ │store/        │ │───→│ │Redux Store  │ │
│  │            ││    │ │useAuth()     │ │    │ │             │ │
│  └─────────────┘│    │ └──────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         ↑                       ↑                       ↑
         └───────────────────────┴───────────────────────┘
                      状态变更通知，触发重新渲染

┌─────────────────────────────────────────────────────────────┐
│                      app/layout.tsx                         │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                  RootProvider                         │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │                StoreProvider                    │  │  │
│  │  │  ┌───────────────────────────────────────────┐  │  │  │
│  │  │  │              QueryProvider                │  │  │  │
│  │  │  │  ┌─────────────────────────────────────┐  │  │  │  │
│  │  │  │  │           AuthProvider              │  │  │  │  │
│  │  │  │  │  ┌───────────────────────────────┐  │  │  │  │  │
│  │  │  │  │  │       MoreProviders...        │  │  │  │  │  │
│  │  │  │  │  │  ┌─────────────────────────┐  │  │  │  │  │  │
│  │  │  │  │  │  │    Page Components      │  │  │  │  │  │  │
│  │  │  │  │  │  └─────────────────────────┘  │  │  │  │  │  │
│  │  │  │  │  └───────────────────────────────┘  │  │  │  │  │
│  │  │  │  └─────────────────────────────────────┘  │  │  │  │
│  │  │  └───────────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘