NestJSのコードからOpenAPIを自動生成する際の最適解を探す

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Slide 5

Slide 5 text

© Commune Inc. All rights reserved ● 技術構成 ○ バックエンドはNestJS(monorepo, SWC)でREST API ○ class-validator, class-transformerを使ってAPIリクエストのバリデーションや変換を行っている ○ @nestjs/swaggerを使ってソースコードからOpenAPIを出力 ○ フロントエンド（今回関係ない） ■ Orvalを使ってOpenAPIからフロントエンドで使用するコード(型定義、データフェッチ、モックサーバー)を自動生成 ■ ブラウザからNestJSにHTTPリクエスト(BFFはない) 前提となる技術構成 5

Slide 6

Slide 6 text

© Commune Inc. All rights reserved 過去やってきたことを紹介します 1. @nestjs/swagger CLI Pluginの導入をチャレンジ（失敗） a. 実装中にローカルサーバーがエラーで止まりまくる 2. @nestjs/swagger CLI Pluginを使わず、手動でデコレータを付ける（採用） a. 仕組みは出来たが不満あり今までやってきた OpenAPIの自動生成への取り組み 6

Slide 7

Slide 7 text

© Commune Inc. All rights reserved ParametersとRequest bodyの出力 4. @nestjs/swagger CLI Pluginを使わず、手動でデコレータを付ける 7 ● リクエストボディ、リクエストパラメータは元々 dtoがあったので、ひたすら @ApiPropertyをつけるのみ ● この例は単純だが、他の dtoなどをimportして型定義に使っている場合はもっと色々記述する ○ 結構重要なポイントだが今回は割愛

Slide 8

Slide 8 text

© Commune Inc. All rights reserved Responseの出力のためにClassSerializerを剥がす 4. @nestjs/swagger CLI Pluginを使わず、手動でデコレータを付ける 8 ● ClassSerializerはクラスインスタンスをプレーンオブジェクトに変換してくれる ● 元々エンティティに変換処理のためのデコレータをつけることがみんな微妙だと思っていた（コントローラーで行うべき処理）ので、あまりためらいなく剥がした

Slide 9

Slide 9 text

Slide 10

Slide 10 text

© Commune Inc. All rights reserved Response出力のためにコントローラーにデコレータを追加 4. @nestjs/swagger CLI Pluginを使わず、手動でデコレータを付ける 10 ● コントローラーの関数に＠ApiOkResponseのデコレータを追加 ○ これをつけるとOpenAPIの Responseが出力される ● コントローラーの関数の戻り値の型にdtoを指定することで型安全にする ○ dtoにあるプロパティを書き忘れたらエラーになる

Slide 11

Slide 11 text

Slide 12

Slide 12 text

© Commune Inc. All rights reserved ● OpenAPIのためのデコレータの記述を間違えがち ● 間違っていてもIDE上でエラー等は出ないので、気をつける、ちゃんと確認する以外のソリューションがない ● フロントエンド開発中にミスに気がつくと、バックエンドのコード修正をまずやらないといけないのが面倒 ○ OpenAPIからフロントエンドのコードを自動生成をしているため、フロントエンドの型定義は手動で直せない半年ほど運用してみて 12

Slide 13

Slide 13 text

Slide 14

Slide 14 text

© Commune Inc. All rights reserved ● @nestjs/swaggerのCLI Plugin導入に再チャレンジ ○ NestJSのドキュメント通りに実装したところ ■ 上手く出来ている ● ローカルサーバーは動いている ● OpenAPIのParameters, Request body, Responseはおおよそ出力されている様子 ■ 上手く出来ていない ● 12件型エラーが出ている ● コード変更しているとたまに型エラーが出る ● ローカルサーバーの起動時間が約 3秒→約27秒になった改善に向けて 14

Slide 15

Slide 15 text

Slide 16

Slide 16 text

Slide 17

Slide 17 text

© Commune Inc. All rights reserved ● エラーを起こしているmetadata.tsを上書きする単純なスクリプトを作成 ○ metadata.tsはCLI Pluginを使うと生成されるOpenAPIのためのファイル ○ エラーが起きたらこのスクリプトを実行してリセットスッキリ解決はしてないけど、これでストレスはかなり軽減コード変更しているとたまに型エラーが出る 17

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

© Commune Inc. All rights reserved ● OpenAPIを使わない場合はSwaggerModuleも読み込まない ○ metadata.tsを読み込まなければ速度はあまり変わらないが、不完全な OpenAPIが見たいことはない、混乱の元なので全部読み込まない ● npm scripts(コマンド長い) ローカルサーバーの起動時間が約 3秒→約27秒になった 20 SwaggerModule

Slide 21

Slide 21 text

© Commune Inc. All rights reserved コマンドの使い分け ● 普段のバックエンド開発では OpenAPIは生成しないで立ち上げ ○ バックエンド開発中は OpenAPIをあまり見ないため ○ ローカルサーバーは安定して欲しい、何度も起動するので速度も重要 ● OpenAPIを見たい時、変更するときは OpenAPIを生成して立ち上げ ○ 実装中にエラーが出たときはリセットコマンドで回避可能 ○ プロダクションビルド (nest build)も遅くなるが、サーバーの起動速度はほぼ変わらなかったので問題なし少し苦しいがなんとか課題解決！ローカルサーバーの起動時間が約 3秒→約27秒になった 21 SwaggerModule

Slide 22

Slide 22 text

© Commune Inc. All rights reserved ● dtoにあるOpenAPIには不要なプロパティに @ApiHidePropertyをつけていく ○ toNameのような変換関数が主に不要な値 ● 不要になった@ApiPropertyを消していく ○ あっても問題ない。@ApiPropertyに記述してある値が優先的に使われる ○ 型定義が複雑な場合は引き続き指定する必要がある残りの作業は @ApiHidePropertyをつけていく 22

Slide 23

Slide 23 text

Slide 24

Slide 24 text

© Commune Inc. All rights reserved ○ dtoは1ファイルに1つのみ記載する ○ dtoの各プロパティには基本的に@ApiPropertyをつけない。上手く出力されない場合にのみ@ApiPropertyを使って正しい値を自分で記述する ○ dtoにあるOpenAPIには出力したくないプロパティには@ApiHidePropertyをつける開発時に気にすることまとめ 24

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

© Commune Inc. All rights reserved ● NestJSでそこまでコード量が多くないのにモジュールの読み込みに結構時間がかかるのをどう対処しているのか ● 漏れがなく、負荷が少ない操作ログの設計 ● MySQL, Prismaを使ってマルチテナントの実装する場合の工夫 ● Visual Regression Testで何をどこまで確認しているかこの後の懇親会で相談させてください！！最後に本件と関係ないけど気になっていること 27

Slide 28

Slide 28 text

募集中の求⼈はこちらカジュアル⾯談も実施しています！コミューン株式会社では共に働く仲間を募集中ですありがとうございました