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

FastifyRouterController

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

심볼분류설명
FastifyRouterControllerClass모든 Fastify 컨트롤러의 기반 클래스
basePathPropertyURL 접두사
tagProperty컨트롤러 태그 레이블
registerFastifyRoutes()Method데코레이터 라우트를 Fastify에 등록

개요

FastifyRouterController는 @asapjs/fastify에서 모든 HTTP 컨트롤러가 상속하는 기반 클래스입니다. FastifyRouterPlugin이 route.ts에서 컨트롤러를 로드할 때 registerFastifyRoutes()를 자동으로 호출하여 데코레이터가 누적한 라우트 메타데이터를 Fastify 플러그인 시스템에 등록합니다.

import { FastifyRouterController } from '@asapjs/fastify';

클래스 정의

class FastifyRouterController {
  public basePath: string;   // default: '/'
  public tag: string;        // 컨트롤러 태그 레이블
 
  public registerFastifyRoutes(fastify: FastifyInstance): void;
}

멤버

멤버타입설명
basePathstring이 컨트롤러의 모든 라우트에 대한 URL 접두사. 서브클래스에서 재정의합니다 (예: '/users'). 기본값은 '/'.
tagstring이 컨트롤러를 식별하는 태그 레이블. 서브클래스에서 재정의합니다 (예: 'User').
registerFastifyRoutes(fastify)(FastifyInstance) => void데코레이터가 누적한 모든 라우트를 읽어 Fastify 플러그인 시스템에 등록합니다. FastifyRouterPlugin이 자동으로 호출하므로 직접 호출할 필요가 없습니다.

Express RouterController와의 차이점

@asapjs/router의 RouterController와 비교했을 때 다음 차이가 있습니다:

항목RouterControllerFastifyRouterController
라우트 등록 메서드registerRoutes()registerFastifyRoutes(fastify)
생성자에서 직접 호출필요 (super() 직후)불필요 (플러그인이 자동 호출)
내부 라우터 인스턴스expressRouter없음 (Fastify 플러그인 시스템 사용)
미들웨어 적용 방식Express 미들웨어adaptMiddlewareToHook으로 Fastify preHandler로 변환
Swagger 자동 생성지원미지원

FastifyRouterController를 상속하는 컨트롤러는 생성자에서 registerFastifyRoutes()를 직접 호출하지 않아도 됩니다. FastifyRouterPlugin이 컨트롤러를 로드할 때 Fastify 인스턴스를 전달하며 자동으로 호출합니다.

서브클래스 패턴

import { FastifyRouterController, Get, FastifyExecuteArgs } from '@asapjs/fastify';
import PostApplication from '../application/PostApplication';
import PostInfoDto from '../dto/PostInfoDto';
 
export default class PostController extends FastifyRouterController {
  public tag = 'Post';
  public basePath = '/posts';
 
  private postService: PostApplication;
 
  constructor() {
    super();
    // registerFastifyRoutes()는 직접 호출하지 않습니다.
    // FastifyRouterPlugin이 자동으로 호출합니다.
    this.postService = new PostApplication();
  }
 
  @Get('/', {
    title: '게시글 목록',
    response: PostInfoDto,
  })
  public getPosts = async ({ paging }: FastifyExecuteArgs) => {
    return await this.postService.list(paging);
  };
 
  @Get('/:postId', {
    title: '게시글 상세',
    response: PostInfoDto,
  })
  public getPostById = async ({ path }: FastifyExecuteArgs<{ postId: string }>) => {
    return await this.postService.info(path?.postId);
  };
}

라우트 등록 흐름

FastifyRouterPlugin이 registerFastifyRoutes(fastify)를 호출하면 다음 순서로 동작합니다:

  1. 데코레이터(@Get, @Post, @Put, @Delete)가 누적한 routes 배열을 순회합니다.
  2. 각 라우트의 middleware[] 옵션에 있는 Express 스타일 미들웨어를 adaptMiddlewareToHook으로 Fastify preHandler 훅으로 변환합니다.
  3. Fastify 플러그인 시스템에 prefix: basePath를 적용하여 라우트를 등록합니다.
  4. 각 라우트 핸들러는 FastifyWrapper로 감싸져 FastifyExecuteArgs를 구성하고 에러를 처리합니다.

컨트롤러 등록

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

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

FastifyRouterPlugin은 각 컨트롤러 인스턴스에서 basePath를 읽어 Fastify 플러그인 prefix로 사용하고, registerFastifyRoutes(fastify)를 호출하여 라우트를 등록합니다.

관련 항목

Last updated on
FastifyApplicationFastifyRouterPlugin