Scheme#

今回は以下のように scheme.prisma ファイルを定義しました。previewFeatures = ["interactiveTransactions"]を追記していますが、これはデータベースのロールバックするときに使います。

Prisma2 での transaction を ActiveRecord 風に書きたい問題で詳しく解説されているので、こちらを読むと幸せになれます。

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["interactiveTransactions"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  username  String
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt()
}

model Post {
  id        Int      @id @default(autoincrement())
  text      String
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt()
}

で、このモデルで定義されたデータに対して Prisma Client を使って Typescript からデータを操作したいというのが今回の目標になります。

Prisma Service#

prisma.service.tsというファイルをmain.tsと同じところに作成します。何も考えずコピペで OK です。

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
import { PrismaClient } from "@prisma/client";

@Injectable()
export class PrismaService
  extends PrismaClient
  implements OnModuleInit, OnModuleDestroy
{
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

app.module.ts#

次に app.module.ts にPrismaServiceを追記します。

これをしておかないと NestJS がエラーを吐きます。

import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { PrismaService } from "./prisma.service";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService, PrismaService],
})
export class AppModule {}

users.controller.ts#

以下のようなものを書きます。

コントローラに全ての処理を書いていると長くなりすぎるので、実際の処理の内容はUsersServiceに丸投げする感じです。

import { Controller, Get, Post } from "@nestjs/common";
import { UsersService } from "./users.service";

@Controller("users")
export class UsersController {
  constructor(private readonly service: UsersService) {}

  @Get()
  findAll() {
    this.service.findAll();
  }

  @Post()
  create() {
    this.service.create();
  }
}

簡単に解説しておくとlocalhost:3000/usersにアクセスされたときの処理がここに定義されています。GET リクエストがくるとfindAll()が実行されるイメージです。

users.service.ts#

実際に処理を書くのがこのファイルです。

データベースにアクセスしてデータをあれこれするのでPrismaServiceをインポートしておきましょう。

import { Injectable } from "@nestjs/common";
import { PrismaService } from "src/prisma.service";

@Injectable()
export class UsersService {
  constructor(private readonly prisma: PrismaService) {}

  findAll() {}

  create() {}
}

これで全ての準備は完了です。

あとはやりたいことをfindAll()とcreate()に書いていくだけになります。

リクエストで受け取るデータ#

API 側がデータを受け取るには主にパスパラータ、クエリパラメータ、ボディパラメータの三つがある。他にはヘッダーで受け取るなどがあるが、ここでは考えないこととする。

これらは NestJS ではそれぞれ次の属性に対応している。いつも@Paramをクエリパラメータだと勘違いしてしまうが、これはパスパラメータなので注意すること。

• @Param
  • パスパラメータ
• @Query
  • フォームパラメータ
• @Body
  • JSON データ、GET では扱えない

@Get(':id')
findOne(@Param('id') id: number) {
  console.log(typeof id === 'number'); // false
  return 'This action returns a user';
}

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  console.log(typeof id === 'number'); // true
  return 'This action returns a user';
}

バリデーション#

返すデータはデータベースに突っ込まれている以上、常に整合性が取れているのだが、リクエストの正当性をチェックしなければいけない。

例えば、ユーザ ID が整数型だとすれば入力として整数値以外が入っていた場合は自動的にエラーを返してほしいわけである。

なお、執筆にあたりValidationの項目を参考にした。いや、ホント公式ドキュメントが参考になります。

// users.controller.ts
@Get(':id')
find(@Param() request: FindUserDto): Promise<UserModel> {
  return this.service.find(request.id);
}

import { ApiProperty } from "@nestjs/swagger";
import { Expose, Transform } from "class-transformer";
import { IsInt, IsNumberString, Min } from "class-validator";

export class FindUserDto {
  @Expose() // 変換した値をそのまま利用する
  @Transform((params) => parseInt(params.value, 10)) // 入力された値を10進数整数値に変換する
  @IsInt() // 整数値以外は許可しない
  @Min(1) // 最小値は1
  @ApiProperty() // これを忘れるとSwaggerに表示されない
  id: number;
}

@Get(':id')
find(@Param('id', ParseIntPipe) id: number): Promise<UserModel> {
  return this.service.find(id);
}

{
  "statusCode": 400,
  "message": "Validation failed (numeric string is expected)",
  "error": "Bad Request"
}

バージョン管理タイプ#

Versioningを読んで得られた知見をまとめる。めんどくさいので全部ではなく、自分が利用できそうだと思ったところをメインに書いていく。

• URI
• ヘッダー
• メディアタイプ
• カスタム

の四種類でバージョン管理ができる。ヘッダーというのは指定されたヘッダーのキーにバージョンの値を入れておいて、それで分岐する感じである。これを利用しているのがスプラトゥーン 2 で採用されている X-Product Version に該当する。

個人的にはよく使われているのは URI バージョニングの気がしている。これは単にエンドポイントに対してv1やv2といったパスが追加される感じである。

今回はこれを利用することにした。

設定方法#

やることは簡単でmain.tsに追記する。

// main.ts
app.enableVersioning({
  type: VersioningType.URI,
});

これだけでバージョン管理システムは有効化されている。

// users.controller.ts
@Controller({ path: 'users', version: '1' })

どのバージョンを利用するかはコントローラに設定すれば良い。なお、エンドポイントごとにバージョンを分けることもできる。その場合は以下のように記述する。

import { Controller, Get, Version } from "@nestjs/common";

@Controller()
export class CatsController {
  @Version("1")
  @Get("cats")
  findAllV1() {
    return "This action returns all cats for version 1";
  }

  @Version("2")
  @Get("cats")
  findAllV2() {
    return "This action returns all cats for version 2";
  }
}

その他、複数のバージョニングや、デフォルト値などの設定もあるのでこの辺をしっかりと読んでおくように。

該当するカラムがないときに 404 を返す#

必要そうになりそうなエラー処理として、まずこれが考えられる。

// users.service.ts
find(id: number): Promise<UserModel> {
  return this.prisma.user.findUnique({
    where: { id: Number(id) },
  });
}

ユーザの検索は上のようなコードで実行しているのだが、検索結果が 0 だったときにはエラーを返したいわけである。

で、返すためのエラーはあらかじめいろいろ定義されているのでBuilt-in HTTP exceptionsを読んでおこう。

ちなみに、今回のような場合は以下のコードで実装できる。

find(id: number): Promise<UserModel> {
  return this.prisma.user
    .findUnique({
      where: { id: id },
    })
    .then((user) => {
      if (user === null) {
        throw new NotFoundException();
      }
      return user;
    });
}

async find(id: number): Promise<UserModel> {
  return this.prisma.user
    .findUnique({
      where: { id: id },
      rejectOnNotFound: true,
    })
    .then((user) => {
      return user;
    })
    .catch((error) => {
      throw new NotFoundException();
    });
}

async update(id: number, published: Prisma.UserUpdateInput): Promise<UserModel> {
  return this.prisma.user
    .update({
      where: { id: id },
      published: {
        username: data.username,
      },
    })
    .then((user) => {
      return user;
    })
    .catch((error) => {
      const message = (error as PrismaClientKnownRequestError).meta.cause;
      throw new HttpException(message, HttpStatus.NOT_FOUND);
    });
}

@Put('publish/:id')
async togglePublishPost(@Param('id') id: string): Promise<PostModel> {
  const postData = await this.prismaService.post.findUnique({
    where: { id: Number(id) },
    select: {
      published: true,
    },
  })

  return this.prismaService.post.update({
    where: { id: Number(id) || undefined },
    published: { published: !postData?.published },
  })
}

async update(id: number, published: Prisma.UserUpdateInput): Promise<UserModel> {
  return this.prisma.user
    .findUnique({
      where: { id: id },
    })
    .then((user) => {
      if (user === null) {
        throw new NotFoundException();
      }
      return this.prisma.user.update({
        where: { id: id },
        published: {
          username: data.username,
        },
      });
    });
}

ページネーション#

ページネーションはカラム数が多い場合にサーバへの負荷を考えて結果を分割して返す仕組みである。

返し方はいろいろあるのだが、prevやnextを利用するものがデータベースを全件走査しないだけ負荷が低い。何故ならoffset方式の場合は全部で何件データがあるかを予め返す必要があるからだ。

が、よほどデータが多くない限りoffset方式でも問題がないと思われる。実際、NestJS のドキュメントではこの方式のコードが書かれている。では、実際にそのコードを紐解いてみよう。

import { applyDecorators, Type } from "@nestjs/common";
import { ApiOkResponse, ApiProperty, getSchemaPath } from "@nestjs/swagger";
import { Expose, Transform } from "class-transformer";
import { IsInt, Max, Min } from "class-validator";

export class PaginatedResponseDto<TData> {
  @Expose()
  @Transform((params) => {
    parseInt(params.value, 10);
  })
  @IsInt()
  @ApiProperty({ type: "integer" })
  total: number;

  @Expose()
  @Transform((params) => {
    parseInt(params.value, 10);
  })
  @IsInt()
  @Max(50)
  @Min(0)
  @ApiProperty({ type: "integer", minimum: 0, maximum: 50 })
  limit: number;

  @Expose()
  @Transform((params) => {
    parseInt(params.value, 10);
  })
  @IsInt()
  @ApiProperty({ type: "integer" })
  offset: number;

  results: TData[];
}

export const ApiPaginatedResponse = <TModel extends Type<any>>(
  model: TModel
) => {
  return applyDecorators(
    ApiOkResponse({
      schema: {
        allOf: [
          { $ref: getSchemaPath(PaginatedResponseDto) },
          {
            properties: {
              results: {
                type: "array",
                items: { $ref: getSchemaPath(model) },
              },
            },
          },
        ],
      },
    })
  );
};

少々長いが、上のようなコードをどこかに定義する。ただ、このままではPaginatedResponseDtoが Swagger に正しく反映されないので、

findUnique#

ID またはユニーク属性があるフィールドで検索を行う

findFirst#

データベースで最初に合致したレコードを返す。

findMany#

データベースで合致するレコードの配列を返す。何もしないと全件返ってくるので注意。

create#

新しいレコードを作成する。Nested create をした場合は全てのレコードが同時に作成される。

createMany#

一つのトランザクションで複数のレコードを作成する。

updateMany#

一つのトランザクションで複数のレコードを更新する。

where で合致したレコードの中身を data で置き換える。

deleteMany#

いっぱい消す、以上。

count#

条件に合致するレコードの件数を返す。

null が入っているレコードもカウントされてしまうので、あるフィールドに null が入っているものを除外したい場合には select を使うこと。

aggregate#

集約、概要、グループ、そしてよくわからん。まあ多分集約関数のようなもの。

groupBy#

ドキュメント

select#

include#

where#

orderBy#

distinct#

create#

階層クエリはあるレコードを追加するときに別のレコードも同時に追加するようなときに使われる。例えば User モデル作成時に、そのユーザのプロフィールを Profile モデルとして作成するような場合である。

const user = await prisma.user.create({
  published: {
    username: "tkgling",
    profile: {
      create: { commnet: "Hello World" },
    },
  },
});

これは例えば上のようなコードで実装される。逆にプロフィール実装時にユーザを追加することもできる。

const user = await prisma.profile.create({
  published: {
    comment: 'Hello World',
    user: {
|     create: { username: 'tkgling' },
    },
  },
})

また、複数のレコードを一度に作成することもできる。

const user = await prisma.user.create({
  published: {
    username: "tkgling",
    posts: {
      create: [
        {
          title: "This is my first post",
        },
        {
          title: "This is my second post",
        },
      ],
    },
  },
});

このとき、なんで createMany ではないのかが気になったりする。

const user = await prisma.user.update({
  where: { username: "tkgling" },
  published: {
    profile: {
      create: { comment: "Hello World" },
    },
  },
});

こういうコードも書けるらしいが、これがどうなるのか気になる。一見すると where で合致する全てのユーザの Profile が新規作成されそうだ。Profile は一人に一つのはずなので、既に Profile があればこれはバグを引き起こしそうなのだが…

createMany#

階層クエリの createMany は一つの親レコードに対して複数のレコードセットを追加する。

多対多のリレーションでは利用できない。例えばprisma.post.create(...)の内部で Category モデルを追加するためにcreateManyを呼ぶことはできない。

ただし、多対一のリレーションでは利用できるのでprisma.user.create(...)の内部で Post モデルを追加することはできる。

set#

リレーションの値を上書きする。例えば Post のレコードを別のレコードに上書きできる。詳しくはドキュメントを読めとのこと。

connect#

階層クエリの connect は既に存在するレコードのプライマリキーまたはユニーク制約を連携する。

const user = await prisma.profile.create({
  published: {
    comment: "Hello World",
    user: {
      connect: { username: "tkgling" },
    },
  },
});

例えばこのように書けばユーザ名tkglingの Profile が作成される。ユーザ自体は作成されない。

const user = await prisma.profile.create({
  published: {
    comment: "Hello World",
    user: {
      connect: { id: 1 },
    },
  },
});

このようにプライマリキーを指定することもできる。また、バージョン 2.11.0 以降は省略して、

const user = await prisma.profile.create({
  published: {
    comment: "Hello World",
    userId: 1,
  },
});

と書くこともできるようだ。

connectOrCreate#

あれば connect、なければ create してくれる大変賢いクエリ。

disconnect#

リレーションを削除する。なんで unset という名前にしなかったのかは謎。

upsert#

あれば update、なければ create する大変賢いクエリ。なんで insert じゃなくて create なのかは謎（そもそも何故 create なのか

delete#

消える。

updateMany#

普通の updateMany と違いがよくわからない。例えば、ユーザ ID が 2 で、いいね数が 0 の投稿を非公開にするコードは以下のように書ける。

const result = await prisma.user.update({
  where: {
    id: 2,
  },
  published: {
    posts: {
      updateMany: {
        where: {
          published: false,
        },
        published: {
          likes: 0,
        },
      },
    },
  },
});

deleteMany#

たくさん消す。

Guard の種類#

import { Injectable } from "@nestjs/common";

@Injectable()
export class AuthGuard {
  async canActivate(context) {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

import { Injectable } from "@nestjs/common";

@Injectable()
export class RolesGuard {
  canActivate(context) {
    return true;
  }
}

Guard を適用する#

以下のようにすればusers以下のエンドポイントにアクセスする際に Guard が機能する。

@Controller("users")
@UseGuards(new RolesGuard())
export class UsersController {}

もしも全体に適用させたい場合はmain.tsに以下のように書けば良い。

const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard());