Skip to Content
API 레퍼런스@asapjs/routerRouterController

RouterController

이 페이지에서 찾을 수 있는 것

심볼분류설명
RouterControllerClass모든 컨트롤러의 기반 클래스
basePathPropertyURL 접두사
tagPropertySwagger 태그 그룹
expressRouterProperty내부 Express Router 인스턴스
registerRoutes()Method데코레이터 라우트를 Express에 등록

개요

RouterController는 ASAPJS에서 모든 HTTP 컨트롤러가 상속하는 기반 클래스입니다. Express Router 인스턴스를 생성하고, 데코레이터가 누적한 라우트 메타데이터를 Express 라우터에 바인딩하는 역할을 합니다.

import { RouterController } from '@asapjs/router';

클래스 정의

class RouterController {
  public basePath: string;        // default: '/'
  public tag: string;             // Swagger 태그 그룹 레이블
  public expressRouter: Router;   // 내부 Express Router
 
  constructor();
 
  protected registerRoutes(): void;
}

멤버

멤버타입설명
basePathstring이 컨트롤러의 모든 라우트에 대한 URL 접두사. 서브클래스에서 재정의합니다 (예: '/users'). 기본값은 '/'.
tagstring이 컨트롤러의 모든 라우트를 그룹화하는 Swagger 태그. 서브클래스에서 재정의합니다 (예: 'User').
expressRouterRouterExpress Router 인스턴스. RouterPlugin이 컨트롤러를 마운트할 때 내부적으로 사용합니다.
registerRoutes()() => void데코레이터가 누적한 모든 라우트를 읽어 expressRouter에 등록합니다. 서브클래스 생성자에서 반드시 호출해야 합니다.

서브클래스 패턴

import { RouterController, Get, ExecuteArgs } from '@asapjs/router';
import PostApplication from '../application/PostApplication';
import PostInfoDto from '../dto/PostInfoDto';
 
export default class PostController extends RouterController {
  public tag = 'Post';
  public basePath = '/posts';
 
  private postService: PostApplication;
 
  constructor() {
    super();
    this.registerRoutes();          // 생성자에서 항상 호출
    this.postService = new PostApplication();
  }
 
  @Get('/', {
    title: '게시글 목록',
    response: PostInfoDto,
  })
  public getPosts = async ({ paging }: ExecuteArgs) => {
    return await this.postService.list(paging);
  };
}

중요: registerRoutes()는 반드시 super() 직후, 서비스 인스턴스화 이전에 호출하세요. 이렇게 해야 첫 번째 요청이 도착하기 전에 라우트 메타데이터가 완전히 바인딩됩니다.

라우트 등록 흐름

registerRoutes()가 호출되면 다음 순서로 동작합니다:

  1. 데코레이터(@Get, @Post, @Put, @Delete)가 누적한 routes 배열을 순회합니다.
  2. 각 라우트의 methodName으로 실제 메서드를 찾아 wrapWithEffect()로 감쌉니다 (Effect 기반 트레이싱 적용).
  3. excute(method)(options)를 호출하여 다음 순서로 Express 라우터에 등록합니다:
    • jwtVerification(auth) — JWT 검증 미들웨어
    • middleware[] — 라우트별 추가 미들웨어
    • Wrapper(handler) — 핸들러 래퍼 (ExecuteArgs 구성)
  4. 동시에 Swagger 경로/스키마 정보를 addPaths()로 등록합니다.

컨트롤러 등록

컨트롤러를 작성한 후, RouterPlugin이 이를 발견하고 마운트할 수 있도록 route.ts 파일에서 컨트롤러 인스턴스를 직접 내보내야 합니다:

// src/route.ts
import UserController from './user/controller/UserController';
import PostController from './post/controller/PostController';
 
export default [
  new UserController(),
  new PostController(),
];

RouterPlugin은 각 컨트롤러 인스턴스에서 basePath와 expressRouter를 읽어 Express 앱의 /<basePath> 아래에 마운트합니다. .expressRouter만 내보내면 basePath를 읽을 수 없으므로 반드시 인스턴스 자체를 내보내세요.

관련 항목

Last updated on
requestType / responseTypeRouterPlugin