型付き API リクエストを実現するいくつかの手法とその選択 / Typed API Request

TSKaigi Kansai 2024 https://kansai.tskaigi.org/talks/euxn23

Transcript

1. 型付きAPIリクエストを実現する いくつかの手法とその選択 Presented by ユーン @TSKaigi Kansai 2024
2. 自己紹介 ユーン (@euxn23) ドワンゴ教育事業のエンジニア ZEN ID という認証基盤を作っています Web フロント 前段バックエンド (TypeScript) RABBIT 小隊が好き
3. 2025年4月 ZEN大学 開学
5. このセッションでは、 安全な API リクエストを実現する いくつかの手法を紹介します
6. API 連携の安全性確保のための手法 コードファーストでない API 仕様書 (NOT OpenAPI) を書く 結合テストを増やす 監視で異常系を発見する コードファーストな 実装や定義を共有する OpenAPI を実装と結びつける フレームワークの機能に乗る
7. コードファーストでない API 連携の課題 API 仕様書 → 仕様と実装の乖離 結合テスト → テストケースが多い 監視 → 発見までにエラーは発生してしまう
8. コードファーストにするとどう解決されるか API仕様書 → 仕様 (OpenAPI) と実装が関連付く、型により守られる 結合テスト → 型で表現できるレベルのテストケースは省略可能になる 監視 → 型によりコーディングタイムでバグを発見しやすくなる
9. コードファーストなアプローチを考える
10. コードファーストなアプローチ TypeScript ファーストな手法 型定義の共有 Zod スキーマの共有 フレームワークの機能の利用 Hono RPC tRPC 言語に依存しない手法 サーバコードから OpenAPI を 自動生成 OpenAPI からクライアントコードを 自動生成
11. コードファーストなアプローチ TypeScript ファーストな手法 型定義の共有 Zod スキーマの共有 フレームワークの機能の利用 Hono RPC tRPC 言語に依存しない手法 サーバコードから OpenAPI を 自動生成 OpenAPI からクライアントコードを 自動生成
12. 注意: ほとんどのケースで monorepo を前提とします
13. サーバ側の型定義 1. 型定義の共有 export type GetPetRequest = { param: { id: string } }; export type GetPetResponse = Pet; export type PostPetRequest = { body: Pet }; export type PostPetRequest = never;
14. クライアント側の実装 1. 型定義の共有 import type { GetPetRequest, GetPetResponse, PostPetRequest, PostPetResponse } from '@/server'; export async function requestGetPet(req: GetPetRequest): Promise<GetPetResponse> { return fetch(`/api/pets/${req.param.id}`).then(res => res.json()); } export async function requestPostPet(req: PostPetRequest): Promise<PostPetResponse> { return fetch(`/api/pets`, { method: 'POST', body: JSON.stringify(req.body) }) .then(res => res.json()); } const pet = await requestGetPet({ param: { id: '1' } }); const newPet = { // ... }; await requestPostPet({ body: newPet });
15. 1. 型定義の共有 Pros 外部ライブラリや特別な設計に 依存しないので簡単に始めやすい Cons fetch の中は型がわからないまま 書くしかない API client のレイヤが別れている 必要がある
16. 共通コード 2. Zod スキーマの共有 const PetTagSchema = z.object({ id: z.number(), name: z.string(), }); const PetSchema = z.object({ id: z.string(), name: z.string(), tags: z.array(PetTagSchema), }); https://github.com/colinhacks/zod
17. クライアント側の実装 2. Zod スキーマの共有 async function postPet(pet: z.infer<typeof PetSchema>): Promise<void> { const result = PetSchema.safeParse(pet); if (!result.success) { throw new Error('Invalid pet'); } await fetch('/api/pets', { method: 'POST', body: JSON.stringify(pet) }); }
18. サーバ側の実装(例: Express) 2. Zod スキーマの共有 app.post('/pets', async (req, res) => { const result = PetSchema.safeParse(req.body); if (!result.success) { res.status(400).json(result.error); return; } const pet = result.data; const inserted = await insertPet(pet) res.json(inserted); return; });
19. 2. Zod スキーマの共有 Pros バリデーションと型定義が一致する バリデーションロジックごと サーバ・クライアントで共有できる Cons schema のプロパティ変更は infer した型の変数には波及しないため、 type で引き回す方が良い 型定義と Zod の Schema の二重管理 が発生するが、乖離を防ぐため次の ような工夫が必要
20. 工夫の例 export type PetTag = { id: number; name: string; }; export type Pet = { id: string; name: string; tags: PetTag[]; }; const PetTagSchema = z.object({ id: z.number(), name: z.string(), }) satisfies ZodType<PetTag>; const PetSchema = z.object({ id: z.string(), name: z.string(), tags: z.array(PetTagSchema), }) satisfies ZodType<Pet>;
21. 3. フレームワークの機能の利用 - Hono RPC const route = app.post( '/posts', zValidator( 'form', z.object({ title: z.string(), body: z.string(), }) ), (c) => { // ... return c.json({ ok: true, message: 'Created!', }, 201) } ) export type AppType = typeof route https://hono.dev/docs/guides/rpc
22. 3. フレームワークの機能の利用 - Hono RPC import { AppType } from '.' import { hc } from 'hono/client' const client = hc<AppType>('http://localhost:8787/') const res = await client.posts.$post({ form: { title: 'Hello', body: 'Hono is a cool project', }, }) if (res.ok) { const data = await res.json() console.log(data.message) }
23. TypeScript ファーストな手法 Pros コードの共有から小さく始めやすい フレームワークの機能に乗れると 高速に開発ができる Cons TypeScript であることに強く依存 → 片方を別の言語で書き換えると、   安全性は失われてしまう
24. TypeScript に依存してしまっては、 柔軟さか安全さのどちらかが将来失われてしまう
25. アバンパート終了
26. どうする！？ TypeScript と心中するか！？
27. 突如そこに OpenAPI が！
28. OpenAPI ベースな 型付き API リクエスト
29. コードファーストなアプローチ 言語に依存しない手法 サーバコードから OpenAPI を 自動生成 OpenAPI からクライアントコードを 自動生成 TypeScript ファーストな手法 型定義の共有 Zod スキーマの共有 フレームワークの機能の利用 Hono RPC tRPC
30. OpenAPI のよいところ 言語非依存 仕様が標準化されている エコシステムが成熟しており、各言語にツールがある 既存の実装を損なわずに採用できるケースがままある etc…
31. なぜ gRPC や GraphQL ではないか gRPC HTTP/2 が必要 プロトコルバッファの表現力の問題 Go まわり以外、エコシステムがあまり成熟していない GraphQL そもそもが根本的に難しい バックエンドの実装負担が大きい 既存の実装を GraphQL 化するのは難しい
32. OpenAPIと実装を繋ぐ手法 サーバコードから OpenAPI を生成 OpenAPI から API クライアントを生成 OpenAPI からサーバコードを生成
33. サーバコードから OpenAPI を自動生成
34. サーバコードから OpenAPI を 生成する機能を持つフレームワーク NestJS Hono (@hono/zod-openapi) FastAPI (Python) etc… サーバコードから OpenAPI を生成
35. NestJS のサンプルコード export class Cat { /** * The name of the Cat * @example Kitty */ name: string; @ApiProperty({ example: 1, description: 'The age of the Cat' }) age: number; @ApiProperty({ example: 'Maine Coon', description: 'The breed of the Cat', }) breed: string; } https://github.com/nestjs/nest/tree/master/sample/11-swagger
36. @ApiBearerAuth() @ApiTags('cats') @Controller('cats') export class CatsController { constructor(private readonly catsService: CatsService) {} @Post() @ApiOperation({ summary: 'Create cat' }) @ApiResponse({ status: 403, description: 'Forbidden.' }) async create(@Body() createCatDto: CreateCatDto): Promise<Cat> { return this.catsService.create(createCatDto); } @Get(':id') @ApiResponse({ status: 200, description: 'The found record', type: Cat, }) findOne(@Param('id') id: string): Cat { return this.catsService.findOne(+id); } }
37. @hono/zod-openapi のサンプルコード const route = createRoute({ method: 'get', path: '/users/{id}', request: { params: ParamsSchema, }, responses: { 200: { content: { 'application/json': { schema: UserSchema, }, }, description: 'Retrieve the user', }, }, }) https://hono.dev/examples/zod-openapi
38. const app = new OpenAPIHono() app.openapi(route, (c) => { const { id } = c.req.valid('param') return c.json({ id, age: 20, name: 'Ultra-man', }) }) // The OpenAPI documentation will be available at /doc app.doc('/doc', { openapi: '3.0.0', info: { version: '1.0.0', title: 'My API', }, })
39. FastAPI の例は省略 (Pythonなので)
40. サーバ実装から OpenAPI を生成することの是非 Pros 仕様と実装が一致する 常に最新になる OpenAPI を手書きしなくてよい Cons 実装を変更しないと OpenAPI を変更 できない まだ実装されていないが変更予定 のものを OpenAPI にしにくい OpenAPI を中心として議論しにく い
41. 誰がOpenAPIを書くか (=API仕様を決めるか) に応じて選択しましょう → みんなで書くなら実装ベースじゃない方が 議論もしやすい
42. OpenAPI から API クライアントを生成
43. OpenAPI から API クライアントを 生成するライブラリ openapi-fetch orval etc…
44. openapi-typescript / openapi-fetch openapi-typescript は OpenAPI から TS コードを生成 openapi-fetch はこれを元に API Client コードを生成 https://openapi-ts.dev/ https://openapi-ts.dev/openapi-fetch/
45. openapi-typescript のサンプルコード import { paths, components } from "./path/to/my/schema"; // <- generated by openapi-typescript // Schema Obj type MyType = components["schemas"]["MyType"]; // Path params type EndpointParams = paths["/my/endpoint"]["parameters"]; // Response obj type SuccessResponse = paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"] type ErrorResponse = paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"][" https://openapi-ts.dev/introduction
46. openapi-fetch のサンプルコード import createClient from "openapi-fetch"; import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" }); const { data, // only present if 2XX response error, // only present if 4XX or 5XX response } = await client.GET("/blogposts/{post_id}", { params: { path: { post_id: "123" }, }, }); await client.PUT("/blogposts", { body: { title: "My New Post", }, }); https://openapi-ts.dev/openapi-fetch/
47. orval Axios ベースの API Client コードを生成 TanStack Query や SWR、Zod との連携もある https://orval.dev/
48. orval のサンプルコード import type { CreatePetsBody } from '../model'; import { customInstance } from '../mutator/custom-instance'; export const createPets = ( createPetsBody: CreatePetsBody, version: number = 1, ) => { return customInstance<void>({ url: `/v${version}/pets`, method: 'POST', headers: { 'Content-Type': 'application/json' }, data: createPetsBody, }); }; https://github.com/anymaniax/orval/blob/master/samples/react-app
49. OpenAPI から API クライアントを生成 Pros 実装が変わった際に型エラーで 検知できる エンドポイントのパスや パスパラメータも 補完・チェックできる Cons OpenAPI を実装から生成していない 場合、実装との乖離は起こりうる
50. OpenAPI からサーバコードを生成
51. 残念ながら、TS ではメジャーな(十分枯れた)ものはない 例えば golang なら oapi-codegen や ogen などがある ogen は interface を生成、それに合わせて実装する レイヤが別れるので後入れは難しい、開発初期なら検討の余地あり OpenAPI からサーバコードを生成
52. Q. ところで OpenAPI は yaml を手書きするの？ A. OpenAPI を書くための次世代 DSL、TypeSpec がある
53. TypeSpec TypeScript / C# 風味の DSL で OpenAPI Schema を書けるライブラリ LanguageServer を提供されており、VSCode 向けにプラグインを提供 コンパイル時に valid な記法か確認されるので安心 https://typespec.io/
54. import "@typespec/http"; using TypeSpec.Http; model PetTag { id: number; name: string; }; model Pet { id: string; name: string; tags: PetTag[]; } @route("/pets/{id}") interface Stores { @opetationId("get-pet") @summary("Get a pet by ID") @get get(@path id: string): { @statusCode statusCode: 200; @body Pet; }; }
55. yaml 手書きと比べて 複雑でない module システムを備え、ファイルの分割や再利用が容易 デフォルト値が設定されているものは省略可能であり、文量が少ない monorepoにも対応、別パッケージの定義を参照することも可能
56. まとめ サーバとクライアントの TS コード共有は楽だが、 結合レイヤの TS 依存はリスクである 結合レイヤはエコシステムが充実しており、 言語非依存の OpenAPI を用いるのが良いのではないか OpenAPI により仕様と実装を近づけることで コード面の安全性や開発効率の向上が期待できる
57. Q. OpenAPI とバックエンドの乖離はどうするの？ A. テストケースを書いて頑張ろう(ここは課題です) 結局バックエンドの実装と仕様を一致させるのが一番大変ですよね でも、乖離しうる箇所を減らせているだけでも大きな進歩です テスト用のクライアントコードを OpenAPI から生成するなどして頑張りましょう 想定質問
58. Any question?
59. ドワンゴのスポンサーブースにいます、遊びに来てね 質問やディスカッションも大歓迎
60. ありがとうございました
61. Appendix: 過去に話した関連する登壇資料 NestJS アプリケーションから Swagger を自動生成する Powerfully Typed TypeScript TypeSpec を使い倒してる
62. Appendix: 関連する有益な参考資料 WebフロントエンドにおけるGraphQL（あるいはバックエンドのAPI）と の向き合い方 見よ、これがHonoのRPCだ Hono × Zod-OpenAPIで快適API開発 最近のGoのOpenAPI Generatorの推しはogen