generic-fullstack-feature-developer

Fullstack Feature Developer 技能介绍

用途

本技能用于指导 Next.js/NestJS 全栈应用的功能开发，关注架构层面的设计与实现。适用于以下场景：新增功能、重构现有代码、规划重大改动。

该技能扩展自 Generic Feature Developer 基础技能（路径：../generic-feature-developer/SKILL.md），开发工作流、决策框架、数据流模式和错误处理等内容需阅读基础技能。

全栈数据流

技能给出了全栈请求的数据流向：

用户操作 → 事件处理器 → API 调用 → NestJS 控制器 → 服务 → Prisma → 数据库，再沿相反方向返回响应并更新 UI。

示例代码展示了前端调用 API 与后端处理请求的对应写法：

// Frontend: Call API
const response = await fetch('/api/users', {
  method: 'POST',
  body: JSON.stringify(userData),
});

// Backend: Handle request
@Post()
@UseGuards(JwtAuthGuard)
async createUser(@Body() dto: CreateUserDto) {
  return this.userService.create(dto);
}

Next.js App Router 模式

文件约定

文件	用途
`page.tsx`	路由 UI（默认服务端组件）
`layout.tsx`	共享 UI 包装
`loading.tsx`	Suspense 加载 UI
`error.tsx`	错误边界
`route.ts`	API 端点

服务端组件与客户端组件

服务端组件为默认形式，可直接获取数据；客户端组件需添加 'use client' 指令，并使用 useState 等状态钩子。示例：

// Server Component (default) - can fetch data
export default async function Page() {
  const data = await getData(); // Direct DB/API call
  return <div>{data.title}</div>;
}

// Client Component - needs 'use client'
'use client';
export default function Interactive() {
  const [state, setState] = useState();
  return <button onClick={() => setState(...)}>Click</button>;
}

NestJS 模块模式

后端遵循 Module → Controller → Service → Prisma 的结构。新增功能模块的步骤示例：

// 1. Module definition
@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// 2. Controller with guards
@Controller("users")
@UseGuards(JwtAuthGuard)
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

// 3. Service with Prisma
@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  create(dto: CreateUserDto) {
    return this.prisma.user.create({ data: dto });
  }
}

Prisma 工作流

模式变更步骤

# 1. Edit schema.prisma
# 2. Create migration
npx prisma migrate dev --name add_user_role

# 3. Regenerate client
npx prisma generate

# 4. Update services to use new fields

类型安全查询

技能建议使用生成的类型进行类型安全查询，并避免无类型安全的原始 SQL：

// ✓ Type-safe with generated types
const user = await this.prisma.user.findUnique({
  where: { id },
  include: { posts: true },
});

// ✗ Avoid raw SQL
await this.prisma.$queryRaw`SELECT * FROM users`; // No type safety

认证流程

登录请求 → 校验凭证 → 生成 JWT → 设置 Cookie；受保护路由 → JwtAuthGuard → 提取用户 → 注入控制器。集成示例：

// Frontend: Include credentials
fetch('/api/protected', { credentials: 'include' });

// Backend: Guard + decorator
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}

全栈功能检查清单

开始前

规划数据模型（Prisma schema）
定义 API 契约（DTO）
识别认证需求

开发中

创建/更新 Prisma schema
运行迁移
实现 NestJS 模块（控制器 + 服务）
创建前端组件
添加加载/错误状态

完成前

添加 DTO 校验装饰器
对照 DTO 和调用方审查服务与 API 错误路径
仅在用户要求时编写后端单元测试和 API E2E 测试
验证 TypeScript 类型一致

适用场景与限制

该技能面向使用 Next.js 与 NestJS 的全栈项目，适合在开发新功能、重构代码或规划架构变更时参考其数据流、模块划分与检查清单。其中涉及的技术栈为 Next.js App Router、NestJS、Prisma 和 JWT 认证。关于收费、价格、平台支持范围或其他未在资料中出现的信息，暂未提供。