@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/frontend-common-issues.md

@@ -0,0 +1,482 @@
+# 前端常见问题检查清单 (Frontend Common Issues)
+
+> 前端开发中经常出现的 Bug 和问题，代码审查时必须逐项检查。
+
+---
+
+## 🔴 P0 级问题 (必须修复)
+
+### 1. 状态管理问题
+
+#### 1.1 闭包陷阱 (Stale Closure)
+
+```typescript
+// ❌ 错误：闭包捕获了旧的 state 值
+const [count, setCount] = useState(0);
+
+useEffect(() => {
+  const timer = setInterval(() => {
+    console.log(count); // 永远是 0！
+    setCount(count + 1); // 永远设置为 1！
+  }, 1000);
+  return () => clearInterval(timer);
+}, []); // 空依赖数组导致闭包陷阱
+
+// ✅ 正确：使用函数式更新
+useEffect(() => {
+  const timer = setInterval(() => {
+    setCount(prev => prev + 1); // 使用最新值
+  }, 1000);
+  return () => clearInterval(timer);
+}, []);
+```
+
+**检查点**:
+- [ ] setInterval/setTimeout 中是否使用了函数式更新
+- [ ] 事件监听器中是否使用了 useCallback 或 useRef
+- [ ] 异步回调中是否依赖了可能过期的 state
+
+#### 1.2 useEffect 依赖缺失
+
+```typescript
+// ❌ 错误：缺少依赖
+const [userId, setUserId] = useState(1);
+const [user, setUser] = useState(null);
+
+useEffect(() => {
+  fetchUser(userId).then(setUser);
+}, []); // 缺少 userId 依赖！userId 变化不会重新获取
+
+// ✅ 正确：包含所有依赖
+useEffect(() => {
+  fetchUser(userId).then(setUser);
+}, [userId]);
+```
+
+**检查点**:
+- [ ] useEffect 依赖数组是否包含所有使用的变量
+- [ ] ESLint exhaustive-deps 规则是否启用
+- [ ] 是否有 // eslint-disable-next-line 注释绕过检查
+
+#### 1.3 useEffect 清理缺失
+
+```typescript
+// ❌ 错误：没有清理订阅
+useEffect(() => {
+  const subscription = eventBus.subscribe('event', handler);
+  // 组件卸载后 handler 仍会被调用！
+}, []);
+
+// ✅ 正确：清理订阅
+useEffect(() => {
+  const subscription = eventBus.subscribe('event', handler);
+  return () => subscription.unsubscribe();
+}, []);
+```
+
+**检查点**:
+- [ ] WebSocket 连接是否在卸载时关闭
+- [ ] 定时器是否在卸载时清除
+- [ ] 事件监听是否在卸载时移除
+- [ ] 异步请求是否有取消机制
+
+#### 1.4 竞态条件 (Race Condition)
+
+```typescript
+// ❌ 错误：快速切换 userId 可能显示错误数据
+useEffect(() => {
+  fetchUser(userId).then(setUser);
+}, [userId]);
+
+// ✅ 正确：使用标志位或 AbortController
+useEffect(() => {
+  let cancelled = false;
+  fetchUser(userId).then(data => {
+    if (!cancelled) setUser(data);
+  });
+  return () => { cancelled = true; };
+}, [userId]);
+
+// ✅ 更好：使用 AbortController
+useEffect(() => {
+  const controller = new AbortController();
+  fetchUser(userId, { signal: controller.signal })
+    .then(setUser)
+    .catch(e => {
+      if (e.name !== 'AbortError') throw e;
+    });
+  return () => controller.abort();
+}, [userId]);
+```
+
+**检查点**:
+- [ ] 快速切换参数时是否会显示错误数据
+- [ ] 是否有取消机制防止过期响应更新状态
+
+---
+
+### 2. 表单处理问题
+
+#### 2.1 表单重复提交
+
+```typescript
+// ❌ 错误：没有防重复提交
+const handleSubmit = async () => {
+  await api.submit(formData);
+};
+
+// ✅ 正确：禁用按钮 + loading 状态
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+const handleSubmit = async () => {
+  if (isSubmitting) return;
+  setIsSubmitting(true);
+  try {
+    await api.submit(formData);
+  } finally {
+    setIsSubmitting(false);
+  }
+};
+
+<button disabled={isSubmitting} onClick={handleSubmit}>
+  {isSubmitting ? '提交中...' : '提交'}
+</button>
+```
+
+**检查点**:
+- [ ] 提交按钮是否在请求期间禁用
+- [ ] 是否有 loading 状态提示
+- [ ] 是否防止了快速双击
+
+#### 2.2 表单验证缺失
+
+```typescript
+// ❌ 错误：没有前端验证
+const handleSubmit = () => {
+  api.submit({ email, password }); // 直接提交
+};
+
+// ✅ 正确：前端验证 + 错误提示
+const handleSubmit = () => {
+  const errors = {};
+  if (!email) errors.email = '邮箱不能为空';
+  if (!email.includes('@')) errors.email = '邮箱格式不正确';
+  if (!password) errors.password = '密码不能为空';
+  if (password.length < 8) errors.password = '密码至少8位';
+
+  if (Object.keys(errors).length > 0) {
+    setErrors(errors);
+    return;
+  }
+  api.submit({ email, password });
+};
+```
+
+**检查点**:
+- [ ] 必填字段是否有验证
+- [ ] 格式验证是否完整（邮箱、手机号、身份证等）
+- [ ] 错误信息是否清晰显示
+- [ ] 验证失败时是否阻止提交
+
+---
+
+### 3. 异步处理问题
+
+#### 3.1 Promise 错误未捕获
+
+```typescript
+// ❌ 错误：Promise 错误未处理
+const fetchData = async () => {
+  const data = await api.getData(); // 如果失败，错误被吞掉
+  setData(data);
+};
+
+// ✅ 正确：捕获并处理错误
+const fetchData = async () => {
+  try {
+    const data = await api.getData();
+    setData(data);
+  } catch (error) {
+    setError(error.message);
+    toast.error('获取数据失败');
+  }
+};
+```
+
+**检查点**:
+- [ ] 所有 async 函数是否有 try-catch
+- [ ] 所有 Promise 是否有 .catch()
+- [ ] 错误是否有用户友好的提示
+
+#### 3.2 Loading 状态缺失
+
+```typescript
+// ❌ 错误：没有 loading 状态
+const [data, setData] = useState(null);
+
+useEffect(() => {
+  api.getData().then(setData);
+}, []);
+
+return <div>{data?.name}</div>; // 加载时显示空白
+
+// ✅ 正确：完整的状态处理
+const [data, setData] = useState(null);
+const [loading, setLoading] = useState(true);
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  setLoading(true);
+  api.getData()
+    .then(setData)
+    .catch(setError)
+    .finally(() => setLoading(false));
+}, []);
+
+if (loading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+if (!data) return <EmptyState />;
+return <div>{data.name}</div>;
+```
+
+**检查点**:
+- [ ] 是否有 loading 状态
+- [ ] 是否有 error 状态
+- [ ] 是否有 empty 状态
+- [ ] 状态切换是否平滑
+
+---
+
+### 4. 渲染问题
+
+#### 4.1 条件渲染短路问题
+
+```typescript
+// ❌ 错误：0 会被渲染出来
+const count = 0;
+return <div>{count && <span>Count: {count}</span>}</div>;
+// 渲染结果: <div>0</div>
+
+// ✅ 正确：使用三元运算符或 Boolean 转换
+return <div>{count > 0 && <span>Count: {count}</span>}</div>;
+// 或
+return <div>{Boolean(count) && <span>Count: {count}</span>}</div>;
+// 或
+return <div>{count ? <span>Count: {count}</span> : null}</div>;
+```
+
+**检查点**:
+- [ ] && 左侧是否可能是 0 或空字符串
+- [ ] 条件渲染是否使用了正确的方式
+
+#### 4.2 列表 key 问题
+
+```typescript
+// ❌ 错误：使用 index 作为 key
+{items.map((item, index) => (
+  <Item key={index} data={item} />
+))}
+
+// ✅ 正确：使用唯一标识
+{items.map(item => (
+  <Item key={item.id} data={item} />
+))}
+```
+
+**检查点**:
+- [ ] 列表是否使用了唯一且稳定的 key
+- [ ] key 是否避免使用 index（除非列表不会重排序）
+
+#### 4.3 无限渲染循环
+
+```typescript
+// ❌ 错误：每次渲染都创建新对象，触发无限循环
+const Component = () => {
+  const [data, setData] = useState({});
+
+  useEffect(() => {
+    setData({ ...data, updated: true }); // 无限循环！
+  }, [data]);
+};
+
+// ✅ 正确：使用函数式更新或正确的依赖
+useEffect(() => {
+  setData(prev => ({ ...prev, updated: true }));
+}, []); // 只执行一次
+```
+
+**检查点**:
+- [ ] useEffect 是否可能触发无限循环
+- [ ] setState 是否在 render 中直接调用
+
+---
+
+## 🟠 P1 级问题 (应该修复)
+
+### 5. 性能问题
+
+#### 5.1 不必要的重渲染
+
+```typescript
+// ❌ 错误：每次父组件渲染都创建新函数
+const Parent = () => {
+  const handleClick = () => console.log('clicked');
+  return <Child onClick={handleClick} />;
+};
+
+// ✅ 正确：使用 useCallback
+const Parent = () => {
+  const handleClick = useCallback(() => console.log('clicked'), []);
+  return <Child onClick={handleClick} />;
+};
+```
+
+**检查点**:
+- [ ] 传递给子组件的函数是否使用 useCallback
+- [ ] 传递给子组件的对象是否使用 useMemo
+- [ ] 子组件是否使用 React.memo
+
+#### 5.2 大列表未虚拟化
+
+```typescript
+// ❌ 错误：渲染 10000 个 DOM 节点
+{items.map(item => <Item key={item.id} data={item} />)}
+
+// ✅ 正确：使用虚拟列表
+import { FixedSizeList } from 'react-window';
+
+<FixedSizeList
+  height={400}
+  itemCount={items.length}
+  itemSize={50}
+>
+  {({ index, style }) => (
+    <Item style={style} data={items[index]} />
+  )}
+</FixedSizeList>
+```
+
+**检查点**:
+- [ ] 列表超过 100 项是否使用虚拟化
+- [ ] 表格数据量大时是否有分页或虚拟滚动
+
+---
+
+### 6. 用户体验问题
+
+#### 6.1 无障碍访问缺失
+
+```typescript
+// ❌ 错误：缺少无障碍属性
+<div onClick={handleClick}>点击我</div>
+
+// ✅ 正确：添加无障碍支持
+<button onClick={handleClick}>点击我</button>
+// 或
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={e => e.key === 'Enter' && handleClick()}
+>
+  点击我
+</div>
+```
+
+**检查点**:
+- [ ] 可点击元素是否使用 button 或有 role="button"
+- [ ] 图片是否有 alt 属性
+- [ ] 表单元素是否有 label
+- [ ] 颜色对比度是否足够
+
+#### 6.2 移动端适配问题
+
+```css
+/* ❌ 错误：点击区域太小 */
+.icon-button {
+  width: 24px;
+  height: 24px;
+}
+
+/* ✅ 正确：最小 44x44px */
+.icon-button {
+  width: 44px;
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+**检查点**:
+- [ ] 点击区域是否至少 44x44px
+- [ ] 是否有响应式布局
+- [ ] 输入框字体是否 >= 16px（防止 iOS 缩放）
+
+---
+
+### 7. 安全问题
+
+#### 7.1 XSS 风险
+
+```typescript
+// ❌ 危险：直接插入 HTML
+<div dangerouslySetInnerHTML={{ __html: userInput }} />
+
+// ✅ 安全：使用 DOMPurify 清理
+import DOMPurify from 'dompurify';
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userInput) }} />
+```
+
+**检查点**:
+- [ ] 是否使用了 dangerouslySetInnerHTML
+- [ ] 用户输入是否经过清理
+- [ ] URL 参数是否经过验证
+
+#### 7.2 敏感信息泄露
+
+```typescript
+// ❌ 错误：在前端存储敏感信息
+localStorage.setItem('password', password);
+console.log('API Key:', apiKey);
+
+// ✅ 正确：只存储必要的 token
+localStorage.setItem('accessToken', token);
+// 敏感信息只在内存中短暂存在
+```
+
+**检查点**:
+- [ ] localStorage 是否存储了敏感信息
+- [ ] console.log 是否输出了敏感信息
+- [ ] 错误信息是否暴露了内部细节
+
+---
+
+## 📋 前端检查清单汇总
+
+```markdown
+## 前端代码审查检查清单
+
+### P0 必须检查
+- [ ] 闭包陷阱：setInterval/setTimeout 中使用函数式更新
+- [ ] useEffect 依赖：依赖数组完整
+- [ ] useEffect 清理：订阅/定时器/连接正确清理
+- [ ] 竞态条件：快速切换不会显示错误数据
+- [ ] 表单重复提交：按钮禁用 + loading 状态
+- [ ] 表单验证：必填 + 格式验证
+- [ ] Promise 错误处理：try-catch 或 .catch()
+- [ ] Loading/Error/Empty 状态：三态完整
+
+### P1 应该检查
+- [ ] 条件渲染：&& 左侧不是 0 或空字符串
+- [ ] 列表 key：使用唯一标识
+- [ ] 无限循环：useEffect 不会无限触发
+- [ ] 性能优化：useCallback/useMemo/React.memo
+- [ ] 大列表：虚拟化或分页
+- [ ] 无障碍：button/role/alt/label
+- [ ] 移动端：点击区域 >= 44px
+
+### P0 安全检查
+- [ ] XSS：dangerouslySetInnerHTML 使用 DOMPurify
+- [ ] 敏感信息：不在 localStorage/console 暴露
+```