# 前端开发规范 - CODING-STANDARDS-FRONTEND

**版本**: 2.0.0
**适用范围**: 前端开发岗位（Web/移动APP/桌面应用，技术栈无关）
**最后更新**: 2025-12-25

---

## 🚨 核心铁律（继承自 common.md）

> **必须遵循 common.md 的四大核心铁律**

```
铁律1: SPEC 是唯一真源（SSOT）
       - UI 实现必须符合 SPEC 定义
       - 交互、布局、样式以 SPEC 为准

铁律2: 智能复用与销毁重建
       - 现有组件完全匹配 → 直接复用
       - 部分匹配 → 删除重建，不做渐进式修改

铁律3: 禁止渐进式开发
       - 禁止在旧组件上添加新功能
       - 禁止保留兼容性代码

铁律4: Context7 调研先行
       - 使用成熟的 UI 库和组件
       - 禁止自己实现常见 UI 组件
```

---

## 🏗️ 组件设计

### 组件职责
- ✅ 单个组件文件 < 300行
- ✅ 组件只负责一个功能或UI片段
- ✅ 容器组件与展示组件分离
- ❌ 禁止"万能组件"包含多个不相关功能

### 组件层次
- ✅ 原子组件：按钮、输入框、图标（不可再分）
- ✅ 分子组件：搜索框 = 输入框 + 按钮
- ✅ 组织组件：头部 = Logo + 导航 + 搜索
- ✅ 嵌套层级 < 5层

### Props/接口设计
- ✅ 单个组件Props < 10个
- ✅ 必填和可选参数明确标注
- ✅ 布尔值使用 is/has/should 前缀
- ✅ 事件回调使用 on 前缀
- ✅ 使用类型定义（TypeScript/Flow/PropTypes）
- ❌ 禁止Props类型为any

---

## 📊 状态管理

### 状态原则
- ✅ 每个数据只有一个权威来源（Single Source of Truth）
- ✅ 只存储必要状态，能计算得出的不存储
- ✅ 共享状态提升到共同父组件
- ✅ 使用不可变更新（不直接修改state）
- ❌ 禁止在多处维护相同数据

### 数据流
- ✅ 数据从父组件流向子组件
- ✅ 事件从子组件流向父组件
- ✅ 状态变更触发UI更新
- ❌ 避免双向绑定的复杂性（除非框架强制）

---

## 🎨 HTML/CSS规范

### HTML语义化
- ✅ 使用语义化标签（header、nav、main、article、footer）
- ✅ 表单字段必须有label
- ✅ 图片必须有alt属性
- ✅ 通过W3C验证
- ❌ 避免过度使用div和span

### CSS命名
- ✅ 使用一致的命名方法（BEM、CSS Modules、CSS-in-JS）
- ✅ 样式作用域隔离，避免全局污染
- ✅ 类名语义化，表达用途而非样式
- ❌ 禁止内联样式（除非动态计算）

### 响应式设计
- ✅ 移动优先设计（Mobile First）
- ✅ 使用相对单位（rem、em、%、vh/vw）
- ✅ 使用媒体查询适配不同屏幕
- ✅ 测试常见设备尺寸（手机、平板、桌面）
- ✅ 触摸目标 ≥ 44x44px

---

## ⚡ 性能优化

### 渲染优化
- ✅ 避免不必要的重渲染（使用缓存机制）
- ✅ 列表渲染必须有唯一key
- ✅ 长列表（>100项）使用虚拟化
- ✅ 大数据集分页加载
- ❌ 禁止在渲染函数中定义组件

### 代码分割
- ✅ 路由级代码分割
- ✅ 大组件懒加载
- ✅ 第三方库按需引入
- ✅ 初始加载体积 < 200KB（gzip后）

### 资源优化
- ✅ 图片懒加载
- ✅ 使用现代图片格式（WebP、AVIF）
- ✅ 响应式图片（srcset）
- ✅ 压缩和优化资源
- ✅ 关键资源预加载（preload）

---

## ♿ 无障碍访问

### WCAG合规
- ✅ 键盘可访问（Tab导航）
- ✅ 屏幕阅读器友好（ARIA标签）
- ✅ 颜色对比度 ≥ 4.5:1（普通文本）
- ✅ 焦点可见（focus状态）
- ✅ 表单错误提示明确

### 常见要求
- ✅ 交互元素有焦点状态
- ✅ 按钮和链接有清晰文本
- ✅ 动态内容更新通知屏幕阅读器
- ❌ 禁止仅通过颜色区分状态

---

## 🔒 前端安全

### XSS防护
- ✅ 使用框架的自动转义
- ❌ 禁止使用危险的HTML注入API（如dangerouslySetInnerHTML）
- ✅ 用户输入必须验证和清理
- ✅ 设置CSP（Content Security Policy）

### CSRF防护
- ✅ 使用CSRF Token
- ✅ SameSite Cookie
- ✅ 验证请求来源

### 敏感数据
- ❌ 禁止在前端存储敏感信息（密码、完整身份证）
- ✅ Token存储在HttpOnly Cookie或安全存储
- ✅ HTTPS传输
- ✅ 敏感操作二次确认

---

## 🧪 前端测试

### 测试范围
- ✅ 组件渲染测试
- ✅ 用户交互测试
- ✅ 状态变化测试
- ✅ 边界情况和错误处理
- ❌ 避免测试实现细节

### 测试覆盖
- ✅ 关键业务组件必须有测试
- ✅ 工具函数必须有单元测试
- ✅ 跨浏览器测试
- ✅ 移动端测试

---

## 📋 前端开发检查清单

- [ ] 组件职责单一（< 300行）
- [ ] Props类型定义完整
- [ ] 状态管理清晰（单一数据源）
- [ ] HTML语义化标签
- [ ] CSS样式隔离
- [ ] 响应式设计
- [ ] 性能优化（懒加载、虚拟化）
- [ ] 无障碍访问（键盘、ARIA、对比度）
- [ ] XSS/CSRF防护
- [ ] 组件和工具函数有测试

---

---

## 🏛️ 高级架构模式（20+年经验）

### 微前端架构
```
✅ 适用场景：
- 多团队协作的大型应用
- 需要独立部署的模块
- 技术栈异构（React/Vue/Angular共存）

架构模式：
- Module Federation（Webpack 5）
- Single-SPA 编排
- qiankun 沙箱隔离
- Web Components 边界

通信机制：
- CustomEvent 跨应用通信
- 共享状态管理（Redux/Zustand Store Slice）
- PostMessage 安全通道
```

### 状态管理高级模式
```
原子化状态（Jotai/Recoil）：
- 自底向上的状态原子
- 派生状态自动计算
- 精确订阅，最小重渲染

服务端状态（TanStack Query/SWR）：
- 请求缓存和去重
- 乐观更新
- 后台刷新
- 离线支持

状态机（XState）：
- 复杂业务流程建模
- 明确的状态转换
- 可视化调试
```

### 渲染架构选择
```
CSR (客户端渲染):
- 适用：交互密集型应用（后台管理）
- 缺点：首屏慢，SEO差

SSR (服务端渲染):
- 适用：内容网站，SEO需求
- 技术：Next.js/Nuxt.js
- 注意：水合成本

SSG (静态生成):
- 适用：博客、文档站
- 优点：最佳性能

ISR (增量静态再生):
- 适用：电商产品页
- 结合SSG和SSR优点

Streaming SSR:
- React 18 Suspense
- 渐进式渲染
```

---

## 🔧 资深开发者必备技巧

### 构建优化深度技巧
```
Bundle分析：
- webpack-bundle-analyzer
- source-map-explorer
- 依赖大小可视化

Tree Shaking 优化：
- 确保 sideEffects: false
- 避免重导出（re-export）
- 使用 ESM 格式库

代码分割策略：
- 路由级分割（基础）
- 组件级分割（进阶）
- 数据预取分割（高级）

长期缓存：
- contenthash 文件名
- 抽离稳定依赖（vendor chunk）
- 运行时分离（runtime chunk）
```

### 运行时性能深度优化
```
React 优化：
- React.memo + useMemo + useCallback 三剑客
- 状态下沉，避免提升
- Context 分割，避免整体重渲染
- 使用 useTransition 延迟非紧急更新

Vue 优化：
- v-once 静态内容
- v-memo 条件缓存
- 函数式组件
- KeepAlive 组件缓存

通用优化：
- requestIdleCallback 空闲调度
- IntersectionObserver 懒加载
- ResizeObserver 布局监控
- 虚拟滚动（react-window/vue-virtual-scroller）
```

### 调试和性能分析
```
DevTools 高级用法：
- Performance Tab 火焰图分析
- Memory Tab 内存泄漏检测
- Coverage Tab 代码覆盖率
- Layers Tab 合成层分析

React DevTools：
- Profiler 组件渲染分析
- Highlight Updates 重渲染可视化
- Components 树状态检查

性能指标监控：
- Core Web Vitals（LCP/FID/CLS）
- TTFB/FCP/TTI
- Lighthouse CI 集成
```

### 复杂表单处理
```
表单库选择：
- React Hook Form（性能优先）
- Formik（功能全面）
- VeeValidate（Vue生态）

高级模式：
- 动态表单（JSON Schema驱动）
- 表单向导（多步骤）
- 表单联动（条件字段）
- 异步校验（防抖）

性能要点：
- 非受控组件（减少重渲染）
- 字段级校验（局部更新）
- 表单状态隔离
```

---

## 🚨 资深开发者常见陷阱

### 架构陷阱
```
❌ 过度抽象：
- 为了"复用"创建过度通用的组件
- 配置项比代码还多
- 正确做法：先具体后抽象，Rule of Three

❌ 状态全局化：
- 所有状态都放全局Store
- 导致组件耦合严重
- 正确做法：状态就近原则，能local不global

❌ 微前端滥用：
- 小项目强行微前端
- 增加复杂度无实际收益
- 正确做法：评估团队规模和项目复杂度
```

### 性能陷阱
```
❌ useMemo/useCallback 滥用：
- 到处加缓存
- 反而增加内存开销
- 正确做法：Profile后优化，不盲目优化

❌ 过度组件拆分：
- 每个DOM元素一个组件
- Props drilling 地狱
- 正确做法：合理粒度，组件有明确职责

❌ 图片无限加载：
- 没有限制并发请求
- 网络阻塞
- 正确做法：请求队列，优先级调度
```

### 测试陷阱
```
❌ 测试实现细节：
- 检查组件内部state
- 检查私有方法调用
- 正确做法：测试行为和输出

❌ 快照测试滥用：
- 对复杂组件snapshot
- 每次都更新快照
- 正确做法：快照仅用于简单静态组件

❌ E2E覆盖不足：
- 只有单元测试
- 集成场景无覆盖
- 正确做法：金字塔策略，关键路径E2E
```

---

## 📊 性能监控指标

| 指标 | 目标值 | 告警阈值 | 测量方法 |
|------|--------|----------|----------|
| LCP | < 2.5s | > 4s | Lighthouse/RUM |
| FID | < 100ms | > 300ms | Lighthouse/RUM |
| CLS | < 0.1 | > 0.25 | Lighthouse/RUM |
| TTI | < 3.8s | > 7.3s | Lighthouse |
| FCP | < 1.8s | > 3s | Lighthouse |
| Bundle Size (gzip) | < 200KB | > 500KB | Bundle Analyzer |
| 首屏渲染 | < 1.5s | > 3s | Performance API |
| 内存占用 | < 100MB | > 300MB | Memory Tab |
| 组件重渲染 | < 3次/交互 | > 10次 | React Profiler |

---

## 📋 前端开发检查清单（完整版）

### 基础检查
- [ ] 组件职责单一（< 300行）
- [ ] Props类型定义完整
- [ ] 状态管理清晰（单一数据源）
- [ ] HTML语义化标签
- [ ] CSS样式隔离
- [ ] 响应式设计

### 性能检查
- [ ] Core Web Vitals 达标
- [ ] Bundle Size < 200KB (gzip)
- [ ] 路由级代码分割
- [ ] 图片懒加载和现代格式
- [ ] 长列表虚拟化
- [ ] 无内存泄漏

### 安全检查
- [ ] XSS/CSRF防护
- [ ] 敏感数据不存前端
- [ ] CSP策略配置
- [ ] HTTPS强制

### 测试检查
- [ ] 组件单元测试
- [ ] 集成测试覆盖
- [ ] E2E关键路径测试
- [ ] 跨浏览器测试

---

**前端开发原则总结**：
组件化、单一职责、状态最小化、语义化HTML、样式隔离、响应式设计、性能优先、无障碍访问、安全防护、测试覆盖
