[NestJS] Interface, type, class의 차이

 

Express에서 Nest로 처음 넘어갔을 때, Nest의 아키텍처를 이해하는 것이 꽤나 어려웠다.

공식문서를 읽고 어느 정도는 이해했다고 생각한 상태로 일단 뭐라도 직접 만들어보자 라는 생각에 깃허브에 다른 개발자들이 Nest를 사용한 코드를 올려둔 리포지토리를 참고해서 무작정 따라 만들고 여러 코드를 둘러봤었는데

개발자들마다 누구는  types, 누구는 interface, class를  여기저기서 사용하고 있는 걸 보니 왜 다 다르게 사용하고 있는 건지 혼란스럽기만 하고,  이것들은 도대체 언제 어디에 쓰는 건지 궁금해졌다.

타입을 정의하는 이유? 
우선 세가지 방식을 다루기에 앞서 이 세 가지 방식 모두 타입을 정의하는데 사용하는 문법이라는 것을 짚고 넘어간다.
타입을 정의하는 것은 선택사항이지만, 타입을 정의하는 것으로서 컴파일 타임에 타입 오류를 방지할 수 있고, 코드의 가독성을 향상해 읽는 입장에서 더 코드를 쉽게 이해하며 읽을 수 있다. (readable)

세 가지 방식의 차이

Interface

타입 정의의 기본은 인터페이스다. 변수의 타입만을 체크하는 방식으로 주로 객체의 타입을 정의할 때 사용한다.

// user.interface.ts
export interface IUser {
  id: number;
  username: string;
  email: string;
}

export class UserService {
  private users: IUser[] = [];

  createUser(user: IUser): IUser {
    this.users.push(user);
    return user;
  }

  getUsers(): IUser[] {
    return this.users;
  }
}

Type

type은 유연한 타입 정의가 가능하다. 인터페이스와  비슷하지만, 객체 타입 외에도 유니언 타입, 교차 타입 등 복잡한 구조를 정의할 수 있다.

// user.type.ts
export type User = {
  id: number;
  username: string;
  email: string;
};

export type Admin = User & {
  role: 'admin';
};

export class UserService {
  private users: User[] = [];

  createUser(user: User): User {
    this.users.push(user);
    return user;
  }

  getUsers(): User[] {
    return this.users;
  }
}

Class

class는 실제 구현체에 해당된다. 변수의 타입도  체크하고, 객체의 인스턴스 또한  생성할 수 있는 템플릿을 제공한다.

메서드와 생성자를 포함할 수 있다.

// user.class.ts
export class User {
  constructor(
    public id: number,
    public username: string,
    public email: string,
  ) {}

  displayInfo(): string {
    return `${this.username} - ${this.email}`;
  }
}

export class UserService {
  private users: User[] = [];

  createUser(user: User): User {
    this.users.push(user);
    return user;
  }

  getUsers(): User[] {
    return this.users;
  }
}

 

 

그래서 언제 무엇을 써야할까?

여러 상황에 맞춰서 3가지 방식을 각각 언제 활용하면 좋을지 알아보자.

 

1. 데코레이터와 메타데이터

@Entity('users')
@Unique(['login_id']) 
export class UserEntity {
    @PrimaryGeneratedColumn({ type: 'int', unsigned: true })
    id: number;

    @Column({ type: 'varchar', length: 30, nullable: false })
    login_id: string;
    // ...
    
}

NestJS를 사용하다 보면, 대부분의 상황에서 데코레이터로 모든 것을 제어하는 것을 알 수 있다.

그런데 interface의 경우 컴파일 후에 사라지기 때문에 데코레이터를 사용할 수 없다. 

이런 맥락에서 DTO나 Pipe 같은 요소는 런타임에서 사용할 수 있는 것이 중요하기 때문에

인터페이스보다 클래스가 선호된다.

 

 

2. 의존성  주입(DI)

실제 프로젝트에서는  Type -> Repository -> Service -> Module 순서로 사용되며 의존성이 설정된다.

// product.types.ts
// 1. 타입 정의: 엔티티와 Repository 인터페이스
interface Product {
  id: number;
  name: string;
  price: number;
}

export const PRODUCT_REPOSITORY = Symbol('PRODUCT_REPOSITORY');

interface IProductRepository {
  findOne(id: number): Promise<Product>;
  save(product: Omit<Product, 'id'>): Promise<Product>;
}



// product.repository.ts
// 2. Repository 구현체
import { Injectable } from '@nestjs/common';
import { IProductRepository, Product, PRODUCT_REPOSITORY } from './product.types';

@Injectable()
export class ProductRepository implements IProductRepository {
  async findOne(id: number): Promise<Product> {
    // 실제 DB 조회 로직
    return { id, name: 'Laptop', price: 1000 };
  }

  async save(product: Omit<Product, 'id'>): Promise<Product> {
    // 실제 DB 저장 로직
    return { id: 1, ...product };
  }
}



// product.service.ts
// 3. Service에서 Repository 사용
// service에서 interface repo를 쓰는 이유는 실제 repo와 service의 결합성을 낮추기 위함
import { Injectable } from '@nestjs/common';
import { IProductRepository, Product, PRODUCT_REPOSITORY } from './product.types';
import { Inject } from '@nestjs/common';

@Injectable()
export class ProductService {
  constructor(
    @Inject(PRODUCT_REPOSITORY)
    private readonly productRepository: IProductRepository,
  ) {}

  async getProductById(id: number): Promise<Product> {
    return this.productRepository.findOne(id);
  }

  async createProduct(name: string, price: number): Promise<Product> {
    return this.productRepository.save({ name, price });
  }
}


// product.module.ts
// 4. Module에서 의존성 설정
import { Module } from '@nestjs/common';
import { ProductService } from './product.service';
import { ProductRepository } from './product.repository';
import { PRODUCT_REPOSITORY } from './product.types';

@Module({
  providers: [
    ProductService,
    {
      provide: PRODUCT_REPOSITORY,
      useClass: ProductRepository,
    },
  ],
  exports: [ProductService],
})
export class ProductModule {}

이 구조는 NestJS의 의존성 주입(DI) 시스템을 기반으로 동작한다.

 

1. 컴파일 타임: TypeScript가 타입을 체크하는 시점

• IProductRepository 인터페이스의 메서드들이 제대로 구현되었는지 확인
• 메서드의 파라미터와 반환 타입이 일치하는지 검사

2. 런타임: 실제 JavsScript가 실행되는 시점

• 인터페이스는 사라지고 없음
• PRODUCT_REPOSITORY 토큰을 사용해 ProductRepository 클래스를 인스턴스화하여 서비스에 주입

3. Type의 활용

3-1. 유니온 타입으로 값을 제한할 수 있다.

유니온 타입은 여러 가지 가능한 값 중 하나를 지정할 때 사용한다. 이를 통해 특정 값이 허용되는 범위를 제한할 수 있다.

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
type UserRole = 'admin' | 'manager' | 'user' | 'guest';
type ValidationStatus = 'idle' | 'pending' | 'success' | 'error';

 

3-2. 상태 관리를 위한 차별화된 타입

상태를 관리할 때 각 상태에 따라 다르게 처리할 수 있도록 타입을 정의한다. 여기서 제네릭을 활용하면 상태에 맞는 데이터를 유동적으로 관리할 수 있다. 

type RequestState<T> = 
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'success'; data: T }
    | { status: 'error'; error: Error };

 

3-3. 유틸리티 타입을 활용한 타입 변환

:Omit, Partial, Pick 같은 유틸리티 타입을 사용하여 기존의 타입을 변형하거나, 일부 필드만 선택할 수도 있다.

interface User {
    id: number;
    name: string;
    email: string;
    password: string;
    role: UserRole;
    createdAt: Date;
}

type CreateUserDto = Omit<User, 'id' | 'createdAt'>;  // id, createdAt 제외
type UpdateUserDto = Partial<Pick<User, 'name' | 'email'>>;  // name, email만 선택적
type SafeUser = Omit<User, 'password'>;  // password 제외

 

 

3-4. 이벤트 타입 정의

type UserCreatedEvent = { type: 'USER_CREATED'; userId: number; timestamp: Date; }
type UserDeletedEvent = { type: 'USER_DELETED'; userId: number; reason: string; timestamp: Date; }

type UserEvent = UserCreatedEvent | UserDeletedEvent;

이벤트 시스템에 발생할 수 있는 여러 이벤트의 타입을 정의하여, 해당 이벤트에 맞는 처리를 할 수 있다. 

위 예시에서 UserEvent는 여러 이벤트를 유니온 타입으로 묶어, 이벤트 종류에 따라 적절한 처리가 가능하도록 할 수 있다.

NestJS에서는 type을 이런 식으로 활용하면 유용하다. 

@Injectable()
class UserEventEmitter {
    @OnEvent('user.*')
    handleUserEvent(payload: UserEvent) {
        switch(payload.type) {
            case 'USER_CREATED':
                // payload가 UserCreatedEvent로 타입 추론됨
                break;
            case 'USER_DELETED':
                // payload가 UserDeletedEvent로 타입 추론됨
                break;
        }
    }
}

 

3-5. 복잡한 상태 관리

상태를 더 복잡하게 관리할 때는 여러 필드를 갖는 타입을 정의하여 상태의 변화를 추적할 수 있다.

type CacheState<T> = {
    data: T | null;
    lastUpdated: Date | null;
    isLoading: boolean;
    error: Error | null;
};

여기서 CacheState <T>는 캐시 상태를 관리하며, 데이터를 저장하고 업데이트 시간을 추적하고, 로딩 상태 및 오류를 관리한다.

@Injectable()
class CacheService<T> {
    private state: CacheState<T> = {
        data: null,
        lastUpdated: null,
        isLoading: false,
        error: null
    };
}

 

 

실전에서 선택의 기준

Interface의 강점: 확장과 상속

Interface는 주로 아래와 같은 상황에서 선택하기 적합하다.

 

1. API 응답처럼 확장 가능성이 높은 객체 구조

interface ApiResponse {
    status: number;
    message: string;
}

interface DetailedApiResponse extends ApiResponse {
    data: unknown;
    timestamp: Date;
}

interface PaginatedApiResponse extends DetailedApiResponse {
    page: number;
    totalPages: number;
    hasNext: boolean;
}

 

이 경우 인터페이스는 상속을 통해 여러 가지 응답 구조를 확장할 수 있어 유용하다. 

 

2. 플러그인이나 외부에 공개되는 API

interface Plugin {
    init(): void;
    destroy(): void;
}

외부 시스템에서 구현해야 할 메서드들이나 기능을 정의할 때 유용하다. 플러그인을 작성할 때, 외부에서 구현해야 할 메서드를 명확하게 규정할 수 있다. 

 

3. DB 엔티티처럼 명확한 스키마가 있는 객체

interface User {
    id: number;
    name: string;
    email: string;
    createdAt: Date;
}

DB 엔티티나 모델처럼 고정된 구조를 갖는 객체에서는 interface가 유용하다. 명확한 스키마를 정의하여 데이터의 형태를 일관되게 관리할 수 있다. (다만 ORM 등을 도입하여 데코레이터를 엔티티에 적용해야 하는 경우에는 클래스가 적합)

 

Type의 강점: 유연성과 정교한 타입 정의

1.  튜플 타입 정의

튜플을 정의할 때 사용된다. 각 요소가 특정 타입을 가질 수 있으며, 정확한 위치와 타입을 지정할 수 있다.

type Point = [number, number]; // 2D 좌표
type RGB = [number, number, number]; // RGB 색상
type StateChange = [string, any]; // [key, value] 형태

 

2. 유니온 타입으로 정확한 값 제한

유니온 타입은 특정 값 중 하나만 허용하는 타입을 정의할 때 사용된다. 여러 가지 가능한 값 중에서 선택 가능한 값을 제한할 수 있다.

type Status = 'idle' | 'loading' | 'success' | 'error';  // 상태 값
type Theme = 'light' | 'dark' | 'system';  // 테마 선택
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';  // HTTP 메서드

 

3. 유틸리티 타입을 활용한 변환

유틸리티 타입은 기존 타입을 변형하거나 필요한 부분만 선택할 때 유용하다. 타입을  변환하거나 부분적으로 선택할 수 있다.

interface User {
    id: number;
    name: string;
    email: string;
    password: string;
}

type CreateUser = Omit<User, 'id'>;  // 'id' 제외한 CreateUser 타입
type UpdateUser = Partial<Pick<User, 'name' | 'email'>>;  // name과 email만 선택적
type SafeUser = Omit<User, 'password'>;  // password 제외한 SafeUser 타입

 

4. 템플릿 리터럴 타입

템플릿 리터럴 타입으로 문자열 타입을 동적으로 생성할 수 있다.

type CssUnit = `${number}px` | `${number}rem` | `${number}em`;  // CSS 단위
type EventName = `user:${string}`;  // user:로 시작하는 이벤트 이름

 

결론

결국 세 가지 방식 중 무엇을 선택해야 하느냐는 각자의 자리가 있기 때문에 그때그때 알아서 잘 갖다 써야 한다는 결론이다.  

 

간략하게 정리한 선택 기준은 다음과 같다.

1. Interface  - 컴파일 타임에 타입 안정성 제공

• 객체 구조를 정의할 때
• 확장 가능성이 있는 API 설계
• 명확한 계약(contract)이 필요할 때
• Repository나 Service의 명세 정의

2. Type  - 타입 변환, 조합 처리에 유용

• 정확한 값의 집합을 정의할 때
• 타입 변환이나 조합이 필요할 때
• 튜플이나 유니온 타입을 정의할 때
• 기존 타입을 변형해서 새로운 타입을 만들 때

3. Class 사용처 - 런타임에 실제 동작 구현

• 실제 구현체가 필요할 때
• NestJS의 데코레이터 사용이 필요할 때
• 상태와 행위를 함께 관리할 때
• DI 시스템에서 주입할 대상일 때

나도 공부하면서 알게 된 내용을 정리했을 뿐 결국 경험이 좀 더 쌓여야 상황에 맞게 적절하게 도구를 선택할 수 있게 될 것 같다. 현재 작업 중인 프로젝트만 하더라도 그냥 아무렇게나 클래스를 남발하고 있으니.. 구현이 완성되면 공부한 내용을 토대로 구조를 전체적으로 수정해 주어야겠다고 생각하고 있다.

 

실제 경험이 있는 개발자의 블로그에서는 기본적으로 Interface로 정의하고, 복잡한 타입이나 변환이 필요할 때는 type을 쓰고, 실제 구현이 필요한 경우 class를 사용하는 게 효과적이라고 한다. 

 

 

 

출처 

https://coking.tistory.com/60

https://www.inflearn.com/course/%EB%94%B0%EB%9D%BC%ED%95%98%EB%8A%94-%EB%84%A4%EC%8A%A4%ED%8A%B8-%EC%A0%9C%EC%9D%B4%EC%97%90%EC%8A%A4