RORO = Receive an Object, Return an Object

• 함수의 파라미터를 여러 개 나열하지 않고, 하나의 객체(Object)로 받고, 반환값도 객체(Object)로 반환하는 패턴

왜 쓰는가?

1. 가독성 증가
2. 파라미터 순서 의존 제거
3. 확장에 강함
4. TypeScript와 매우 궁합이 좋음

❌ 안 좋은 예

findVenueParticipationByUserAndDate(
  venueId: number,
  userId: number,
  scheduledDate: string,
) 

⭕ RORO 적용 예

findVenueParticipationByUserAndDate({
  venueId,
  userId,
  scheduledDate,
}: FindVenueParticipationByUserAndDateParams)

RORO 패턴 적용해보기

기존 호출 코드

const participation =
      await this.venueParticipationRepository.findVenueParticipationByUserAndDate(
        venueId,
        userId,
        scheduledDate,
      );

...

async findVenueParticipationByUserAndDate(
  venueId: number,
  userId: number,
  scheduledDate: string,
) {
  return await this.venueParticipationRepository.findOne({
    where: {
      venue: {
        id: venueId,
      },
      user: {
        id: userId,
      },
      scheduledDate: new Date(scheduledDate),
    },
  });
}

RORO 패턴 적용 후 호출 코드

const participation =
      await this.venueParticipationRepository.findVenueParticipationByUserAndDate({
        venueId,
        userId,
        scheduledDate,
      });

...

interface FindVenueParticipationByUserAndDateParams {
  venueId: number;
  userId: number;
  scheduledDate: string;
}

async findVenueParticipationByUserAndDate({
  venueId,
  userId,
  scheduledDate,
}: FindVenueParticipationByUserAndDateParams) {
  return await this.venueParticipationRepository.findOne({
    where: {
      venue: {
        id: venueId,
      },
      user: {
        id: userId,
      },
      scheduledDate: new Date(scheduledDate),
    },
  });
}

네이밍 규칙 추천

예시

SaveClusterCommentParams
FindClusterCommentsQuery
CreateClusterCommentResult

언제 RORO를 쓰는 것이 좋을까?

✔ 파라미터가 3개 이상일 경우 ✔ 나중에 확장될 가능성 있을 경우 ✔ TypeScript 사용 중일 경우

• 증상: nest build 중 아래와 같은 OOM 오류로 프로세스 종료

  FATAL ERROR: Ineffective mark-compacts near heap limit
  Allocation failed - JavaScript heap out of memory

• 환경: AWS Lightsail (RAM 512MB / vCPU 2 / SSD 20GB)

• 원인: TypeScript 타입체크+트랜스파일 단계에서 Node.js 힙 사용량이 시스템 메모리 한도(≈512MB)와 스왑을 넘어섬 → GC가 메모리 회수 불가 → heap out of memory 발생.

2) 내가 사용한 해결 방법

2-1. 인스턴스 업그레이드

• Lightsail 사양을 상향(≥2GB RAM 권장)하여 빌드 메모리 여유를 확보.
• 업그레이드 후 빌드가 정상 완료됨.

2-2. SWC 기반 빌드로 전환(속도/메모리 개선)

• 목적: 빌드 속도와 메모리 사용량을 줄여 개발 및 CI 안정화.

• 적용 사항:

  1. 패키지 설치

     npm i -D @swc/cli @swc/core

  2. nest-cli.json

     { "compilerOptions": { "builder": "swc" } }

     (또는 nest build --builder swc, nest start -b swc)

  3. 타입체크 필요 시 병렬 수행

     • CLI: nest start -b swc --type-check

     • 설정:

       { "compilerOptions": { "builder": "swc", "typeCheck": true } }

  4. .swcrc(선택)

     {
       "sourceMaps": true,
       "jsc": { "parser": { "syntax": "typescript", "decorators": true, "dynamicImport": true } },
       "minify": false
     }

  5. TS 옵션 권장: skipLibCheck: true, incremental: true

3) (SWC 빌드 시) 새로 발생했던 의존성 문제

• 에러:

  ReferenceError: Cannot access 'Product' before initialization

• 상황: 엔티티 간 양방향 정적 import(순환 참조) + 데코레이터 메타데이터 조합.

• 원인 분석:

  • tsc는 CommonJS 변환에서 순환 참조를 비교적 “관대하게” 처리하는 반면,
  • swc는 초기화 순서에 엄격하여 아직 초기화 전 클래스에 접근하면 ReferenceError 발생.
  • TypeORM의 엔티티 양방향 관계(예: Product ↔ ProductMapping)에서 자주 노출.

예)

// product.entity.ts
import { ProductMapping } from './product_mapping.entity';
@OneToMany(() => ProductMapping, m => m.product) mappings: ProductMapping[];

// product_mapping.entity.ts
import { Product } from './product.entity';
@ManyToOne(() => Product, p => p.mappings) product: Product;

4) 문제 해결 방법 (SWC 의존성/초기화 이슈)

4-1. 지연 평가(Lazy)로 순환 절단

• 정적 import 제거 → 런타임 require + 람다로 참조 지연:

// BEFORE
@ManyToOne(() => Product, p => p.mappings)

// AFTER
@ManyToOne(() => (require('./product.entity').Product), p => p.mappings)

• 동일 패턴을 모든 순환 관계에 적용(Shop, User, Review, Image 등).

4-2. 양방향 축소 & 조인 엔티티로 단순화

• Product ↔ Shop의 ManyToMany 제거.

• **명시적 조인 엔티티(product_mapping)**로만 연결:

  • 중복 관계 제거, 순환 위험 해제, 확장 속성(예: 가격/상태) 부여 용이.

4-3. 타입 의존성 최소화

• type-only import로 런타임 의존성 제거:

  import type { Product } from './product.entity';

• 관계 필드 타입은 필요 시 any/any[]로 완화 (런타임에는 데코레이터 메타데이터가 타입 정보를 제공하므로 동작에 문제 없음. 서비스/DTO 레이어에서 타입 안전성 보완).

4-4. TS/빌드 설정 점검

• tsconfig.json

  { "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } }

• .swcrc에서 decorators: true 확인.

• 경로 별칭(tsconfig paths)을 사용 중이면 해결 순서가 순환을 강화하지 않도록 import 정리.

4-5. 파일별 핵심 변경 요약

• product.entity.ts: 다른 엔티티에 대한 직접 관계 제거(필요 최소 컬럼만 유지).

• product_mapping.entity.ts:

  @ManyToOne(() => (require('./product.entity').Product), ...) 
  @ManyToOne(() => (require('./shop.entity').Shop), ...)
  // FK 컬럼 유지, onDelete: 'CASCADE'

• shop.entity.ts: Product와의 직접 ManyToMany 제거. 기존 OneToMany(운영시간/리뷰/매핑)는 유지.

• operating-hours.entity.ts: @ManyToOne(() => (require('./shop.entity').Shop), ...)

• review.entity.ts: User, Shop, Image에 대해 require 지연 + 관계 타입 완화.

• image.entity.ts, user.entity.ts, wishlist.entity.ts, region.entity.ts, submit-user.entity.ts: 모두 동일하게 require 지연 참조와 타입 완화 적용.

결론

• 메모리 부족 문제는 인스턴스 업그레이드로 즉시 해소.
• SWC 전환으로 빌드 성능이 향상되었으나, 엔티티 순환 참조로 인한 초기화 에러가 발생.
• 이를 지연 평가(require) 패턴, 양방향 관계 축소/조인 엔티티화, type-only import/타입 완화, 데코레이터/메타데이터 설정 유지로 해결하여 SWC 빌드 안정화를 달성했습니다.

1. 내가 사용한 방법

• 백엔드는 코드 우선(Code-First) 방식으로 개발하고, 완료된 API를 Swagger에 반영하는 형태로 진행.
• 프론트엔드(Flutter)는 UI 화면을 먼저 제작한 뒤, 각 페이지에서 필요한 데이터는 텍스트 하드코딩으로 채워 넣음.
• 이후 실제 API가 나오면 하드코딩 데이터를 제거하고 API 연동 코드로 교체.
• 데이터 처리를 위해 UI 기준으로 모델 Class를 만들고 사용했음.

2. 문제점

1. 하드코딩 의존성
   • 초기 화면 제작을 위해 데이터 하드코딩을 많이 사용하다 보니, 실제 API를 붙일 때 교체 과정이 복잡하고 실수가 잦았음.
2. API 정의 완료 시점 지연
   • API 정의가 백엔드 개발 완료 후에야 Swagger로 공유되었기 때문에, 프론트는 UI를 먼저 개발한 다음에 API를 붙일 수 있었음.
3. UI 중심 모델과 API Response 불일치
   • Flutter에서 UI를 기준으로 모델 Class를 설계했기 때문에, 실제 서버 API Response와 구조가 달라 오류가 발생함.
   • 필요 없는 데이터가 포함되거나, 필요한 데이터가 누락되는 문제가 자주 생겼음.

3. 해결 방법

1. API 우선 개발하기
   • 백엔드 구현 전에 최소한의 API 스펙(OpenAPI 문서)을 먼저 정의하고 공유.
   • 이를 기반으로 프론트/백엔드가 병렬 개발 → 하드코딩 의존 줄이기.
2. 코드 생성(Codegen) 도입
   • OpenAPI 문서를 기반으로 Flutter용 모델 Class와 API Client 자동 생성.
   • 수동으로 UI 전용 모델을 만들지 않고, API Response 스펙을 기준으로 사용.
3. Mock 서버 활용
   • 하드코딩 대신 Prism Mock, MSW(Mock Service Worker), Flutter용 Fake Repository 등을 이용.
   • 프론트는 항상 “API 레이어”를 통해 데이터를 가져오게 만들고, 실제 API가 나오면 엔드포인트만 교체.

느낀점

첫 프론트엔드 작업이다 보니 시행착오가 많았다. 특히 UI에 보이는 데이터를 기준으로 모델 Class를 설계한 것이 가장 큰 실수였다. 처음부터 Swagger에 정의된 API 스펙을 참고했다면 실수도 줄고 개발 속도도 더 빨랐을 텐데, “UI를 빨리 완성하고 싶다”는 마음에 무리하게 하드코딩에 의존했던 것 같다. 또한 “실제 API가 나오면 그때 바꾸면 되겠지”라는 막연한 생각으로 접근했지만, 그 결과 교체 과정에서 많은 오류와 비효율이 발생했다. 결국 요구사항에 맞는 UI만 우선 구현하고 뒤에서 맞추려다 보니 후폭풍이 컸다. 이번 경험을 통해 앞으로는 하드코딩을 최소화하되 필요한 경우에는 단순 UI 확인용으로만 제한적으로 사용해야 한다는 점을 깨달았다. 실제 API가 준비되면 바로 연동할 수 있도록, 중요 UI와 API 기반 구조를 함께 고려하며 개발하는 것이 더 효율적이라는 것을 배웠다.

1. 보안 위험

• 누구나 접근 가능: URL만 알면 로그인/권한 검증 없이 모든 사람이 이미지에 접근할 수 있음.
• 데이터 유출: 리뷰 이미지에 개인정보·민감한 데이터가 포함될 경우, 외부 유출 위험이 큼.
• 링크 유출 회수 불가: 한 번 노출된 퍼블릭 URL은 삭제 전까지 계속 유효 → 접근 통제 불가능.

2. 비용/운영 문제

• 무단 트래픽 발생: 다른 사이트에서 이미지 핫링킹이 가능 → 불필요한 S3 egress 비용 발생.
• 트래픽 폭주 대응 어려움: 퍼블릭으로 열려 있으면 DDoS나 무단 다운로드에도 그대로 노출.
• 캐시 제어 한계: 버킷에서 내려주는 응답 헤더 제어가 제한적이라, 캐시 정책 관리가 어렵다.

3. 관리 및 확장성 부족

• 권한 제어 불가: 사용자별/권한별로 접근 허용 범위를 설정할 수 없음.
• 접근 로그/감사 어려움: Presigned URL이나 CloudFront와 달리, “누가 접근했는지” 추적이 힘듦.
• 운영 정책 위반 위험: 보안 규정을 지켜야 하는 서비스(예: 개인정보 처리, 기업 규정)에서는 Public Bucket이 문제 소지가 큼.

각 문제에 대한 해결 방법

1. 보안 위험

누구나 접근 가능

해결:

• S3 모든 퍼블릭 액세스 차단(Block Public Access ON), ACL 비활성/Bucket owner enforced.
• 공개 정책/퍼블릭 ACL 제거 → 직접 URL 접근 불가.
• 오직 서버가 발급한 Presigned GET/PUT(짧은 TTL)으로만 접근.

데이터 유출(민감 이미지 포함 가능)

해결(완화):

• Presigned 짧은 TTL(예: 3~5분) + 서버 인증/인가 통과 후 발급.
• 키 설계: users/{uuid}/avatar/..., review/{date}/... 처럼 소유자/용도별 prefix.
• prefix 검증: PATCH /users/me 등에서 전달된 profileImgKey가 내 prefix로 시작하는지 확인.
• MIME 화이트리스트(예: image/jpeg/png/webp) + (선택) 업로드 후 HEAD 검사/AV 스캔/리사이즈.

링크 유출 회수 불가

해결:

• Presigned는 만료되면 자동 무효 → 유출 창구를 시간으로 제한.
• 즉시 차단이 필요하면 객체 삭제 또는 키 변경.
• (규모↑ 시) CloudFront Signed Cookie/URL로 세션 단위 통제도 가능.

2. 비용/운영 문제

무단 트래픽(핫링킹)로 egress 비용 증가

해결:

• 버킷 Private 전환 → 퍼블릭 핫링킹 원천 차단.
• Presigned는 서버 통과 후 발급되므로 레이트 리밋/WAF로 제어 가능.

트래픽 폭주 대응 어려움

해결:

• Presigned 발급 API에 레이트 리밋/토큰 버킷 적용.
• 업로드/뷰 모두 파일 크기 제한 및 동시 업로드 제한.

3. 관리 및 확장성 부족

권한 제어 불가

해결:

• DB에는 key만 저장, URL 저장 금지.

• 접근은 항상 서버 인증 → 소유자 확인 → Presigned 발급 순서.

• IAM 최소 권한(경로 스코프) 부여:

    {
      "Effect": "Allow",
      "Action": ["s3:GetObject","s3:PutObject","s3:DeleteObject"],
      "Resource": [
        "arn:aws:s3:::<BUCKET>/users/*",
        "arn:aws:s3:::<BUCKET>/review/*"
      ]
    }
  

• 리소스 스코프형 API: POST /users/me/avatar/presigned → PATCH /users/me/avatar → GET /users/me/avatar.

접근 로그/감사 어려움

해결:

• 애플리케이션 로그에 Presigned 발급 이벤트 기록(누가/어떤 key/TTL/IP).
• S3 CloudTrail Data Events(GetObject/PutObject) 또는 Server Access Logs 활성화.
• (CDN 사용 시) CloudFront 액세스 로그로 조회 트래킹.

운영 정책 위반 위험(보안 규정)

해결:

• 기본 암호화(SSE-S3 또는 KMS) 활성화.

• Lifecycle 정책으로 오래된 원본 IA/Glacier 이동.

• 파일명/메타에 PII 포함 금지, 업로드 후 정책 기반 검사(필요 시).

• 버킷 정책에 HTTPS 강제 Deny 추가:

    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:*",
      "Resource": ["arn:aws:s3:::<BUCKET>","arn:aws:s3:::<BUCKET>/*"],
      "Condition": {"Bool": {"aws:SecureTransport": "false"}}
    }
  

S3 Private 설정

• 모든 퍼블릭 액세스 차단을 선택해서 만든다.

I AM 설정

• https://velog.io/@cchoi-geon/AWS-S3-%EC%83%9D%EC%84%B1-%EB%B0%8F-%EA%B6%8C%ED%95%9C-%EC%84%A4%EC%A0%95 에서 s3 권한만 갖은 사용자 생성하기를 참고하면 된다.

코드 설정

1) DTO

// dto/profile.dto.ts
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { IsIn, IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
import { Transform } from 'class-transformer';

export class ProfileImagePresignedDTO {
  @ApiProperty({
    description: '사용자가 업로드하려는 원본 파일명',
    example: 'profile.png',
  })
  @IsString()
  @IsNotEmpty()
  originalName: string;

  @ApiProperty({
    description: '콘텐츠 타입(MIME). 허용되는 이미지 타입만 전달',
    enum: ['image/jpeg', 'image/png', 'image/webp'],
    example: 'image/png',
  })
  @IsString()
  @IsIn(['image/jpeg', 'image/png', 'image/webp'])
  contentType!: string;
}

export class PreSignedURLResponseDto {
  @ApiProperty({ description: 'DB에 저장할 S3 Key', example: 'users/<uuid>/avatar/20250818/xxxx.webp' })
  key!: string;

  @ApiProperty({ description: 'S3로 직접 PUT할 Presigned URL', example: 'https://...X-Amz-Expires=300...' })
  url!: string;

  @ApiProperty({ description: '유효기간(초)', example: 300 })
  expiresIn!: number;

  constructor(args: { key: string; url: string; expiresIn: number }) {
    Object.assign(this, args);
  }
}

export class PresignedUserProfileImgResponseDto {
  @ApiPropertyOptional({ description: '프로필 이미지(표시용) Presigned GET URL', example: 'https://...X-Amz-Expires=300...' })
  profileImg?: string | null;

  @ApiProperty({ description: '유효기간(초)', example: 300 })
  expiresIn!: number;

  constructor(profileImg: string | null, expiresIn: number) {
    this.profileImg = profileImg;
    this.expiresIn = expiresIn;
  }
}

export class UpdateProfileDto {
  @ApiPropertyOptional({ example: '소소한유저' })
  @IsOptional()
  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
  @Matches(/^[^\\x00-\\x1F\\x7F]*$/, { message: '제어 문자를 포함할 수 없습니다.' })
  @Matches(/^(?!.*(<script|<\\/script>|<iframe|on\\w+=|javascript:|eval\\()).*$/i, { message: '스크립트 또는 악성 코드를 포함할 수 없습니다.' })
  @Matches(/^[A-Za-z0-9가-힣 _-]{2,20}$/, { message: '닉네임은 2~20자' })
  nickName?: string | null;

  @ApiPropertyOptional({ description: '업로드 완료된 S3 Key', example: 'users/<uuid>/avatar/20250818/xxxx.webp' })
  @IsOptional()
  profileImgKey?: string | null;
}

2) AWS Service

// aws/aws.service.ts
import {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
  HeadObjectCommand,
  DeleteObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { Injectable, BadRequestException, NotFoundException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { randomUUID } from 'crypto';

const ALLOWED_IMAGE_MIME = ['image/jpeg','image/png','image/webp']; // Common 폴더에서 관리

@Injectable()
export class AwsService {
  private readonly s3: S3Client;
  private readonly bucket: string;
  private readonly region: string;

  constructor(private readonly config: ConfigService) {
    this.region = this.config.get<string>('AWS_REGION')!;
    this.bucket = this.config.get<string>('AWS_BUCKET_NAME')!;
    this.s3 = new S3Client({
      region: this.region,
      credentials: {
        accessKeyId: this.config.get<string>('AWS_ACCESS_KEY')!,
        secretAccessKey: this.config.get<string>('AWS_SECRET_ACCESS_KEY')!,
      },
    });
  }

  /** 프로필 이미지 전용 Key 생성 */
  private generateReviewKey(originalName: string) {
    const safe = originalName.replace(/[^\w.\-]/g, '_');
    const yyyy = new Date().toISOString().slice(0, 10).replace(/-/g, '');
    return `review/${yyyy}/${Date.now()}-${safe}`;
  }

  /** PUT용 Presigned (키 지정) */
  async getPresignedPutUrlByKey(key: string, contentType: string, ttlSec = 300) {
    if (!ALLOWED_IMAGE_MIME.includes(contentType)) {
      throw new BadRequestException(`Unsupported contentType: ${contentType}`);
    }
    const cmd = new PutObjectCommand({
      Bucket: this.bucket,
      Key: key,
      ContentType: contentType,
    });
    const url = await getSignedUrl(this.s3, cmd, { expiresIn: ttlSec });
    return { key, url, expiresIn: ttlSec };
  }

  /** GET용 Presigned (표시) */
  async getPresignedGetUrlByKey(key: string, ttlSec = 300, disposition: string = 'inline') {
    const cmd = new GetObjectCommand({
      Bucket: this.bucket,
      Key: key,
      ResponseContentDisposition: disposition,
    });
    return getSignedUrl(this.s3, cmd, { expiresIn: ttlSec });
  }

  /** 존재 확인(선택) */
  async assertObjectExists(key: string) {
    try {
      await this.s3.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
    } catch {
      throw new NotFoundException('S3 object not found');
    }
  }

  async deleteByKey(key: string) {
    await this.s3.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
  }
}

3) Users Service

// users/users.service.ts
import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
import { AwsService } from '../aws/aws.service';
import { ProfileImagePresignRequestDto, PreSignedURLResponseDto, PresignedUserProfileImgResponseDto, UpdateProfileDto } from './dto/profile.dto';

@Injectable()
export class UsersService {
  constructor(
    private readonly aws: AwsService,
    // private readonly userRepository: UserRepository, // 실제 구현 주입
  ) {}

  /** 업로드용 Presigned 발급 */
  async createProfileImagePresignedUrl(profileImagePresignedDTO: ProfileImagePresignedDTO, uuid: string) {
    const { originalName, contentType } = profileImagePresignedDTO;
    const result = await this.awsService.getPresignedPutUrl(originalName, contentType);

    return new PreSignedURLResponsesDTO(result);
  }

  /** 프로필 정보 업데이트(닉네임/프로필 이미지 키) */
  async updateUserProfile(update: UpdateProfileDto, uuid: string) {
    const { nickName, profileImgKey } = update;

    if (nickName) {
      const exists = await this.userRepository.findUserByNickName(nickName);
      if (exists) throw new ConflictException('Nickname already exists.');
      const r = await this.userRepository.updateNickName(uuid, nickName);
      if (r.affected === 0) throw new NotFoundException('Fail update nickname');
    }

    if (profileImgKey) {
      // (선택) 실제 존재 확인
      await this.aws.assertObjectExists(profileImgKey);
      const updateUrl = await this.userRepository.updateUserPhotoUrl(uuid, profileImgKey);
      if (updateUrl.affected == 0) throw new NotFoundException('Fail update profileImg');
    }
  }

  /** 표시용 Presigned GET */
  async getPresignedURLUserProfileImg(uuid: string) {
    const user = await this.userRepository.findUserByUUID(uuid);
    if (!user) throw new NotFoundException('Not Found User');

    const expiresIn = 300;
    const url = await this.aws.getPresignedGetUrlByKey(user.photoUrl, expiresIn, 'inline');
    return new PresignedUserProfileImgResponseDto(url, expiresIn);
  }
}

4) Users Controller

// users/users.controller.ts
import { Body, Controller, Get, Patch, Post, UseGuards } from '@nestjs/common';
import { ApiBearerAuth, ApiExtraModels, ApiOkResponse, ApiOperation, getSchemaPath } from '@nestjs/swagger';
import { JwtAuthGuard } from '../auth/jwt.guard';
import { GetUUID } from '../common/decorators/get-uuid.decorator';
import { UsersService } from './users.service';
import { ProfileImagePresignRequestDto, PreSignedURLResponseDto, PresignedUserProfileImgResponseDto, UpdateProfileDto } from './dto/profile.dto';
import { SuccessResponseDTO, SuccessNoResultResponseDTO } from '../common/response/response.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Patch('/me')
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: '프로필 정보 수정(닉네임/프로필 이미지 키)' })
  @ApiOkResponse({ description: '프로필 정보 수정 성공', type: SuccessNoResultResponseDTO })
  async updateProfile(@GetUUID() uuid: string, @Body() dto: UpdateProfileDto) {
    await this.users.updateUserProfile(dto, uuid);
    return new SuccessNoResultResponseDTO();
  }

  @Post('/me/avatar/presigned')
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiExtraModels(SuccessResponseDTO, PreSignedURLResponseDto)
  @ApiOperation({ summary: '프로필 이미지 업로드용 Presigned(PUT) 발급' })
  @ApiOkResponse({
    description: 'Presigned URL 발급 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        { properties: { result: { $ref: getSchemaPath(PreSignedURLResponseDto) } } },
      ],
    },
  })
  async generateProfileImagePresignedUrl(@GetUUID() uuid: string, @Body() dto: ProfileImagePresignRequestDto) {
    const result = await this.users.createProfileImagePresignedUrl(dto, uuid);
    return new SuccessResponseDTO(result);
  }

  @Get('/me/avatar')
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiExtraModels(SuccessResponseDTO, PresignedUserProfileImgResponseDto)
  @ApiOperation({ summary: '프로필 이미지 보기(Presigned GET URL 반환)' })
  @ApiOkResponse({
    description: 'Presigned URL 발급 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        { properties: { result: { $ref: getSchemaPath(PresignedUserProfileImgResponseDto) } } },
      ],
    },
  })
  async getMyAvatar(@GetUUID() uuid: string) {
    const result = await this.users.getPresignedURLUserProfileImg(uuid);
    return new SuccessResponseDTO(result);
  }
}

5) Flow

1. 업로드 준비 (Presigned 발급)
   • 클라 → POST /users/me/avatar/presigned (body: { originalName,contentType })
     • 파일 이름: originalName
     • 파일 타입: contentType
   • 서버:
     • generateProfileKey로 내 소유 prefix 키 생성
     • getPresignedPutUrlByKey(key, contentType, 300)으로 PUT Presigned URL 발급
   • 응답: { key, url, expiresIn }
2. 브라우저에서 S3 업로드
   • 클라 → PUT url (헤더: Content-Type: <파일 MIME>, 바디: 파일)
   • 버킷 CORS에 AllowedOrigins=프론트, Methods=PUT,GET,HEAD가 설정되어 있어야 함
3. 프로필에 반영 (DB 저장) (2번에서 Success후)
   • 클라 → PATCH /users/me (body: { profileImgKey, nickName? })
   • 서버:
     • prefix 검증: profileImgKey가 users/{uuid}/avatar/로 시작하는지 확인
     • (선택) HeadObject로 실존 확인
     • DB에 photoUrl = key 저장 (닉네임도 있으면 중복검사 후 업데이트)
     • (옵션) 기존 아바타 키가 있으면 백그라운드로 삭제
4. 조회 (표시용 URL 받기)
   • 클라 → GET /users/me/avatar
   • 서버:
     • DB에서 내 photoUrl(=key) 조회
     • getPresignedGetUrlByKey(key, 300, 'inline')으로 GET Presigned URL 발급
   • 응답: { profileImg: <url>, expiresIn: 300 }
   • 클라는 <img src={profileImg}>로 렌더링 (만료되면 다시 호출)

• 기존 프로젝트에서는 각 도메인별로 하나의 DTO만 두며 사용하고 있었다.

문제점

단일 책임 원칙(SRP) 위반

하나의 파일에 Query, Path, Body, Response, 내부용 DTO까지 모두 몰아 넣다 보니 변경 사유가 여러 개가 된다. 그 결과 수정 범위가 불필요하게 커지고, 코드 리뷰도 비효율적으로 진행된다.

이름 충돌/네이밍 난맥상

CreateXDto, CreateXRequest, CreateXResponse가 한 파일에서 중복/혼용되며 import 시 오타·충돌 위험 증가.

변경 파급(캡슐화 붕괴)

특정 엔드포인트의 스펙만 바꿔도 같은 파일을 건드리면서 다른 DTO까지 린터/빌드/테스트에 영향 → 작은 변경도 큰 PR로 부풀어짐.

바뀐 DTO

리팩토링 결과 설명

1) Params는 DTO에서 분리 (파이프 사용)

• 의도: 경로 변수는 대부분 스칼라 타입(숫자/문자열)이라 DTO까지 만들 필요가 없음.
• 사용: Nest의 @Param() + 파이프(예: ParseIntPipe)로 즉시 변환·검증.
• 효과: DTO 파일에서 불필요한 타입을 제거 → DTO는 “메시지 바디/쿼리/응답”에만 집중.

// controller
@Get('/:shopId')
getShop(@Param('shopId', ParseIntPipe) shopId: number) {
  return this.shopService.findOne(shopId);
}

2) dto/query/ — Query 전용 DTO

• 의도: 페이지네이션, 정렬, 필터 등 URL 쿼리스트링을 명확히 분리.

• 특징:

  • class-transformer로 숫자/불리언 변환 (@Type(() => Number), @Transform(...)).
  • class-validator로 유효성 보장 (@IsInt, @Min, @IsOptional 등).
  • Swagger 문서화(@ApiPropertyOptional)로 클라이언트와 스펙 공유.

• 예: pagination.dto.ts, user.dto.ts(사용자 조회 조건 등)

// shop/dto/query/pagination.dto.ts
import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsInt, IsOptional, Min } from 'class-validator';
import { Type } from 'class-transformer';

export class GetShopWithin1KmDTO {
  @ApiProperty({ description: '위도', example: 37.5665 })
  @IsNumber()
  @IsNotEmpty()
  @Type(() => Number)
  lat: number;

  @ApiProperty({ description: '경도', example: 127 })
  @IsNumber()
  @IsNotEmpty()
  @Type(() => Number)
  lng: number;

사용처:

async getShopWithin1Km(
  @Query() getShopWithin1KmDTO: GetShopWithin1KmDTO,               @GetUUID() uuid: string
) {...}

3) dto/requests/ — RequestBody 전용 DTO

• 의도: 클라이언트가 서버로 보내는 데이터(Body) 만을 명확히 규정.

• 특징:

  • 입력 검증 중심(class-validator 필수).
  • 서버가 관리하는 필드(id, createdAt 등)는 절대 포함하지 않음.
  • 엔드포인트별로 구분: user_requests.dto.ts, wishlist_requests.dto.ts, review_request.dto.ts 등.

• 효과: 입력 스키마가 명확해지고 Under/Over-posting 위험 감소.

// shop/dto/requests/review_request.dto.ts
import { ApiProperty } from '@nestjs/swagger';
import { IsInt, IsNotEmpty, IsString, MaxLength, Min, Type } from 'class-transformer';

export class SubmitNewShopDto {
  @ApiProperty({ description: '소품샵 정보' })
  @IsNotEmpty()
  shop: SubmitShop;

  @ApiPropertyOptional({ description: '운영 시간 정보' })
  operatingHours?: OperatingHoursDto;

  @ApiPropertyOptional({ description: '판매 제품 리스트', type: [Products] })
  products?: Products[];
}

사용처:

  async submitNewShop(
    @Body() newShopData: SubmitNewShopDto, 
    @GetUUID() uuid: string
  ) {...}

4) dto/responses/ — Response 전용 DTO(ViewModel)

• 의도: 서버가 클라이언트로 반환하는 형태를 명확히 분리(엔티티와 분리).

• 특징:

  • 문서화 중심(@ApiProperty 적극 사용).
  • 가공/집계 필드, 관계형 데이터의 표현용 구조를 포함 가능.
  • 검증 데코레이터는 보통 생략하고, 필요 시 class-transformer의 @Expose/@Transform으로 직렬화 제어.
  • 페이지네이션 래퍼(pagination_response.dto.ts) 등 공용 뷰모델 제공.

• 효과: 엔티티 스키마 변경이 외부 계약을 곧바로 흔들지 않음. 응답 일관성↑.

// shop/dto/responses/shop_responses.dto.ts
import { ApiProperty } from '@nestjs/swagger';

export class ShopWithin1KmResponseItemDTO {
  @ApiProperty({ example: 1 })
  id: number;

  @ApiProperty({ example: 'Green Valley Market' })
  name: string;

  ...
}

서비스 → 응답 매핑은 어셈블러/프레젠터에서:

  return new ShopSearchPageNationResultDTO(mappedResults, pageInfoDTO);

5) 이 구조의 핵심 장점

• 계약 명확화: 입력(Query/Body)과 출력(Response)을 분리해 API 계약이 선명.
• SRP 준수: 목적별 DTO로 파일·리뷰 범위 축소.
• 테스트 용이: 각 DTO를 독립적으로 검증 테스트 가능.
• 문서 품질↑: Swagger 스키마가 역할별로 정돈.
• 버저닝 용이: v1/v2 응답 DTO를 폴더로 공존시키기 쉬움.

• https://docs.nestjs.com/openapi/introduction

기존 Swagger 문서 관리

• 현재 Swagger 문서를 직접 생성해서 수동으로 작성하고 있었음.

• swagger 문서 생성 및 외부 문서 병합하여 사용 중. swaggerDocs.paths와 기존 document.paths를 병합 → 수동 정의된 Swagger 문서(swaggerDocs)를 병합해 함께 사용하려는 목적

  const document = SwaggerModule.createDocument(app, config);
  (document as any).paths = {
  ...document.paths,
  ...swaggerDocs.paths,
  };

  수동 작성에 따른 문제점

• 개발 과정에서 매개변수나 로직이 변경되면서 쿼리스트링, 응답 데이터(Response) 등이 자주 수정되는 경우가 있었다. 그러나 매번 변경 사항을 수동으로 반영하다 보니, 최신 상태로 유지되지 않는 경우가 종종 발생했다.

데코레이터 기반 자동화 전환

import { Controller, Get, Param, ParseIntPipe, Query, UseGuards } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiOkResponse, getSchemaPath, ApiExtraModels } from '@nestjs/swagger';
import { ShopService } from './shop.service';
import { SuccessResponseDTO } from 'src/common/response/response.dto';
import { GetSearchPageShopDTO, GetShopByShopIdDTO, GetShopWithin1KmDTO, ShopSearchPageNationResultDTO } from './dto/paging.dto';
import { GetUUID } from '../../common/deco/get-user.deco';
import { OptionalAuthGuard } from 'src/common/gurad/optional-auth-guard.guard';
import { ShopDetailResponseDTO, ShopRegionDTO, ShopWithin1KmResponseItemDTO } from './dto/response.dto';

@ApiTags('Shop')
@Controller('shop')
export class ShopController {
  constructor(private shopService: ShopService) {}

  @Get('/')
  @ApiOperation({
    summary: '1km 반경 내 소품샵 조회',
    description: '사용자 위치 기준 1km 반경 내의 소품샵들을 조회합니다. 거리순 또는 인기순으로 정렬할 수 있습니다.',
  })
  @ApiExtraModels(SuccessResponseDTO, ShopWithin1KmResponseItemDTO)
  @ApiOkResponse({
    description: '소품샵 목록 조회 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        {
          properties: {
            result: {
              type: 'array',
              items: { $ref: getSchemaPath(ShopWithin1KmResponseItemDTO) },
            },
          },
        },
      ],
    },
  })
  @UseGuards(OptionalAuthGuard)
  async getShopWithin1Km(@Query() getShopWithin1KmDTO: GetShopWithin1KmDTO, @GetUUID() uuid: string) {
    return new SuccessResponseDTO(await this.shopService.findShopsWithin1Km(getShopWithin1KmDTO, uuid));
  }

  @Get('/search')
  @ApiOperation({
    summary: '키워드로 소품샵 검색',
    description: '키워드를 사용하여 소품샵을 검색합니다.',
  })
  @ApiExtraModels(SuccessResponseDTO, ShopSearchPageNationResultDTO)
  @ApiOkResponse({
    description: '검색 결과 조회 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        {
          properties: {
            result: {
              $ref: getSchemaPath(ShopSearchPageNationResultDTO),
            },
          },
        },
      ],
    },
  })
  async getSearchPageShop(@Query() getSearchPageShopDTO: GetSearchPageShopDTO) {
    return new SuccessResponseDTO(await this.shopService.findShopsByKeyword(getSearchPageShopDTO));
  }

  @Get('/region')
  @ApiOperation({
    summary: '전체 지역 조회',
    description: '소품샵이 있는 모든 지역을 조회합니다.',
  })
  @ApiExtraModels(SuccessResponseDTO, ShopRegionDTO)
  @ApiOkResponse({
    description: '지역 목록 조회 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        {
          properties: {
            result: {
              type: 'array',
              items: { $ref: getSchemaPath(ShopRegionDTO) },
            },
          },
        },
      ],
    },
  })
  async getAllShopRegion() {
    return new SuccessResponseDTO(await this.shopService.findAllShopRegion());
  }

  @Get('/temp')
  @ApiResponse({
    status: 200,
    description: '임시 데이터 조회 성공',
  })
  async getTemp() {
    return new SuccessResponseDTO(await this.shopService.findTemp());
  }

  @ApiBearerAuth('JWT-auth')
  @Get('/:shopId')
  @ApiOperation({
    summary: '소품샵 상세 정보 조회',
    description: '특정 소품샵의 상세 정보를 조회합니다.',
  })
  @ApiExtraModels(SuccessResponseDTO, ShopDetailResponseDTO)
  @ApiOkResponse({
    description: '소품샵 상세 정보 조회 성공',
    schema: {
      allOf: [
        { $ref: getSchemaPath(SuccessResponseDTO) },
        {
          properties: {
            result: { $ref: getSchemaPath(ShopDetailResponseDTO) },
          },
        },
      ],
    },
  })
  @UseGuards(OptionalAuthGuard)
  async getShopByShopId(@Param() getShopByShopIdDTO: GetShopByShopIdDTO, @GetUUID() uuid: string) {
    return new SuccessResponseDTO(await this.shopService.findShopByShopId(getShopByShopIdDTO, uuid));
  }
}

막혔던 부분

• 현재 아래 형태로 response가 되게 사용 중이였다.

  {
  message: string
  statusCode: number
  result: T
  }

• 따라서 Swagger에서 Response를 정의할 때 해당 API에 맞는 ResponseDTO를 result 타입에 정의해줘야 했다.
• 하지만 아래와 같이 코드를 작성했을 때 result의 타입을 Swagger에서 인식하지 못하는 오류가 발생했다.

  @ApiOkResponse({
  description: '소품샵 목록 조회 성공',
  schema: {
    allOf: [
      { $ref: getSchemaPath(SuccessResponseDTO) },
      {
        properties: {
          result: {
            type: 'array',
            items: { $ref: getSchemaPath(ShopWithin1KmResponseItemDTO) }
          }
        }
      }
    ]
  }
  })

  

• 찾아보니 @ApiExtraModels를 통해 Swagger에게 명시적으로 "이 DTO들 쓸 거야" 라고 등록하는 작업을 했어야 했다. NestJS는 제네릭 타입이나 중첩된 타입은 자동으로 감지 못하기 때문에, 수동으로 알려줘야 Swagger가 올바르게 문서를 생성한다.

• 따라서 아래와 같이 코드를 수정했다.

  @ApiExtraModels(SuccessResponseDTO, ShopWithin1KmResponseItemDTO)
  @ApiOkResponse({
  description: '소품샵 목록 조회 성공',
  schema: {
    allOf: [
      { $ref: getSchemaPath(SuccessResponseDTO) },
      {
        properties: {
          result: {
            type: 'array',
            items: { $ref: getSchemaPath(ShopWithin1KmResponseItemDTO) }
          }
        }
      }
    ]
  }
  })
  

![](https://velog.velcdn.com/images/cchoi-geon/post/f51af9f7-0089-481d-a25e-8c5cfb91cf69/image.png)


### `@ApiExtraModels(...)`란?

```tsx
@ApiExtraModels(SuccessResponseDTO, ShopWithin1KmResponseItemDTO)

• Swagger에게 명시적으로 "이 DTO들 쓸 거야" 라고 등록하는 작업.
• NestJS는 제네릭 타입이나 중첩된 타입은 자동으로 감지 못하기 때문에, 수동으로 알려줘야 Swagger가 올바르게 문서를 생성한다.

@ApiOkResponse({ schema: ... })란?

@ApiOkResponse({
  description: '소품샵 목록 조회 성공',
  schema: {
    allOf: [
      { $ref: getSchemaPath(SuccessResponseDTO) },
      {
        properties: {
          result: {
            type: 'array',
            items: { $ref: getSchemaPath(ShopWithin1KmResponseItemDTO) }
          }
        }
      }
    ]
  }
})

• Swagger에 "응답은 SuccessResponseDTO이고, result는 배열이야" 라고 구체적으로 알려주는 코드

allOf: [...]란?

• Swagger/OpenAPI에서 스키마 조합을 의미함
• SuccessResponseDTO의 기본 구조 사용 (message, statusCode, result)
• 그 안의 result 속성만 구체적으로 다시 정의함 (배열 형태로 덮어쓰기)

{
  "message": "Success",
  "statusCode": 200,
  "result": [
    {
      "id": 1,
      "name": "Green Valley Market",
      "lat": 37.5665,
      ...
    }
  ]
}

getSchemaPath(...)란?

getSchemaPath(SuccessResponseDTO)

• DTO 클래스를 $ref 형식의 Swagger 경로(#/components/schemas/...)로 변환해줌
• Swagger 문서 내부에서 $ref를 통해 재사용 가능한 객체 스키마를 지정할 수 있음

코드 설명

@ApiOkResponse 데코레이터는 해당 API가 성공적으로 응답했을 때의 응답 형식을 Swagger 문서에 명시하는 역할을 한다.

이 코드에서는 응답이 SuccessResponseDTO 구조를 따르되, 그 안의 result 필드는 ShopWithin1KmResponseItemDTO 타입의 객체 배열임을 명확하게 정의하고 있다.

allOf 키워드를 사용해 기본 응답 구조(message, statusCode, result)는 SuccessResponseDTO로부터 참조하고, 그 중 result 필드만 ShopWithin1KmResponseItemDTO[]로 덮어써서 Swagger 문서에 반영하는 방식이다.

궁금증

• 현재 서비스에서 JWT Auth 인증이 필요하지 않은 API들이 존재한다. 따라서

  @ApiTags('User')
  @ApiBearerAuth('JWT-auth')
  @Controller('user')

위처럼 사용하지 못하고, 각 EndPoint 별로 @ApiBearerAuth('JWT-auth') 를 설정해줘야 하는 번거로움이 생겼다.

  @ApiBearerAuth('JWT-auth')
  @Delete('/:uuid')
  @UseGuards(JwtAuthGuard)
  async deleteUser(@Query('deleteType') deleteType: number, @Param('uuid') uuid: string, @GetUUID() currentUUID: string) {
    if (uuid !== currentUUID) throw new ConflictException('Not equal User UUID');
    return new SuccessResponseDTO(await this.userService.deleteUser(uuid, deleteType));
  }

  ...

  @ApiBearerAuth('JWT-auth')
  @Post('/nickname')
  @UseGuards(JwtAuthGuard)
  async setNickName(@Body() nickNameDTO: NickNameDTO, @GetUUID() uuid: string) {
    return new SuccessResponseDTO(await this.userService.findAndUpdateUserNickname(nickNameDTO, uuid));
  }

• 여기서 든 생각이
  1. 어차피 @ApiBearerAuth('JWT-auth') 를 각 Controller의 상단에 배치시켜도 동작하는 데는 문제가 없으니 상단에 항상 배치할까?
  2. 실제 JWT 로직인 @UseGuards(JwtAuthGuard) 와 @ApiBearerAuth('JWT-auth') 를 묶은 데코레이터를 사용할까?
  • 위 두가지였다.
• 1번의 경우 번거로움도 없고 로직상 추가되는 것도 없어서 편할 것 같지만 Swagger란 API를 문서화하기 위한 도구인데, JWT Auth 로직이 필요하지 않는 곳에 Swagger에서 자물쇠가 걸려있다면 JWT가 필요한 로직으로 착각할 수 있을 것 같다.
• 따라서 2번을 택하는 게 좋다고 생각한다.

export function AuthGuardWithSwagger() {
  return applyDecorators(
    UseGuards(JwtAuthGuard),
    ApiBearerAuth('JWT-auth'),
  );
}

  @Delete('/:uuid')
  AuthGuardWithSwagger()
  async deleteUser(@Query('deleteType') deleteType: number, @Param('uuid') uuid: string, @GetUUID() currentUUID: string) {
    if (uuid !== currentUUID) throw new ConflictException('Not equal User UUID');
    return new SuccessResponseDTO(await this.userService.deleteUser(uuid, deleteType));
  }

  ...

  @Post('/nickname')
    AuthGuardWithSwagger()
  async setNickName(@Body() nickNameDTO: NickNameDTO, @GetUUID() uuid: string) {
    return new SuccessResponseDTO(await this.userService.findAndUpdateUserNickname(nickNameDTO, uuid));
  }

• 이게 최선의 방법인지 모르겠다...

• 소품샵 정보를 제공하고, 리뷰·운영시간·상품 등을 포함한 상세 데이터를 보여주는 서비스

사이트

• https://soso-client-soso-web.vercel.app/

기존 API Endpoint

사용자 관련 (/user)

• DELETE /user/:uuid: 사용자 삭제
• GET /user/nickname/:nickName: 닉네임 중복 체크
• GET /user/profile: 사용자 프로필 조회
• GET /user/submit: 사용자의 제출 기록 조회
• GET /user/review: 사용자의 리뷰 목록 조회
• GET /user/wishlist: 사용자의 위시리스트 조회

상점 관련 (/shop)

• GET /shop/: 1km 이내의 상점 조회
• GET /shop/search: 키워드로 상점 검색
• GET /shop/region: 모든 상점 지역 조회
• GET /shop/temp: 임시 상점 목록 조회
• GET /shop/:shopId: 특정 상점 상세 정보 조회

제출 관련 (/submit)

• POST /submit/: 새로운 상점 제출
• POST /submit/operating: 상점 운영 시간 제출
• POST /submit/products: 상품 정보 제출

신고 관련 (/report)

• POST /report/review: 리뷰 신고
• POST /report/shop: 상점 신고

위시리스트 관련 (/wishlist)

• POST /wishlist/: 위시리스트 추가

최근 검색어 관련 (/recent-search)

• GET /recent-search/: 최근 검색어 조회
• DELETE /recent-search/: 특정 최근 검색어 삭제
• DELETE /recent-search/all: 모든 최근 검색어 삭제

공지사항 관련 (/notice)

• GET /notice/: 공지사항 목록 조회

피드백 관련 (/feedback)

• POST /feedback/: 피드백 저장

RESTFul API로 수정한 Endpoint

사용자 관련 (/users)

• GET /users/me 프로필 정보 불러오기
• PATCH /users/me 프로필 정보 수정하기
• DELETE /users/me 회원탈퇴
• GET /users/duplicate-check 닉네임 중복 체크
• GET /users/me/shop-submissions 사용자가 등록/제안한 소품샵 목록
• DELETE /users/me/shop-submissions/{submitId} 제보한 데이터 삭제
• GET /users/me/reviews 사용자가 등록한 리뷰 목록
• GET /users/me/wishlist 사용자가 찜한 소품샵 리스트
• POST /users/me/wishlist 소품샵 찜하기
• GET /users/me/recent-searches 최근 검색 기록 조회
• DELETE /users/me/recent-searches 최근 검색 기록 전체 삭제
• DELETE /users/me/recent-searches/{recentSearchId} 최근 검색 기록 개별 삭제

상점 관련 (/shops)

• GET /shops 1km 반경 내 소품샵 조회
• POST /shops 새로운 소품샵 제보
• GET /shops/search 키워드로 소품샵 검색
• GET /shops/temp 임시 소품샵 목록 조회
• GET /shops/{shopId} 소품샵 상세 정보 조회
• POST /shops/{shopId}/operating 소품샵 운영정보 제보
• POST /shops/{shopId}/products 소품샵 판매 목록 제보
• POST /shops/{shopId}/reviews 리뷰 작성
• PATCH /shops/{shopId}/reviews/{reviewId} 리뷰 수정
• DELETE /shops/{shopId}/reviews/{reviewId} 리뷰 삭제
• POST /shops/{shopId}/shop/report 소품샵 신고
• POST /shops/{shopId}/reviews/{reviewId}/report 리뷰 신고

RESTFul API로 적용 후 느낀점

문제점

일단 Users와 Shops 도메인에 너무 많은 코드가 몰렸다. 코드 리팩토링할 때 힘들 것 같다. 수정이 생기거나, 추가해야 되는 부분이 있을 경우 힘들 것 같다.

내가 원하는 방향

나는 엔드포인트를 도메인별(Review, Report 등)로 분리하는 것이 더 효율적이라고 생각한다. 그 이유는, 도메인 단위로 구분하면 유지보수가 용이하고 코드가 한곳에 과도하게 몰리지 않아 수정 시에도 훨씬 수월하기 때문이다.

앞으로 계획

OpenAPI와 스웨거를 활용한 실전 API 설계 책: https://product.kyobobook.co.kr/detail/S000211655004 을 읽고 RESTFul에 대한 공부를 더 한 뒤 추가적으로 글을 쓸 예정이다!

• 어느 날 서버 500 에러가 나더니, 위처럼 오류가 발생했다.
• 이유를 찾던 도중 SSL 인증서(HTTPS 인증서)의 유효 기간 또는 날짜 설정에 관련된 문제라는 글을 발견했다.
• 해당 상태는 SSL 인증서의 유효 기간이 만료되어 생기는 문제였다.

해결 방법

1. 인증서 만료 여부 확인

• 처음에 인증서를 어디에 두었는지부터 찾아야 한다. /opt/bitnami/letsencrypt/certificates/ 나는 이 곳에 두었다.

• 인증서를 확인해야 하므로, .crt인 파일을 찾아야 한다. sudo openssl x509 -in /opt/bitnami/letsencrypt/certificates/api.sosohan.shop.crt -noout -dates

notBefore=May  1 10:02:29 2025 GMT
notAfter=Jul 30 10:02:28 2025 GMT  ← 이게 과거면 만료됨

• 위처럼 결과가 나오는데, noAfter을 현재 날짜와 비교해서 만료되었다면 인증서를 재발급 받아야 한다.
• Jul 30으로 되어 있기 때문에 현재 8월 1일이므로 기한이 만료됐다...

1-1. 인증서 발급시 등록한 이메일 찾기

• 등록한 이메일을 알아야 재발급이 가능하다.
• 아래와 같은 명령어로 등록한 이메일을 찾을 수 있다.

  # 경로 이동
  cd /opt/bitnami/letsencrypt/accounts/acme-v02.api.letsencrypt.org/
  

#내부 확인 ls

#### 2. 인증서 재발급 받기

sudo /opt/bitnami/letsencrypt/lego
--tls
--email 이메일
--domains 도메인
--path "/opt/bitnami/letsencrypt"
renew

- 위 코드를 입력해주면 완성이다.
- 단 주의할게 있는데, 위 명령어에서 443 포트를 잠깐 점유해야 하기 때문에 다른 프로세스 (예: nginx, Node.js 등)가 443을 사용 중이면 충돌이 생긴다. 따라서 실행 중인 서비스를 중단해야 한다. 

• https://typeorm.io/working-with-repository

Repository란?

• TypeORM에서 특정 엔티티(User 등) 에 대해 데이터베이스 작업(조회, 저장, 삭제 등)을 수행하는 전용 도구
• EntityManager와 유사하지만, 하나의 엔티티에만 집중하도록 설계되어 있어 타입 안전성(Type Safety) 이 높고, 코드가 간결해진다.

Repository는 특정 엔티티 전용의 EntityManager다.

import { User } from "./entity/User"

const userRepository = dataSource.getRepository(User)
const user = await userRepository.findOneBy({
    id: 1,
})
user.name = "Umed"
await userRepository.save(user)

주요 옵션

1. select

• 반환되는 객체에서 가져올 컬럼만 지정

userRepository.find({
  select: {
    firstName: true,
    lastName: true,
  },
})
// → SELECT "firstName", "lastName" FROM "user"

2. relations

• 관계 설정된 엔티티도 함께 가져옴 (JOIN)

userRepository.find({
  relations: {
    profile: true,
    photos: true,
  },
})

• 중첩도 가능:

relations: {
  videos: {
    videoAttributes: true,
  },
}

3. where

• 조건 설정. AND 연산자처럼 작동

where: {
  firstName: "Timber",
  lastName: "Saw",
}

• 관계 엔티티 조건:

where: {
  project: {
    name: "TypeORM",
    initials: "TORM",
  },
}

4. OR 조건

• 여러 조건 중 하나라도 만족하면

where: [
  { firstName: "Timber", lastName: "Saw" },
  { firstName: "Stan", lastName: "Lee" },
]

5. order

• 정렬 지정

order: {
  name: "ASC",
  id: "DESC",
}

6. skip + take

• pagination 구현 시 사용:

skip: 5,   // OFFSET
take: 10,  // LIMIT

MSSQL에서는 order 없으면 오류 발생하므로 함께 사용해야 함

7. withDeleted

• softDelete된 데이터까지 포함

withDeleted: true

8. cache

• 결과 캐싱 사용

cache: true

9. lock

lock: { mode: "optimistic", version: 1 }

조건자(Advanced Operators)

findBy() 또는 where에서 사용할 수 있는 조건자들

Repository 주요 기능

사용 예시

기본 생성 & 저장

const user = repository.create({ firstName: "Timber" })
await repository.save(user)

조건 검색

await repository.find({ where: { firstName: "Timber" } })
await repository.findBy({ firstName: "Timber" }) // 더 단순

업데이트 & 업서트

await repository.update(1, { age: 30 })
await repository.upsert([{ externalId: "abc123", name: "Timber" }], ["externalId"])

삭제

await repository.delete(1)
await repository.softDelete({ name: "Timber" })
await repository.restore(1)

통계 메서드

await repository.countBy({ firstName: "Timber" })
await repository.sum("age", { active: true })
await repository.maximum("score", {})

Raw Query

await repository.query("SELECT * FROM user WHERE name = ?", ["John"])

preload() vs merge() 차이

Additional Options 예시

Save 시

await repository.save(users, {
  chunk: 1000, // 매우 큰 데이터 분할 저장
  transaction: false, // 트랜잭션 사용 안함
  listeners: false // subscriber 이벤트 발생 안함
})

Remove 시

await repository.remove(users, {
  chunk: 1000,
  transaction: false,
})

• https://typeorm.io/working-with-entity-manager

EntityManager란?

• TypeORM에서 모든 엔티티에 대해 삽입(insert), 조회(find), 수정(update), 삭제(delete) 등의 작업을 하나의 객체로 처리할 수 있게 해주는 중앙 관리자 같은 역할을 한다.

• Repository들을 일일이 가져오지 않고도, EntityManager만으로 대부분의 DB 조작이 가능하다.

예시 코드

import { DataSource } from "typeorm"
import { User } from "./entity/User"

const myDataSource = new DataSource(/*...*/)
const user = await myDataSource.manager.findOneBy(User, {
    id: 1,
})
user.name = "Umed"
await myDataSource.manager.save(user)

EntityManager와 Repository의 차이점

• Repository가 한 엔티티에 특화된 도구라면, EntityManager는 전체 엔티티에 대해 범용적으로 사용할 수 있는 관리자다.

사용 방법

Entity 생성 및 병합

데이터 조작 메서드

조회 관련 메서드

기타

사용 예시 요약

// 조회
const user = await manager.findOne(User, { where: { id: 1 } })

// 생성
const user = manager.create(User, { name: 'Timber' })
await manager.save(user)

// 트랜잭션
await manager.transaction(async (m) => {
  await m.update(User, 1, { name: 'Updated' })
})

• https://typeorm.io/relations#cascade-options

Relation 종류

1. 일대일 (One-to-One)

• 한 엔티티가 다른 엔티티와 1:1로 매핑됩니다. 예를 들어, 한 사용자가 하나의 프로필을 가질 수 있다.

    @OneToOne(() => Profile)
    @JoinColumn()
    profile: Profile;
  

2. 일대다 / 다대일 (One-to-Many / Many-to-One)

• 한 엔티티가 여러 엔티티와 연관되거나, 여러 엔티티가 하나의 엔티티와 연관됩니다. 예를 들어, 한 사용자가 여러 게시물을 작성할 수 있다.

    @OneToMany(() => Post, post => post.user)
    posts: Post[];
  
    @ManyToOne(() => User, user => user.posts)
    user: User;
  

3. 다대다 (Many-to-Many)

• 여러 엔티티가 서로 다수와 연관됩니다. 예를 들어, 여러 학생이 여러 과목을 수강할 수 있다.

    @ManyToMany(() => Subject)
    @JoinTable()
    subjects: Subject[];
  

Relation Option

• eager: true로 설정하면, 관계된 엔티티를 자동으로 로드한다.
• cascade: 연관된 엔티티를 자동으로 삽입, 업데이트, 삭제할 수 있다. 예: cascade: true 또는 cascade: ['insert', 'update']
• onDelete: 부모 엔티티 삭제 시 자식 엔티티의 동작을 정의한다. 옵션: 'RESTRICT', 'CASCADE', 'SET NULL'
• nullable: 관계 컬럼이 NULL을 허용할지 여부를 설정한다.
• orphanedRowAction: 부모 엔티티에서 제거된 자식 엔티티의 처리 방식을 정의한다. 옵션: 'nullify', 'delete', 'soft-delete', 'disable'

cascade란?

cascade는 연관된 엔티티도 함께 저장(insert), 수정(update), 삭제(remove)할 수 있도록 하는 옵션

• 예를 들어, Question 엔티티를 저장할 때, 연결된 Category 엔티티도 자동으로 저장되게 만들 수 있다.
• 이를 위해 @ManyToMany, @OneToMany, @OneToOne 등의 관계 설정에 cascade 옵션을 지정한다.

Category Entity

@Entity()
export class Category {
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    name: string

    @ManyToMany(() => Question, question => question.categories)
    questions: Question[]
}

Question Entity

@Entity()
export class Question {
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    title: string

    @Column()
    text: string

    @ManyToMany(() => Category, category => category.questions, {
        cascade: true,  // 중요 포인트
    })
    @JoinTable()
    categories: Category[]
}

cascade: true를 설정하면 Question을 저장할 때 Category도 같이 저장됨

저장 코드

const category1 = new Category()
category1.name = "ORMs"

const category2 = new Category()
category2.name = "Programming"

const question = new Question()
question.title = "How to ask questions?"
question.text = "Where can I ask TypeORM-related questions?"
question.categories = [category1, category2]

await dataSource.manager.save(question)

category1, category2를 따로 save() 하지 않아도, cascade 때문에 자동으로 DB에 저장됩니다.

cascade 옵션 종류

예시

@ManyToMany(() => PostCategory, {
    cascade: true // insert, update, remove 모두 포함
})
categories: PostCategory[]

@ManyToMany(() => PostDetails, {
    cascade: ["insert"] // 새로 생성된 것만 저장
})
details: PostDetails[]

@ManyToMany(() => PostImage, {
    cascade: ["update"] // 기존 객체 수정만 반영
})
images: PostImage[]

@ManyToMany(() => PostInformation, {
    cascade: ["insert", "update"]
})
informations: PostInformation[]

@JoinColumn이란?

• @JoinColumn은 관계를 정의할 때 외래 키 컬럼을 설정하는 데 사용된다.
• 주로 @ManyToOne 또는 @OneToOne 관계에서 사용된다.

기본 동작

@ManyToOne(() => Category)
@JoinColumn()
category: Category;

위 코드는 categoryId라는 컬럼(FK)을 생성하여 Category 엔티티의 id(기본 키)를 참조하는 외래 키로 사용한다.

컬럼 이름 커스터마이징

@ManyToOne(() => Category)
@JoinColumn({ name: "cat_id" })
category: Category;

categoryId(자동으로 생성되는 컬럼) 대신 cat_id라는 외래 키 컬럼을 사용하도록 지정한 것.

참조 컬럼 지정 (기본키 말고 다른 컬럼)

@ManyToOne(() => Category)
@JoinColumn({ referencedColumnName: "name" })
category: Category;

• 이 경우 외래 키는 Category.name을 참조하며, 자동으로 생성되는 컬럼(FK) 이름은 categoryName 이 된다.

다중 컬럼 조인 (복합 외래 키)

@ManyToOne(() => Category)
@JoinColumn([
  { name: "category_id", referencedColumnName: "id" },
  { name: "locale_id", referencedColumnName: "locale_id" }
])
category: Category;

정확한 이해를 돕기 위해 @JoinTable의 동작 원리와 옵션들을 예제 기반으로 알기 쉽게 설명해드릴게요.

@JoinTable이란?

• @ManyToMany 관계에서는 두 엔티티 간의 관계를 나타내기 위한 중간 테이블(junction table) 이 자동 생성된다.
• 이 중간 테이블의 이름, 그리고 어떤 컬럼이 어떤 엔티티의 어떤 컬럼을 참조하는지를 설정할 수 있는 데코레이터가 @JoinTable 이다.

기본 사용 예시

@ManyToMany(() => Category)
@JoinTable()
categories: Category[];

• 이 코드는 기본적으로 question_categories_category 같은 중간 테이블을 자동 생성하며, 컬럼은 questionId, categoryId처럼 자동으로 설정된다.

옵션 지정 예시

@ManyToMany(() => Category)
@JoinTable({
  name: "question_categories", // 중간 테이블 이름
  joinColumn: {
    name: "question", // 현재 엔티티(Question)의 FK 컬럼명
    referencedColumnName: "id" // Question의 어떤 컬럼을 참조할지 (기본은 id)
  },
  inverseJoinColumn: {
    name: "category", // 반대편 엔티티(Category)의 FK 컬럼명
    referencedColumnName: "id" // Category의 어떤 컬럼을 참조할지
  }
})
categories: Category[];

➡ 결과적으로 생성되는 중간 테이블은 다음과 같이 생깁니다:

복합키(Composite Key)일 경우

예를 들어 Category의 기본키가 id + localeId 두 개라면:

@ManyToMany(() => Category)
@JoinTable({
  name: "question_categories",
  joinColumn: [
    { name: "question_id", referencedColumnName: "id" }
  ],
  inverseJoinColumn: [
    { name: "category_id", referencedColumnName: "id" },
    { name: "category_locale", referencedColumnName: "localeId" }
  ]
})
categories: Category[];

• 이처럼 joinColumn 또는 inverseJoinColumn에 배열을 넣어 복합키를 설정할 수 있다.

• https://typeorm.io/view-entities

View Entity란?

• DB View를 표현하는 읽기 전용 엔티티
• @ViewEntity() 데코레이터로 정의
• 실제 테이블이 아니라 SQL SELECT 문을 기반으로 구성됨

예시

@ViewEntity({
  name: "post_category", // 생략 가능
  expression: `
    SELECT post.id AS id, post.name AS name, category.name AS categoryName
    FROM post
    LEFT JOIN category ON category.id = post.categoryId
  `,
})
export class PostCategory {
  @ViewColumn()
  id: number;

  @ViewColumn()
  name: string;

  @ViewColumn()
  categoryName: string;
}

또는 QueryBuilder로도 표현 가능:

@ViewEntity({
  expression: (dataSource: DataSource) =>
    dataSource
      .createQueryBuilder()
      .select("post.id", "id")
      .addSelect("post.name", "name")
      .addSelect("category.name", "categoryName")
      .from(Post, "post")
      .leftJoin(Category, "category", "category.id = post.categoryId"),
})

• 중요: where("... = :value", { value }) 형태의 파라미터 바인딩은 안 된다. 문자열 리터럴만 사용 가능.

ViewEntity vs 일반 Entity 차이점

실행 흐름 요약

1. Post와 Category 테이블 생성
2. 그 둘을 조인한 PostCategory ViewEntity 생성
3. @ViewColumn()으로 SELECT된 값을 매핑
4. ViewEntity는 entities: [PostCategory]로 등록 필요
5. find() 또는 findOneBy()로 일반 엔티티처럼 조회 가능

const postCategories = await dataSource.manager.find(PostCategory);
// 결과: [{ id: 1, name: "About BMW", categoryName: "Cars" }, ...]

• https://typeorm.io/embedded-entities

Embedded Entities란?

• 상속(inheritance) 대신 구성(composition)을 활용하여 코드 중복을 줄이는 강력한 방법
• 여러 엔티티(User, Employee, Student 등)가 동일한 속성(firstName, lastName)을 반복적으로 갖고 있을 때, 그 중복을 없애기 위한 기능이다.

개념

예시 구조

중복 구조:

@Column()
firstName: string;

@Column()
lastName: string;

위 코드가 User, Employee, Student에 중복되어 있음.

Embedded 구조:

export class Name {
    @Column()
    first: string;

    @Column()
    last: string;
}

@Column(() => Name)
name: Name;

실제 테이블 구조

-- User 테이블
id | nameFirst | nameLast | isActive
-- Employee 테이블
id | nameFirst | nameLast | salary
-- Student 테이블
id | nameFirst | nameLast | faculty

• 즉, name: Name으로 객체를 묶었지만 실제 DB에는 nameFirst, nameLast처럼 평탄화된 컬럼으로 생됨

Embedded Entity의 장점

• 코드 재사용성 향상
• 테이블 구조는 평탄화되어 있어 SQL에서도 접근 쉬움
• 중첩(embedded inside embedded)도 가능

• https://typeorm.io/entities

Entity란?

• Entity는 데이터베이스 테이블에 매핑되는 클래스이다.
• 즉, TypeORM에서는 User와 같은 클래스를 만들고 여기에 데코레이터(@Entity, @Column 등)를 붙여주면, 그것이 곧 데이터베이스의 하나의 테이블이 된다.

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";

@Entity()  // 이 클래스는 테이블로 매핑된다
export class User {
  @PrimaryGeneratedColumn()  // 기본키 + AUTO_INCREMENT
  id: number;

  @Column()
  firstName: string;

  @Column()
  lastName: string;

  @Column()
  isActive: boolean;
}

@Column() 이란?

@Column()
firstName: string;

• @Column() 데코레이터를 사용하면 이 속성이 데이터베이스 테이블의 열로 매핑된다.

• 데이터 타입은 TypeScript의 타입을 기준으로 자동 추론된다 (예: string → varchar, number → int).

• 자세한 내용은 뒤에 있다.

@Primary Column()이란?

• Entity는 반드시 최소한 하나의 Primary Key를 가져야 한다.

복합 기본 키 사용 법

@Entity()
export class User {
  @PrimaryColumn()
  firstName: string;

  @PrimaryColumn()
  lastName: string;
}

• 두 컬럼을 함께 기본 키로 사용한다.
• 데이터는 firstName + lastName 조합이 고유해야 저장된다.

TypeORM Special Columns

예시 코드:

import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  DeleteDateColumn,
  VersionColumn,
} from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @DeleteDateColumn()
  deletedAt?: Date;  // soft-delete되기 전에는 null

  @VersionColumn()
  version: number;
}

생성되는 DB 테이블 예시

컬럼 타입 지정 방법

1. 기본 문법

@Column("int")
age: number;

2. 옵션 객체로 지정

@Column({ type: "int", width: 11 })
age: number;

3. 문자열 길이 지정 (varchar 등)

@Column("varchar", { length: 200 })
name: string;

MySQL / MariaDB에서 지원하는 주요 컬럼 타입

bigint 주의사항

• bigint는 JavaScript의 number 범위를 초과하므로 TypeORM에서는 string으로 매핑된다.

@Column("bigint")
longValue: string;

const entity = new MyEntity();
entity.longValue = "9007199254740992"; // 문자열로 처리

Enum 컬럼 타입

(추천)

export enum UserRole {
  ADMIN = "admin",
  EDITOR = "editor",
  GHOST = "ghost",
}

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({
    type: "enum",
    enum: UserRole,
    default: UserRole.GHOST,
  })
  role: UserRole;
}

또는

 export type UserRoleType = "admin" | "editor" | "ghost";

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({
    type: "enum",
    enum: ["admin", "editor", "ghost"],
    default: "ghost",
  })
  role: UserRoleType;
}

set 컬럼 타입

(추천)

export enum UserRole {
  ADMIN = "admin",
  EDITOR = "editor",
  GHOST = "ghost",
}

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({
    type: "set",
    enum: UserRole,
    default: [UserRole.GHOST, UserRole.EDITOR],
  })
  roles: UserRole[];
}

또는

export type UserRoleType = "admin" | "editor" | "ghost";

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({
    type: "set",
    enum: ["admin", "editor", "ghost"],
    default: ["ghost", "editor"],
  })
  roles: UserRoleType[];
}

simple-array 컬럼 타입

• string[], number[] 등 배열을 문자열로 콤마(,) 구분해 저장.

  @Entity()
  export class User {
  @PrimaryGeneratedColumn()
  id: number;
  
  @Column("simple-array")
  names: string[];
  }

user.names = ["Alex", "Sasha"];
// DB에는 "Alex,Sasha"로 저장됨

simple-json 컬럼 타입

• JSON 객체를 문자열 형태로 저장 (별도의 JSON 타입 없이도 가능)

  @Entity()
  export class User {
  @PrimaryGeneratedColumn()
  id: number;
  
  @Column("simple-json")
  profile: { name: string; nickname: string };
  }

user.profile = { name: "John", nickname: "Malkovich" };
// DB에는 '{"name":"John","nickname":"Malkovich"}'로 저장됨

한계

@Generated() 데코레이터란?

• TypeORM에서 데이터베이스가 자동으로 생성해주는 값을 가지는 컬럼에 붙이는 데코레이터

지원되는 생성 타입

UUID 자동 생성 컬럼

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  @Generated("uuid")
  uuid: string;
}

숫자 자동 증가 컬럼 (비기본키)

@Entity()
export class Order {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  @Generated("increment")
  orderNumber: number;
}

Column 옵션

• https://docs.nestjs.com/exception-filters

Exception Filters란?

• NestJS에서 예외 발생 시 에러 응답의 형식과 처리 방식을 개발자가 직접 제어할 수 있도록 해주는 전용 에러 처리 컴포넌트이다.
• NestJS 애플리케이션 전반에서 발생하는 예외를 가로채어, 적절한 응답 형식을 생성하거나 추가적인 처리를 수행할 수 있도록 해주는 구조화된 예외 처리 메커니즘이다.
• NestJS의 기본 Exception Filter는 기본적으로 HttpException 또는 그 하위 클래스들을 처리하도록 설계되어 있다.

HttpException이란?

• NestJS는 REST API 및 GraphQL API에서 에러 발생 시 HTTP 상태 코드에 맞는 표준화된 에러 응답을 보내기 위해 HttpException 클래스를 제공한다.

  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);

• 이처럼 예외를 발생시키면 NestJS가 자동으로 다음과 같은 응답을 만들어 준다.

  {
  "statusCode": 403,
  "message": "Forbidden"
  }

HttpException 생성자 인자

new HttpException(response, status, options?)

• respons : JSON 응답에 담길 본문. 문자열이면 메시지로 처리되고, 객체를 넘기면 그대로 응답 바디로 사용됨
• status: HTTP 상태 코드 (HttpStatus.FORBIDDEN 등)
• options (선택) 내부적으로만 사용하는 cause 값을 포함할 수 있음 (로깅에 유용)

메시지 커스터마이징 방법

(1) 기본 메시지 사용 (문자열)

throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);

응답:

{
  "statusCode": 403,
  "message": "Forbidden"
}

• 문자열만 넘기면 message 필드만 변경됨. Nest가 자동으로 statusCode를 추가.

(2) 전체 JSON 응답 구조 커스터마이징 (객체 전달)

throw new HttpException(
  {
    status: HttpStatus.FORBIDDEN,
    error: 'This is a custom message',
  },
  HttpStatus.FORBIDDEN,
  {
    cause: error  // 내부 로깅용, 클라이언트에게는 응답되지 않음
  }
);

응답:

{
  "status": 403,
  "error": "This is a custom message"
}

• 이 경우 statusCode 대신 status가 들어가고, message 대신 error라는 사용자 지정 키가 사용됨.
• 내부적으로 로깅할 때 어떤 원인(exception)이 있었는지 추적할 수 있게 함

Custom Exceptions란?

• NestJS에서 기본으로 제공하는 BadRequestException,NotFoundException 등의 예외 클래스 외에, 프로젝트 상황에 맞게 새롭게 정의한 예외 클래스

예시: forbidden exception 사용

// forbidden.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';

export class ForbiddenException extends HttpException {
  constructor() {
    super('Forbidden', HttpStatus.FORBIDDEN);
  }
}

// cats.controller.ts
@Get()
async findAll() {
  throw new ForbiddenException();
}

응답:

{
  "statusCode": 403,
  "message": "Forbidden"
}

@nestjs/common 에서 지원해주는 Exception

사용방법

throw new NotFoundException('User not found');

응답:

{
  "statusCode": 404,
  "message": "User not found"
}

고급 사용법 : options 파라미터 사용

throw new BadRequestException('Something bad happened', {
  cause: new Error(),
  description: 'Some error description',
});

응답:

{
  "message": "Something bad happened",
  "error": "Some error description",
  "statusCode": 400
}

왜 커스텀 Exception Filter를 쓰는가?

NestJS의 기본 예외 필터는 HttpException 기반 예외에 대해 잘 작동하지만, 다음과 같은 요구가 있을 때는 직접 예외 필터를 구현해야 한다

• 예외 발생 시 로깅 추가
• 응답 구조를 API 사양에 맞게 수정
• 클라이언트 요청 경로, 타임스탬프 등을 응답에 포함
• 예외 타입에 따라 분기 처리

예시

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();                         // HTTP 컨텍스트 추출
    const response = ctx.getResponse<Response>();            // Express의 Response 객체
    const request = ctx.getRequest<Request>();               // Express의 Request 객체
    const status = exception.getStatus();                    // 상태코드 추출

    // 로깅 서비스 이용 등...
    response.status(status).json({                           // 직접 응답 구성
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }
}

Catch(...)

• 특정 예외 클래스만 걸러내기 위한 데코레이터
• 특정 예외만 등록해서 걸러내기 가능
• ex) @Catch(BadRequestException, ForbiddenException)

Exception Filter 적용 범위

1. 메서드 범위(Method-scoped)

@Post()
@UseFilters(HttpExceptionFilter)
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}

2. 컨트롤러 범위(Controller-scoped)

@Controller()
@UseFilters(HttpExceptionFilter)
export class CatsController {
  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    throw new ForbiddenException();
  }

  @Get()
  async findAll() {
    throw new ForbiddenException();
  }
}

3. 전역 범위(Global-scoped)

방법 A. main.ts에서 적용

// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());  // 전역 필터 등록
  await app.listen(3000);
}

• new HttpExceptionFilter()로 직접 인스턴스화하므로 의존성 주입 불가
• 예: 로깅 서비스, 설정 서비스 등 주입 불가

방법 B. AppModule에서 APP_FILTER 토큰을 활용한 등록 (DI 가능)

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
  ],
})
export class AppModule {}

• NestJS가 자동으로 인스턴스를 생성하고 의존성 주입도 지원
• 진짜 글로벌 필터이면서도 유연하게 활용 가능

모든 예외 잡기

• Catch() 데코레이터에 아무 인자도 주지 않음으로써 예외의 종류와 상관없이 전부 잡는 필터를 만드는 것
• @Catch()에 아무 인자도 넣지 않으면 모든 종류의 예외(즉, HttpException 이외의 일반 Error, TypeError, ReferenceError 등도 포함)를 포괄 처리할 수 있다.

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class CatchEverythingFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}

응답:

// ex) 
const responseBody = {
  statusCode: 500,
  timestamp: new Date().toISOString(),
  path: httpAdapter.getRequestUrl(ctx.getRequest()),
};

httpAdapter.reply(ctx.getResponse(), responseBody, 500);

->
{
  "statusCode": 500,
  "timestamp": "2025-05-08T06:30:45.123Z",
  "path": "/users"
}

BaseExceptionFilter 상속 후 커스터마이징

• 기존 Nest의 예외 처리 로직을 유지하면서, 거기에 추가 로직을 더하고 싶을 때 사용한다.
• BaseExceptionFilter는 Nest가 기본적으로 사용하는 내장 예외 필터
• 기본 처리 로직을 재사용하면서 필요한 부분만 오버라이딩 할 수 있다.

Logger + Sentry 연동 예시

import {
  Catch,
  ArgumentsHost,
  HttpException,
  Logger,
} from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';
import { Request } from 'express';
import * as Sentry from '@sentry/node';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const request = ctx.getRequest<Request>();

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : 500;

    // Logger
    this.logger.error(
      `[${request.method}] ${request.url} -> ${status}`,
      (exception as any).stack,
    );

    // Sentry 전송
    Sentry.captureException(exception);

    // Nest 기본 처리 수행 (statusCode, message 응답 전송)
    super.catch(exception, host);
  }
}

적용 방법 1. main.ts에서 HttpAdapter 수동 주입

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

  const { httpAdapter } = app.get(HttpAdapterHost);
  app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));

  await app.listen(3000);
}

적용 방법 2. APP_FILTER 토큰을 이용한 의존성 주입 방식

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,
    },
  ],
})
export class AppModule {}

응답 예시

요청: GET /users/999

예외: throw new NotFoundException('User not found')

클라이언트 응답:

{
  "statusCode": 404,
  "message": "User not found"
}

로그 (콘솔):

[ERROR] AllExceptionsFilter - [GET] /users/999 -> 404
Error: User not found
    at ...

Sentry: 예외 상세 정보가 자동으로 전송

• https://velog.io/@ckdwns9121/Github-Action을-이용해-AWS-Lightsail-CICD-파이프라인-구축하기-1편

• https://velog.io/@ckdwns9121/Github-Action을-이용해-AWS-Lightsail-CICD-파이프라인-구축하기-2편

과정

1. Lightsail 인스턴스 생성 후 SSH 키페어 생성
2. IAM 사용자 생성 및 AWS AccessKey 발급 받기
3. Lightsail에 aws-cli 설치
4. Lightsail에 configure 설정
5. Github 프로젝트(리포지토리)에 SecretKey 등록
6. Github Action의 Workflow 생성

1. Lightsail 인스턴스 생성 후 SSH 키페어 생성

• SSH key > Create custom key 클릭

• 다운로드 받은 .pem키 원하는 곳에 위치 시키기 (Desktop, ssh ...)

• 해당 .pem을 cat으로 열어서 저장해놓기 (---BEGIN RSA PRIVATE KEY---- 부터 제일 마지막 ---END RSA PRIVATE KEY--- 을 포함한 값까지!)

• 아래의 경우 맨 마지막에 보이는 %는 포함시키면 안된다 (이거 때문에 오류가

• 권한 에러가 날 수 있기 때문에 권한 수정해놓기

  chmod 400 CICDTEST.pem

2. IAM 사용자 생성 및 AWS AccessKey 발급 받기

• IAM에서 사용자 생성 → 권한은 AWSCodeDeplyFullAccess 추가하기 → 생성 후 액세스 키 생성해서 다운 받기

3. Lightsail에 aws-cli 설치

• aws-cli 설치:

sudo apt-get update && sudo apt-get install awscli

• 설치 후 버전 확인 :

aws --version

4. Lightsail Configure 설정하기

aws configure

• AWS Access Key ID: IAM에서 발급받은 ACCESS_ID
• AWS Secret Access Key ID: IAM에서 ACCESS_KEY
• region:  ap-northeast-2 (서울)
• output format : json

5. Github 프로젝트에 SecretKey 등록하기

• CI/CD를 적용할 리포지토리의 Settings > Secrets and variables > Actions 클릭

• 이후 키 등록

  • AWS_ACCESS_KEY_ID : IAM에서 발급 받은 ACCESS_ID
  • AWS_SECRET_ACCESS_KEY: IAM에서 발급 받은 ACCESS_KEY
  • LIGHTSAIL_HOST: Lightsail 인스턴스의 public IP
  • LIGHTSAIL_SSH_KEY: 인스턴스를 생성할 때 발급받은 SSH 키페어.
    • ---BEGIN RSA PRIVATE KEY---- 부터 제일 마지막 ---END RSA PRIVATE KEY--- 을 포함한 값까지!

• 예시) Name: AWS_ACCESS_KEY_ID Secret: IAM 콘솔에서 발급 받은 ACCESS_ID

6. Github Actions Workflow 생성

• CI/CD를 적용할 리포지토리의 Actions > set up a workflow yourself 클릭

• 아래 코드 복붙

  name: CI CD
  

on: push: branches: ['main'] pull_request: branches: ['main']

env: LIGHTSAIL_SSH_KEY: ${{ secrets.LIGHTSAIL_SSH_KEY }} LIGHTSAIL_HOST: ${{ secrets.LIGHTSAIL_HOST }} LIGHTSAIL_USERNAME: bitnami AWS_REGION: ap-northeast-2

jobs: deploy: runs-on: ubuntu-latest

steps:
  - name: 소스 코드 체크아웃
    uses: actions/checkout@v3

  - name: Node.js 설정
    uses: actions/setup-node@v3
    with:
      node-version: 20 // 원하는 버전 선택

  - name: 의존성 설치
    run: sudo npm install

  - name: 빌드
    run: sudo npm run build

  - name: AWS 자격 증명 설정
    uses: aws-actions/configure-aws-credentials@v3
    with:
      aws-region: ${{ env.AWS_REGION }}
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

  - name: SSH 키 설정
    run: |
      mkdir -p $HOME/.ssh
      echo "${{ secrets.LIGHTSAIL_SSH_KEY }}" > $HOME/.ssh/deploy_key
      chmod 600 $HOME/.ssh/deploy_key
      eval $(ssh-agent -s)
      ssh-add $HOME/.ssh/deploy_key
      ssh-keyscan -H ${{ secrets.LIGHTSAIL_HOST }} >> $HOME/.ssh/known_hosts

  - name: 기존 디렉토리 정리 및 권한 설정
    uses: appleboy/ssh-action@master
    with:
      host: ${{ secrets.LIGHTSAIL_HOST }}
      username: ${{ env.LIGHTSAIL_USERNAME }}
      key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
      script: |
        sudo rm -rf /home/bitnami/test-cicd // test-cicd를 자신의 프로젝트명으로 수정!            sudo mkdir -p /home/bitnami/test-cicd
        sudo chown -R bitnami:bitnami /home/bitnami/test-cicd // test-cicd를 자신의 프로젝트명으로 수정!
        sudo chmod -R 755 /home/bitnami/test-cicd // test-cicd를 자신의 프로젝트명으로 수정!

  - name: 애플리케이션 파일 배포
    uses: appleboy/scp-action@master
    with:
      host: ${{ secrets.LIGHTSAIL_HOST }}
      username: ${{ env.LIGHTSAIL_USERNAME }}
      key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
      source: 'dist/,package.json,package-lock.json'
      target: '/home/bitnami/test-cicd' // test-cicd를 자신의 프로젝트명으로 수정!
      strip_components: 0
      overwrite: true

  - name: PM2 프로세스 재시작
    uses: appleboy/ssh-action@master
    with:
      host: ${{ secrets.LIGHTSAIL_HOST }}
      username: ${{ env.LIGHTSAIL_USERNAME }}
      key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
      script: |
        cd /home/bitnami/test-cicd // test-cicd를 자신의 프로젝트명으로 수정!
        sudo npm ci --production
        sudo pm2 restart main || sudo pm2 start dist/main.js --name main

![](https://velog.velcdn.com/images/cchoi-geon/post/26309da5-9659-4465-ba94-a6b5c1663d6a/image.png)


## workflow 설명 
```yml
name: CI CD

# main 브랜치에 push 또는 pull request 발생 시 워크플로우 실행
on:
  push:
    branches: ['main']
  pull_request:
    branches: ['main']

# 공통 환경 변수 정의 (GitHub Secrets 사용)
env:
  LIGHTSAIL_SSH_KEY: ${{ secrets.LIGHTSAIL_SSH_KEY }}
  LIGHTSAIL_HOST: ${{ secrets.LIGHTSAIL_HOST }}
  LIGHTSAIL_USERNAME: bitnami
  AWS_REGION: ap-northeast-2

jobs:
  deploy:
    runs-on: ubuntu-latest  # 최신 Ubuntu 환경에서 실행

    steps:
      # GitHub 저장소에서 소스 코드를 체크아웃
      - name: 소스 코드 체크아웃
        uses: actions/checkout@v3

      # Node.js 20버전 설정
      - name: Node.js 설정
        uses: actions/setup-node@v3
        with:
          node-version: 20 # 원하는 Node.js 버전

      # npm 의존성 설치
      - name: 의존성 설치
        run: sudo npm install

      # 빌드 명령 실행 (예: Next.js 앱 빌드)
      - name: 빌드
        run: sudo npm run build

      # AWS 자격 증명 환경 설정 (Secrets에 저장된 키 사용)
      - name: AWS 자격 증명 설정
        uses: aws-actions/configure-aws-credentials@v3
        with:
          aws-region: ${{ env.AWS_REGION }}
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

      # Lightsail 서버 접근을 위한 SSH 키 설정
      - name: SSH 키 설정
        run: |
          mkdir -p $HOME/.ssh
          echo "${{ secrets.LIGHTSAIL_SSH_KEY }}" > $HOME/.ssh/deploy_key
          chmod 600 $HOME/.ssh/deploy_key
          eval $(ssh-agent -s)
          ssh-add $HOME/.ssh/deploy_key
          ssh-keyscan -H ${{ secrets.LIGHTSAIL_HOST }} >> $HOME/.ssh/known_hosts

      # 서버에서 기존 프로젝트 디렉토리 삭제 후 재생성, 권한 설정
      - name: 기존 디렉토리 정리 및 권한 설정
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.LIGHTSAIL_HOST }}
          username: ${{ env.LIGHTSAIL_USERNAME }}
          key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
          script: |
            # 기존 디렉토리 삭제 및 생성 (프로젝트명에 따라 경로 변경 가능)
            sudo rm -rf /home/bitnami/test-cicd
            sudo mkdir -p /home/bitnami/test-cicd
            sudo chown -R bitnami:bitnami /home/bitnami/test-cicd
            sudo chmod -R 755 /home/bitnami/test-cicd

      # 빌드된 파일을 서버로 전송
      - name: 애플리케이션 파일 배포
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.LIGHTSAIL_HOST }}
          username: ${{ env.LIGHTSAIL_USERNAME }}
          key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
          source: 'dist/,package.json,package-lock.json'
          target: '/home/bitnami/test-cicd' # 이 경로는 프로젝트명에 맞게 수정
          strip_components: 0
          overwrite: true

      # PM2를 통해 앱 재시작 또는 새로 시작
      - name: PM2 프로세스 재시작
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.LIGHTSAIL_HOST }}
          username: ${{ env.LIGHTSAIL_USERNAME }}
          key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
          script: |
            cd /home/bitnami/test-cicd  # 해당 디렉토리로 이동
            sudo npm ci --production    # production 환경용 의존성만 설치
            # main이라는 이름으로 프로세스를 재시작, 없으면 새로 실행
            sudo pm2 restart main || sudo pm2 start dist/main.js --name main

• SSH key > Create custom key 선택

• 다운 받은 키는 원하는 곳에 위치시키기 (Desktop, ssh 등)

• 아래 예시는 Desktop에 위치시킴

• 권한 문제가 발생할 수 있기 때문에 chmod 400 your-key.pem 로 권한 변경

  chmod 400 ~Desktop/CICDTEST.pem

SSH 접속

ssh -i 키위치/키이름.pem bitnami@<인스턴스-공인IP>

ssh -i ~/Desktop/CICDTEST.pem bitnami@3.34.135.165

• 접속된 상태

• https://docs.nestjs.com/modules

Module이란?

• @Module() 데코레이터로 정의된 클래스이며, NestJS에서 어플리케이션을 구조화하고 관리하는 기본 단위이다.
• 모든 NestJS 앱은 최소한 하나의 루트 모듈(AppModule) 을 가진다.
• 모듈은 providers, controllers, imports, exports로 구성되어 내부 구성요소를 캡슐화하며 재사용 가능하게 만든다.

주요 속성

• providers: 서비스, 유틸 등 의존성 주입 대상
• controllers: 요청/응답 처리용 컨트롤러
• imports: 다른 모듈을 현재 모듈에서 사용
• exports: 외부 모듈에서 사용할 수 있도록 내보냄

// cats.module.ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  imports:[AnyModule],
  controllers: [CatsController],
  providers: [CatsService],  // CatsService 제공
  exports: [CatsService]  // 외부 모듈에서도 사용 가능하도록 export
})
export class CatsModule {}

// app.module.ts (또는 다른 모듈)
import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],  // CatsModule을 불러옴
})
export class AppModule {}

exports를 해야하는 이유

• exports를 사용하지 않으면 해당 모듈의 Provider를 다른 모듈에서 사용할 수 없다.
• 즉, provider는 모듈 내부에서 기본적으로 캡슐화되어 있어서 exports 하지 않으면 외부에 공개되지 않는다.(private 설정이 Default라고 생각하는 게 편할 것 같다.)
• 위 코드를 예시로 들면, CatsService를 담고 있는 Module에서 exports: [CatsService]를 설정해주지 않는다면, 다른 모듈에서 CatsService에 접근할 수 없다.

  // cats.module.ts
  import { Module } from '@nestjs/common';
  import { CatsController } from './cats.controller';
  import { CatsService } from './cats.service';
  

@Module({ imports:[AnyModule], controllers: [CatsController], providers: [CatsService], // CatsService 제공 exports: [] // CatsService 외부로 내보내지 않음 (private) }) export class CatsModule {}

```ts
// anyModule.module.ts
@Module({
  imports: [CatsModule],
  providers: [AnyService],
})
export class AnyModule {}

// any.service.ts
@Injectable()
export class AnyService {
  constructor(private catsService: CatsService) {} // 이 시점에서 에러 발생
}

• AnyModule에서는 CatsModule에 있는 CatsService에 접근할 수 없다.
• 위와 같은 경우 CatsService를 주입하려 하면 NestJS는 Cannot resolve dependency 에러를 던지게 된다.

Global 모듈 만들기

• 다른 모듈에 접근할 때 해당 모듈에서 imports:[Module...]로 불러와야한다.
• 하지만 @Global() 데코레이터를 사용하면 다른 모듈에서 해당 모듈에 접근할 때 imports를 하지 않아도 바로 사용이 가능하다.
• 단, exports로 사용할 Provider를 설정해야 한다!!
• 보통 공통 서비스(Helper, Logger, DB, Auth) 등은 Global로 설정한다.

import { Module, Global } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Global()
@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService],  // 반드시 exports도 함께 해야 외부 사용 가능
})
export class CatsModule {}

// 다른 모듈에서 CatsModule을 import하지 않아도 CatsService 사용 가능
@Injectable()
export class OtherService {
  constructor(private catsService: CatsService) {}
}

Dynamic Module이란?

• 반적으로 모듈은 정적으로 정의되며, @Module() 데코레이터 내부에서 providers, controllers, imports, exports 등을 미리 지정해야 한다.
• 하지만 경우에 따라 앱이 실행될 때 동적으로 모듈을 설정해야 하는 상황이 발생할 수 있다.
• 예를 들어 데이터베이스 연결 → 환경 변수에 따라 다른 DB에 연결해야 할 때, API 인증 모듈 → 특정 설정 값에 따라 다른 인증 전략을 사용할 때, 다국어 지원 (i18n) → 설정에 따라 지원하는 언어를 다르게 구성할 때
• 이러한 경우 동적 모듈(Dynamic Module) 을 사용하면 모듈을 유연하게 생성 및 구성할 수 있다.

import { Module, DynamicModule } from '@nestjs/common';
import { createDatabaseProviders } from './database.providers';
import { Connection } from './connection.provider';

@Module({
  providers: [Connection], // 기본 Provider
  exports: [Connection],
})
export class DatabaseModule {
  static forRoot(entities = [], options?): DynamicModule {
    const providers = createDatabaseProviders(options, entities); // 동적 Provider 생성

    return {
      module: DatabaseModule,
      providers: providers, // 동적으로 설정된 providers 추가
      exports: providers,
    };
  }
}

• forRoot() 메서드를 통해 모듈을 생성할 때 옵션을 받을 수 있음.
• 이 옵션을 기반으로 createDatabaseProviders() 함수를 호출하여 동적으로 Provider를 생성.
• providers와 exports를 설정하여 해당 설정을 다른 모듈에서도 사용 가능하게 함.

import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';

@Module({
  imports: [DatabaseModule.forRoot(['User', 'Product'], { sync: true })],
})
export class AppModule {}

• forRoot() 메서드에서 ['User', 'Product'] 엔티티와 sync: true 옵션을 받아 런타임에서 동적으로 provider를 설정한다.

글로벌 동적 모듈

• 만약 전역(Global)으로 사용할 동적 모듈을 만들고 싶다면 { global: true } 옵션을 추가할 수 있다.

static forRoot(entities = [], options?): DynamicModule {
  const providers = createDatabaseProviders(options, entities);

  return {
    global: true,  // 글로벌 모듈 설정
    module: DatabaseModule,
    providers: providers,
    exports: providers,
  };
}

• https://docs.nestjs.com/providers

Provider란?

• 서비스, 리포지토리, 팩토리, 헬퍼와 같은 많은 기본 Nest 클래스이다.
• Provider는 종속성으로 주입될 수 있어 객체가 서로 다양한 관계를 형성할 수 있다.

Service 생성 CLI 명령어

nest g service [경로]/[모듈명] 

nest g service api/cats 

-> src/api/cats/cats.service.ts 생성

• 만약 경로를 설정하지 않고 바로 모듈명을 입력하면 src아래 모듈아래 생성된다.

• src/cats/cats.service.ts 생성

• 본인이 사용하고 있는 디렉토리 구조에 맞게 생성하면 된다.

nest g service api/cats  --no-sepc

• --no-spec을 붙이면 테스트 코드가 같이 생기지 않는다.

@Injectable() 데코레이터

• @Injectable()를 추가하면 NestJS가 해당 클래스를 "의존성 주입 컨테이너(DI)"에서 관리할 수 있도록 설정한다.
• 의존성 주입이란? : 객체 간의 의존성을 직접 생성하는 대신, 외부에서 주입하여 관리하는 디자인 패턴

  import { Injectable } from '@nestjs/common';
  import { Cat } from './interfaces/cat.interface';
  

@Injectable() export class CatsService { private readonly cats: Cat[] = [];

create(cat: Cat) { this.cats.push(cat); }

findAll(): Cat[] { return this.cats; } }

- 위와 같이 CatsService를 구성했을 때, 다른 컴포넌트(예: 컨트롤러)에서 주입(Injection)하여 사용할 수 있다.
```ts
@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {} // DI (의존성 주입)

Provider 등록

• NestJS는 IoC (Inversion of Control) 원칙에 따라 클래스 간 의존성을 Nest가 자동으로 주입해주는 구조이다
• 이를 위해선 Nest가 해당 provider(CatsService 같은)를 미리 알고 있어야 한다.

import { Module } from '@nestjs/common';
import { CatsController } from './cats/cats.controller';
import { CatsService } from './cats/cats.service';

@Module({
  controllers: [CatsController],   // 요청을 처리하는 컨트롤러 등록
  providers: [CatsService],        // 주입받을 서비스(= Provider) 등록
})
export class AppModule {}

스코프란?

• NestJS에서 스코프(Scope)는 Provider(서비스, 리포지토리, 가드 등)의 생명 주기를 결정하는 설정이다.
• 기본적으로 NestJS의 Provider는 싱글톤(Singleton)으로 동작하며, 애플리케이션이 실행될 때 한 번만 생성한다.
• 하지만 특정 경우(예: 요청마다 새로운 인스턴스 필요)에는 Request-Scoped(요청 단위 스코프)로 변경할 수 있다.

기본 Provider의 생명 주기 (Singleton)

import { Injectable } from '@nestjs/common';

@Injectable()
export class CatsService {
  private count = 0;

  increment() {
    this.count++;
    return this.count;
  }
}

• 애플리케이션이 실행되는 동안 단 하나의 인스턴스만 유지한다.
• 즉, 모든 요청에서 CatsService 내부는 count 값을 공유한다.

Request-Scoped (요청 단위 스코프)

• 요청(Request)마다 새로운 인스턴스를 생성하고 싶다면, 스코프를 Scope.REQUEST로 설정하면 된다.

  import { Injectable, Scope } from '@nestjs/common';
  

@Injectable({ scope: Scope.REQUEST }) // 요청 단위 스코프 설정 export class CatsService { private count = 0;

increment() { this.count++; return this.count; } }

- 매번 요청이 들어올 때마다 새로운 CatsService 인스턴스가 생성된다.
- count 값이 요청마다 초기화됨 → 요청 간 데이터 공유 X.
- 특정 요청 단위에서만 유지해야 하는 상태(예: 트랜잭션, 요청 ID 추적 등)에 유용하다.

• https://typeorm.io/
• 해당 글은 NestJS 프레임워크를 기반으로 설명합니다.
• Database는 MySQL을 기준으로 합니다.

TypeORM 라이브러리 다운로드 및 기타 설정

1. TypeORM + DB 드라이버 설치

   npm install @nestjs/typeorm typeorm mysql2
   

2. TypeORM 설정
```ts
// app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './user/user.entity';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres', // 또는 'mysql', 'sqlite' 등
      host: 'localhost',
      port: 5432,
      username: 'your_username',
      password: 'your_password',
      database: 'your_database',
      entities: [User], // 또는 path: [__dirname + '/**/*.entity{.ts,.js}']
      synchronize: true, // 개발용 옵션 (운영환경에서는 false)
    }),
    TypeOrmModule.forFeature([User]), // Repository 사용을 위한 Entity 등록
  ],
})
export class AppModule {}