Web API作成入門

2024-2025 Shunsuke Watanabe

このチュートリアルについて

twitchまたはYoutubeで配信します、配信時間は1時間前後です。

Twitch → https://www.twitch.tv/shun__suke__

Youtube → https://www.youtube.com/@Captain_Emo

🧭 配信予定はconnpassをご確認ください → https://hands-on.connpass.com/

👨‍💻サンプルコード → https://github.com/craftgear/api_handson

discord → https://discord.gg/3havwjWGsw

bluesky → https://bsky.app/profile/craftgear.bsky.social

📝 blog → https://craftgear.github.io/posts/

1. 開発資料

EventStorming

• イベントストーミングの利点3つ

• https://www.youtube.com/watch?v=mLXQIYEwK24

• https://github.com/SAP/curated-resources-for-domain-driven-design/blob/main/knowledgebase/tools/eventstorming.md

Big Picture

Design Level

Onion Architecture

• https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/
• オニオンアーキテクチャのルール

その他の3層アーキテクチャ

• Clean Architecture
  • https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
• Hexagonal Architecture
  • https://alistair.cockburn.us/hexagonal-architecture/

2. 開発環境の準備

対象環境

• macOS
• Node.js 20〜
  • LinuxやWindowsの方は自分でnodeとnpmをインストールできれば後は同じです

Node.js

• nodeとnpmのバージョン確認

  1
  ❯ node -v
  2
  v22.2.0
  3
  
  4
  ❯ npm -v
  5
  10.8.3

  • インストール手順 https://nodejs.org/ja/download

SQLite3

• sqlite3が使えることを確認

  1
  ❯ sqlite3 --version
  2
  3.22.0 2018-01-22 18:45:57 0c55d179733b46d8d0ba4d88e01a25e10677046ee3da1d5b1581e86726f2alt2

コードエディタ

• VisualStudio Code, neovim, emacsなどプログラミング支援機能が使えるもの
  • テキストエディット、メモ帳などのテキストエディタは避けてください

新しいプロジェクトの作成

• 初期化

  • テンプレートは下にスクロールして node.js を選択してください。

  1
  npm create hono@latest api

• コードフォーマッタとLinterのインストール

  1
  npm i -D eslint @eslint/js @types/eslint__js typescript typescript-eslint prettier

• eslint.config.mjs ファイルを作成

  1
  // @ts-check
  2
  import eslint from '@eslint/js';
  3
  import tseslint from 'typescript-eslint';
  4
  
  5
  export default tseslint.config(
  6
    eslint.configs.recommended,
  7
    ...tseslint.configs.recommended,
  8
  );

• tsconfig.json の設定を変更

  • “module”: “NodeNext” を “module”: “ESNext” に変更
  • "verbatimModuleSyntax": true, を消す
  • "moduleResolution": "bundler", を追加する

3. ドメインモデルの定義

zod https://zod.dev/

1. zodをインストール

   1
   npm i zod

2. /src/todo/domain.ts を作成、zodを使ってバリデーションスキーマと型を定義

   1
   import { z } from 'zod';
   2
   
   3
   export const TodoSchema = z.object({
   4
     id: z.number().brand('TodoId'),
   5
     title: z.string(),
   6
     done: z.coerce.boolean().default(false),
   7
     doneAt: z.coerce.date().nullish(),
   8
   });
   9
   
   10
   export type Todo = z.infer<typeof TodoSchema>;
   11
   export type TodoId = Todo['id'];

3. JSONのパース関数を追加

   1
   export const parseTodo = (data: unknown): Todo => TodoSchema.parse(data);
   2
   export const parseTodoId = (id: number): TodoId => TodoSchema.shape.id.parse(id);

4. 新しく追加するTodoには id がないので、 NewTodo という型を追加する。

   1
   export type NewTodo = Omit<Todo, 'id'>;
   2
   export const parseNewTodo = (data: unknown): NewTodo => TodoSchema.omit({ id: true }).parse(data);

5. vitestをインストール

   1
   npm i -D vitest

6. テスト作成 /src/todo/domain.spec.ts

   1
   import { describe, it, expect, expectTypeOf } from 'vitest';
   2
   import {
   3
     parseTodo,
   4
     parseTodoId,
   5
     parseNewTodo,
   6
     Todo,
   7
     TodoId,
   8
     NewTodo,
   9
   } from './domain';
   10
   
   11
   describe('parseTodo', () => {
   12
     it('parse a valid todo', () => {
   13
       const result = parseTodo({ id: 1, title: "Buy milk" });
   14
       expect(result).toEqual({
   15
         id: 1,
   16
         title: "Buy milk",
   17
         done: false,
   18
       });
   19
       expectTypeOf(result).toEqualTypeOf<Todo>();
   20
       const now = new Date();
   21
       expect(parseTodo({ id: 1, title: 'Buy milk done', done: true, doneAt: now })).toEqual({
   22
         id: 1,
   23
         title: 'Buy milk done',
   24
         done: true,
   25
         doneAt: now,
   26
       });
   27
     });
   28
   });
   29
   
   30
   describe('parseTodoId', () => {
   31
     it('parse a valid todo id', () => {
   32
       const todoId = parseTodoId(1);
   33
       expectTypeOf(todoId).toEqualTypeOf<TodoId>();
   34
     });
   35
   });
   36
   
   37
   describe('parseNewTodo', () => {
   38
      it('parse a valid new todo', () => {
   39
        const result = parseNewTodo({ title: "Buy milk" });
   40
        expect(result).toEqual({
   41
          title: "Buy milk",
   42
          done: false,
   43
        });
   44
        expectTypeOf(result).toEqualTypeOf<NewTodo>();
   45
      });
   46
    });

7. package.jsonに test コマンドを追加

8. テスト実行

   1
   npm test

4. ビジネスロジックの実装

1. タイトルのチェックをzodのスキーマに追加

   1
    export const TodoSchema = z
   2
      .object({
   3
        id: z.number().brand('TodoId'),
   4
        title: z.string({
   5
          // パース時にタイトルの有無をチェック
   6
          required_error: 'Title is required',
   7
        })
   8
        .trim()
   9
        // パース時にタイトルが一文字以上あるかどうかチェック
   10
        .min(1, { message: 'Title must be at least 1 character long' }),
   11
        done: z.coerce.boolean().default(false),
   12
        doneAt: z.date().optional(),
   13
      });

2. 完了チェックの関数を追加

   1
   export const isComplete = (todo: Todo) => todo.done;

3. テスト追加

   1
   import { describe, it, expect, expectTypeOf } from 'vitest';
   2
   import {
   3
     parseTodo,
   4
     parseTodoId,
   5
     isComplete,
   6
     parseNewTodo,
   7
     Todo,
   8
     TodoId,
   9
     NewTodo,
   10
   } from './domain';
   11
   
   12
   describe.concurrent('parseTodo', () => {
   13
      it('parse a valid todo', () => {
   14
        const result = parseTodo({ id: 1, title: "Buy milk" });
   15
        expect(result).toEqual({
   16
          id: 1,
   17
          title: "Buy milk",
   18
          done: false,
   19
        });
   20
        expectTypeOf(result).toEqualTypeOf<Todo>();
   21
        const now = new Date();
   22
        expect(parseTodo({ id: 1, title: 'Buy milk done', done: true, doneAt: now })).toEqual({
   23
          id: 1,
   24
          title: 'Buy milk done',
   25
          done: true,
   26
          doneAt: now,
   27
        });
   28
      });
   29
   
   30
      it('throws an error when title is missing', () => {
   31
        expect(() => parseTodo({ id: 1 })).toThrowError('Title is required');
   32
      });
   33
   
   34
      it('throws an error when title is empty', () => {
   35
        expect(() => parseTodo({ id: 1, title: '' })).toThrowError(
   36
          'Title must be at least 1 character long'
   37
        );
   38
      });
   39
   
   40
      it('throws an error when title is only whitespaces', () => {
   41
        expect(() => parseTodo({ id: 1, title: ' ' })).toThrowError(
   42
          'Title must be at least 1 character long'
   43
        );
   44
      });
   45
   })
   46
   
   47
   describe('parseTodoId', () => {
   48
     it('parse a valid todo id', () => {
   49
       const todoId = parseTodoId(1);
   50
       expectTypeOf(todoId).toEqualTypeOf<TodoId>();
   51
     });
   52
   });
   53
   
   54
   describe.concurrent('parseNewTodo', () => {
   55
     it('parse a valid new todo', () => {
   56
        const result = parseNewTodo({ title: "Buy milk" });
   57
        expect(result).toEqual({
   58
          title: "Buy milk",
   59
          done: false,
   60
        });
   61
        expectTypeOf(result).toEqualTypeOf<NewTodo>();
   62
     });
   63
   
   64
     it('throws an error when title is missing', () => {
   65
       expect(() => parseNewTodo({})).toThrowError('Title is required');
   66
     });
   67
   
   68
     it('throws an error when title is empty', () => {
   69
       expect(() => parseNewTodo({ title: '' })).toThrowError(
   70
         'Title must be at least 1 character long'
   71
       );
   72
     });
   73
   
   74
     it("throws an error when title is only whitespaces", () => {
   75
       expect(() => parseTodo({ title: " " })).toThrowError(
   76
         "Title must be at least 1 character long",
   77
       );
   78
     });
   79
   });
   80
   
   81
   describe.concurrent('isComplete', () => {
   82
     it('returns true when todo is completed', () => {
   83
       const todo = parseTodo({ id: 1, title: 'Buy milk', done: true });
   84
       expect(isComplete(todo)).toBe(true);
   85
     });
   86
   
   87
     it('returns false when todo is not completed', () => {
   88
       const todo = parseTodo({ id: 1, title: 'Buy milk', done: false });
   89
       expect(isComplete(todo)).toBe(false);
   90
     });
   91
   });

ドメイン層のコードはすべての関数が純粋関数になります。

5. ユースケース作成

Applicationという単語が一般的すぎるので、ここでは代わりにUsecaseと呼ぶことにします。

1. /src/todo/usecase.ts を作成

   1
   import { TodoId, TodoRepository } from './domain';
   2
   
   3
   export const readTodos = (repository: TodoRepository, page = 1, limit = 10) => {
   4
     // TODO: implement
   5
   };
   6
   
   7
   export const createTodo = (repository: TodoRepository, title: string) => {
   8
     // TODO: Implement
   9
   };
   10
   
   11
   export const completeTodo = (repository: TodoRepository, id: TodoId) => {
   12
     // TODO: Implement
   13
   };

2. /src/todo/domain.ts にリポジトリの型定義を追加

   1
    export type TodoRepository = {
   2
      selectAll: (offset: number, limit: number) => Promise<Todo[]>;
   3
      selectById: (id: TodoId) => Promise<Todo | null>;
   4
      insert: (todo: NewTodo) => Promise<Todo | null>;
   5
      setCompleted: (id: TodoId) => Promise<Todo | null>;
   6
    };

3. 1で定義したユースケースの実装

   1
   import {
   2
     parseNewTodo,
   3
     isComplete,
   4
     TodoRepository,
   5
     TodoId,
   6
   } from './domain';
   7
   
   8
   export const readTodos = async ({ selectAll }: TodoRepository, page = 1, limit = 10) => {
   9
     if (page < 1) {
   10
       throw Error('page should be a positive number');
   11
     }
   12
     return await selectAll(page - 1, limit);
   13
   };
   14
   
   15
   export const createTodo = async ({ insert }: TodoRepository, title: string) => {
   16
     const todo = parseNewTodo({ title });
   17
     return await insert(todo);
   18
   };
   19
   
   20
   export const completeTodo = async (
   21
     { selectById, setCompleted }: TodoRepository,
   22
     id: TodoId
   23
   ) => {
   24
     const todo = await selectById(id);
   25
     if (!todo) {
   26
       throw new Error('Todo not found');
   27
     }
   28
     if (isComplete(todo)) {
   29
       return todo;
   30
     }
   31
     return await setCompleted(id);
   32
   };

4. ユースケースのテストを追加 /src/todo/usecase.spec.ts

   1
   import { describe, it, expect, vi, afterEach } from 'vitest';
   2
   import { readTodos, createTodo, completeTodo } from './usecase';
   3
   import type { TodoRepository, TodoId } from './domain';
   4
   
   5
   describe.concurrent('todo usecases', () => {
   6
     const repository: TodoRepository = {
   7
       insert: vi.fn(),
   8
       selectAll: vi.fn(),
   9
       selectById: vi.fn(),
   10
       setCompleted: vi.fn(),
   11
     };
   12
   
   13
     afterEach(() => {
   14
       vi.resetAllMocks();
   15
     });
   16
   
   17
     it('reads todos', async () => {
   18
       await readTodos(repository);
   19
       expect(repository.selectAll).toHaveBeenCalledWith(0, 10);
   20
     });
   21
   
   22
      it("page number should be larger then 0", async () => {
   23
        await expect(() => readTodos(repository, 0)).rejects.toThrowError(
   24
          "page should be a positive number",
   25
        );
   26
      });
   27
   
   28
      it('creates a new todo', async () => {
   29
        const title = 'Buy milk';
   30
        await createTodo(repository, title);
   31
        expect(repository.insert).toHaveBeenCalledWith({ title, done: false });
   32
      });
   33
   
   34
      it('completes a todo', async () => {
   35
        const id = 1 as TodoId;
   36
        const repo = {
   37
           ...repository,
   38
           selectById: vi.fn().mockResolvedValueOnce({
   39
             id: 1 as TodoId,
   40
             title: "Buy milk",
   41
             done: false,
   42
           }),
   43
        };
   44
        await completeTodo(repo, id);
   45
        expect(repo.selectById).toHaveBeenCalledWith(id);
   46
        expect(repo.setCompleted).toHaveBeenCalledWith(id);
   47
      });
   48
   
   49
      it('does NOT completes a todo which is already done', async () => {
   50
        const id = 2 as TodoId;
   51
        const repo = {
   52
          ...repository,
   53
          selectById: vi.fn().mockResolvedValueOnce({
   54
            id: 2 as TodoId,
   55
            title: "Buy eggs",
   56
            done: true,
   57
          }),
   58
        };
   59
        await completeTodo(repo, id);
   60
        expect(repo.selectById).toHaveBeenCalledWith(id);
   61
        expect(repo.setCompleted).not.toHaveBeenCalledWith(id);
   62
      });
   63
   
   64
      it('throws an error when todo is not found', async () => {
   65
        const id = 999 as TodoId;
   66
        const repo = {
   67
          ...repository,
   68
          selectById: vi.fn().mockResolvedValueOnce(null),
   69
        };
   70
        await expect(() => completeTodo(repo, id)).rejects.toThrowError("Todo not found");
   71
      });
   72
    });

5. テストカバレッジを測定する

6. Httpサーバー作成

hono https://hono.dev/docs/

1. /src/todo/route.ts を作成し、エンドポイントを定義

   1
   import { Hono } from 'hono';
   2
   import { HTTPException } from 'hono/http-exception';
   3
   
   4
   import { parseTodoId } from './domain';
   5
   import { readTodos, createTodo, completeTodo } from './usecase';
   6
   import { todoRepository } from './infra/repo';
   7
   
   8
   export const todoRoute = new Hono().basePath('/todos');
   9
   
   10
   todoRoute.get('/', async (c) => {
   11
     const { page, limit } = c.req.query();
   12
     const pageNumber = page ? Number(page) : undefined;
   13
     const limitNumber = limit ? Number(limit) : undefined;
   14
   
   15
     const todos = await readTodos(todoRepository, pageNumber, limitNumber);
   16
     return c.json(todos);
   17
   });
   18
   
   19
   todoRoute.post('/', async (c) => {
   20
     const data = await c.req.json();
   21
     try {
   22
       const newTodo = await createTodo(todoRepository, data.title);
   23
       return c.json(newTodo);
   24
     } catch (e: unknown) {
   25
       throw new HTTPException(400, { message: (e as Error).message });
   26
     }
   27
   });
   28
   
   29
   todoRoute.patch('/:id/complete', async (c) => {
   30
     const id = c.req.param('id');
   31
     try {
   32
       const todoId = parseTodoId(Number(id));
   33
       const todo = await completeTodo(todoRepository, todoId);
   34
       return c.json(todo);
   35
     } catch (e: unknown) {
   36
       throw new HTTPException(400, { message: (e as Error).message });
   37
     }
   38
   });

2. /src/todo/infra/repo.ts を作成し、todoRepositoryのスケルトンを作成

   1
   import type { TodoRepository, Todo } from '../domain';
   2
   export const todoRepository: TodoRepository = {
   3
     selectAll: async (offset, limit) => {
   4
       //TODO: Implement
   5
       return [];
   6
     },
   7
     selectById: async (id) => {
   8
       //TODO: Implement
   9
       return {} as Todo;
   10
     },
   11
     insert: async (todo) => {
   12
       //TODO: Implement
   13
       return {} as Todo;
   14
     },
   15
     setCompleted: async (id) => {
   16
       //TODO: Implement
   17
       return {} as Todo;
   18
     },
   19
   };

3. /src/index.ts でルートを登録

   1
   import { serve } from "@hono/node-server";
   2
   import { Hono } from "hono";
   3
   import { HTTPException } from "hono/http-exception";
   4
   import { logger } from 'hono/logger';
   5
   import { cors } from "hono/cors";
   6
   
   7
   import { todoRoute } from "./todo/route";
   8
   
   9
   const app = new Hono();
   10
   
   11
   app.use(logger());
   12
   app.use("/v1/*", cors());
   13
   
   14
   app.route("/v1", todoRoute);
   15
   app.onError((e, c) => {
   16
     if (e instanceof HTTPException) {
   17
       return e.getResponse();
   18
     }
   19
     return c.json({ error: e.message }, 500);
   20
   });
   21
   
   22
   const port = 3000;
   23
   console.log(`Server is running on port ${port}`);
   24
   
   25
   serve({
   26
     fetch: app.fetch,
   27
     port,
   28
   });

4. npm run dev でサーバーを起動

7. リポジトリ作成

kysely https://kysely.dev/docs/getting-started

1. DBスキーマを作成 /src/todo/infra/schema.sql

   1
   CREATE TABLE todo (
   2
     id INTEGER PRIMARY KEY AUTOINCREMENT,
   3
     title TEXT NOT NULL,
   4
     done INTEGER DEFAULT 0,
   5
     done_at INTEGER
   6
   );

2. DB作成

   1
   cat src/todo/infra/schema.sql | sqlite3 database.sqlite

3. クエリビルダーとSQLドライバーをインストール

   1
   npm i kysely better-sqlite3 snake-camel
   2
   npm i -D kysely-codegen @types/better-sqlite3

4. データベースの型情報を生成

   1
   echo 'DATABASE_URL=./database.sqlite' > .env && npx kysely-codegen\
   2
      --out-file=./src/todo/infra/database.d.ts

5. /src/todo/infra/db.ts を作成

   1
   import type { DB } from './database';
   2
   import SQLite from 'better-sqlite3';
   3
   import { Kysely, SqliteDialect } from 'kysely';
   4
   
   5
   const dialect = new SqliteDialect({
   6
     database: new SQLite('./database.sqlite'),
   7
   });
   8
   
   9
   export const db = new Kysely<DB>({ dialect });

6. /src/todo/infra/repo.ts のTODOを実装

   1
   import { db } from './db';
   2
   import { toCamel } from 'snake-camel';
   3
   import type { TodoRepository } from '../domain';
   4
   import { parseTodo } from '../domain';
   5
   
   6
   export const todoRepository: TodoRepository = {
   7
     selectAll: async (offset, limit) => {
   8
       const data = await db
   9
         .selectFrom('todo')
   10
         .selectAll()
   11
         .offset(offset * limit)
   12
         .limit(limit)
   13
         .orderBy('id desc')
   14
         .execute();
   15
       return data.map((x) => parseTodo(toCamel(x)));
   16
     },
   17
     selectById: async (id) => {
   18
       const data = await db
   19
         .selectFrom('todo')
   20
         .selectAll()
   21
         .where('todo.id', '=', id)
   22
         .executeTakeFirst();
   23
       return data ? parseTodo(toCamel(data)) : null;
   24
     },
   25
     insert: async (input) => {
   26
       const data = await db
   27
         .insertInto('todo')
   28
         .values({
   29
           ...input,
   30
           done: 0,
   31
         })
   32
         .returningAll()
   33
         .executeTakeFirst();
   34
       return data ? parseTodo(toCamel(data)) : null;
   35
     },
   36
     setCompleted: async (id) => {
   37
       const data = await db
   38
          .updateTable('todo')
   39
          .set({ done: 1, done_at: Date.now() })
   40
          .where('todo.id', '=', id)
   41
          .returningAll()
   42
          .executeTakeFirst();
   43
       return data ? parseTodo(toCamel(data)) : null;
   44
     },
   45
   };

7. postman等を用いてAPI呼び出しができることを確認する

8. OpenAPI定義作成

1. ライブラリを追加

   1
   npm i @hono/zod-openapi @hono/swagger-ui

2. /src/todo/route.ts のルート定義を OpenAPI対応のものに変更

   1
   import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
   2
   import { HTTPException } from 'hono/http-exception';
   3
   
   4
   import { parseTodoId, TodoSchema } from "./domain";
   5
   import { readTodos, createTodo, completeTodo } from "./usecase";
   6
   import { todoRepository } from "./infra/repo";
   7
   
   8
   export const todoRoute = new OpenAPIHono();
   9
   
   10
   const getTodosRoute = createRoute({
   11
     operationId: 'getTodos',
   12
     tags: ['todos'],
   13
     path: '/todos',
   14
     method: 'get',
   15
     description: 'Read all todos',
   16
     request: {
   17
       query: z.object({
   18
         page: z.coerce.number().optional(),
   19
         limit: z.coerce.number().optional(),
   20
       })
   21
     },
   22
     responses: {
   23
       200: {
   24
         description: 'Get a list of todos',
   25
         content: {
   26
           'application/json': {
   27
             schema: z.array(TodoSchema),
   28
           },
   29
         },
   30
       },
   31
     },
   32
   });
   33
   
   34
   todoRoute.openapi(getTodosRoute, async (c) => {
   35
     const { page, limit } = c.req.valid('query');
   36
     const pageNumber = page ? Number(page) : undefined;
   37
     const limitNumber = limit ? Number(limit) : undefined;
   38
   
   39
     const todos = await readTodos(todoRepository, pageNumber, limitNumber);
   40
     return c.json(todos);
   41
   });
   42
   
   43
   const postTodoRoute = createRoute({
   44
     operationId: 'createTodo',
   45
     tags: ['todos'],
   46
     path: '/todos',
   47
     method: 'post',
   48
     description: 'Create a new todo item',
   49
     request: {
   50
       body: {
   51
         required: true,
   52
         content: {
   53
           'application/json': {
   54
             schema: z.object({
   55
               title: z.string().openapi({
   56
                 example: 'Buy milk',
   57
                 description: 'The title of the todo',
   58
               }),
   59
             }),
   60
           },
   61
         },
   62
       },
   63
     },
   64
     responses: {
   65
       200: {
   66
         description: 'a newly created todo item',
   67
         content: {
   68
           'application/json': {
   69
             schema: TodoSchema,
   70
           },
   71
         },
   72
       },
   73
       400: {
   74
         description: 'Bad request',
   75
       },
   76
     },
   77
   });
   78
   
   79
   todoRoute.openapi(postTodoRoute, async (c) => {
   80
     const data = await c.req.json();
   81
     try {
   82
       const newTodo = await createTodo(todoRepository, data.title);
   83
       return c.json(newTodo);
   84
     } catch (e: unknown) {
   85
       throw new HTTPException(400, { message: (e as Error).message });
   86
     }
   87
   });
   88
   
   89
   const patchTodoRoute = createRoute({
   90
     operationId: 'completeTodo',
   91
     tags: ['todos'],
   92
     path: '/todos/{id}/complete',
   93
     method: 'patch',
   94
     description: 'Mark a todo item as complete',
   95
     request: {
   96
        params: z.object({
   97
          id: z.string(),
   98
        }),
   99
     },
   100
     responses: {
   101
       200: {
   102
         description: 'a completed todo todo item',
   103
         content: {
   104
           'application/json': {
   105
             schema: TodoSchema,
   106
           },
   107
         },
   108
       },
   109
       400: {
   110
         description: 'Bad request',
   111
       },
   112
     },
   113
   });
   114
   
   115
   todoRoute.openapi(patchTodoRoute, async (c) => {
   116
     const id = c.req.param('id');
   117
     try {
   118
       const todoId = parseTodoId(Number(id));
   119
       const todo = await completeTodo(todoRepository, todoId);
   120
       return c.json(todo);
   121
     } catch (e: unknown) {
   122
       throw new HTTPException(400, { message: (e as Error).message });
   123
     }
   124
   });

3. /src/index.ts に OpenAPI の定義とUIを表示するルートを追加

   1
   import { serve } from "@hono/node-server";
   2
   import { OpenAPIHono } from '@hono/zod-openapi';
   3
   import { swaggerUI } from '@hono/swagger-ui';
   4
   import { HTTPException } from 'hono/http-exception';
   5
   import { logger } from 'hono/logger';
   6
   import { cors } from "hono/cors";
   7
   
   8
   import { todoRoute } from "./todo/route";
   9
   
   10
   const app = new OpenAPIHono();
   11
   
   12
   app.use(logger());
   13
   app.use("/v1/*", cors());
   14
   
   15
   app.route('/v1', todoRoute);
   16
   app.onError((e, c) => {
   17
     if (e instanceof HTTPException) {
   18
       return e.getResponse();
   19
     }
   20
     return c.json({ error: e.message }, 500);
   21
   });
   22
   
   23
   app.doc31('/open-api', {
   24
     openapi: '3.1.0',
   25
     info: { title: 'API Hands On', version: '1' },
   26
     servers: [{ url: 'http://localhost:3000' }],
   27
     tags: [
   28
       {
   29
         name: 'todos',
   30
         description: 'Operations about todos',
   31
       },
   32
     ],
   33
   });
   34
   app.get('/doc', swaggerUI({ url: '/open-api' }));
   35
   
   36
   const port = 3000;
   37
   console.log(`Server is running on port ${port}`);
   38
   
   39
   serve({
   40
     fetch: app.fetch,
   41
     port,
   42
   });

4. /src/todo/domain.ts に OpenAPI用のデータを追加

   1
   import { z } from "@hono/zod-openapi";
   2
   
   3
   export const TodoSchema = z
   4
     .object({
   5
       id: z.number().brand("TodoId").openapi("TodoId"),
   6
       title: z
   7
         .string({
   8
           // パース時にタイトルの有無をチェック
   9
           required_error: "Title is required",
   10
         })
   11
         .trim()
   12
         // パース時にタイトルが一文字以上あるかどうかチェック
   13
         .min(1, { message: "Title must be at least 1 character long" }),
   14
       done: z.coerce.boolean().default(false),
   15
       doneAt: z.coerce.date().optional(),
   16
     })
   17
     .openapi("Todo");

5. http://localhost:3000/open-api で API定義表示、http://localhost:3000/doc で ドキュメント表示

9. APIテスト

StepCI https://docs.stepci.com

1. Step CIをインストール

   1
   npm i -D stepci

2. テストワークフローを生成

   1
   mkdir api-tests
   2
   npx stepci generate http://localhost:3000/open-api ./api-tests/todo.yml

3. 生成されたworkflowの名前と数値を修正する

4. テスト実行

   1
   npx stepci run ./api-tests/todo.yml

10. クライアント用コード生成

React入門で作ったTodoページのAPI呼び出しを置き換えてみます

React入門

Hey API https://heyapi.vercel.app/openapi-ts/get-started.html

1. React入門のリポジトリをcloneし、ディレクトリに入る

   1
   git clone https://github.com/craftgear/react-hands-on
   2
   cd react-hands-on && npm i

2. hey-apiをインストール

   1
   npm i -D @hey-api/openapi-ts @hey-api/client-fetch

3. プロジェクトルートに openapi-ts.config.ts ファイルを作成

   1
   import { defineConfig } from '@hey-api/openapi-ts';
   2
   
   3
   export default defineConfig({
   4
     input: 'http://localhost:3000/open-api',
   5
     output: {
   6
       path: "src/api/generated",
   7
       format: "prettier",
   8
     },
   9
     plugins: ['@hey-api/client-fetch', '@tanstack/react-query']
   10
   });

4. TanStack Queryのフックに渡すオプションを生成

   1
   npx @hey-api/openapi-ts

5. /src/api/todos.ts の クエリを生成したコードで置き換え

   1
   import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
   2
   import { client } from "./generated/client.gen";
   3
   import {
   4
     getTodosOptions,
   5
     getTodosQueryKey,
   6
     completeTodoMutation,
   7
     createTodoMutation,
   8
   } from './generated/@tanstack/react-query.gen';
   9
   
   10
   client.setConfig({
   11
     baseUrl: "http://localhost:3000",
   12
   });
   13
   
   14
   const queryKey = getTodosQueryKey();
   15
   
   16
   export const useGetTodos = () => useQuery(getTodosOptions());
   17
   
   18
   export const usePatchTodo = () => {
   19
     const queryClient = useQueryClient();
   20
     return useMutation({
   21
       ...completeTodoMutation(),
   22
       onSuccess: () => {
   23
         queryClient.invalidateQueries({ queryKey });
   24
       },
   25
     });
   26
   };
   27
   
   28
   export const usePostTodo = () => {
   29
     const queryClient = useQueryClient();
   30
     return useMutation({
   31
       ...createTodoMutation(),
   32
       onSuccess: () =>
   33
         queryClient.invalidateQueries({ queryKey }),
   34
     });
   35
   };

6. usePatchTodo と usePostTodo にわたす引数を修正

   1
   ...
   2
   
   3
      const { mutate } = usePatchTodo();
   4
   
   5
      const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
   6
        const id = e.target.value;
   7
        mutate({ path: { id });
   8
      };
   9
   
   10
   ...

   1
   ...
   2
   
   3
      const { mutate } = usePostTodo();
   4
   
   5
      const submitForm: SubmitHandler<FormData> = (data) => {
   6
        if (!data.title) return;
   7
        mutate({ body: { title: data.title } }, { onSuccess: () => reset() });
   8
      };
   9
   
   10
   ...

TanStack Startで溶ける境界

Tanstack Start

https://tanstack.com/start/latest

1. cd tanstack-start

2. npm i; npm run dev

3. app/routes/todos.tsx ファイルを新規作成すると、自動で以下の内容が生成される。

   1
   import { createFileRoute } from '@tanstack/react-router'
   2
   
   3
   export const Route = createFileRoute('/todos')({
   4
     component: RouteComponent,
   5
   })
   6
   
   7
   function RouteComponent() {
   8
     return <div>Hello "/todos"!</div>
   9
   }

4. Todo と TodoForm コンポーネントを app/routes/todos.tsx にコピーする。

   コンポーネント

   1
   import { ChangeEvent } from "react";
   2
   import { useForm, type SubmitHandler } from 'react-hook-form';
   3
   
   4
   function Todos() {
   5
     const router = useRouter();
   6
     const data = Route.useLoaderData();
   7
   
   8
     const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
   9
       const id = e.target.value;
   10
       updateTodo({ data: Number(id) }).then(() => router.invalidate());
   11
     };
   12
   
   13
     return (
   14
       <div>
   15
         <h1>Todos</h1>
   16
         <TodoForm />
   17
         {data?.map(({ id, title, done }) => (
   18
           <div key={id}>
   19
             <input
   20
               type="checkbox"
   21
               id={`${id}`}
   22
               value={id}
   23
               checked={done ? true : false}
   24
               onChange={handleChange}
   25
             />
   26
             <label htmlFor={`${id}`}>{title}</label>
   27
           </div>
   28
         ))}
   29
       </div>
   30
     );
   31
   }
   32
   
   33
   type FormData = {
   34
     title: string;
   35
   };
   36
   
   37
   function TodoForm() {
   38
     const {
   39
       register,
   40
       handleSubmit,
   41
       reset,
   42
       formState: { errors },
   43
     } = useForm<FormData>();
   44
     const router = useRouter();
   45
   
   46
     const submitForm: SubmitHandler<FormData> = (data) => {
   47
       if (!data.title) return;
   48
       addTodo({ data: data.title }).then(() => {
   49
         router.invalidate();
   50
         reset();
   51
       });
   52
     };
   53
   
   54
     return (
   55
       <form onSubmit={handleSubmit(submitForm)}>
   56
         {errors.title && <p>タイトルを入力してください</p>}
   57
         <input type="text" {...register("title", { required: true })} />
   58
         <button className="btn btn-primary btn-sm">追加</button>
   59
       </form>
   60
     );
   61
   }

5. app/domain ディレクトリを作成し、api_handson のリポジトリから、todo/ ディレクトリを app/domain/todo にコピーする

6. api_handson のリポジトリから、database.sqlilte をコピーする。

7. 必要なライブラリをインストールする

   1
   npm i react-hook-form npm i kysely better-sqlite3 snake-camel; npm i -D kysely-codegen @types/better-sqlite3 @hono/zod-openapi prettier eslint typescript-eslint;

8. フロントエンドとサーバーサイドをつなぐコードを追加する

   1
   import { createFileRoute, useRouter } from '@tanstack/react-router'
   2
   ...
   3
   import { createServerFn } from '@tanstack/start'
   4
   
   5
   import { parseTodoId, parseTodo } from '../domain/todo/domain'
   6
   import { readTodos, completeTodo, createTodo } from '../domain/todo/usecase'
   7
   import { todoRepository } from '../domain/todo/infra/repo'
   8
   
   9
   const getTodos = createServerFn({ method: 'GET' }).handler(async () => {
   10
      const data = await readTodos(todoRepository)
   11
      return data.map((x) => ({
   12
        ...x,
   13
        id: x.id as number,
   14
      }))
   15
     }
   16
   )
   17
   
   18
   const updateTodo = createServerFn({ method: 'POST' })
   19
     .validator((data: number) => data)
   20
     .handler(async ({ data }) => {
   21
       await completeTodo(todoRepository, parseTodoId(data))
   22
     })
   23
   
   24
   const addTodo = createServerFn({ method: 'POST' })
   25
     .validator((data: string) => data)
   26
     .handler(async ({ data }) => {
   27
       await createTodo(todoRepository, data)
   28
     })
   29
   
   30
   export const Route = createFileRoute('/todos')({
   31
     loader: async () => (await getTodos()).map((x) => parseTodo(x)),
   32
     component: Todos,
   33
   })
   34
   
   35
   function Todos() {
   36
      const { data, isPending, error } = useGetTodos();
   37
      const { mutate } = usePatchTodo();
   38
      const router = useRouter()
   39
      const data = Route.useLoaderData()
   40
   
   41
      const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
   42
        const id = e.target.value
   43
        mutate({ id: Number(id), done: e.target.checked });
   44
        updateTodo({ data: Number(id) }).then(() => router.invalidate())
   45
      }
   46
   
   47
     if (isPending) {
   48
       return <div>Loading... </div>;
   49
     }
   50
   
   51
     if (error) {
   52
       return <div>Error: {error.message}</div>;
   53
     }
   54
   
   55
     ...
   56
   }
   57
   
   58
   function TodoForm() {
   59
     ...
   60
   
   61
     const router = useRouter()
   62
   
   63
     const submitForm: SubmitHandler<FormData> = (data) => {
   64
       if (!data.title) return
   65
          mutate({ title: data.title }, { onSuccess: () => reset() })
   66
          addTodo({ data: data.title }).then(() => {
   67
            router.invalidate()
   68
            reset()
   69
          })
   70
     }
   71
   
   72
     ...
   73
   }

9. http://localhost:3000/todos で動作確認