Back to Details

generic-fullstack-feature-developer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fullstack Feature Developer

全栈功能开发者指南

Guide feature development for Next.js/NestJS full-stack applications.
Extends: Generic Feature Developer - Read base skill for development workflow, decision frameworks, data flow patterns, and error handling.
为基于Next.js/NestJS的全栈应用提供功能开发指导。
扩展自： 通用功能开发者 - 请阅读基础技能文档了解开发工作流、决策框架、数据流模式和错误处理。

Full-Stack Data Flow

全栈数据流

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

Request/Response Cycle

请求/响应周期

typescript
// 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);
}
typescript
// 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 Patterns

Next.js App Router模式

File Conventions

文件约定

FilePurpose
page.tsx
Route UI (server component by default)
layout.tsx
Shared UI wrapper
loading.tsx
Suspense loading UI
error.tsx
Error boundary
route.ts
API endpoint
File用途
page.tsx
路由UI（默认是服务端组件）
layout.tsx
共享UI包装器
loading.tsx
Suspense加载UI
error.tsx
错误边界
route.ts
API端点

Server vs Client Components

服务端 vs 客户端组件

typescript
// 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>;
}
typescript
// 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 Pattern

NestJS模块模式

Module → Controller → Service → Prisma
Module → Controller → Service → Prisma

Adding a Feature Module

添加功能模块

typescript
// 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 });
  }
}
typescript
// 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 Workflow

Prisma工作流

Schema Changes

Schema变更

bash
undefined
bash
undefined

1. Edit schema.prisma

1. Edit schema.prisma

2. Create migration

2. Create migration

npx prisma migrate dev --name add_user_role
npx prisma migrate dev --name add_user_role

3. Regenerate client

3. Regenerate client

npx prisma generate
npx prisma generate

4. Update services to use new fields

4. Update services to use new fields

undefined
undefined

Type-Safe Queries

类型安全查询

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

Authentication Flow

认证流程

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

Auth Integration Points

认证集成点

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

// Backend: Guard + decorator
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}
typescript
// Frontend: Include credentials
fetch('/api/protected', { credentials: 'include' });

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

Feature Checklist (Fullstack)

全栈功能检查清单

Before Starting

开始前

  • Plan data model (Prisma schema)
  • Define API contract (DTOs)
  • Identify auth requirements
  • 规划数据模型（Prisma schema）
  • 定义API契约（DTO）
  • 确定认证需求

During Development

开发过程中

  • Create/update Prisma schema
  • Run migrations
  • Implement NestJS module (controller + service)
  • Create frontend components
  • Add loading/error states
  • 创建/更新Prisma schema
  • 运行迁移
  • 实现NestJS模块（控制器 + 服务）
  • 创建前端组件
  • 添加加载/错误状态

Before Completion

完成前

  • Add DTO validation decorators
  • Write backend unit tests
  • Write E2E tests for API
  • Verify TypeScript types match
  • 添加DTO验证装饰器
  • 编写后端单元测试
  • 为API编写端到端测试
  • 验证TypeScript类型匹配

See Also

另请参阅

  • Generic Feature Developer - Base methodology
  • Code Review Standards - Quality requirements
  • Design Patterns - UI patterns
  • 通用功能开发者 - 基础方法论
  • 代码评审标准 - 质量要求
  • 设计模式 - UI模式