🐡

NestJSについて軽く調べてまとめた

2023/03/12に公開

TypeScript

NestJS

tech

特徴

TypeScriptで開発されたバックエンドのフレームワーク。デフォルトでTypeScriptをサポート
デフォルトでExpressを活用。Fastifyも活用できる
Expressのミドルウェアをそのまま転用できる
OOP(オブジェクト指向プログラミング)、FP(関数型プログラミング)、FRP(関数型リアクティブプログラミング)の要素をフル活用できる
DIコンテナをデフォルトで活用できる
テストが簡単で疎結合であり、スケーラブル。専用のテストフレームワークが用意されている
モジュール構造により、プロジェクトを個別のブロックに分割できる。これによって、プロジェクト内で外部のライブラリを簡単に活用できる
すぐに利用を開始できるCLIツールがある。コマンド一つで開発に必要な雛形を簡単に作れる
マイクロサービスを開発しやすい
GraphQLとREST APIの開発を両方ともサポートしている
拡張性が高い
- TypeORM、Mongoose、GraphQL、Logging、Validation、Caching、WebSocketsなどNest固有のモジュールのサポートを提供

基本的な概念

軽く紹介

Controllers
Providers
Modules
Middleware
Exception filters
Pipes
Guards
Interceptors

Controllers、Providers、Modules は、クライアントからのリクエストに対するルーティングやビジネスロジック、それらをまとめる機能を提供

Controllers

送られてくるリクエストを処理してレスポンスをクライアントに返す枠割を担ってる
Controllerの目的は、アプリケーション内の特定のリクエストを受け取ることで、ルーティングはどのControllerがどのリクエストを受信するのかを制御している

import { Body, Controller, Delete, Get, Param, ParseUUIDPipe, Patch, Post } from '@nestjs/common';
import { Item } from './item.model';
import { ItemsService } from './items.service';
import { CreateItemDto } from './dto/create-item.dto';

@Controller('items')
export class ItemsController {
  constructor(private readonly itemsService: ItemsService) {}

  @Get()
  findAll(): Item[] {
    return this.itemsService.findAll();
  }

  @Get(':id')
  findById(@Param('id', ParseUUIDPipe) id: string): Item {
    return this.itemsService.findById(id);
  }

  @Post()
  create(@Body() createItemDto: CreateItemDto): Item {
    return this.itemsService.create(createItemDto);
  }

  @Patch(':id')
  updateStatus(@Param('id', ParseUUIDPipe) id: string): Item {
    return this.itemsService.updateStatus(id);
  }

  @Delete(':id')
  delete(@Param('id', ParseUUIDPipe) id: string) {
    return this.itemsService.delete(id);
  }
}

Providers

NestJSの基本的なクラスの多くはProviderとして扱われることが多い。
Providerの基本的な考えは依存関係として注入できること。言い換えるとオブジェクトはお互いに様々な関係を作れる。
Controllerから複雑なタスクを依頼される

ビジネスロジックを定義するサービスクラスとか

import { Injectable, NotFoundException } from '@nestjs/common';
import { ItemStatus } from './item-status.enum';
import { Item } from './item.model';
import { CreateItemDto } from './dto/create-item.dto';
import { v4 as uuid } from 'uuid';

@Injectable()
export class ItemsService {
  private items: Item[] = [];

  findAll() {
    return this.items;
  }

  findById(id: string): Item {
    const found = this.items.find((item) => item.id === id);
    if (!found) {
      // スタンダード
      // throw new HttpException(
      //   { reason: 'this can be a human readable reason' },
      //   HttpStatus.BAD_REQUEST,
      // );

      // HttpExceptionを継承している用意されてるやつ
      throw new NotFoundException();
    }
    return found;
  }

  create(createItemDto: CreateItemDto) {
    const item: Item = {
      id: uuid(),
      ...createItemDto,
      status: ItemStatus.ON_SALE,
    };

    this.items.push(item);
    return item;
  }

  updateStatus(id: string): Item {
    const item = this.findById(id);
    item.status = ItemStatus.SOLD_OUT;
    return item;
  }

  delete(id: string): void {
    this.items = this.items.filter((item) => item.id !== id);
  }
}

Modules

@Module()デコレータでアノテーションされたクラスを意味する。@Module()デコレータは、NestJSがアプリケーションの構造を整理するために利用するメタデータを提供。
以下の要素から構成される:

providers: Nest injector によりインスタンス化される Provider で、Module 内でシェアされる
controllers: Module で定義される Controller
imports: Module で使用する Provider をエクスポートしている他の Module
exports: Module からエクスポートされる Provider で、Module の public interface といえる

少なくとも一つのModule(Root module) を必要とし、これと他のインポートされたModuleの連鎖であるapplication graph によって構成される
特定の役割に応じて一つの Module が構成されるべきである(1機能1Module)

import { Module } from '@nestjs/common';
import { ItemsController } from './items.controller';
import { ItemsService } from './items.service';

@Module({
  controllers: [ItemsController], // Controller の登録
  providers: [ItemsService], // Service の登録
exports: [ItemsService], // エクスポートする Provider の登録
})
export class ItemsModule {}

pipe

ハンドラーがリクエストを受け取る前にリクエストに対して処理を行う
データの変換とバリデーションが可能
処理を行なった後のデータをハンドラーに渡す
Pipeの処理中に例外を返すことも可能

組み込むのPipeが用意されている

ValidationPipe
ParseIntPipe
ParseBoolPipe
ParseArrayPipe
ParseUUIDPipe
DefaultValuePipe

1.ハンドラに適用
2.パラメータごとに適用
3.グローバルに適用

@Get(':id')
findById(@Param('id', ParseUUIDPipe) id: string): Item {
  return this.itemsService.findById(id);
}

カスタムのパイプも割と簡単に作れそう

DTO

NestJSのDTOはRequestPayload(body)の型定義を行うためのもの
一般的な DAO/DTO の文脈とは少し違った印象を受けるイメージ
型定義と同時にバリデーションまで含むことができる

class-validator および class-transformer パッケージを利用することでDTO定義の中でバリデーションできる
Controller に処理が渡ってくる時点で正しいデータであることが保証される

import { Type } from 'class-transformer';
import { IsInt, IsNotEmpty, IsString, MaxLength, Min } from 'class-validator';

export class CreateItemDto {
  @IsString()
  @IsNotEmpty()
  @MaxLength(40)
  name: string;

  @IsInt()
  @Min(1)
  @Type(() => Number)
  price: number;

  @IsString()
  @IsNotEmpty()
  description: string;
}

Exception filters

未処理のすべての例外を処理できる例外フィルタがデフォルトで組み込まれている
アプリのコードで処理されない例外が発生した場合、このフィルタが例外をキャッチしてレスポンスを自動送信してくれる

組み込みで色々な例外が用意されている

例外フィルタを完全に制御したい場合もある
下記はHttpExceptionクラスのインスタンスである例外をキャッチし、その例外に対するカスタムのレスポンスのロジックを実装するための例外フィルタ

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';
 
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();
 
    response
      .status(status)
      .json({
        statusCode: status,
        timestamp: new Date().toISOString(),
        path: request.url,
      });
  }
}

使うときはコントローラーで下記のようにする
Exception filters は、メソッドのレベル、コントローラのレベル、グローバルなレベルで使用することができる

@Post()
@UseFilters(HttpExceptionFilter) // Exception filter を登録
async create(@Body() createCatDto: CreateCatDto) {
  // ...
}

Guards

ガードが持つ責任は一つ。ランタイムに存在する特定の条件（パーミッション、ロール、ACL等）に依存して、与えられたリクエストがルートハンドラによって処理されるかどうかを決定する事.。これは認可と呼ばれる。

認可に使用するGuard
特定のルートは呼び出し側（通常は特定の認証済みユーザー）が十分なパーミッションを持っている場合にのみ利用可能であるべき。
下記のAuthGuardは、認証されたユーザーを想定している(リクエストヘッダにトークンが添付されていることを想定)。トークンを抽出して検証し、抽出された情報を使ってリクエストを続行できるかどうかを決定。

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

trueを返す場合は、リクエストがそのまま進行されます。
falseを返す場合は、リクエストを拒否します。

Interceptors

以下のことなどが可能:

メソッドの実行の前後において追加のロジックをバインドする
関数の返り値を変換する
関数から送出された例外を変換する
関数の振る舞いを拡張する
(たとえばキャッシュを目的として) 特定の条件に応じて関数をオーバーライドする

インターセプターを使用してユーザとのやり取りを記録する場合です。シンプルなLoggingInterceptorの例

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log('Before...');

    const now = Date.now();
    return next
      .handle()
      .pipe(
        tap(() => console.log(`After... ${Date.now() - now}ms`)),
      );
  }
}

バインドする

@UseInterceptors(LoggingInterceptor)
export class CatsController {}

※GuardsとInterceptorsはまだしっかり触れてません

メリット

DIコンテナをデフォルトで活用できる

あまり意識せずにDIの実装できる
NestJSを使うことで自然と依存関係を意識したコートが作れそう
テストがしやすい

OpinionatedArchitecture(こだわりの強いアーキテクチャ)

Diを前提としたServiceとそれを利用するProvider / Module
自然とレイヤとユースケースについて考慮されるようになる
他のフレームワークにあるが本質的でないものは無関心でコアにRDBやNoSQLへの機能は存在しない(追加はできる)
必要なものを選択するだけで、自然とNestらしくなる利点がある

「convention over configuration」というパラダイムを採用していて開発者が考えることを減らそうとしてる
逆にExpressはシンプルで自由度が高い分、自分達で責任を持って設計しないと大変

豊富なエコシステム

NestJSにはコアにはないがオフィシャルのパッケージがたくさんある
- TypeORM,Sequalize / Mongoose
- GraphQL, grpc
- OpenAPI

Expressの知見も活かせる

ExpressがベースなのでNestが用意していない機能が必要になった場合は、Expressのmiddlewareの知見が活かせる
- Fastifyを選ぶとFastifyのライブラリが充実していなかったりもするらしい

DXの観点

好み分かれるかもだがデコレータで色々指定できるのは楽だった
- コード量は減るが増えると煩雑になりそう。
ExceptionFiltersやDTO,Pipesといった機能を使用してのバリデーションが便利だった
Interceptors,Guardsはまだ触れてないが認証部分はGuardsを使用するといい感じに実装できる
Nest　CLIでファイル作成とかできる

デメリット・不安点

Expressのような柔軟性がない。ディレクトリの構造がファイル単位で予め決まっているので、自由なアーキテクチャでの開発には向かないかも
Rails、LaravelやDjangoと比較してユーザが少なく、情報量も少ない
日本語での情報がちょい少ない
AngularやTypeScriptに慣れていれば習得はそこまで難しくないが、慣れていない場合は学習コストが多少かかるかも
階層化を重ねるとディレクトリの構造が複雑になり、Moduleの依存関係を把握しづらくなる
デコレータの設定が煩雑