설치

사전 요구사항

ASAPJS를 설치하기 전에 환경이 다음 요구사항을 충족하는지 확인하세요:

Node.js 18+ — ASAPJS는 최신 Node.js API를 사용합니다. node --version으로 버전을 확인하세요.
TypeScript 프로젝트 — ASAPJS는 TypeScript로 작성되었으며 TypeScript를 위해 설계되었습니다. 새로 시작하는 경우 yarn init -y && yarn add -D typescript로 프로젝트를 초기화하세요.
데이터베이스 — @asapjs/sequelize는 MySQL, PostgreSQL, MariaDB, MSSQL, SQLite를 지원합니다. 데이터베이스 서버 없이 로컬 개발을 하려면 SQLite를 바로 사용할 수 있습니다.

패키지 설치

프로젝트에 필요한 패키지만 설치하세요. Express 기반 애플리케이션의 경우 @asapjs/core와 @asapjs/router가 필수입니다:


# 핵심 프레임워크 (필수)
yarn add @asapjs/core @asapjs/router
 
# 데이터베이스 통합 (선택사항이지만 대부분의 API에 필요)
yarn add @asapjs/sequelize
 
# 실시간 Socket.io 통합 (선택사항)
yarn add @asapjs/socket

Fastify 어댑터 (선택사항)

Express 대신 Fastify를 사용하려면 @asapjs/fastify를 설치하세요:


# Fastify 기반 서버 (Express 대체)
yarn add @asapjs/fastify

참고: @asapjs/fastify는 @asapjs/router의 대안입니다. 하나의 프로젝트에서 둘 중 하나만 선택하여 사용하세요. Fastify 어댑터는 동일한 데코레이터 기반 개발 방식을 유지하면서 Fastify의 고성능 HTTP 처리를 활용합니다.

피어 의존성으로 reflect-metadata도 필요합니다:


yarn add reflect-metadata

@asapjs/sequelize를 사용할 계획이라면 Sequelize 피어 의존성과 데이터베이스 드라이버를 설치하세요:


yarn add sequelize sequelize-typescript
 
# 데이터베이스 드라이버를 선택하세요:
yarn add mysql2          # MySQL / MariaDB
yarn add pg pg-hstore    # PostgreSQL
yarn add sqlite3         # SQLite (로컬 개발에 적합)

TypeScript 설정

ASAPJS는 TypeScript의 실험적 데코레이터 지원과 메타데이터 리플렉션을 필요로 합니다. 이 두 가지 컴파일러 옵션은 필수입니다 — 없으면 프레임워크가 올바르게 작동하지 않습니다.

tsconfig.json을 열거나 생성하고 compilerOptions 아래에 다음 옵션이 포함되어 있는지 확인하세요:


{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "strictPropertyInitialization": false,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

strictPropertyInitialization: false가 필요한 이유는? ASAPJS 데코레이터는 런타임에 클래스 프로퍼티를 초기화합니다. strictPropertyInitialization이 활성화되면 TypeScript는 데코레이터로 장식된 프로퍼티가 생성자에서 할당되지 않았다고 오류를 발생시킵니다. strict: true를 유지하면서 strictPropertyInitialization: false만 비활성화하면 나머지 타입 안전성은 보존하면서 데코레이터 패턴을 사용할 수 있습니다.

진입점: `reflect-metadata` 임포트

ASAPJS는 런타임에 TypeScript 타입 정보를 검사하기 위해 reflect-metadata를 사용합니다. 진입점 상단에 임포트하세요:


// src/index.ts
import 'reflect-metadata';
 
import { Application } from '@asapjs/core';
// ... 나머지 임포트

참고: @asapjs/sequelize가 내부적으로 reflect-metadata를 임포트하지만, 진입점에 명시적으로 포함하는 것이 안전한 관행입니다.

설정 확인

설정이 올바른지 확인하기 위해 최소한의 src/index.ts를 만드세요:


import 'reflect-metadata';
import { Application } from '@asapjs/core';
import { RouterController, Get, ExecuteArgs } from '@asapjs/router';
 
class HelloController extends RouterController {
  public tag = 'Hello';
  public basePath = '/hello';
 
  constructor() {
    super();
    this.registerRoutes();
  }
 
  @Get('/', { title: 'Hello World' })
  async hello({ }: ExecuteArgs) {
    return { message: 'Hello, ASAPJS!' };
  }
}
 
const config = {
  name: 'my-app',
  port: 3000,
  basePath: 'api',
  extensions: ['@asapjs/router'],
  auth: {
    jwt_access_token_secret: 'dev-secret',
  },
};
 
const app = new Application(__dirname, config);
app.run(() => {
  console.log('Server running at http://localhost:3000/api/hello');
});

다음 명령으로 실행하세요:


npx ts-node src/index.ts

그런 다음 브라우저에서 http://localhost:3000/api/hello를 방문하세요. 다음과 같이 표시되어야 합니다:


{ "message": "Hello, ASAPJS!" }

이것이 작동한다면 설치가 완료된 것입니다. 첫 번째 API로 이동하여 엔티티, DTO, 컨트롤러를 갖춘 전체 도메인을 구축해보세요.

Fastify를 사용하는 경우:

Fastify 기반 애플리케이션은 FastifyApplication과 FastifyRouterController를 사용합니다. 데코레이터 사용법은 Express 버전과 동일합니다.


// src/controller/HelloController.ts
import { FastifyRouterController, Get } from '@asapjs/fastify';
import type { FastifyExecuteArgs } from '@asapjs/fastify';
 
export default class HelloController extends FastifyRouterController {
  public tag = 'Hello';
  public basePath = '/hello';
 
  @Get('/', { title: 'Hello World' })
  async hello({}: FastifyExecuteArgs) {
    return { message: 'Hello, ASAPJS with Fastify!' };
  }
}


// src/route.ts
import HelloController from './controller/HelloController';
export default [new HelloController()];


// src/index.ts
import 'reflect-metadata';
import { FastifyApplication } from '@asapjs/fastify';
 
const config = {
  name: 'my-app',
  port: 3000,
  basePath: 'api',
  extensions: ['@asapjs/fastify'],
};
 
const app = new FastifyApplication(__dirname, config);
app.run(() => {
  console.log('Fastify server running at http://localhost:3000/api/hello');
});

CLI로 빠르게 시작하기: @asapjs/cli를 사용하면 프로젝트 스캐폴딩을 자동화할 수 있습니다. npx @asapjs/cli new my-app 명령으로 tsconfig, 패키지 설치, 기본 디렉토리 구조가 포함된 프로젝트를 즉시 생성할 수 있습니다.

설치