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();
  },
};