echovic/frontend/component-development

前端组件开发方法论

组件设计原则

单一职责原则

• 每个组件只负责一个功能模块
• 复杂组件拆分为多个子组件
• 容器组件（逻辑）与展示组件（UI）分离

可复用性设计

• 通过 Props/属性实现组件配置化
• 避免硬编码业务逻辑
• 提供合理的默认值
• 支持插槽/children 扩展

组件命名规范

• 使用 PascalCase 命名组件
• 名称应清晰描述组件功能
• 避免过于通用的名称（如 Item、Component）
• 文件名与组件名保持一致

状态管理策略

状态分类

| 状态类型 | 管理方式 | 适用场景 | |----------|----------|----------| | 本地状态 | useState/ref | 组件内部状态（表单输入、展开/收起） | | 共享状态 | Context/Store | 跨组件共享（用户信息、主题） | | 服务端状态 | Query库/SWR | API 数据缓存和同步 | | URL 状态 | Router | 页面参数、筛选条件 |

状态提升原则

• 状态放在最近的公共父组件
• 避免过度提升导致不必要的重渲染
• 使用 Context 避免 Props 层层传递

副作用管理

• 使用框架的副作用 Hook（useEffect/onMounted）
• 清理订阅和定时器
• 依赖数组准确声明
• 避免在渲染函数中执行副作用

样式实现规范

UI 规范优先级

ui-design.json > ui-spec.md > 项目现有样式 > 框架默认值

ui-design.json 集成

当 .boss/<feature>/ui-design.json 存在时：

1. 读取 tokens：映射为 CSS 变量或主题对象

   // 示例：从 tokens 生成 CSS 变量
   const colors = uiDesign.tokens.colors;
   // --color-primary: #007AFF
   

2. 解析 pages 和 frames：推导页面结构和布局

   • 从 pages[].frames[] 提取页面组件层级
   • 从 frames[].layout 获取布局约束（宽度、间距、对齐）

3. 实现 prototype.links：推导导航和交互

   • 按钮点击跳转
   • 表单提交流程
   • 模态框打开/关闭

4. 复用 components：提取可复用组件

   • 从 components[] 识别通用组件（Button、Input、Card）
   • 实现为独立组件文件

样式编写原则

• 使用项目约定的样式方案（CSS Modules/Tailwind/CSS-in-JS）
• 响应式设计：移动端优先或桌面端优先（按项目约定）
• 使用设计系统的间距、颜色、字体变量
• 避免魔法数字，使用语义化变量

无障碍实现

• 添加正确的 ARIA 属性（role、aria-label、aria-describedby）
• 确保键盘导航可用（tabindex、focus 样式）
• 表单元素关联 label
• 图片添加 alt 文本

性能优化技巧

渲染优化

• 使用 Memo/shouldComponentUpdate 避免不必要的重渲染
• 列表渲染使用稳定的 key
• 虚拟滚动处理长列表
• 避免在渲染函数中创建新对象/函数

代码分割

• 路由级别的懒加载
• 大型组件按需加载
• 第三方库按需引入

资源优化

• 图片懒加载和响应式图片
• 使用 WebP 等现代图片格式
• SVG 图标内联或雪碧图

API 契约管理

契约来源

实现前端 API 调用前，必须阅读：

1. architecture.md §5（API 设计）：获取端点列表、请求/响应格式
2. 后端共享类型（如有）：复用类型定义

API 调用层设计

// services/api/users.ts
export const userApi = {
  async getUser(id: string): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  },
  
  async createUser(data: CreateUserRequest): Promise<User> {
    const response = await fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify(data),
    });
    return response.json();
  },
};

错误处理

• 统一错误处理：按 architecture.md 定义的错误格式
• 用户友好的错误提示
• 网络错误重试机制
• 加载和错误状态展示

Mock 策略

后端未就绪时，基于 architecture.md §5 创建 Mock：

// services/api/users.mock.ts
export const mockUserApi = {
  async getUser(id: string): Promise<User> {
    return { id, name: 'Mock User', email: '[email protected]' };
  },
};

组件测试策略

测试金字塔

| 测试类型 | 占比 | 工具示例 | |----------|------|----------| | 单元测试 | 70% | Jest + Testing Library | | 集成测试 | 20% | Testing Library | | E2E 测试 | 10% | Playwright/Cypress |

单元测试覆盖

• 组件渲染：关键元素是否存在
• Props 变化：不同 Props 下的渲染结果
• 用户交互：点击、输入、表单提交
• Hooks 逻辑：自定义 Hook 的状态变化

集成测试覆盖

• 组件间交互：父子组件通信
• 状态管理：全局状态变化对组件的影响
• 路由导航：页面跳转和参数传递

E2E 测试覆盖（必须）

• 创建流程：填写表单 → 提交 → 验证结果
• 编辑流程：打开编辑 → 修改 → 保存 → 验证
• 删除流程：点击删除 → 确认 → 验证消失
• 列表展示：加载列表 → 筛选 → 分页
• 核心业务流程：完整用户路径

实现检查清单

实现组件前：

• [ ] 阅读 ui-design.json（如有）和 ui-spec.md
• [ ] 阅读 architecture.md §5 API 设计
• [ ] 探索项目现有组件模式和样式方案
• [ ] 确认状态管理方案（本地/共享/服务端）

实现组件后：

• [ ] 组件符合单一职责原则
• [ ] 添加必要的 Props 类型定义
• [ ] 实现响应式布局
• [ ] 添加无障碍属性
• [ ] 编写单元测试（70%）
• [ ] 编写集成测试（20%）
• [ ] 编写 E2E 测试（10%，必须）
• [ ] 测试覆盖率达标
• [ ] 代码通过 Lint 检查