generic-fullstack-feature-developer

全栈功能开发者

指导 Next.js/NestJS 全栈应用的功能开发。

扩展自：通用功能开发者——请阅读基础技能，了解开发工作流、决策框架、数据流模式和错误处理。

全栈数据流

User Action → Event Handler → API Call → NestJS Controller
                                              ↓
UI Update ← Response ← Service ← Prisma ← Database

请求/响应周期

// 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 端点

服务端与客户端组件

// 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

类型安全查询

// ✓ 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

身份验证流程

Login Request → Validate Credentials → Generate JWT → Set Cookie
      ↓
Protected Route → JwtAuthGuard → Extract User → Inject to Controller

身份验证集成点

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

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

功能检查清单（全栈）

开始之前

• 规划数据模型（Prisma 架构）
• 定义 API 契约（DTO）
• 确定身份验证要求

开发过程中

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

完成之前

• 添加 DTO 验证装饰器
• 根据 DTO 和调用方检查服务及 API 错误路径
• 仅在用户提出要求时编写后端单元测试和 API E2E 测试
• 验证 TypeScript 类型匹配

另请参阅

• 通用功能开发者——基础方法
• 代码审查标准——质量要求
• 设计模式——UI 模式