2026년 TypeScript 데코레이터 완벽 가이드: 실전 예제로 배우기

function Logger(target: any) {
  console.log('로깅 중...', target);
}

@Logger
class User {
  name = "홍길동";
}

function Component(constructor: Function) {
  console.log(`${constructor.name} 컴포넌트가 생성되었어요!`);
  // 클래스에 메타데이터 추가
  constructor.prototype.createdAt = new Date();
}

@Component
class UserComponent {
  name = 'User';
}

const user = new UserComponent();
console.log(user.createdAt); // 현재 시간 출력

function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = function(...args: any[]) {
    console.log(`${propertyKey} 메서드 실행 시작!`);
    const result = originalMethod.apply(this, args);
    console.log(`${propertyKey} 메서드 실행 완료!`);
    return result;
  };
}

class Calculator {
  @Log
  add(a: number, b: number) {
    return a + b;
  }
}

function Required(target: any, propertyKey: string) {
  let value: any;
  
  Object.defineProperty(target, propertyKey, {
    get() { return value; },
    set(newVal) {
      if (!newVal) {
        throw new Error(`${propertyKey}는 필수 항목이에요!`);
      }
      value = newVal;
    }
  });
}

class User {
  @Required
  email: string;
}

function Configurable(value: boolean) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    descriptor.configurable = value;
  };
}

class Person {
  private _name: string = '';
  
  @Configurable(false)
  get name() { return this._name; }
  
  set name(value: string) { this._name = value; }
}

function Inject(target: any, propertyKey: string, parameterIndex: number) {
  console.log(`파라미터 인덱스 ${parameterIndex}에 주입됩니다!`);
  // 메타데이터 저장
  const existingInjectedParams = Reflect.getOwnMetadata('injected', target, propertyKey) || [];
  existingInjectedParams.push(parameterIndex);
  Reflect.defineMetadata('injected', existingInjectedParams, target, propertyKey);
}

class Service {
  getData(@Inject id: string) {
    return `데이터 ${id}`;
  }
}

• 1단계: 프로퍼티 데코레이터
• 2단계: 접근자/파라미터 데코레이터
• 3단계: 메서드 데코레이터
• 4단계: 클래스 데코레이터

function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = function(...args: any[]) {
    console.log(`[${new Date().toISOString()}] ${propertyKey} 호출됨`);
    console.log('받은 인자:', args);
    
    const result = originalMethod.apply(this, args);
    
    console.log('반환 값:', result);
    return result;
  };
  
  return descriptor;
}

class UserService {
  @Log
  createUser(name: string, email: string) {
    return { id: 1, name, email };
  }
}

const service = new UserService();
service.createUser('김철수', 'chulsoo@example.com');
// 콘솔에 자동으로 로그가 찍혀요!

function Measure(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = async function(...args: any[]) {
    const start = performance.now();
    
    const result = await originalMethod.apply(this, args);
    
    const end = performance.now();
    const executionTime = (end - start).toFixed(2);
    
    console.log(`⏱️ ${propertyKey} 실행 시간: ${executionTime}ms`);
    
    if (parseFloat(executionTime) > 1000) {
      console.warn(`⚠️ ${propertyKey}가 느려요! (${executionTime}ms)`);
    }
    
    return result;
  };
  
  return descriptor;
}

class DataService {
  @Measure
  async fetchLargeData() {
    // 시뮬레이션: 2초 걸리는 작업
    await new Promise(resolve => setTimeout(resolve, 2000));
    return '데이터 로드 완료';
  }
}

const dataService = new DataService();
await dataService.fetchLargeData();
// ⏱️ fetchLargeData 실행 시간: 2001.23ms
// ⚠️ fetchLargeData가 느려요! (2001.23ms)

// 권한 타입 정의
type Role = 'admin' | 'user' | 'guest';

// 현재 사용자 정보 (실제로는 인증 시스템에서 가져옴)
let currentUser: { role: Role } = { role: 'user' };

function RequireRole(role: Role) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = function(...args: any[]) {
      if (currentUser.role !== role) {
        throw new Error(`❌ 권한 없음! ${role} 권한이 필요해요.`);
      }
      
      console.log(`✅ ${role} 권한 확인됨`);
      return originalMethod.apply(this, args);
    };
    
    return descriptor;
  };
}

class AdminController {
  @RequireRole('admin')
  deleteAllUsers() {
    console.log('모든 사용자 삭제... (위험!)');
    return '삭제 완료';
  }
  
  @RequireRole('user')
  updateProfile(name: string) {
    console.log(`프로필 업데이트: ${name}`);
    return '업데이트 완료';
  }
}

const controller = new AdminController();

// 일반 사용자로 실행
try {
  controller.deleteAllUsers();
} catch (error) {
  console.log(error.message); // ❌ 권한 없음! admin 권한이 필요해요.
}

// 일반 사용자는 프로필 수정 가능
controller.updateProfile('새이름'); // ✅ user 권한 확인됨

// 유효성 검증 메타데이터 저장소
const validationRules = new Map<any, Map<string, Function[]>>();

// 필수 입력 데코레이터
function Required(target: any, propertyKey: string) {
  const rules = validationRules.get(target.constructor) || new Map();
  const fieldRules = rules.get(propertyKey) || [];
  
  fieldRules.push((value: any) => {
    if (!value) {
      return `${propertyKey}는 필수 입력이에요!`;
    }
    return null;
  });
  
  rules.set(propertyKey, fieldRules);
  validationRules.set(target.constructor, rules);
}

// 최소 길이 데코레이터
function MinLength(min: number) {
  return function(target: any, propertyKey: string) {
    const rules = validationRules.get(target.constructor) || new Map();
    const fieldRules = rules.get(propertyKey) || [];
    
    fieldRules.push((value: string) => {
      if (value && value.length < min) {
        return `${propertyKey}는 최소 ${min}자 이상이어야 해요!`;
      }
      return null;
    });
    
    rules.set(propertyKey, fieldRules);
    validationRules.set(target.constructor, rules);
  };
}

// 이메일 형식 데코레이터
function IsEmail(target: any, propertyKey: string) {
  const rules = validationRules.get(target.constructor) || new Map();
  const fieldRules = rules.get(propertyKey) || [];
  
  fieldRules.push((value: string) => {
    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      return `${propertyKey}는 올바른 이메일 형식이 아니에요!`;
    }
    return null;
  });
  
  rules.set(propertyKey, fieldRules);
  validationRules.set(target.constructor, rules);
}

// 유효성 검증 실행 함수
function validate(instance: any): string[] {
  const errors: string[] = [];
  const rules = validationRules.get(instance.constructor);
  
  if (!rules) return errors;
  
  rules.forEach((fieldRules, propertyKey) => {
    const value = (instance as any)[propertyKey];
    fieldRules.forEach(rule => {
      const error = rule(value);
      if (error) errors.push(error);
    });
  });
  
  return errors;
}

// 실제 사용 예시
class RegisterDTO {
  @Required
  @MinLength(2)
  username: string;
  
  @Required
  @IsEmail
  email: string;
  
  @Required
  @MinLength(8)
  password: string;
  
  constructor(username: string, email: string, password: string) {
    this.username = username;
    this.email = email;
    this.password = password;
  }
}

// 올바른 데이터
const validUser = new RegisterDTO('김철수', 'chulsoo@example.com', 'password123');
console.log('검증 결과:', validate(validUser)); // []

// 잘못된 데이터
const invalidUser = new RegisterDTO('김', 'invalid-email', '123');
console.log('검증 결과:', validate(invalidUser));
// [
//   'username는 최소 2자 이상이어야 해요!',
//   'email는 올바른 이메일 형식이 아니에요!',
//   'password는 최소 8자 이상이어야 해요!'
// ]

function Memoize(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  const cache = new Map<string, any>();
  
  descriptor.value = function(...args: any[]) {
    // 인자를 문자열로 변환해서 캐시 키로 사용
    const cacheKey = JSON.stringify(args);
    
    if (cache.has(cacheKey)) {
      console.log(`? 캐시에서 가져옴: ${propertyKey}(${cacheKey})`);
      return cache.get(cacheKey);
    }
    
    console.log(`? 새로 계산: ${propertyKey}(${cacheKey})`);
    const result = originalMethod.apply(this, args);
    cache.set(cacheKey, result);
    
    return result;
  };
  
  return descriptor;
}

class Calculator {
  @Memoize
  fibonacci(n: number): number {
    if (n  setTimeout(resolve, 1000));
    return { id: userId, name: `사용자${userId}`, email: `user${userId}@example.com` };
  }
}

const calc = new Calculator();

// 첫 번째 호출 - 실제로 계산
console.log(calc.fibonacci(10)); // ? 새로 계산: fibonacci([10])

// 두 번째 호출 - 캐시에서 즉시 반환
console.log(calc.fibonacci(10)); // ? 캐시에서 가져옴: fibonacci([10])

// API 호출도 마찬가지
await calc.fetchUserData(1); // ? 새로 계산: fetchUserData([1])
await calc.fetchUserData(1); // ? 캐시에서 가져옴: fetchUserData([1])

class ProductService {
  // 위에서 아래로 실행돼요!
  @Log              // 3번째: 로그 기록
  @Measure          // 2번째: 성능 측정
  @RequireRole('admin')  // 1번째: 권한 확인
  async deleteProduct(productId: number) {
    console.log(`상품 ${productId} 삭제 중...`);
    await new Promise(resolve => setTimeout(resolve, 500));
    return `상품 ${productId} 삭제 완료`;
  }
  
  @Memoize
  @Measure
  @Log
  getProductDetails(productId: number) {
    // 무거운 연산...
    return {
      id: productId,
      name: '노트북',
      price: 1500000
    };
  }
}

// 실행 순서:
// 1. RequireRole: 권한 체크
// 2. Measure: 성능 측정 시작
// 3. Log: 메서드 호출 로그
// 4. 실제 메서드 실행
// 5. Log: 반환값 로그
// 6. Measure: 성능 측정 종료
// 7. RequireRole: 종료

function Retry(maxRetries: number = 3, delayMs: number = 1000) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = async function(...args: any[]) {
      let lastError: any;
      
      for (let attempt = 1; attempt  setTimeout(resolve, delayMs));
          }
        }
      }
      
      throw new Error(`${maxRetries}번 시도 후 실패: ${lastError.message}`);
    };
    
    return descriptor;
  };
}

class ApiService {
  private callCount = 0;
  
  @Retry(3, 1000)
  async fetchData() {
    this.callCount++;
    console.log(`  → API 호출 #${this.callCount}`);
    
    // 2번째 시도에서 성공하도록 시뮬레이션
    if (this.callCount < 2) {
      throw new Error('네트워크 오류');
    }
    
    return '데이터 로드 성공!';
  }
}

const api = new ApiService();
const result = await api.fetchData();
console.log('최종 결과:', result);
// ? 시도 1/3...
//   → API 호출 #1
// ❌ 시도 1 실패: 네트워크 오류
// ⏳ 1000ms 후 재시도...
// ? 시도 2/3...
//   → API 호출 #2
// 최종 결과: 데이터 로드 성공!

function Retry(maxAttempts: number, delay: number = 1000) {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    const originalMethod = descriptor.value;
    
    descriptor.value = async function (...args: any[]) {
      let lastError: Error;
      
      for (let attempt = 1; attempt  setTimeout(resolve, delay));
          }
        }
      }
      
      throw new Error(`${maxAttempts}번 시도 후 실패: ${lastError.message}`);
    };
    
    return descriptor;
  };
}

class ApiClient {
  @Retry(3, 2000)
  async fetchData(url: string) {
    const response = await fetch(url);
    if (!response.ok) throw new Error('API 요청 실패');
    return response.json();
  }
}

class UserService {
  @Log('사용자 조회')
  @Validate('id', 'isPositive')
  @Cache({ ttl: 60000 })
  @Retry(3)
  async getUser(id: number) {
    // 실제 API 호출
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  }
}

import 'reflect-metadata';

const ROUTE_METADATA = Symbol('route');

function Route(path: string) {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    Reflect.defineMetadata(ROUTE_METADATA, path, target, propertyKey);
  };
}

function getRoutes(target: any) {
  const routes: { method: string; path: string }[] = [];
  
  for (const propertyKey of Object.getOwnPropertyNames(target.prototype)) {
    const path = Reflect.getMetadata(
      ROUTE_METADATA,
      target.prototype,
      propertyKey
    );
    
    if (path) {
      routes.push({ method: propertyKey, path });
    }
  }
  
  return routes;
}

class UserController {
  @Route('/users')
  getUsers() {
    return '사용자 목록';
  }
  
  @Route('/users/:id')
  getUser() {
    return '사용자 상세';
  }
}

// 라우트 자동 등록
const routes = getRoutes(UserController);
console.log(routes);

function Memoize() {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    const originalMethod = descriptor.value;
    const cache = new Map();
    
    descriptor.value = function (...args: any[]) {
      const key = JSON.stringify(args);
      
      if (cache.has(key)) {
        console.log('캐시에서 가져옴!');
        return cache.get(key);
      }
      
      const result = originalMethod.apply(this, args);
      cache.set(key, result);
      console.log('새로 계산함');
      
      return result;
    };
    
    return descriptor;
  };
}

class Calculator {
  @Memoize()
  fibonacci(n: number): number {
    if (n (
  validator: (args: Parameters) => boolean
) {
  return function(
    target: any,
    key: string,
    descriptor: TypedPropertyDescriptor
  ) {
    const originalMethod = descriptor.value!;
    
    descriptor.value = function(...args: Parameters) {
      if (!validator(args)) {
        throw new Error('유효하지 않은 인자입니다');
      }
      return originalMethod.apply(this, args);
    } as T;
  };
}

• @LogExecutionTime - 실행 시간을 로깅한다는 게 명확해요
• @ValidateEmail - 이메일 검증만 담당하죠
• @CacheResult(300) - 결과를 300초간 캐싱한다는 게 보여요
• @RequireAuth - 인증 필요하다는 게 한눈에 들어와요

• @DoStuff - 뭘 하는 건데요?
• @Magic - 마법은 코드에서 금물이에요
• @Helper - 너무 모호하죠

이런 이름은 6개월 뒤에 보면 본인도 뭔지 몰라요. 진짜예요.

// 제네릭을 활용한 타입 안전 데코레이터
function ValidateParams<T extends (...args: any[]) => any>(
  validator: (params: Parameters<T>) => boolean
) {
  return function (
    target: T,
    context: ClassMethodDecoratorContext
  ): T {
    return function (this: any, ...args: Parameters<T>) {
      if (!validator(args)) {
        throw new Error(`Invalid parameters for ${String(context.name)}`);
      }
      return target.apply(this, args);
    } as T;
  };
}

// 사용 예시
class UserService {
  @ValidateParams<typeof UserService.prototype.createUser>(
    ([name, age]) => typeof name === 'string' && age > 0
  )
  createUser(name: string, age: number) {
    return { name, age, id: Date.now() };
  }
}

1. 캐싱 활용하기
   같은 입력에 대해 매번 계산하지 말고 결과를 캐싱하세요. 메모이제이션 데코레이터가 딱이에요.
2. 느긋한 초기화 (Lazy Initialization)
   데코레이터에서 무거운 작업은 실제로 필요할 때까지 미루는 게 좋아요. 클래스 정의 시점이 아니라 메서드 호출 시점에요.
3. 조건부 실행
   개발 환경에서만 동작하는 데코레이터는 프로덕션에서 완전히 비활성화하세요.

// 메모이제이션 데코레이터 (성능 개선)
function Memoize() {
  const cache = new Map<string, any>();
  
  return function (
    target: Function,
    context: ClassMethodDecoratorContext
  ) {
    return function (this: any, ...args: any[]) {
      const key = JSON.stringify(args);
      
      if (cache.has(key)) {
        return cache.get(key); // 캐시된 결과 반환
      }
      
      const result = target.apply(this, args);
      cache.set(key, result);
      return result;
    };
  };
}

// 조건부 디버깅 데코레이터
function Debug() {
  return function (
    target: Function,
    context: ClassMethodDecoratorContext
  ) {
    // 프로덕션에서는 원본 그대로 반환
    if (process.env.NODE_ENV === 'production') {
      return target;
    }
    
    // 개발 환경에서만 로깅 추가
    return function (this: any, ...args: any[]) {
      console.log(`[DEBUG] ${String(context.name)} called with:`, args);
      const result = target.apply(this, args);
      console.log(`[DEBUG] ${String(context.name)} returned:`, result);
      return result;
    };
  };
}

데코레이터는 아래에서 위로 평가되고, 위에서 아래로 실행돼요. 뭔 소린가 싶죠? 예시 보면 이해돼요.

class Example {
  @First()   // 3번째로 실행됨
  @Second()  // 2번째로 실행됨
  @Third()   // 1번째로 실행됨
  method() {}
}

// 실행 순서: Third → Second → First
// 왜? Third가 가장 먼저 원본 메서드를 감싸고,
// Second가 그걸 또 감싸고, First가 마지막으로 감싸거든요

이걸 알고 있으면 @Auth → @Validate → @Log 같은 순서를 의도적으로 만들 수 있어요.

/**
 * 메서드 실행 시간을 측정하고 콘솔에 출력하는 데코레이터
 * 
 * @param threshold - 경고를 표시할 임계값(밀리초), 기본값 1000ms
 * 
 * @example
 * ```typescript
 * class DataService {
 *   @MeasureTime(500)
 *   async fetchData() {
 *     // 500ms 이상 걸리면 경고 표시됨
 *     return await api.getData();
 *   }
 * }
 *
 * 
 * @remarks
 * - 프로덕션 환경에서는 자동으로 비활성화됩니다
 * - Promise를 반환하는 메서드도 지원합니다
 * 
 * @since 2026-02-01
 */
function MeasureTime(threshold: number = 1000) {
  // 구현...
}

• 명확한 에러 메시지 - 어떤 데코레이터에서, 왜 실패했는지 알려주세요
• 원본 스택 보존 - 에러를 다시 던질 때 원본 스택 트레이스를 유지하세요
• 디버그 모드 - 환경 변수로 상세 로깅을 켜고 끌 수 있게 만드세요
• 타입 가드 - 잘못된 타입이 들어왔을 때 컴파일 타임에 잡히도록 하세요

function SafeExecute() {
  return function (
    target: Function,
    context: ClassMethodDecoratorContext
  ) {
    const methodName = String(context.name);
    
    return function (this: any, ...args: any[]) {
      try {
        const result = target.apply(this, args);
        
        // Promise 처리
        if (result instanceof Promise) {
          return result.catch((error: Error) => {
            console.error(
              `[${methodName}] Async error:`,
              error.message
            );
            // 원본 에러를 다시 던져서 스택 트레이스 보존
            throw error;
          });
        }
        
        return result;
      } catch (error) {
        // 명확한 에러 메시지와 함께 컨텍스트 제공
        console.error(
          `[${methodName}] Error occurred:`,
          error instanceof Error ? error.message : error
        );
        
        // 프로덕션에서는 사용자 친화적 메시지로 변환
        if (process.env.NODE_ENV === 'production') {
          throw new Error(`작업 실행 중 오류가 발생했습니다.`);
        }
        
        throw error;
      }
    };
  };
}

• ✓ 명확하고 설명적인 이름 사용했나요?
• ✓ 타입 안정성을 제네릭으로 확보했나요?
• ✓ 성능 오버헤드를 최소화했나요?
• ✓ 데코레이터 조합 순서를 고려했나요?
• ✓ JSDoc으로 충분히 문서화했나요?
• ✓ 에러 처리와 디버깅이 쉽게 구현됐나요?
• ✓ 단위 테스트를 작성했나요?
• ✓ 팀 코딩 컨벤션에 맞춰 작성했나요?