メインコンテンツまでスキップ

Zod

Frourio ではバリデーションに zod を使用します。Zod スキーマの定義方法については上のリンクからドキュメントを参照してください。

2 種類のバリデーター​

Frourio は コントローラーレベル バリデーター と ディレクトリレベル バリデーター の 2 種類のバリデーターを提供しています。 それぞれで検証可能な要素が異なります。

  • コントローラーレベル バリデーター: 現在の階層でのみ呼ばれます。params は検証できません。
    • query
    • headers
    • body
  • ディレクトリレベル バリデーター: 現在と 配下の 階層で呼ばれます。params のみ検証できます。
    • params

コントローラーレベル​

defineController() についてはルーティングページを参照してください。

{
  [(target key)]?: z.object({ ... })
}

validators は key が RequestParams (query や headers、body) に等しく、value が Zod オブジェクトスキーマ (z.object()) であるオブジェクトです。

それぞれのスキーマは z.ZodType を用いて API 型定義との一貫性が確認されます。

server/api/_id@string/index.ts
import { DefineMethods } from 'aspida';
import { Fuga, Res } from '$/types';

export type Methods = DefineMethods<{
  get: {
    resBody: string;
  };
  post: {
    reqBody: {
      hogeString: string;
      fugaObject: Fuga;
      piyoBoolean?: boolean;
    };
    query: {
      length?: number;
    };
    resBody: Res;
  };
}>;
server/api/_id@string/controller.ts
import { defineController } from './$relay';
import { z } from 'zod';

export default defineController(() => ({
  get: () => ({ status: 200, body: 'Hello' }),
  post: {
    validators: {
      query: z.object({
        length: z.number().optional(),
      }),
      body: z.object({
        hogeString: z.string(),
        fugaObject: z.object({ ... }),
        piyoBoolean: z.boolean().optional(),
      }),
    },
    handler: async ({ params: { id }, body, query: { length } }) => {
      const res = await createBaz(id, body, length);
      if (!res) return { status: 400 };
      return { status: 201, body: res };
    },
  },
}));

ディレクトリレベル​

ディレクトリレベルバリデーターを定義するには、対象のディレクトリの最上層に validators.ts を作成し、./$relay.ts でエクスポートされた defineValidators を使用します。

エンドポイントに影響する複数のディレクトリレベルバリデーターがある場合、.and を用いて交差型に変換されます。

注記

名前にパスパラメータを持つディレクトリが作成された際、Frourio は自動的に validators.ts を作成します。

server/api/_id@string/validators.ts
import { defineValidators } from './$relay';
import { z } from 'zod';

export default defineValidators(() => ({
  params: z.object({ id: z.string() }),
}));

関数 defineValidators​

引数の型​

  • function (fastify: FastifyInstance) => { params: (zod object schema) }

(zod object schema) の実際の定義は z.ZodType<{ (params type) }> ですが、これを意識する必要はありません。 これによって API 型定義との一貫性が確保されているのです。

{ (params type) }

そのディレクトリが持つパスパラメータの型定義。 上位のディレクトリのものは含まれません。 無指定の場合は string になりますが、自動バリデーションのページにもあるように、指定することを推奨します。