senior-frontend

高级前端工程师

概述

按照结构化的三阶段工作流交付可用于生产环境的前端代码：了解上下文、开发和交接。此技能要求严格遵循质量标准，包括原子设计组件架构、全面的状态管理模式、SSR/SSG/ISR 优化，以及必须使用 Vitest、React Testing Library 和 Playwright 达到 >85% 的测试覆盖率。

开始时声明：“我正在使用 senior-frontend 技能进行可用于生产环境的 React/TypeScript 开发。”

---

阶段 1：了解上下文

目标： 编写任何代码之前，先了解现有代码库。

操作

1. 分析现有代码库结构和约定
2. 确认技术栈版本（React 18/19、Next.js 14/15、TypeScript 版本）
3. 检查现有组件库和设计系统
4. 检查当前使用的状态管理方案
5. 了解构建工具和 CI 流水线
6. 梳理现有测试基础设施和覆盖率

停止 — 完成以下事项前，不要进入阶段 2：

• 确认技术栈版本
• 记录现有模式和约定
• 梳理测试基础设施
• 确认状态管理方案

---

阶段 2：开发

目标： 使用严格的 TypeScript、原子设计和 TDD 进行实现。

操作

1. 按照原子设计规划组件架构
2. 使用 TypeScript 严格模式进行实现
3. 在实现的同时编写测试（适用时采用 TDD）
4. 优化性能（包体积、渲染、加载）
5. 确保符合无障碍要求

组件架构决策表（原子设计）

级别	描述	业务逻辑	示例
Atoms	最小构建单元	无	Button、Input、Icon、Badge
Molecules	由原子组件组合而成	极少	FormField、SearchBar、Card
Organisms	复杂且包含业务逻辑	有	DataTable、NavigationBar、CommentThread
Templates	不含数据的页面结构	仅布局	DashboardLayout、AuthLayout
Pages	连接到数据的模板	数据获取	UsersPage、SettingsPage

原子组件示例

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

export function Button({ variant = 'primary', size = 'md', isLoading, children, ...props }: ButtonProps) {
  return (
    <button className={cn(buttonVariants({ variant, size }))} disabled={isLoading || props.disabled} {...props}>
      {isLoading ? <Spinner size={size} /> : children}
    </button>
  );
}

状态管理决策表

状态类型	方案	适用场景
服务端状态	React Query / TanStack Query	API 数据、缓存、同步
表单状态	React Hook Form + Zod	表单验证、提交
全局 UI 状态	Zustand	主题、侧边栏展开、模态框
本地 UI 状态	useState / useReducer	组件专属状态
URL 状态	nuqs / useSearchParams	筛选、分页、标签页
复杂本地状态	useReducer	多个相关状态转换
共享上下文	React Context	主题、区域设置、身份验证（不频繁更新）

SSR / SSG / ISR 决策表（Next.js App Router）

模式	适用场景	缓存策略
静态（SSG）	内容很少变化	构建时
ISR	内容定期变化	重新验证间隔
SSR	内容随请求变化	不缓存
客户端	用户专属、可交互内容	浏览器

服务端组件与客户端组件的选择

需求	组件类型
直接获取数据	服务端（默认）
事件处理器（onClick、onChange）	客户端（'use client'）
useState / useReducer	客户端
useEffect / useLayoutEffect	客户端
浏览器 API（window、localStorage）	客户端
使用客户端功能的第三方库	客户端
无需交互	服务端（默认）

停止 — 完成以下事项前，不要进入阶段 3：

• 组件遵循原子设计层级
• 已启用 TypeScript 严格模式，且不使用 any 类型
• 已为所有组件编写测试
• 已验证无障碍功能（axe-core）

---

阶段 3：交接

目标： 验证质量门禁并准备好进行审查。

操作

1. 验证测试覆盖率是否达到 >85% 的阈值
2. 运行完整的 lint 和类型检查
3. 使用 JSDoc/TSDoc 为复杂组件编写文档
4. 为 UI 组件创建 Storybook stories
5. 性能审计（Lighthouse、包分析）

性能检查清单

• 压缩后的包大小 < 200KB（初始加载）
• 最大内容绘制时间 < 2.5s
• 首次输入延迟 < 100ms
• 累积布局偏移 < 0.1
• 图像：使用 next/image，并设置合适的尺寸和格式
• 字体：使用 next/font，并设置 display swap
• 不发生布局抖动（批量读取/写入 DOM）
• 对超过 100 项的列表进行虚拟化

覆盖率阈值

{
  "coverageThreshold": {
    "global": {
      "branches": 85,
      "functions": 85,
      "lines": 85,
      "statements": 85
    }
  }
}

停止 — 满足以下条件后即可完成交接：

• 已验证测试覆盖率 >85%
• Lint 和类型检查通过，且无错误
• 已完成性能审计
• 已为复杂组件编写文档

---

测试要求

单元测试（Vitest + React Testing Library）

describe('Button', () => {
  it('renders children', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
  });

  it('shows loading state', () => {
    render(<Button isLoading>Click me</Button>);
    expect(screen.getByRole('button')).toBeDisabled();
  });

  it('calls onClick when clicked', async () => {
    const onClick = vi.fn();
    render(<Button onClick={onClick}>Click me</Button>);
    await userEvent.click(screen.getByRole('button'));
    expect(onClick).toHaveBeenCalledOnce();
  });
});

集成测试

• 组件组合（表单提交流程）
• 使用 MSW（Mock Service Worker）获取数据
• 路由和导航
• 错误边界和回退机制

E2E 测试（Playwright）

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).first().click();
  await page.getByRole('link', { name: 'Cart' }).click();
  await expect(page.getByText('1 item')).toBeVisible();
  await page.getByRole('button', { name: 'Checkout' }).click();
});

---

React Query 模式

function useUsers(filters: UserFilters) {
  return useQuery({
    queryKey: ['users', filters],
    queryFn: () => fetchUsers(filters),
    staleTime: 5 * 60 * 1000,
    placeholderData: keepPreviousData,
  });
}

function useUpdateUser() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: updateUser,
    onMutate: async (newUser) => {
      await queryClient.cancelQueries({ queryKey: ['users'] });
      const previous = queryClient.getQueryData(['users']);
      queryClient.setQueryData(['users'], (old) =>
        old.map(u => u.id === newUser.id ? { ...u, ...newUser } : u)
      );
      return { previous };
    },
    onError: (err, newUser, context) => {
      queryClient.setQueryData(['users'], context.previous);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}

---

记忆化决策表

技术	适用场景	不适用场景
useMemo	耗时计算、依赖项需要引用相等性	简单计算、基本类型值
useCallback	函数会传递给经过记忆化的子组件	函数不会作为 props 传递
React.memo	组件经常在 props 相同的情况下重新渲染	每次渲染时 props 都会变化
无	默认做法 — 不要进行记忆化	始终先进行性能分析

---

反模式 / 常见错误

反模式	错误原因	正确做法
使用 useEffect 获取数据	竞态条件、无缓存、无去重	使用 React Query 或 Server Components
通过超过 2 层传递 props	耦合紧密、维护负担重	使用组合、上下文或 Zustand
在组件中编写业务逻辑	无法测试、无法复用	提取到 hooks 或工具函数中
使用 Barrel exports	破坏 tree-shaking，导致构建变慢	直接导入
测试实现细节	测试脆弱，重构时容易失败	测试行为：用户操作及其结果
在任何地方使用 any 类型	违背 TypeScript 的设计目的	使用 unknown + 类型守卫
对非动态值使用内联样式	不一致、难以维护	使用 CSS modules、Tailwind 或 styled-components
对所有内容都进行记忆化	增加复杂度，且通常会降低速度	先进行性能分析，再进行记忆化

---

文档查询（Context7）

使用 mcp__context7__resolve-library-id，然后使用 mcp__context7__query-docs 查询最新文档。返回的文档优先于记忆中的知识。

• react — 不确定 hooks API、组件生命周期或 React 19+ 功能时
• next.js — 用于 App Router、Server Components 或 Next.js 特定 API
• typescript — 用于高级类型模式或编译器选项
• tailwindcss — 用于工具类、配置或插件 API
• vitest — 用于测试运行器 API、匹配器或 mock 工具

---

集成点

技能	关联
testing-strategy	策略定义前端测试框架
test-driven-development	使用 TDD 循环构建组件
react-best-practices	详细的 React 模式补充本技能
performance-optimization	前端性能遵循优化方法论
code-review	通过审查验证组件架构和测试覆盖率
clean-code	代码质量原则适用于组件代码
webapp-testing	Playwright E2E 测试使用本技能的页面结构
acceptance-testing	UI 验收标准推动组件测试

---

核心原则

• TypeScript 严格模式，不使用 any（使用 unknown 和类型守卫）
• 优先采用组合，而非继承
• 将测试、样式和故事文件与组件放在一起
• 默认使用服务器组件；仅在必要时使用客户端组件
• 在路由和功能边界设置错误边界
• 无障碍访问不是可选项（使用 axe-core 测试）

---

技能类型

灵活 — 根据现有项目规范调整组件架构和状态管理。强烈建议采用三阶段工作流。测试覆盖率必须达到 85% 以上。TypeScript 严格模式不可妥协。