zodを使ったスキーマ

CoddyのNode.jsジャーニー「REST API」セクションの一部。レッスン 11/25。

手作業でのチェックは、フィールドやルートが増えるたびに複雑になります。zodのスキーマを一度定義すれば、値がそのスキーマに適合するかをsafeParseでテストできます。

import { z } from 'zod';

const Event = z.object({
    name: z.string().trim().min(1).max(80),
    seats: z.number().int().min(1),
}).strict();

const result = Event.safeParse(req.body);
if (!result.success) {
    return res.status(400).json({ error: z.flattenError(result.error) });
}
// result.data には検証済みの body が格納されており、name は前後の空白が除去されている

.strict()は、スキーマに記載されていないフィールドを拒否します。Event.partial()を使うとすべてのフィールドが省略可能になります。これはPATCHで必要な動作です。Event.partial({ seats: true })ではseatsだけが省略可能になり、const { seats = 1 } = result.dataは値がない場合に1を使います。z.flattenError(result.error)は、問題を{ formErrors, fieldErrors }にまとめます。formErrorsには不明なフィールドなど、リクエスト本文全体に関する問題が入り、fieldErrorsには各フィールドの問題が入ります。Event.parseも同じチェックを行いますが、値が不正な場合は例外をスローします。ルート内で例外がスローされると、500エラーになります。

チャレンジ

簡単

このステップでは、入力の検証で作成したプロジェクトファイル（routes/tasks.jsを含む）ではなく、コース用に用意されたタスクトラッカーAPIプロジェクトを開きます。これまでの作業は、元のレッスン内に残っています。routes/tasks.jsを編集する前に、用意されたファイルを読んでください。このコピーにはタスクのCRUDルートと、手書きの入力検証が含まれています。

手書きのチェックは、フィールドやルートが増えるたびに増えていきます。zodスキーマでタスクを一度定義し、リクエストボディを受け取る3つのルートすべてで使いましょう。

routes/tasks.jsで、zodからzをインポートし、Taskというスキーマを記述します。
- title：文字列。前後の空白を取り除いた後、1〜100文字。
- done：trueまたはfalse（z.boolean()）。
- スキーマは厳密なので、colorのように定義されていないフィールドは拒否されます。
用意されているtitleErrorヘルパー（「入力の検証」で使った検証処理のコース版）を削除します。
.partial()を使って、Taskから2つのバージョンを作ります。POST用のバージョンではdoneだけを省略可能にします。PATCH用のバージョンでは両方のフィールドを省略可能にします。PUTではTask自体を使うため、両方のフィールドが必要です。
POST、PATCH、PUTでは、safeParseでreq.bodyをチェックします。チェックに失敗した場合は、ステータス400を返し、z.flattenError(result.error)で作成したzodの問題一覧をerrorの下に含めます。{ "title": 123 }の場合、次のようになります。
```
{ "error": { "formErrors": [], "fieldErrors": { "title": ["Invalid input: expected string, received number"] } } }
```
チェックに成功したら、req.bodyではなくresult.dataから保存します。ここには空白が取り除かれたタイトルが入っています。POSTでは、doneを含まないボディでタスクを作成すると、"done": falseになります（フィールドがない場合、result.dataではundefinedになり、??でデフォルト値が使われます）。PUTでは、保存済みタスクのidとcreatedAtを引き続き保持します。

試してみましょう：{ "title": " Order new chairs ", "color": "red" }を/api/tasksにPOSTします。400が返り、formErrorsにUnrecognized key: "color"と表示されます。今度はcolorを付けずにもう一度送信します。201が返り、"title": "Order new chairs"（空白なし）と"done": falseが含まれます。{ "done": "yes" }を使ってPATCH /api/tasks/2を送信すると、fieldErrorsにdoneのエントリーが含まれた400が返ります。{ "title": "Book the big room", "done": false }を使ってPUT /api/tasks/2を送信すると、200が返り、タスク2の以前のcreatedAtが保持されます。

自分で試してみよう

import { Router } from 'express';
import { nextId, tasks } from '../store.js';

const router = Router();

// titleを保存できない理由を返し、保存できる場合はnullを返す。
const titleError = (title) => {
    if (typeof title !== 'string' || title.trim() === '' || title.length > 100) {
        return 'title must be a string of 1 to 100 characters';
    }
    return null;
};

router.get('/', (req, res) => {
    res.json(tasks);
});

router.get('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return res.status(404).json({ error: 'Task not found' });
    }
    res.json(task);
});

router.post('/', (req, res) => {
    const { title } = req.body ?? {};
    const problem = titleError(title);
    if (problem) {
        return res.status(400).json({ error: problem });
    }
    const task = { id: nextId(), title, done: false, createdAt: new Date().toISOString() };
    tasks.push(task);
    res.status(201).location(`/api/tasks/${task.id}`).json(task);
});

router.patch('/:id', (req, res) => {
    const task = tasks.find((t) => t.id === Number(req.params.id));
    if (!task) {
        return res.status(404).json({ error: 'Task not found' });
    }
    const { title, done } = req.body ?? {};
    if (title !== undefined && titleError(title)) {
        return res.status(400).json({ error: titleError(title) });
    }
    if (done !== undefined && typeof done !== 'boolean') {
        return res.status(400).json({ error: 'done must be true or false' });
    }
    if (title !== undefined) task.title = title;
    if (done !== undefined) task.done = done;
    res.json(task);
});

router.put('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return res.status(404).json({ error: 'Task not found' });
    }
    const { title, done } = req.body ?? {};
    if (title === undefined || done === undefined) {
        return res.status(400).json({ error: 'PUT needs every field: title and done' });
    }
    const { id, createdAt } = tasks[index];
    tasks[index] = { id, title, done, createdAt };
    res.json(tasks[index]);
});

router.delete('/:id', (req, res) => {
    const index = tasks.findIndex((t) => t.id === Number(req.params.id));
    if (index === -1) {
        return res.status(404).json({ error: 'Task not found' });
    }
    tasks.splice(index, 1);
    res.status(204).end();
});

export default router;