senior-fullstack

高级全栈工程师

概述

交付完整的端到端 TypeScript 应用，涵盖数据库设计、API 层、前端 UI、身份验证和部署。此技能专注于现代 TypeScript 全栈开发：Next.js App Router、用于类型安全 API 的 tRPC、用于数据库访问的 Prisma，以及包含监控的生产环境部署。

开始时宣告：“我将使用 senior-fullstack 技能进行端到端 TypeScript 开发。”

---

阶段 1：数据层

**目标：**设计数据库架构和数据访问模式。

操作

1. 使用 Prisma 设计数据库架构
2. 定义关系和索引
3. 创建用于开发的种子数据
4. 设置迁移工作流
5. 实现用于数据访问的仓储模式

Prisma 架构示例

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  role      Role     @default(USER)
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([email])
  @@index([createdAt])
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
  authorId  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([authorId])
  @@index([published, createdAt])
}

索引策略决策表

查询模式	索引类型	示例
按唯一字段查找	唯一索引	@@unique([email])
按外键筛选	标准索引	@@index([authorId])
组合筛选和排序	复合索引	@@index([published, createdAt])
全文搜索	全文索引	特定于数据库
地理空间查询	空间索引	特定于数据库

停止 — 在进入阶段 2 之前，必须满足以下条件：

• 已定义包含所有关系的架构
• 索引覆盖所有查询模式
• 种子数据脚本已就绪
• 已生成并测试迁移

---

阶段 2：API 层

**目标：**使用 tRPC 和 Zod 验证构建类型安全的 API。

操作

1. 定义 tRPC 路由器和过程
2. 使用 Zod 实现输入验证
3. 添加身份验证中间件
4. 在服务层构建业务逻辑
5. 添加错误处理和日志记录

tRPC 路由器示例

export const userRouter = router({
  list: protectedProcedure
    .input(z.object({
      page: z.number().min(1).default(1),
      pageSize: z.number().min(1).max(100).default(20),
      search: z.string().optional(),
    }))
    .query(async ({ ctx, input }) => {
      const { page, pageSize, search } = input;
      const where = search ? { name: { contains: search, mode: 'insensitive' } } : {};
      const [users, total] = await Promise.all([
        ctx.db.user.findMany({
          where, skip: (page - 1) * pageSize, take: pageSize, orderBy: { createdAt: 'desc' },
        }),
        ctx.db.user.count({ where }),
      ]);
      return { users, total, totalPages: Math.ceil(total / pageSize) };
    }),

  create: protectedProcedure
    .input(createUserSchema)
    .mutation(async ({ ctx, input }) => {
      return ctx.db.user.create({ data: input });
    }),
});

授权模式决策表

模式	使用场景	示例
基于角色（RBAC）	简单的权限模型	管理员与用户
资源级别	仅所有者可访问	用户可以编辑自己的帖子
基于属性（ABAC）	复杂规则	组织成员身份 + 角色 + 资源状态
功能开关	逐步发布	高级功能

停止 — 在进入阶段 3 之前，必须满足以下条件：

• 已定义所有带 Zod 验证的 tRPC 路由器
• 身份验证中间件保护适当的路由
• 业务逻辑位于服务层（而非路由器中）
• 错误处理会返回结构化错误

---

阶段 3：UI 层

**目标：**默认使用 Server Components 构建页面，并使用 Client Components 实现交互功能。

操作

1. 使用 Server Components 构建页面（默认）
2. 添加 Client Components 实现交互功能
3. 通过 tRPC hooks 连接 API
4. 实现乐观更新
5. 添加加载和错误状态

组件类型决策表

需求	组件类型	数据来源
静态内容、数据显示	Server Component	直接调用 DB/API
交互式表单	Client Component	tRPC mutation hook
实时更新	Client Component	tRPC subscription 或轮询
搜索/筛选	Client Component	带防抖的 tRPC query
导航界面	Server Component	会话数据

停止 — 在进入阶段 4 之前，必须满足以下条件：

• 页面默认使用 Server Components
• Client Components 保持精简且有充分理由
• 所有数据获取路径都具备加载和错误状态
• mutation 的乐观更新正常工作

---

阶段 4：生产环境

**目标：**通过身份验证、监控和 CI/CD 为部署做好准备。

操作

1. 设置身份验证（NextAuth.js / Clerk / Lucia）
2. 配置部署（Vercel / Docker）
3. 添加监控和错误跟踪
4. 实现 CI/CD 流水线
5. 执行性能审计

身份验证解决方案决策表

解决方案	适用场景	SSR 支持	可自托管
NextAuth.js (Auth.js)	OAuth 提供商、JWT/会话	是	是
Clerk	快速设置、托管服务	是	否
Lucia	自定义、轻量级	是	是
Supabase Auth	Supabase 生态系统	是	部分

监控清单

• 使用 source maps 进行错误跟踪（Sentry）
• 性能监控（Vercel Analytics 或自定义方案）
• 数据库查询性能（Prisma 指标）
• API 端点延迟和错误率
• 正常运行时间监控（外部 ping）
• 使用结构化日志进行日志聚合
• 针对错误率激增的告警

Docker 部署

FROM node:20-alpine AS base
RUN corepack enable

FROM base AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm prisma generate
RUN pnpm build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

停止 — 满足以下条件后即可用于生产环境：

• 身份验证已配置并经过测试
• 部署流水线正常运行（预览 + 生产环境）
• 监控和告警已启用
• 已完成性能审计

---

全栈类型安全流程

Prisma Schema -> Prisma Client (types) -> tRPC Router -> tRPC Hooks -> React Components
     |                  |                     |              |              |
  Migration        Type-safe DB          Validated API    Auto-typed    Rendered UI
                   queries               with Zod         queries

---

项目结构

prisma/
  schema.prisma
  migrations/
  seed.ts
src/
  app/                    # Next.js App Router
    (auth)/               # Auth route group
    (dashboard)/          # Protected route group
    api/trpc/[trpc]/      # tRPC handler
  server/
    db.ts                 # Prisma client singleton
    trpc.ts               # tRPC init
    routers/              # tRPC routers
    services/             # Business logic
  components/
    ui/                   # Design system atoms
    features/             # Feature components
  hooks/                  # Custom React hooks
  lib/
    trpc.ts               # tRPC client
    auth.ts               # Auth configuration
    validators.ts         # Zod schemas
tests/
  unit/
  integration/
  e2e/

---

反模式 / 常见错误

反模式	错误原因	正确做法
在组件中编写原始 SQL	绕过类型安全和安全机制	通过 tRPC 使用 Prisma
Server Components 可用时仍在客户端获取数据	产生不必要的 JavaScript，速度更慢	静态数据使用 Server Components
与前端共享 Prisma 客户端	安全漏洞，会暴露数据库	仅在服务端代码中使用 Prisma
外键缺少索引	联接和查询速度慢	为每个外键建立索引
在 localStorage 中存储令牌	存在 XSS 漏洞	使用 HttpOnly cookies
跳过 Zod 验证	运行时类型错误	在 API 边界验证所有输入
单体式 tRPC 路由器	难以维护，容易产生合并冲突	按领域拆分（用户、帖子等）
在 tRPC 过程函数中编写业务逻辑	难以测试，无法复用	提取到服务层

---

文档查询（Context7）

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

• react — 用于组件模式、hooks 或 React 19+ 功能
• next.js — 用于 App Router、API 路由或服务端组件
• prisma — 用于模式设计、客户端查询或迁移
• tailwindcss — 用于实用优先的 CSS 模式或配置

---

集成点

技能	关联
senior-frontend	UI 层遵循前端模式
senior-backend	API 层遵循后端模式
senior-architect	架构决策指导服务边界的划分
security-review	身份验证实现遵循安全模式
testing-strategy	全栈测试采用策略框架
code-review	审查涵盖技术栈的所有层
performance-optimization	优化适用于所有层

---

核心原则

• 从数据库到浏览器统一使用 TypeScript
• 整个技术栈均保证类型安全（不出现运行时类型不匹配）
• 默认使用 Server Components，仅在必要时使用 Client Components
• 使用 Zod 在 API 边界验证所有输入
• 为每种查询模式建立数据库索引
• 基于环境进行配置（不使用硬编码值）

---

技能类型

灵活 — 根据项目上下文调整技术选择。强烈建议采用四阶段流程。整个技术栈的类型安全不可妥协。所有 API 输入都必须使用 Zod 验证。数据库模式变更必须使用迁移。