버전 관리와 API 진화 전략

// src/main.ts (업데이트)
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe, VersioningType } from '@nestjs/common'; // VersioningType 임포트
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // API 버전 관리 활성화 (URI 기반)
  app.enableVersioning({
    type: VersioningType.URI, // URI 기반 버전 관리 사용
    defaultVersion: '1', // 기본 버전 설정 (버전이 명시되지 않은 요청에 적용)
  });

  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
    disableErrorMessages: process.env.NODE_ENV === 'production',
  }));

  const config = new DocumentBuilder()
    .setTitle('Users API Example')
    .setDescription('The Users API description with CRUD operations.')
    .setVersion('1.0') // Swagger 문서 자체의 버전, API 버전과 다름
    .addTag('users', 'User related endpoints')
    .addBearerAuth(
      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT', in: 'header', name: 'JWT' },
      'access-token'
    )
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

// src/users/users.controller.ts (업데이트 - v1, v2)
import { Controller, Get, Post, Body, Param, Patch, Delete, HttpCode, HttpStatus, NotFoundException, Version } from '@nestjs/common';
import { UsersService, User } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { ApiTags, ApiOperation, ApiResponse, ApiParam, ApiBody, ApiSecurity } from '@nestjs/swagger';

// Version 1 Controller
@ApiTags('users - v1') // Swagger 태그도 버전별로 분리하여 명확하게 합니다.
@Controller('users')
@Version('1') // 이 컨트롤러의 모든 라우트는 v1 API로 동작합니다. (예: /v1/users)
export class UsersV1Controller {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  @ApiOperation({ summary: '[v1] 모든 사용자 조회', description: 'v1 API: 등록된 모든 사용자 목록을 반환합니다.' })
  @ApiResponse({ status: 200, description: '성공적으로 모든 사용자를 반환합니다.', type: [User] })
  findAll(): User[] {
    return this.usersService.findAll();
  }

  // ... (다른 CRUD 메서드도 동일하게 구현)
}

// Version 2 Controller (가상의 변경: email 필드 제거, phoneNumber 필드 추가 등)
// 실제 User 인터페이스나 DTO도 v2에 맞게 변경되어야 합니다.
export interface UserV2 {
  id: number;
  name: string;
  phoneNumber?: string; // v2에서 추가될 필드
}

@ApiTags('users - v2')
@Controller('users')
@Version('2') // 이 컨트롤러의 모든 라우트는 v2 API로 동작합니다. (예: /v2/users)
export class UsersV2Controller {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  @ApiOperation({ summary: '[v2] 모든 사용자 조회', description: 'v2 API: 등록된 모든 사용자 목록을 반환합니다. (Email 필드 제거, PhoneNumber 필드 추가)' })
  @ApiResponse({ status: 200, description: '성공적으로 모든 사용자를 반환합니다.', type: [UserV2] })
  findAll(): UserV2[] {
    // 실제 서비스 로직은 v2 응답 형태에 맞게 데이터를 변환해야 합니다.
    const v1Users = this.usersService.findAll();
    return v1Users.map(user => ({ id: user.id, name: user.name, phoneNumber: '010-XXXX-XXXX' }));
  }

  // ... (v2에 맞는 다른 CRUD 메서드 구현)
}

// src/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersService } from './users.service';
import { UsersV1Controller, UsersV2Controller } from './users.controller'; // 두 컨트롤러 임포트

@Module({
  controllers: [UsersV1Controller, UsersV2Controller], // 두 컨트롤러 모두 등록
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// main.ts
app.enableVersioning({
  type: VersioningType.HEADER,
  header: 'X-API-Version', // 사용할 헤더 이름
  defaultVersion: '1',
});

// main.ts
app.enableVersioning({
  type: VersioningType.MEDIA_TYPE,
  key: 'v', // Accept 헤더에서 'v=' 뒤에 오는 값을 버전으로 인식합니다.
            // 예: Accept: application/json;v=1
  defaultVersion: '1',
});