PoC

목차

• Swagger builder 패키지 비교
  • 비교표
  • 기능 비교
    • tsoa
    • swagger-autogen
    • swagger-jsdoc
    • tspec
  • 결론
• Request validate 패키지 비교
  • 비교표
  • 기능 비교
    • class-validator
    • express-validator
    • express-openapi-validator
  • 결론
• Raw Query VS Query Builder VS ORM
  • Raw Query
    • 장점
    • 단점
  • Query Builder
    • 장점
    • 단점
  • ORM (Object-Relation Mapper)
    • 장점
    • 단점
  • 결론
• ORM 패키지 비교
  • 비교표
  • 기능 비교
    • Prisma
    • TypeORM
    • Sequelize
  • 결론

Swagger builder 패키지 비교

비교표

Package	Stars	Open issues	Close issues	Last commit
tsoa	2752	95	816	2023.06.23
swagger-autogen	317	37	153	2023.06.25
swagger-jsdoc	1536	30	150	2023.01.16
tspec	42	0	2	2023.06.21

기능 비교

tsoa

장점

1. TypeScript 기반.
2. 코드로 swagger 를 관리할 수 있어 스웨거 형식을 일정하게 유지가능. (SSOT)
3. 텍스트 형식이 필요한 경우 주석으로 작성 가능.
4. 자세한 예제 코드를 풍부하게 제공.

단점

1. TypeScript 에 관련 설정을 추가해줘야 됨.
2. TypeScript 의 decorator 를 사용하여 기능이 구현되어 있음.(현재 decorator 는 experimental 한 기능)
3. Controller 코드를 tsoa 문법에 맞게 변경해야 함.

예시 코드

import { Get, Route } from "tsoa";

interface PingResponse {
  message: string;
}

@Route("ping")
export default class PingController {
  @Get("/")
  public async getMessage(): Promise<PingResponse> {
    return {
      message: "pong",
    };
  }
}

swagger-autogen

장점

1. Controller 의 경로들과 주석을 읽어 자동으로 통합된 파일을 완성.

단점

1. 주석으로 swagger 를 관리하기 때문에 수정 시 일일이 확인해서 반영해야 됨.

예시 코드

app.post('/users', (req, res) => {
	...
	/*  #swagger.parameters['obj'] = {
			in: 'body',
			description: 'Add a user',
			schema: { $ref: '#/definitions/AddUser' }
	} */
	...
})

swagger-jsdoc

장점

1. 단순한 기능을 지원하기 때문에 설정이 편함.

단점

1. YAML 파일로 작성된 파일들을 읽어 하나의 파일로 통합하는 기능만을 포함.
2. 주석으로 swagger 를 관리하기 때문에 수정 시 일일이 확인해서 반영해야 됨.

예시 코드

/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

tspec

장점

1. TypeScript 기반.
2. 코드로 swagger 를 관리할 수 있어 스웨거 형식을 일정하게 유지가능. (SSOT).
3. 자세한 예제 코드를 풍부하게 제공.

단점

1. 출시한지 얼마되지 않아 예상치 못한 문제가 발생할 수 있음.
2. Open API Spec 을 위한 타입과 handler 함수의 타입 간 싱크를 맞춰야 됨.

예시 코드

interface Greeting {
  message: string;
}

type GreetingApiSpec = Tspec.DefineApiSpec<{
  basePath: '/api/v1/dev';
  paths: {
    '/greeting': {
      post: {
        summary: 'Greeting';
        requestBody: Greeting;
        responses: {
          201: Greeting;
        };
      };
    };
  };
}>;

결론

Controller 의 형태를 전혀 제한하지 않아 가장 유연하게 사용할 수 있고 SSoT 를 지킬 수 있다는 장점으로 tspec을 사용하기로 결정. 단점으로 꼽았던 출시된지 얼마되지 않아 문제가 생길 수 있다는 점은 계속해서 추이를 지켜봐야할 필요가 있음. 이외로 Open API Spec 을 위한 타입과 handler 함수의 타입 간 싱크를 맞춰야 하는 부분이 있지만 장점에 비해 큰 단점이라 판단하지 않았음.

Request validate 패키지 비교

비교표

Package	Stars	Open issues	Closed issues	Last commit
class-validator	9.6k	204	711	2023.07.14
express-validator	5.6k	46	813	2023.07.15
express-openapi-validator	781	131	250	2023.05.01

기능 비교

class-validator

특징

• Class 에 decorator 를 적용하여 각 propertry 들을 validate 하는 패키지

장점

1. 각 필드에 대해 정밀한 validation 내용들을 작성할 수 있다. (자세한 내용)

단점

1. 기능 구현이 class 를 베이스로 이루어져 있기 때문에 plain object 에 적용하기 위해서는 별도의 class instantiate 하는 과정을 거쳐야 한다.
2. 각 필드마다 검증할 내용들을 데코레이터로 작성해야하기 때문에 작성해야될 코드가 많다.
3. 1의 내용대로 class instantiate 하는 과정이 필수이기에 target class 를 알아야 검증할 수 있다. 따라서 요청의 타입 정보를 알고있는 handler 수 만큼의 validate 함수 호출 코드 중복이 발생할 수 있다.

예시 코드

import {
  validate,
  validateOrReject,
  Contains,
  IsInt,
  Length,
  IsEmail,
  IsFQDN,
  IsDate,
  Min,
  Max,
} from 'class-validator';

export class Post {
  @Length(10, 20)
  title: string;

  @Contains('hello')
  text: string;

  @IsInt()
  @Min(0)
  @Max(10)
  rating: number;

  @IsEmail()
  email: string;

  @IsFQDN()
  site: string;

  @IsDate()
  createDate: Date;
}

let post = new Post();
post.title = 'Hello'; // should not pass
post.text = 'this is a great post about hell world'; // should not pass
post.rating = 11; // should not pass
post.email = 'google.com'; // should not pass
post.site = 'googlecom'; // should not pass

validate(post).then(errors => {
  // errors is an array of validation errors
  if (errors.length > 0) {
    console.log('validation failed. errors: ', errors);
  } else {
    console.log('validation succeed');
  }
});

validateOrReject(post).catch(errors => {
  console.log('Promise rejected (validation failed). Errors: ', errors);
});
// or
async function validateOrRejectExample(input) {
  try {
    await validateOrReject(input);
  } catch (errors) {
    console.log('Caught promise rejection (validation failed). Errors: ', errors);
  }
}

express-validator

특징

• 미리 정의된 express 의 middleware 들을 사용하여 request 를 validate 및 sanitize 하는 패키지

장점

1. Validation chain 을 활용하여 검증과 내용의 정제를 원하는 순서대로 구성할 수 있다.

단점

1. Validation chain 을 재사용할때 버그가 발생할 수 있다.(참고 )
2. 1의 버그를 막기 위해서는 매번 같은 검증 코드를 작성해야 한다.

예시 코드

import * as express from 'express';
import { query, validationResult } from 'express-validator';
const app = express();

app.use(express.json());
app.get('/hello', query('person').notEmpty(), (req, res) => {
  const result = validationResult(req);
  if (result.isEmpty()) {
    return res.send(`Hello, ${req.query.person}!`);
  }

  res.send({ errors: result.array() });
});

app.listen(3000);

express-openapi-validator

특징

• OAS(OpenAPI Specification) 에 명시된 내용을 통해서 request 및 response 를 validation 하는 패키지

장점

1. OAS 의 schema 내용을 보고 validate 하고 대부분의 타입들은 기본적으로 지원하기 때문에 작성해야될 코드의 양이 적음.(미리 정의된 middleware 를 적용하기만 하면 됨)
2. 풍부한 에러 내용 제공 (status code 포함)

단점

1. 패키지의 에러 형태를 서버에서 이해할 수 있게 가공하는 작업이 필요함.
2. 문서 내용에서 부족한 내용이 일부 보임.

예시 코드

const express = require('express');
const path = require('path');
const http = require('http');
const app = express();

// 1. Import the express-openapi-validator library
const OpenApiValidator = require('express-openapi-validator');

// 2. Set up body parsers for the request body types you expect
//    Must be specified prior to endpoints in 5.
app.use(express.json());
app.use(express.text());
app.use(express.urlencoded({ extended: false }));

// 3. (optionally) Serve the OpenAPI spec
const spec = path.join(__dirname, 'api.yaml');
app.use('/spec', express.static(spec));

// 4. Install the OpenApiValidator onto your express app
app.use(
  OpenApiValidator.middleware({
    apiSpec: './api.yaml',
    validateResponses: true, // <-- to validate responses
  }),
);

// 5. Define routes using Express
app.get('/v1/pets', function (req, res, next) {
  res.json([
    { id: 1, type: 'cat', name: 'max' },
    { id: 2, type: 'cat', name: 'mini' },
  ]);
});

// 6. Create an Express error handler
app.use((err, req, res, next) => {
  // 7. Customize errors
  console.error(err); // dump error to console for debug
  res.status(err.status || 500).json({
    message: err.message,
    errors: err.errors,
  });
});

http.createServer(app).listen(3000);

결론

신뢰성의 측면에서 star 수 , open / close issue 의 비율등의 수치는 class-validator 와 express-validator 가 좋은 면이 있음. 하지만, 매번 같은 내용의 코드를 작성해야 하고 패키지의 기능 구현 방식으로 인한 고정적인 구조(i.e validate 를 위해서는 class instance 하는 과정이 포함되어야 한다든지)는 사용성에 큰 제약이 있음. 따라서, 패키지의 신뢰성은 떨어지더라도 사용하기에는 보다 더 깔끔한 구조를 가지고 있는 express-openapi-validator 를 사용하기로 결정. 다만, 신뢰성이 떨어지는 패키지이기 때문에 충분한 테스트 및 repo 에 올라온 이슈 내용들을 확인할 필요가 있음.

Raw Query VS Query Builder VS ORM

Raw Query

장점

1. 질의를 작성하고 관리하는 것을 명시적으로 할 수 있다.
2. 추상화를 통해 구현된 다른 tool 들보다 성능이 좋을 수 있다.
3. 유연성이 좋다. 직접 질의를 작성하는게 유연성이 다른 어떤 추상화가 적용된 tool 들보다 좋을 수 없다.

단점

1. 가파른 러닝 커브. 의도했던 대로 제대로 다루기 위해서는 데이터베이스의 구조와 SQL 에 대해서 알아야 하는게 많다.
2. SQL injection 과 같은 문제를 막기 위해 입력을 정화하는 로직을 만들어 적용해야 한다. 직접 구현해야 하기 때문에 시간과 실수로 인한 치명적인 보안에 대한 결점이 생길 수 있다.
3. 일반 문자열로 관리가 되기 때문에 여러 계층의 데이터들과 섞이며 조작하기 복잡해질 수 있다.

Query Builder

장점

1. 문자열이 아닌 프로그래밍 언어의 메소드나 함수로 구현되기 때문에 raw query 보다는 장기적으로 관리하기 편한다.
2. Raw query 보다는 아니더라도 실제 만들어지는 질의의 내용이 꽤 투명하다. 기능상으로 실제 질의를 보여주는 경우도 있고 그게 아니더라도 연산이 어떤 작업을 수행할지 쉽게 이해가 가능하다.
3. Query builder 는 여러가지 관계형 DBMS 를 추상화를 통해 지원하기 때문에 다른 DBMS 로 마이그레이션할때, 도움을 받을 수 있다.

단점

1. Raw query 를 사용할때와 마찬가지로 DB 의 구조와 기능에 대해 학습하는 것이 필요하다. 그뿐만아니라 query builder 가 어떻게 동작할지에 대해서도 추가적으로 학습을 해야한다.
2. Query builder 는 DB 의 데이터와 어플리케이션의 데이터가 어떻게 매핑되는지 정의해야 한다.

ORM (Object-Relation Mapper)

장점

1. 추상화를 통하여 현재의 작업의 연장에서 데이터 시스템에 접근하고 조작하는 것에 도움을 준다.
2. DB 와의 데이터 송수신에 필요한 많은 boilerplate 가 필요 없어지게 된다. ORM 에는 migration tool 이 포함된 경우도 있기 때문에, 개발자가 schema 변경점을 완벽히 찾아 DB 에 적용할 필요없이 DB 의 구조 변경에 도움을 준다.

단점

1. 높은 정도의 추상화 때문에 ORM 은 DB backend 의 디테일한 사항들을 숨겨버린다. 간단한 경우나 작은 규모의 작업에서는 ORM 을 더 쉽게 사용하게 해주지만, 복잡성이 커질수록 문제가 발생한다.
2. ORM 과 질의 언어에 대한 이해없이 사용하게 되면 문제적 상황들을 초래하게 된다. 디버깅과 성능에서는 문제를 일으킬 수 있다.
3. Object 와 Relation 의 패러다임의 차이에서 오는 불일치로 간단한 질의도 점점 복잡해질 우려가 있다.

결론

ORM 을 사용하기로 결정

1. Raw query/query builder 를 사용할 경우, object-relation 맵핑을 직접 구현해야 한다. 각 질의에 대해서 타입을 작성하고 맵핑하는 부분까지 구현하게 된다면, 전체 프로젝트 진행속도가 지금보다 더뎌질 것이 우려된다.
2. ORM 의 가장 큰 단점인 object-relation 을 맵핑하는 과정에서 복잡성이 늘어나 성능 및 디버깅에 악영향을 줄 수 있다는 점인데, 현재 우리 프로젝트에서는 테이블의 수도 적고 복잡한 질의를 사용할만한 기능도 없기에 큰 영향은 없을 것 같다.

따라서 위의 이유들로 ORM 을 사용하기로 결정!

ORM 패키지 비교

비교표

Package	Stars	Open issues	Close issues	Last commit
Prisma	33.5k	2731	6265	2023.08.30
TypeORM	32k	2052	5594	2023.08.20
Sequelize	28.3k	782	9351	2023.08.30

기능 비교

Prisma

특징

• 비교적 최근에 출시된 DB toolkit
• Prisma schema로 모델을 선언하며, 선언적 데이터 모델 정의와 마이그레이션을 지원
• Prisma Client: Prisma schema를 기반으로 타입 안정한 쿼리 빌더 제공
• Prisma Migrate: Prisma schema 기반의 마이그레이션 시스템
• Prisma Studio: 데이터베이스를 직접 조작하고 볼 수 있는 GUI 도구

장점

• 데이터 생성 및 조회에 강력한 타입 안정성을 보장 (중첩된 데이터 생성 및 조회 포함)
• 다양한 데이터베이스 지원 (PostgreSQL, MySQL, MSSQL 등)
• SSoT(Single source of truth)을 보장하기 위해 Prisma schema 기반으로 타입 정보 생성
• 새로운 기능 및 업데이트가 지속적으로 이루어짐

단점

• 다른 ORM으로 마이그레이션하기 어려울 수 있음 (자체 스키마 형식 사용)
• 패키지 크기가 크고 고급 기능이 부족할 수 있음

예시 코드

// schema.prisma
model UserModel {
  id    BigInt @id @default(autoincrement())
  name  String @db.VarChar(64)
  email String @db.VarChar(64)
}

// user.repository.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

const user = await prisma.user.create({
    data: {
        name: 'John Doe',
        email: '[email protected]',
    },
});

TypeORM

특징

• Hibernate 영향을 받은 TypeScript 기반의 ORM
• Active Record 및 Data Mapper 패턴 지원

장점

• 데이터 생성에 대한 타입 안정성 보장 (중첩된 데이터 생성 포함)
• 다양한 데이터베이스 지원 (MySQL, PostgreSQL, SQLite 등)
• Active Record 및 Data Mapper 패턴 모두 지원하여 유연한 개발 가능

단점

• 데이터 조회에 대한 타입 안정성은 부분적 (중첩된 데이터 조회에 추가 작업 필요)
• 초기 학습 곡선이 가파름
• 설정이 복잡할 수 있음

예시 코드

// user.entity.ts
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    name: string;

    @Column()
    email: string;
}

// user.repository.ts
const firstUser = await conn
    .getRepository(User)
    .createQueryBuilder("user")
    .where("user.id = :id", { id: 1 })
    .getOne();

Sequelize

특징

• Promise 기반 Node.js ORM
• Active Record 패턴 지원
• 다양한 데이터베이스 지원 (PostgreSQL, MySQL, SQLite 등)

장점

• 다양한 데이터베이스 지원
• 기존에 많이 사용되고 있는 패키지로 레퍼런스가 풍부

단점

• 데이터 생성 및 조회 모두 타입 안정성 부족
• 프로젝트 진행이 둔화되어 개발이 제대로 되고 있지 않음

예시 코드

const { Sequelize, Model, DataTypes } = require('sequelize');

const sequelize = new Sequelize('database', 'username', 'password', {
  dialect: 'mysql',
});

class User extends Model {}
User.init({
  name: DataTypes.STRING,
  email: DataTypes.STRING,
}, {
  sequelize,
  modelName: 'user',
});

User.hasMany(Photo);
Photo.belongsTo(User);

(async () => {
  await sequelize.sync({ force: true });
  const user = await User.create({
    name: 'John Doe',
    email: '[email protected]',
  });
  const photo = await user.createPhoto({
    url: 'example.com/photo.jpg',
  });
})();

결론

세 가지 패키지를 비교해보면, Prisma가 데이터 생성과 조회 모두에 강력한 타입 안정성을 제공하며, SSoT를 유지하면서 다양한 데이터베이스 지원과 지속적인 업데이트로 인해 가장 좋은 선택이 될 것으로 판단.