状态管理

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 前端状态管理方案

## 状态分类

### 1. 全局状态（Global State）

**定义**：跨多个组件共享的状态

**管理方式**：Zustand

**适用场景**：
- 用户认证信息
- 用户权限信息
- 应用配置（主题、语言等）
- 全局通知消息

**示例**：
```typescript
// auth.store.ts
interface AuthState {
  user: User | null;
  token: string | null;
  isAuthenticated: boolean;
  login: (credentials: LoginCredentials) => Promise<void>;
  logout: () => void;
}
```

### 2. 本地状态（Local State）

**定义**：仅在单个组件或其子组件中使用的状态

**管理方式**：useState

**适用场景**：
- 表单输入值
- 组件显示/隐藏
- 交互状态（hover、active）
- 临时数据

**示例**：
```typescript
const [isOpen, setIsOpen] = useState(false);
const [formData, setFormData] = useState({});
```

### 3. 服务端状态（Server State）

**定义**：从服务器获取的数据

**管理方式**：React Query（TanStack Query）

**适用场景**：
- 从API获取的数据
- 需要缓存和重新验证的数据
- 需要乐观更新的数据

**示例**：
```typescript
const { data, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers
});
```

### 4. 表单状态（Form State）

**定义**：表单输入和验证状态

**管理方式**：React Hook Form

**适用场景**：
- 表单输入
- 表单验证
- 表单提交

**示例**：
```typescript
const { register, handleSubmit, formState: { errors } } = useForm();
```

## 技术选型

### 1. Zustand - 全局状态管理

**优势**：
- 简洁轻量（~1KB）
- 无需Provider包装
- 支持TypeScript
- 支持中间件（persist、devtools等）
- 性能优秀

**安装**：
```bash
pnpm add zustand
pnpm add -D @types/zustand
```

### 2. React Query - 服务端状态管理

**优势**：
- 自动缓存和重新验证
- 乐观更新
- 分页和无限滚动
- 自动重试
- 离线支持

**安装**：
```bash
pnpm add @tanstack/react-query
```

### 3. React Hook Form - 表单状态管理

**优势**：
- 性能优秀（减少重渲染）
- 内置验证
- 支持复杂表单
- 与Zod集成良好

**安装**：
```bash
pnpm add react-hook-form
pnpm add @hookform/resolvers zod
```

## Zustand Store 设计

### Store目录结构

```
src/stores/
├── auth.store.ts              # 认证状态
├── user.store.ts              # 用户状态
├── tenant.store.ts            # 租户状态
├── ui.store.ts                # UI状态
├── notification.store.ts      # 通知状态
└── index.ts                   # 统一导出
```

### Store创建模板

```typescript
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface StoreState {
  // 状态
  state: any;

// 操作
  action: () => void;
}

export const useStore = create<StoreState>()(
  persist(
    (set, get) => ({
      // 状态
      state: null,

// 操作
      action: () => {
        set({ state: newValue });
      }
    }),
    {
      name: 'store-name', // localStorage key
      partialize: (state) => ({ state: state.state }) // 只持久化部分状态
    }
  )
);
```

## React Query 设计

### QueryClient配置

```typescript
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5分钟
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});
```

### Query Keys设计

```typescript
// keys.ts
export const queryKeys = {
  auth: ['auth'] as const,
  user: (id: string) => ['users', id] as const,
  users: () => ['users'] as const,
  tenant: (id: string) => ['tenants', id] as const,
  salarySlips: (params?: any) => ['salary-slips', params] as const,
} as const;
```

## 自定义Hooks设计

### Hooks目录结构

```
src/hooks/
├── useAuth.ts              # 认证Hook
├── useUser.ts              # 用户Hook
├── useTenant.ts            # 租户Hook
├── useApi.ts               # API调用Hook
├── usePagination.ts        # 分页Hook
├── useTable.ts             # 表格Hook
├── useForm.ts              # 表单Hook
├── useDebounce.ts          # 防抖Hook
├── useLocalStorage.ts      # 本地存储Hook
└── index.ts                # 统一导出
```

### Hook创建模板

```typescript
import { useStore } from '@/stores';

export const useCustomHook = () => {
  const { state, action } = useStore();

const doSomething = useCallback(() => {
    action();
  }, [action]);

return {
    state,
    doSomething
  };
};
```

## 状态管理最佳实践

### 1. 选择正确的状态管理方式

| 状态类型 | 推荐方案 |
|---------|---------|
| 跨组件共享 | Zustand |
| API数据 | React Query |
| 表单数据 | React Hook Form |
| 组件内部 | useState |
| UI状态（theme、language） | Zustand + Context |

### 2. 避免过度使用全局状态

- 优先使用本地状态
- 只有真正需要跨组件共享时才使用全局状态

### 3. 合理使用React Query

- 利用缓存减少不必要的请求
- 使用invalidateQueries刷新数据
- 使用optimistic updates优化用户体验

### 4. 保持Store简单

- 避免在Store中包含过多逻辑
- 复杂逻辑抽离为独立的Hook

### 5. 类型安全

- 为所有Store和Hook定义明确的TypeScript类型
- 使用as const确保类型推断

## 示例：完整的认证流程

```typescript
// 1. Auth Store
export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      token: null,
      isAuthenticated: false,

login: async (credentials) => {
        const response = await authApi.login(credentials);
        set({
          user: response.user,
          token: response.token,
          isAuthenticated: true
        });
      },

logout: () => {
        set({
          user: null,
          token: null,
          isAuthenticated: false
        });
      }
    }),
    { name: 'auth-storage' }
  )
);

// 2. Auth Hook
export const useAuth = () => {
  const { user, token, isAuthenticated, login, logout } = useAuthStore();

return {
    user,
    token,
    isAuthenticated,
    login,
    logout
  };
};

// 3. 在组件中使用
function LoginPage() {
  const { login } = useAuth();
  const [loading, setLoading] = useState(false);

return <LoginForm onSubmit={handleSubmit} />;
}
```

## 总结

通过合理的状态管理方案，我们可以：

1. **提高代码可维护性**：清晰的状态分类和职责划分
2. **提升性能**：减少不必要的重渲染
3. **改善开发体验**：简洁的API和良好的TypeScript支持
4. **增强用户体验**：合理的数据缓存和更新策略