기술 스택 가이드

개요

Picake 프로젝트의 백엔드 기술 스택과 데이터베이스 설정에 대한 종합 가이드입니다.

NestJS 프레임워크

NestJS 소개

NestJS는 Node.js를 위한 확장 가능한 서버 사이드 애플리케이션 프레임워크입니다. TypeScript를 완전히 지원하며, 모듈화된 아키텍처를 통해 효율적인 애플리케이션 개발을 가능하게 합니다.

NestJS 구조도

graph TB
    subgraph "Client Layer"
        CLIENT[Client Application]
    end

    subgraph "NestJS Application"
        subgraph "Root Module"
            APP[AppModule<br/>루트 모듈]
        end

        subgraph "Feature Modules"
            FM[FeatureModule]
        end

        subgraph "Module Components"
            subgraph "FeatureModule"
                FC[FeatureController]
                FS[FeatureService]
            end
        end

        subgraph "External Services"
            DB[(Database)]
            API[External APIs]
        end
    end

    CLIENT -->|HTTP Request| APP
    APP --> FM

    FM --> FC
    FM --> FS

    FC -->|비즈니스 로직 위임| FS

    FS --> DB
    FS --> API

    FS -->|처리 결과 반환| FC

    FC -->|HTTP Response| CLIENT

요청 처리 흐름

sequenceDiagram
    participant Client
    participant AppModule
    participant Controller
    participant Service
    participant Database

    Client->>AppModule: HTTP Request
    AppModule->>Controller: Route to Controller
    Controller->>Service: Call Business Logic
    Service->>Database: Query Data
    Database-->>Service: Return Data
    Service-->>Controller: Return Processed Data
    Controller-->>AppModule: Return HTTP Response
    AppModule-->>Client: HTTP Response

핵심 구성요소

1. 모듈 (Module)

애플리케이션의 기본 구성 단위로, 관련된 컨트롤러, 서비스, 프로바이더들을 그룹화합니다.

@Module({
  controllers: [FeatureController],
  providers: [FeatureService],
  exports: [FeatureService],
  imports: [ConfigModule],
})
export class FeatureModule {}

2. 컨트롤러 (Controller)

HTTP 요청을 받아 처리하고 응답을 반환하는 역할을 담당합니다.

@Controller("auth")
@UseGuards(JwtAuthGuard)
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post("login")
  @Public()
  @HttpCode(HttpStatus.OK)
  async login(@Body() loginDto: LoginRequestDto) {
    return this.authService.login(loginDto);
  }
}

3. 서비스 (Service)

비즈니스 로직을 담당하는 핵심 구성요소입니다.

@Injectable()
export class AuthService {
  constructor(
    private readonly userService: UserService,
    private readonly phoneService: PhoneService,
  ) {}

  async login(loginDto: LoginRequestDto) {
    return this.userService.login(loginDto);
  }
}

상세 처리 과정

요청 수신: 클라이언트가 HTTP 요청을 서버로 전송
전역 접두사 적용: /v1 접두사가 자동으로 추가됨
CORS 및 보안 헤더: helmet, CORS 설정 적용
Rate Limiting: ThrottlerGuard를 통한 요청 제한 검사
라우팅: NestJS가 요청 URL을 분석하여 적절한 컨트롤러와 메서드 찾기
JWT 인증: JwtAuthGuard를 통한 인증 검사 (Public 데코레이터가 없는 경우)
유효성 검사: ValidationPipe를 통한 DTO 검증
컨트롤러 실행: 해당 컨트롤러 메서드 호출
서비스 호출: 컨트롤러에서 비즈니스 로직을 담당하는 서비스 호출
비즈니스 로직 처리: 서비스에서 실제 데이터 처리 및 계산
응답 인터셉터: SuccessResponseInterceptor가 응답을 통일된 형태로 래핑
HTTP 응답: 클라이언트에게 JSON 응답 반환

의존성 주입 (Dependency Injection)

NestJS는 강력한 의존성 주입 시스템을 제공합니다.

생성자 주입 예시

@Injectable()
export class AuthService {
  constructor(
    private readonly userService: UserService,
    private readonly phoneService: PhoneService,
    private readonly googleService: GoogleService,
    private readonly jwtUtil: JwtUtil,
  ) {}
}

모범 사례

1. 모듈 설계 원칙

단일 책임 원칙: 각 모듈은 하나의 도메인만 담당
응집도: 관련된 기능들을 하나의 모듈로 그룹화
결합도: 모듈 간 의존성을 최소화

2. 컨트롤러 설계 원칙

얇은 컨트롤러: 비즈니스 로직은 서비스에 위임
명확한 라우팅: RESTful API 설계 원칙 준수
적절한 HTTP 상태 코드: 의미 있는 상태 코드 사용

3. 서비스 설계 원칙

비즈니스 로직 집중: 핵심 비즈니스 로직 구현
재사용성: 여러 컨트롤러에서 사용 가능하도록 설계
테스트 가능성: 단위 테스트가 용이하도록 설계

핵심 개념 요약

모듈: 애플리케이션의 기본 구성 단위, 관련 기능들을 그룹화
컨트롤러: HTTP 요청의 진입점, 라우팅과 응답 생성 담당
서비스: 비즈니스 로직의 핵심, 데이터 처리와 외부 연동 담당
의존성 주입: 느슨한 결합을 통한 코드 재사용성과 테스트 용이성 향상

데이터베이스 (PostgreSQL + Prisma)

개발 환경 설정

환경 변수 설정

# apps/backend/.env.development
DATABASE_URL="postgresql://picake_admin:your_password@localhost:5432/picake_dev_db"

macOS

PostgreSQL 설치

brew install postgresql@15

PostgreSQL 서비스 시작

brew services start postgresql@15

PostgreSQL에 접속

psql postgres

데이터베이스 생성

-- .env.development의 DATABASE_URL에서 사용하는 데이터베이스 이름 확인
CREATE DATABASE picake_dev_db;
-- .env.development의 DATABASE_URL에서 사용하는 사용자 이름, 비밀번호 확인
CREATE USER picake_admin WITH PASSWORD 'your_password';
-- 데이터베이스 생성 권한 부여 (Prisma 마이그레이션을 위한 shadow database 생성에 필요)
ALTER USER picake_admin CREATEDB;
-- 권한 부여
GRANT ALL PRIVILEGES ON DATABASE picake_dev_db TO picake_admin;
-- 데이터베이스 소유자 변경
ALTER DATABASE picake_dev_db OWNER TO picake_admin;

Windows

PostgreSQL 설치

PostgreSQL 공식 사이트에서 설치 프로그램 다운로드
- PostgreSQL 15 버전 선택
- Superuser (postgres) 비밀번호 설정 (.env.development의 DATABASE_URL비밀번호와 동일)
- 포트: 기본값 5432 유지

PostgreSQL 설치 확인

Get-Service postgresql*

psql 접속

방법 1: PowerShell에서 접속

psql -U postgres

방법 2: PostgreSQL SQL Shell (psql) 사용
시작 메뉴에서 "SQL Shell (psql)" 실행

주의사항:

Windows에서 PostgreSQL 설치 시 기본적으로 postgres 사용자가 생성됩니다
설치 시 설정한 비밀번호를 사용하여 접속합니다
포트는 기본적으로 5432입니다

데이터베이스 생성

1단계: psql 접속

방법 1 또는 방법 2로 psql에 접속합니다.

방법 1 사용 시: PowerShell에서 psql -U postgres 실행 후 비밀번호 입력
방법 2 사용 시: SQL Shell (psql) 실행 후 연결 프롬프트에서 Enter 키를 눌러 기본값 사용:
- Server [localhost]: → Enter
- Database [postgres]: → Enter
- Port [5432]: → Enter
- Username [postgres]: → Enter
- Password for user postgres: → 비밀번호 입력 후 Enter

2단계: 데이터베이스 생성 명령어 실행

postgres=# 프롬프트가 나타난 후, 다음 SQL 명령어들을 하나씩 순서대로 입력합니다:

-- 데이터베이스 생성 (.env.development의 DATABASE_URL에서 사용하는 데이터베이스 이름 확인)
CREATE DATABASE picake_dev_db;
-- 사용자 생성 (비밀번호는 .env.development의 DATABASE_URL과 동일하게 설정)
CREATE USER picake_admin WITH PASSWORD 'your_password';
-- 데이터베이스 생성 권한 부여 (Prisma 마이그레이션을 위한 shadow database 생성에 필요)
ALTER USER picake_admin CREATEDB;
-- 권한 부여
GRANT ALL PRIVILEGES ON DATABASE picake_dev_db TO picake_admin;
-- 데이터베이스 소유자 변경
ALTER DATABASE picake_dev_db OWNER TO picake_admin;

참고:

각 명령어는 세미콜론(;)으로 끝나며, Enter를 누르면 실행됩니다.
비밀번호는 .env.development 파일의 DATABASE_URL과 동일하게 설정해야 합니다.

3단계: 생성 확인

-- 데이터베이스 목록 확인
\l

-- 사용자 목록 확인
\du

Prisma 명령어

# 개발 환경 마이그레이션
yarn db:migrate:dev

# 개발 환경 데이터베이스 리셋
yarn db:reset:dev

# 개발 환경 시드 데이터
yarn db:seed:dev

# Prisma Studio 실행
yarn db:studio:dev

# 배포 환경 마이그레이션 (환경 변수 필요)
yarn db:migrate:deploy

주의사항

로컬 개발용 데이터베이스이므로 실제 서비스 데이터와 분리
스테이징/프로덕션은 EC2에 직접 설치한 PostgreSQL 사용 (EC2 배포 가이드 참고)
환경 변수는 .env.development 파일에 설정

기술 스택 요약

백엔드 프레임워크

NestJS: TypeScript 기반 Node.js 프레임워크
Express: HTTP 서버 엔진 (NestJS가 내부적으로 사용)
TypeScript: 정적 타입 검사

데이터베이스

PostgreSQL: 관계형 데이터베이스
- 개발: 로컬 PostgreSQL
- 스테이징/프로덕션: EC2에 직접 설치한 PostgreSQL (비용 절감)
Prisma: ORM (Object-Relational Mapping)
- Prisma Client: 타입 안전한 데이터베이스 클라이언트
- Prisma Migrate: 데이터베이스 마이그레이션 관리

인증 및 보안

JWT: JSON Web Token 기반 인증
Passport: 인증 미들웨어
- passport-jwt: JWT 전략 구현
Google OAuth: Google 로그인 (직접 구현, axios 기반)
bcrypt: 비밀번호 해싱
Helmet: 보안 헤더 설정
CORS: Cross-Origin Resource Sharing 설정
@nestjs/throttler: Rate Limiting (요청 제한)

API 문서화

@nestjs/swagger: API 문서 자동 생성
- 3-way 분리: User, Seller, Admin 각각 별도 Swagger 문서

유효성 검사 및 변환

class-validator: DTO 유효성 검사
class-transformer: 객체 변환 및 직렬화

HTTP 및 미들웨어

cookie-parser: 쿠키 파싱 (서브도메인 통합 로그인)
morgan: HTTP 요청 로깅 (개발/스테이징 환경)

WebSocket

@nestjs/websockets: WebSocket 게이트웨이
@nestjs/platform-socket.io: Socket.IO 어댑터
socket.io: 실시간 채팅 및 알림 (채팅 namespace: /, 알림 namespace: /notifications)

알림 (Push Notification)

Firebase Cloud Messaging (FCM): 모바일 푸시 알림 전송

에러 모니터링

@sentry/nestjs: Sentry 에러 로깅 및 성능 모니터링

클라우드 서비스

@aws-sdk/client-s3: AWS S3 파일 업로드

HTTP 클라이언트

axios: HTTP 클라이언트 (Google/Kakao OAuth 등 외부 API 호출)

개발 도구

ESLint: 코드 품질 관리
Prettier: 코드 포맷팅
dotenv-cli: 환경 변수 관리

FilesExpand file tree

기술 스택 - 가이드.md

Latest commit

History