# Opik 前端 ## 架构决策 * **路由** ：TanStack 路由器（基于文件） * **数据获取**：TanStack 查询（从不原始获取/useEffect） * **State** : Zu 代表全局，React 状态代表本地 * **组件** : shadcn/ui + Radix UI 基础 * **Forms** : React Hook Form + Zod 验证 ## 关键问题 ### 切勿使用Effect 进行数据获取 // ❌ 不好使用效果（（）=> { fetch('/api/data').then(setData); }, []); // ✅ 好 const { 数据 } = useQuery({ 查询键：['数据']， queryFn：获取数据， }); ### 选择性记忆 // ✅ 使用 useMemo 进行：复杂计算、大数据转换 const 过滤 = useMemo(() => data.filter(x => x.status === '活动').map(transform), [数据] ）； // ✅ 使用 useCallback for：传递给子级的函数 const handleClick = useCallback(() => doSomething(id), [id]); // ❌ 不要记忆：简单值、原语、局部函数 const 名称 = 数据？.名称 ?? ''; // 不需要 useMemo ### Zustand 选择器 // ✅ GOOD - 特定选择器 const selectedEntity = useEntityStore(state => state.selectedEntity); // ❌ 不好 - 选择整个存储会导致重新渲染 const { selectedEntity, 过滤器 } = useEntityStore(); ## 层架构 ui → 共享 → 页面共享 → 页面（仅限单向） * 无循环依赖 * 没有跨页面导入 * 修改导入后：`npm run deps:validate` ## 州位置决策 * **URL状态**：过滤器、分页、所选项目 * **Zustand** ：用户偏好、跨组件状态 * **反应状态**：表单输入、UI 切换 ## 组件结构 const 组件：React.FC = ({ prop }) => { // 1. 状态钩子 // 2. 查询/变更 // 3. 记忆（仅在需要时） // 4. 事件处理程序 if (isLoading) 返回 ; if (错误) 返回 ; 返回

...

； }; ## 查询模式 // 带参数查询 const { 数据 } = useQuery({ 查询键：[ENTITY_KEY，参数]， queryFn：（上下文）=> fetchEntity（上下文，参数）， }); // 变异导致失效 const 突变 = useMutation({ 突变Fn：更新实体，成功：() => { queryClient.invalidateQueries({ queryKey: [ENTITY_KEY] }); }, }); ## 参考文件 * [forms.md]() \- React Hook Form + Zod 模式 * [ui-components.md]() \- 按钮变体、排版、深色主题 * [responsive-design.md]() \- Tailwind 断点与 useIsPhone * [testing.md]() \- 何时测试，Vitest 模式 * [code-quality.md]() \- Lodash 导入、命名、deps:validate * [performance.md]() \- 捆绑优化、渲染、记忆

Opik 前端

包含技能