docs: add comprehensive refactoring documentation
Add three key documents to guide the project restructure: - REFACTORING_MASTER_PLAN.md: Complete refactoring roadmap with 6 stages - REFACTORING_CHECKLIST.md: Detailed task checklist for tracking progress - REFACTORING_REFERENCE.md: Technical reference and implementation guide This refactoring aims to modernize the codebase with React Query, react-hook-form, zod validation, and shadcn/ui components while maintaining the current Tailwind CSS 4.x stack. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jason
489
docs/REFACTORING_CHECKLIST.md
Normal file
489
docs/REFACTORING_CHECKLIST.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# CC Switch 重构实施清单
|
||||
|
||||
> 用于跟踪重构进度的详细检查清单
|
||||
|
||||
**开始日期**: ___________
|
||||
**预计完成**: ___________
|
||||
**当前阶段**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 0: 准备阶段 (预计 1 天)
|
||||
|
||||
### 环境准备
|
||||
|
||||
- [ ] 创建新分支 `refactor/modernization`
|
||||
- [ ] 创建备份标签 `git tag backup-before-refactor`
|
||||
- [ ] 备份用户配置文件 `~/.cc-switch/config.json`
|
||||
- [ ] 通知团队成员重构开始
|
||||
|
||||
### 依赖安装
|
||||
|
||||
```bash
|
||||
pnpm add @tanstack/react-query
|
||||
pnpm add react-hook-form @hookform/resolvers
|
||||
pnpm add zod
|
||||
pnpm add sonner
|
||||
pnpm add next-themes
|
||||
pnpm add @radix-ui/react-dialog @radix-ui/react-dropdown-menu
|
||||
pnpm add @radix-ui/react-label @radix-ui/react-select
|
||||
pnpm add @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs
|
||||
pnpm add class-variance-authority clsx tailwind-merge tailwindcss-animate
|
||||
```
|
||||
|
||||
- [ ] 安装核心依赖 (上述命令)
|
||||
- [ ] 验证依赖安装成功 `pnpm install`
|
||||
- [ ] 验证编译通过 `pnpm typecheck`
|
||||
|
||||
### 配置文件
|
||||
|
||||
- [ ] 创建 `components.json`
|
||||
- [ ] 更新 `tsconfig.json` 添加路径别名
|
||||
- [ ] 更新 `vite.config.mts` 添加路径解析
|
||||
- [ ] 验证开发服务器启动 `pnpm dev`
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 1: 基础设施 (预计 2-3 天)
|
||||
|
||||
### 1.1 工具函数和基础组件
|
||||
|
||||
- [ ] 创建 `src/lib/utils.ts` (cn 函数)
|
||||
- [ ] 创建 `src/components/ui/button.tsx`
|
||||
- [ ] 创建 `src/components/ui/dialog.tsx`
|
||||
- [ ] 创建 `src/components/ui/input.tsx`
|
||||
- [ ] 创建 `src/components/ui/label.tsx`
|
||||
- [ ] 创建 `src/components/ui/textarea.tsx`
|
||||
- [ ] 创建 `src/components/ui/select.tsx`
|
||||
- [ ] 创建 `src/components/ui/switch.tsx`
|
||||
- [ ] 创建 `src/components/ui/tabs.tsx`
|
||||
- [ ] 创建 `src/components/ui/sonner.tsx`
|
||||
- [ ] 创建 `src/components/ui/form.tsx`
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证所有 UI 组件可以正常导入
|
||||
- [ ] 创建一个测试页面验证组件样式
|
||||
|
||||
### 1.2 Query Client 设置
|
||||
|
||||
- [ ] 创建 `src/lib/query/queryClient.ts`
|
||||
- [ ] 配置默认选项 (retry, staleTime 等)
|
||||
- [ ] 导出 queryClient 实例
|
||||
|
||||
### 1.3 API 层
|
||||
|
||||
- [ ] 创建 `src/lib/api/providers.ts`
|
||||
- [ ] getAll
|
||||
- [ ] getCurrent
|
||||
- [ ] add
|
||||
- [ ] update
|
||||
- [ ] delete
|
||||
- [ ] switch
|
||||
- [ ] importDefault
|
||||
- [ ] updateTrayMenu
|
||||
|
||||
- [ ] 创建 `src/lib/api/settings.ts`
|
||||
- [ ] get
|
||||
- [ ] save
|
||||
|
||||
- [ ] 创建 `src/lib/api/mcp.ts`
|
||||
- [ ] getConfig
|
||||
- [ ] upsertServer
|
||||
- [ ] deleteServer
|
||||
|
||||
- [ ] 创建 `src/lib/api/index.ts` (聚合导出)
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证 API 调用不会出现运行时错误
|
||||
- [ ] 确认类型定义正确
|
||||
|
||||
### 1.4 Query Hooks
|
||||
|
||||
- [ ] 创建 `src/lib/query/queries.ts`
|
||||
- [ ] useProvidersQuery
|
||||
- [ ] useSettingsQuery
|
||||
- [ ] useMcpConfigQuery
|
||||
|
||||
- [ ] 创建 `src/lib/query/mutations.ts`
|
||||
- [ ] useAddProviderMutation
|
||||
- [ ] useSwitchProviderMutation
|
||||
- [ ] useDeleteProviderMutation
|
||||
- [ ] useUpdateProviderMutation
|
||||
- [ ] useSaveSettingsMutation
|
||||
|
||||
- [ ] 创建 `src/lib/query/index.ts` (聚合导出)
|
||||
|
||||
**测试**:
|
||||
- [ ] 在临时组件中测试每个 hook
|
||||
- [ ] 验证 loading/error 状态正确
|
||||
- [ ] 验证缓存和自动刷新工作
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 2: 核心功能重构 (预计 3-4 天)
|
||||
|
||||
### 2.1 主题系统
|
||||
|
||||
- [ ] 创建 `src/components/theme-provider.tsx`
|
||||
- [ ] 创建 `src/components/mode-toggle.tsx`
|
||||
- [ ] 更新 `src/index.css` 添加主题变量
|
||||
- [ ] 删除 `src/hooks/useDarkMode.ts`
|
||||
- [ ] 更新所有组件使用新的主题系统
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证主题切换正常工作
|
||||
- [ ] 验证系统主题跟随功能
|
||||
- [ ] 验证主题持久化
|
||||
|
||||
### 2.2 更新 main.tsx
|
||||
|
||||
- [ ] 引入 QueryClientProvider
|
||||
- [ ] 引入 ThemeProvider
|
||||
- [ ] 添加 Toaster 组件
|
||||
- [ ] 移除旧的 API 导入
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证应用可以正常启动
|
||||
- [ ] 验证 Context 正确传递
|
||||
|
||||
### 2.3 重构 App.tsx
|
||||
|
||||
- [ ] 使用 useProvidersQuery 替代手动状态管理
|
||||
- [ ] 移除所有 loadProviders 相关代码
|
||||
- [ ] 移除手动 notification 状态
|
||||
- [ ] 简化事件监听逻辑
|
||||
- [ ] 更新对话框为新的 Dialog 组件
|
||||
|
||||
**目标**: 将 412 行代码减少到 ~100 行
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证供应商列表正常加载
|
||||
- [ ] 验证切换 Claude/Codex 正常工作
|
||||
- [ ] 验证事件监听正常工作
|
||||
|
||||
### 2.4 重构 ProviderList
|
||||
|
||||
- [ ] 创建 `src/components/providers/ProviderList.tsx`
|
||||
- [ ] 使用 mutation hooks 处理操作
|
||||
- [ ] 移除 onNotify prop
|
||||
- [ ] 移除手动状态管理
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证供应商列表渲染
|
||||
- [ ] 验证切换操作
|
||||
- [ ] 验证删除操作
|
||||
|
||||
### 2.5 重构表单系统
|
||||
|
||||
- [ ] 创建 `src/lib/schemas/provider.ts` (Zod schema)
|
||||
- [ ] 创建 `src/components/providers/ProviderForm.tsx`
|
||||
- [ ] 使用 react-hook-form
|
||||
- [ ] 使用 zodResolver
|
||||
- [ ] 字段级验证
|
||||
|
||||
- [ ] 创建 `src/components/providers/AddProviderDialog.tsx`
|
||||
- [ ] 使用新的 Dialog 组件
|
||||
- [ ] 集成 ProviderForm
|
||||
- [ ] 使用 useAddProviderMutation
|
||||
|
||||
- [ ] 创建 `src/components/providers/EditProviderDialog.tsx`
|
||||
- [ ] 使用新的 Dialog 组件
|
||||
- [ ] 集成 ProviderForm
|
||||
- [ ] 使用 useUpdateProviderMutation
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证表单验证正常工作
|
||||
- [ ] 验证错误提示显示正确
|
||||
- [ ] 验证提交操作成功
|
||||
- [ ] 验证表单重置功能
|
||||
|
||||
### 2.6 清理旧组件
|
||||
|
||||
- [ ] 删除 `src/components/AddProviderModal.tsx`
|
||||
- [ ] 删除 `src/components/EditProviderModal.tsx`
|
||||
- [ ] 更新所有引用这些组件的地方
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 3: 设置和辅助功能 (预计 2-3 天)
|
||||
|
||||
### 3.1 重构 SettingsDialog
|
||||
|
||||
- [ ] 创建 `src/components/settings/SettingsDialog.tsx`
|
||||
- [ ] 使用 Tabs 组件
|
||||
- [ ] 集成各个设置子组件
|
||||
|
||||
- [ ] 创建 `src/components/settings/GeneralSettings.tsx`
|
||||
- [ ] 语言设置
|
||||
- [ ] 配置目录设置
|
||||
- [ ] 其他通用设置
|
||||
|
||||
- [ ] 创建 `src/components/settings/AboutSection.tsx`
|
||||
- [ ] 版本信息
|
||||
- [ ] 更新检查
|
||||
- [ ] 链接
|
||||
|
||||
- [ ] 创建 `src/components/settings/ImportExportSection.tsx`
|
||||
- [ ] 导入功能
|
||||
- [ ] 导出功能
|
||||
|
||||
**目标**: 将 643 行拆分为 4-5 个小组件，每个 100-150 行
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证设置保存功能
|
||||
- [ ] 验证导入导出功能
|
||||
- [ ] 验证更新检查功能
|
||||
|
||||
### 3.2 重构通知系统
|
||||
|
||||
- [ ] 在所有 mutations 中使用 `toast` 替代 `showNotification`
|
||||
- [ ] 移除 App.tsx 中的 notification 状态
|
||||
- [ ] 移除自定义通知组件
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证成功通知显示
|
||||
- [ ] 验证错误通知显示
|
||||
- [ ] 验证通知自动消失
|
||||
|
||||
### 3.3 重构确认对话框
|
||||
|
||||
- [ ] 更新 `src/components/ConfirmDialog.tsx` 使用新的 Dialog
|
||||
- [ ] 或者直接使用 shadcn/ui 的 AlertDialog
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证删除确认对话框
|
||||
- [ ] 验证其他确认场景
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 4: 清理和优化 (预计 1-2 天)
|
||||
|
||||
### 4.1 移除旧代码
|
||||
|
||||
- [ ] 删除 `src/lib/styles.ts`
|
||||
- [ ] 从 `src/lib/tauri-api.ts` 移除 `window.api` 绑定
|
||||
- [ ] 精简 `src/lib/tauri-api.ts`，只保留事件监听相关
|
||||
- [ ] 删除或更新 `src/vite-env.d.ts` 中的过时类型
|
||||
|
||||
### 4.2 代码审查
|
||||
|
||||
- [ ] 检查所有 TODO 注释
|
||||
- [ ] 检查是否还有 `window.api` 调用
|
||||
- [ ] 检查是否还有手动状态管理
|
||||
- [ ] 统一代码风格
|
||||
|
||||
### 4.3 类型检查
|
||||
|
||||
- [ ] 运行 `pnpm typecheck` 确保无错误
|
||||
- [ ] 修复所有类型错误
|
||||
- [ ] 更新类型定义
|
||||
|
||||
### 4.4 性能优化
|
||||
|
||||
- [ ] 检查是否有不必要的重渲染
|
||||
- [ ] 添加必要的 React.memo
|
||||
- [ ] 优化 Query 缓存配置
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 5: 测试和修复 (预计 2-3 天)
|
||||
|
||||
### 5.1 功能测试
|
||||
|
||||
#### 供应商管理
|
||||
- [ ] 添加供应商 (Claude)
|
||||
- [ ] 添加供应商 (Codex)
|
||||
- [ ] 编辑供应商
|
||||
- [ ] 删除供应商
|
||||
- [ ] 切换供应商
|
||||
- [ ] 导入默认配置
|
||||
|
||||
#### 应用切换
|
||||
- [ ] Claude <-> Codex 切换
|
||||
- [ ] 切换后数据正确加载
|
||||
- [ ] 切换后托盘菜单更新
|
||||
|
||||
#### 设置
|
||||
- [ ] 保存通用设置
|
||||
- [ ] 切换语言
|
||||
- [ ] 配置目录选择
|
||||
- [ ] 导入配置
|
||||
- [ ] 导出配置
|
||||
|
||||
#### UI 交互
|
||||
- [ ] 主题切换 (亮色/暗色)
|
||||
- [ ] 对话框打开/关闭
|
||||
- [ ] 表单验证
|
||||
- [ ] Toast 通知
|
||||
|
||||
#### MCP 管理
|
||||
- [ ] 列表显示
|
||||
- [ ] 添加 MCP
|
||||
- [ ] 编辑 MCP
|
||||
- [ ] 删除 MCP
|
||||
- [ ] 启用/禁用 MCP
|
||||
|
||||
### 5.2 边界情况测试
|
||||
|
||||
- [ ] 空供应商列表
|
||||
- [ ] 无效配置文件
|
||||
- [ ] 网络错误
|
||||
- [ ] 后端错误响应
|
||||
- [ ] 并发操作
|
||||
- [ ] 表单输入边界值
|
||||
|
||||
### 5.3 兼容性测试
|
||||
|
||||
- [ ] Windows 测试
|
||||
- [ ] macOS 测试
|
||||
- [ ] Linux 测试
|
||||
|
||||
### 5.4 性能测试
|
||||
|
||||
- [ ] 100+ 供应商加载速度
|
||||
- [ ] 快速切换供应商
|
||||
- [ ] 内存使用情况
|
||||
- [ ] CPU 使用情况
|
||||
|
||||
### 5.5 Bug 修复
|
||||
|
||||
**Bug 列表** (发现后记录):
|
||||
|
||||
1. ___________
|
||||
- [ ] 已修复
|
||||
- [ ] 已验证
|
||||
|
||||
2. ___________
|
||||
- [ ] 已修复
|
||||
- [ ] 已验证
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 最终检查
|
||||
|
||||
### 代码质量
|
||||
|
||||
- [ ] 所有 TypeScript 错误已修复
|
||||
- [ ] 运行 `pnpm format` 格式化代码
|
||||
- [ ] 运行 `pnpm typecheck` 通过
|
||||
- [ ] 代码审查完成
|
||||
|
||||
### 文档更新
|
||||
|
||||
- [ ] 更新 `CLAUDE.md` 反映新架构
|
||||
- [ ] 更新 `README.md` (如有必要)
|
||||
- [ ] 添加 Migration Guide (可选)
|
||||
|
||||
### 性能基准
|
||||
|
||||
记录性能数据:
|
||||
|
||||
**旧版本**:
|
||||
- 启动时间: _____ms
|
||||
- 供应商加载: _____ms
|
||||
- 内存占用: _____MB
|
||||
|
||||
**新版本**:
|
||||
- 启动时间: _____ms
|
||||
- 供应商加载: _____ms
|
||||
- 内存占用: _____MB
|
||||
|
||||
### 代码统计
|
||||
|
||||
**代码行数对比**:
|
||||
|
||||
| 文件 | 旧版本 | 新版本 | 减少 |
|
||||
|------|--------|--------|------|
|
||||
| App.tsx | 412 | ~100 | -76% |
|
||||
| tauri-api.ts | 712 | ~50 | -93% |
|
||||
| ProviderForm.tsx | 271 | ~150 | -45% |
|
||||
| SettingsModal.tsx | 643 | ~400 (拆分) | -38% |
|
||||
| **总计** | 2038 | ~700 | **-66%** |
|
||||
|
||||
---
|
||||
|
||||
## 📦 发布准备
|
||||
|
||||
### Pre-release 测试
|
||||
|
||||
- [ ] 创建 beta 版本 `v4.0.0-beta.1`
|
||||
- [ ] 在测试环境验证
|
||||
- [ ] 收集用户反馈
|
||||
|
||||
### 正式发布
|
||||
|
||||
- [ ] 合并到 main 分支
|
||||
- [ ] 创建 Release Tag `v4.0.0`
|
||||
- [ ] 更新 Changelog
|
||||
- [ ] 发布 GitHub Release
|
||||
- [ ] 通知用户更新
|
||||
|
||||
---
|
||||
|
||||
## 🚨 回滚触发条件
|
||||
|
||||
如果出现以下情况，考虑回滚:
|
||||
|
||||
- [ ] 重大功能无法使用
|
||||
- [ ] 用户数据丢失
|
||||
- [ ] 严重性能问题
|
||||
- [ ] 无法修复的兼容性问题
|
||||
|
||||
**回滚命令**:
|
||||
```bash
|
||||
git reset --hard backup-before-refactor
|
||||
# 或
|
||||
git revert <commit-range>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 总结报告
|
||||
|
||||
### 成功指标
|
||||
|
||||
- [ ] 所有现有功能正常工作
|
||||
- [ ] 代码量减少 40%+
|
||||
- [ ] 无用户数据丢失
|
||||
- [ ] 性能未下降
|
||||
|
||||
### 经验教训
|
||||
|
||||
**遇到的主要挑战**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
**解决方案**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
**未来改进**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
---
|
||||
|
||||
**重构完成日期**: ___________
|
||||
**总耗时**: _____ 天
|
||||
**参与人员**: ___________
|
||||
1679
docs/REFACTORING_MASTER_PLAN.md
Normal file
1679
docs/REFACTORING_MASTER_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
834
docs/REFACTORING_REFERENCE.md
Normal file
834
docs/REFACTORING_REFERENCE.md
Normal file
@@ -0,0 +1,834 @@
|
||||
# 重构快速参考指南
|
||||
|
||||
> 常见模式和代码示例的速查表
|
||||
|
||||
---
|
||||
|
||||
## 📑 目录
|
||||
|
||||
1. [React Query 使用](#react-query-使用)
|
||||
2. [react-hook-form 使用](#react-hook-form-使用)
|
||||
3. [shadcn/ui 组件使用](#shadcnui-组件使用)
|
||||
4. [代码迁移示例](#代码迁移示例)
|
||||
|
||||
---
|
||||
|
||||
## React Query 使用
|
||||
|
||||
### 基础查询
|
||||
|
||||
```typescript
|
||||
// 定义查询 Hook
|
||||
export const useProvidersQuery = (appType: AppType) => {
|
||||
return useQuery({
|
||||
queryKey: ['providers', appType],
|
||||
queryFn: async () => {
|
||||
const data = await providersApi.getAll(appType)
|
||||
return data
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// 在组件中使用
|
||||
function MyComponent() {
|
||||
const { data, isLoading, error } = useProvidersQuery('claude')
|
||||
|
||||
if (isLoading) return <div>Loading...</div>
|
||||
if (error) return <div>Error: {error.message}</div>
|
||||
|
||||
return <div>{/* 使用 data */}</div>
|
||||
}
|
||||
```
|
||||
|
||||
### Mutation (变更操作)
|
||||
|
||||
```typescript
|
||||
// 定义 Mutation Hook
|
||||
export const useAddProviderMutation = (appType: AppType) => {
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
return useMutation({
|
||||
mutationFn: async (provider: Provider) => {
|
||||
return await providersApi.add(provider, appType)
|
||||
},
|
||||
onSuccess: () => {
|
||||
// 重新获取数据
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appType] })
|
||||
toast.success('添加成功')
|
||||
},
|
||||
onError: (error: Error) => {
|
||||
toast.error(`添加失败: ${error.message}`)
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// 在组件中使用
|
||||
function AddProviderDialog() {
|
||||
const mutation = useAddProviderMutation('claude')
|
||||
|
||||
const handleSubmit = (data: Provider) => {
|
||||
mutation.mutate(data)
|
||||
}
|
||||
|
||||
return (
|
||||
<button
|
||||
onClick={() => handleSubmit(formData)}
|
||||
disabled={mutation.isPending}
|
||||
>
|
||||
{mutation.isPending ? '添加中...' : '添加'}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 乐观更新
|
||||
|
||||
```typescript
|
||||
export const useSwitchProviderMutation = (appType: AppType) => {
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
return useMutation({
|
||||
mutationFn: async (providerId: string) => {
|
||||
return await providersApi.switch(providerId, appType)
|
||||
},
|
||||
// 乐观更新: 在请求发送前立即更新 UI
|
||||
onMutate: async (providerId) => {
|
||||
// 取消正在进行的查询
|
||||
await queryClient.cancelQueries({ queryKey: ['providers', appType] })
|
||||
|
||||
// 保存当前数据(以便回滚)
|
||||
const previousData = queryClient.getQueryData(['providers', appType])
|
||||
|
||||
// 乐观更新
|
||||
queryClient.setQueryData(['providers', appType], (old: any) => ({
|
||||
...old,
|
||||
currentProviderId: providerId,
|
||||
}))
|
||||
|
||||
return { previousData }
|
||||
},
|
||||
// 如果失败，回滚
|
||||
onError: (err, providerId, context) => {
|
||||
queryClient.setQueryData(['providers', appType], context?.previousData)
|
||||
toast.error('切换失败')
|
||||
},
|
||||
// 无论成功失败，都重新获取数据
|
||||
onSettled: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appType] })
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖查询
|
||||
|
||||
```typescript
|
||||
// 第二个查询依赖第一个查询的结果
|
||||
const { data: providers } = useProvidersQuery(appType)
|
||||
const currentProviderId = providers?.currentProviderId
|
||||
|
||||
const { data: currentProvider } = useQuery({
|
||||
queryKey: ['provider', currentProviderId],
|
||||
queryFn: () => providersApi.getById(currentProviderId!),
|
||||
enabled: !!currentProviderId, // 只有当 ID 存在时才执行
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## react-hook-form 使用
|
||||
|
||||
### 基础表单
|
||||
|
||||
```typescript
|
||||
import { useForm } from 'react-hook-form'
|
||||
import { zodResolver } from '@hookform/resolvers/zod'
|
||||
import { z } from 'zod'
|
||||
|
||||
// 定义验证 schema
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, '请输入名称'),
|
||||
email: z.string().email('邮箱格式不正确'),
|
||||
age: z.number().min(18, '年龄必须大于18'),
|
||||
})
|
||||
|
||||
type FormData = z.infer<typeof schema>
|
||||
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>({
|
||||
resolver: zodResolver(schema),
|
||||
defaultValues: {
|
||||
name: '',
|
||||
email: '',
|
||||
age: 0,
|
||||
},
|
||||
})
|
||||
|
||||
const onSubmit = (data: FormData) => {
|
||||
console.log(data)
|
||||
}
|
||||
|
||||
return (
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<input {...form.register('name')} />
|
||||
{form.formState.errors.name && (
|
||||
<span>{form.formState.errors.name.message}</span>
|
||||
)}
|
||||
|
||||
<button type="submit">提交</button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 shadcn/ui Form 组件
|
||||
|
||||
```typescript
|
||||
import { useForm } from 'react-hook-form'
|
||||
import { zodResolver } from '@hookform/resolvers/zod'
|
||||
import {
|
||||
Form,
|
||||
FormControl,
|
||||
FormField,
|
||||
FormItem,
|
||||
FormLabel,
|
||||
FormMessage,
|
||||
} from '@/components/ui/form'
|
||||
import { Input } from '@/components/ui/input'
|
||||
import { Button } from '@/components/ui/button'
|
||||
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>({
|
||||
resolver: zodResolver(schema),
|
||||
})
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="name"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormLabel>名称</FormLabel>
|
||||
<FormControl>
|
||||
<Input placeholder="请输入名称" {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<Button type="submit">提交</Button>
|
||||
</form>
|
||||
</Form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 动态表单验证
|
||||
|
||||
```typescript
|
||||
// 根据条件动态验证
|
||||
const schema = z.object({
|
||||
type: z.enum(['official', 'custom']),
|
||||
apiKey: z.string().optional(),
|
||||
baseUrl: z.string().optional(),
|
||||
}).refine(
|
||||
(data) => {
|
||||
// 如果是自定义供应商，必须填写 baseUrl
|
||||
if (data.type === 'custom') {
|
||||
return !!data.baseUrl
|
||||
}
|
||||
return true
|
||||
},
|
||||
{
|
||||
message: '自定义供应商必须填写 Base URL',
|
||||
path: ['baseUrl'],
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### 手动触发验证
|
||||
|
||||
```typescript
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>()
|
||||
|
||||
const handleBlur = async () => {
|
||||
// 验证单个字段
|
||||
await form.trigger('name')
|
||||
|
||||
// 验证多个字段
|
||||
await form.trigger(['name', 'email'])
|
||||
|
||||
// 验证所有字段
|
||||
const isValid = await form.trigger()
|
||||
}
|
||||
|
||||
return <form>...</form>
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## shadcn/ui 组件使用
|
||||
|
||||
### Dialog (对话框)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Dialog,
|
||||
DialogContent,
|
||||
DialogHeader,
|
||||
DialogTitle,
|
||||
DialogDescription,
|
||||
DialogFooter,
|
||||
} from '@/components/ui/dialog'
|
||||
import { Button } from '@/components/ui/button'
|
||||
|
||||
function MyDialog() {
|
||||
const [open, setOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<Dialog open={open} onOpenChange={setOpen}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>标题</DialogTitle>
|
||||
<DialogDescription>描述信息</DialogDescription>
|
||||
</DialogHeader>
|
||||
|
||||
{/* 内容 */}
|
||||
<div>对话框内容</div>
|
||||
|
||||
<DialogFooter>
|
||||
<Button variant="outline" onClick={() => setOpen(false)}>
|
||||
取消
|
||||
</Button>
|
||||
<Button onClick={handleConfirm}>确认</Button>
|
||||
</DialogFooter>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Select (选择器)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Select,
|
||||
SelectContent,
|
||||
SelectItem,
|
||||
SelectTrigger,
|
||||
SelectValue,
|
||||
} from '@/components/ui/select'
|
||||
|
||||
function MySelect() {
|
||||
const [value, setValue] = useState('')
|
||||
|
||||
return (
|
||||
<Select value={value} onValueChange={setValue}>
|
||||
<SelectTrigger>
|
||||
<SelectValue placeholder="请选择" />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
<SelectItem value="option1">选项1</SelectItem>
|
||||
<SelectItem value="option2">选项2</SelectItem>
|
||||
<SelectItem value="option3">选项3</SelectItem>
|
||||
</SelectContent>
|
||||
</Select>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Tabs (标签页)
|
||||
|
||||
```typescript
|
||||
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
|
||||
|
||||
function MyTabs() {
|
||||
return (
|
||||
<Tabs defaultValue="tab1">
|
||||
<TabsList>
|
||||
<TabsTrigger value="tab1">标签1</TabsTrigger>
|
||||
<TabsTrigger value="tab2">标签2</TabsTrigger>
|
||||
<TabsTrigger value="tab3">标签3</TabsTrigger>
|
||||
</TabsList>
|
||||
|
||||
<TabsContent value="tab1">
|
||||
<div>标签1的内容</div>
|
||||
</TabsContent>
|
||||
|
||||
<TabsContent value="tab2">
|
||||
<div>标签2的内容</div>
|
||||
</TabsContent>
|
||||
|
||||
<TabsContent value="tab3">
|
||||
<div>标签3的内容</div>
|
||||
</TabsContent>
|
||||
</Tabs>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Toast 通知 (Sonner)
|
||||
|
||||
```typescript
|
||||
import { toast } from 'sonner'
|
||||
|
||||
// 成功通知
|
||||
toast.success('操作成功')
|
||||
|
||||
// 错误通知
|
||||
toast.error('操作失败')
|
||||
|
||||
// 加载中
|
||||
const toastId = toast.loading('处理中...')
|
||||
// 完成后更新
|
||||
toast.success('处理完成', { id: toastId })
|
||||
// 或
|
||||
toast.dismiss(toastId)
|
||||
|
||||
// 自定义持续时间
|
||||
toast.success('消息', { duration: 5000 })
|
||||
|
||||
// 带操作按钮
|
||||
toast('确认删除?', {
|
||||
action: {
|
||||
label: '删除',
|
||||
onClick: () => handleDelete(),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 代码迁移示例
|
||||
|
||||
### 示例 1: 状态管理迁移
|
||||
|
||||
**旧代码** (手动状态管理):
|
||||
|
||||
```typescript
|
||||
const [providers, setProviders] = useState<Record<string, Provider>>({})
|
||||
const [currentProviderId, setCurrentProviderId] = useState('')
|
||||
const [loading, setLoading] = useState(false)
|
||||
const [error, setError] = useState<Error | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
const load = async () => {
|
||||
setLoading(true)
|
||||
setError(null)
|
||||
try {
|
||||
const data = await window.api.getProviders(appType)
|
||||
const currentId = await window.api.getCurrentProvider(appType)
|
||||
setProviders(data)
|
||||
setCurrentProviderId(currentId)
|
||||
} catch (err) {
|
||||
setError(err as Error)
|
||||
} finally {
|
||||
setLoading(false)
|
||||
}
|
||||
}
|
||||
load()
|
||||
}, [appType])
|
||||
```
|
||||
|
||||
**新代码** (React Query):
|
||||
|
||||
```typescript
|
||||
const { data, isLoading, error } = useProvidersQuery(appType)
|
||||
const providers = data?.providers || {}
|
||||
const currentProviderId = data?.currentProviderId || ''
|
||||
```
|
||||
|
||||
**减少**: 从 20+ 行到 3 行
|
||||
|
||||
---
|
||||
|
||||
### 示例 2: 表单验证迁移
|
||||
|
||||
**旧代码** (手动验证):
|
||||
|
||||
```typescript
|
||||
const [name, setName] = useState('')
|
||||
const [nameError, setNameError] = useState('')
|
||||
const [apiKey, setApiKey] = useState('')
|
||||
const [apiKeyError, setApiKeyError] = useState('')
|
||||
|
||||
const validate = () => {
|
||||
let valid = true
|
||||
|
||||
if (!name.trim()) {
|
||||
setNameError('请输入名称')
|
||||
valid = false
|
||||
} else {
|
||||
setNameError('')
|
||||
}
|
||||
|
||||
if (!apiKey.trim()) {
|
||||
setApiKeyError('请输入 API Key')
|
||||
valid = false
|
||||
} else if (apiKey.length < 10) {
|
||||
setApiKeyError('API Key 长度不足')
|
||||
valid = false
|
||||
} else {
|
||||
setApiKeyError('')
|
||||
}
|
||||
|
||||
return valid
|
||||
}
|
||||
|
||||
const handleSubmit = () => {
|
||||
if (validate()) {
|
||||
// 提交
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<form>
|
||||
<input value={name} onChange={e => setName(e.target.value)} />
|
||||
{nameError && <span>{nameError}</span>}
|
||||
|
||||
<input value={apiKey} onChange={e => setApiKey(e.target.value)} />
|
||||
{apiKeyError && <span>{apiKeyError}</span>}
|
||||
|
||||
<button onClick={handleSubmit}>提交</button>
|
||||
</form>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (react-hook-form + zod):
|
||||
|
||||
```typescript
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, '请输入名称'),
|
||||
apiKey: z.string().min(10, 'API Key 长度不足'),
|
||||
})
|
||||
|
||||
const form = useForm({
|
||||
resolver: zodResolver(schema),
|
||||
})
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="name"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="apiKey"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<Button type="submit">提交</Button>
|
||||
</form>
|
||||
</Form>
|
||||
)
|
||||
```
|
||||
|
||||
**减少**: 从 40+ 行到 30 行，且更健壮
|
||||
|
||||
---
|
||||
|
||||
### 示例 3: 通知系统迁移
|
||||
|
||||
**旧代码** (自定义通知):
|
||||
|
||||
```typescript
|
||||
const [notification, setNotification] = useState<{
|
||||
message: string
|
||||
type: 'success' | 'error'
|
||||
} | null>(null)
|
||||
const [isVisible, setIsVisible] = useState(false)
|
||||
|
||||
const showNotification = (message: string, type: 'success' | 'error') => {
|
||||
setNotification({ message, type })
|
||||
setIsVisible(true)
|
||||
setTimeout(() => {
|
||||
setIsVisible(false)
|
||||
setTimeout(() => setNotification(null), 300)
|
||||
}, 3000)
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
{notification && (
|
||||
<div className={`notification ${isVisible ? 'visible' : ''} ${notification.type}`}>
|
||||
{notification.message}
|
||||
</div>
|
||||
)}
|
||||
{/* 其他内容 */}
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (Sonner):
|
||||
|
||||
```typescript
|
||||
import { toast } from 'sonner'
|
||||
|
||||
// 在需要的地方直接调用
|
||||
toast.success('操作成功')
|
||||
toast.error('操作失败')
|
||||
|
||||
// 在 main.tsx 中只需添加一次
|
||||
import { Toaster } from '@/components/ui/sonner'
|
||||
|
||||
<Toaster />
|
||||
```
|
||||
|
||||
**减少**: 从 20+ 行到 1 行调用
|
||||
|
||||
---
|
||||
|
||||
### 示例 4: 对话框迁移
|
||||
|
||||
**旧代码** (自定义 Modal):
|
||||
|
||||
```typescript
|
||||
const [isOpen, setIsOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<>
|
||||
<button onClick={() => setIsOpen(true)}>打开</button>
|
||||
|
||||
{isOpen && (
|
||||
<div className="modal-backdrop" onClick={() => setIsOpen(false)}>
|
||||
<div className="modal-content" onClick={e => e.stopPropagation()}>
|
||||
<div className="modal-header">
|
||||
<h2>标题</h2>
|
||||
<button onClick={() => setIsOpen(false)}>×</button>
|
||||
</div>
|
||||
<div className="modal-body">
|
||||
{/* 内容 */}
|
||||
</div>
|
||||
<div className="modal-footer">
|
||||
<button onClick={() => setIsOpen(false)}>取消</button>
|
||||
<button onClick={handleConfirm}>确认</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (shadcn/ui Dialog):
|
||||
|
||||
```typescript
|
||||
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
|
||||
|
||||
const [isOpen, setIsOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<>
|
||||
<Button onClick={() => setIsOpen(true)}>打开</Button>
|
||||
|
||||
<Dialog open={isOpen} onOpenChange={setIsOpen}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>标题</DialogTitle>
|
||||
</DialogHeader>
|
||||
{/* 内容 */}
|
||||
<DialogFooter>
|
||||
<Button variant="outline" onClick={() => setIsOpen(false)}>取消</Button>
|
||||
<Button onClick={handleConfirm}>确认</Button>
|
||||
</DialogFooter>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 无需自定义样式
|
||||
- 内置无障碍支持
|
||||
- 自动管理焦点和 ESC 键
|
||||
|
||||
---
|
||||
|
||||
### 示例 5: API 调用迁移
|
||||
|
||||
**旧代码** (window.api):
|
||||
|
||||
```typescript
|
||||
// 添加供应商
|
||||
const handleAdd = async (provider: Provider) => {
|
||||
try {
|
||||
await window.api.addProvider(provider, appType)
|
||||
await loadProviders()
|
||||
showNotification('添加成功', 'success')
|
||||
} catch (error) {
|
||||
showNotification('添加失败', 'error')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新代码** (React Query Mutation):
|
||||
|
||||
```typescript
|
||||
// 在组件中
|
||||
const addMutation = useAddProviderMutation(appType)
|
||||
|
||||
const handleAdd = (provider: Provider) => {
|
||||
addMutation.mutate(provider)
|
||||
// 成功和错误处理已在 mutation 定义中处理
|
||||
}
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 自动处理 loading 状态
|
||||
- 统一的错误处理
|
||||
- 自动刷新数据
|
||||
- 更少的样板代码
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何在 mutation 成功后关闭对话框?
|
||||
|
||||
```typescript
|
||||
const mutation = useAddProviderMutation(appType)
|
||||
|
||||
const handleSubmit = (data: Provider) => {
|
||||
mutation.mutate(data, {
|
||||
onSuccess: () => {
|
||||
setIsOpen(false) // 关闭对话框
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Q: 如何在表单中使用异步验证?
|
||||
|
||||
```typescript
|
||||
const schema = z.object({
|
||||
name: z.string().refine(
|
||||
async (name) => {
|
||||
// 检查名称是否已存在
|
||||
const exists = await checkNameExists(name)
|
||||
return !exists
|
||||
},
|
||||
{ message: '名称已存在' }
|
||||
),
|
||||
})
|
||||
```
|
||||
|
||||
### Q: 如何手动刷新 Query 数据?
|
||||
|
||||
```typescript
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
// 方式1: 使缓存失效，触发重新获取
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appType] })
|
||||
|
||||
// 方式2: 直接刷新
|
||||
queryClient.refetchQueries({ queryKey: ['providers', appType] })
|
||||
|
||||
// 方式3: 更新缓存数据
|
||||
queryClient.setQueryData(['providers', appType], newData)
|
||||
```
|
||||
|
||||
### Q: 如何在组件外部使用 toast?
|
||||
|
||||
```typescript
|
||||
// 直接导入并使用即可
|
||||
import { toast } from 'sonner'
|
||||
|
||||
export const someUtil = () => {
|
||||
toast.success('工具函数中的通知')
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### React Query DevTools
|
||||
|
||||
```typescript
|
||||
// 在 main.tsx 中添加
|
||||
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
|
||||
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<App />
|
||||
<ReactQueryDevtools initialIsOpen={false} />
|
||||
</QueryClientProvider>
|
||||
```
|
||||
|
||||
### 查看表单状态
|
||||
|
||||
```typescript
|
||||
const form = useForm()
|
||||
|
||||
// 在开发模式下打印表单状态
|
||||
console.log('Form values:', form.watch())
|
||||
console.log('Form errors:', form.formState.errors)
|
||||
console.log('Is valid:', form.formState.isValid)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 1. 避免不必要的重渲染
|
||||
|
||||
```typescript
|
||||
// 使用 React.memo
|
||||
export const ProviderCard = React.memo(({ provider, onEdit }: Props) => {
|
||||
// ...
|
||||
})
|
||||
|
||||
// 或使用 useMemo
|
||||
const sortedProviders = useMemo(
|
||||
() => Object.values(providers).sort(...),
|
||||
[providers]
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Query 配置优化
|
||||
|
||||
```typescript
|
||||
const { data } = useQuery({
|
||||
queryKey: ['providers', appType],
|
||||
queryFn: fetchProviders,
|
||||
staleTime: 1000 * 60 * 5, // 5分钟内不重新获取
|
||||
gcTime: 1000 * 60 * 10, // 10分钟后清除缓存
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 表单性能优化
|
||||
|
||||
```typescript
|
||||
// 使用 mode 控制验证时机
|
||||
const form = useForm({
|
||||
mode: 'onBlur', // 失去焦点时验证
|
||||
// mode: 'onChange', // 每次输入都验证(较慢)
|
||||
// mode: 'onSubmit', // 提交时验证(最快)
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**提示**: 将此文档保存在浏览器书签或编辑器中，方便随时查阅！
|
||||
Reference in New Issue
Block a user