フロントエンドとバックエンドのコミュニケーションをスムーズにするスキーマ駆動開発

Transcript

1. フロントエンドとバックエンドのコミュニケーション をスムーズにするスキーマ駆動開発 エンジニアの輪@東京 2023/12/10 @shimakaze_soft shimakaze-soft 1
2. Who are you? おまえだれよ? Twitter: @shimakaze_soft GitHub: shimakaze-git toB系のプロダクトを開発するスタートアップでテックリード的な立場 趣味 サッカー観戦 歴史 shimakaze-soft 2
3. バックエンド & インフラエンジニア Django, FastAPI Pulumi OSS PyConJP 2023 当日Staff DjangoCongress 2018~2021(Staff) shimakaze-soft 3
4. スキーマ駆動開発ってご存知ですか？ shimakaze-soft 4
5. フロントエンドとバックエンドのエンジニア間でこん なやり取りありませんか？ shimakaze-soft 5
6. フロントエンド バックエンドエンジニアが作成したAPIのレスポンスとリクエストボディのスキー マが複雑すぎてフロントの実装が大変 バックエンド フロントエンドが要求したスキーマがかなり複雑すぎて、バックエンドの処理が 大変すぎる。パフォーマンスの観点でもあまり良くないスキーマを要求される。 shimakaze-soft 6
7. 例 : ユーザーの一覧のページを作成するとする shimakaze-soft 7
8. フロントエンドエンジニアが欲しいレスポンスのスキ ーマ { "users": [ { "id": 1, "name": "test1" }, { "id": 2, "name": "test2" } ] } shimakaze-soft 8
9. バックエンドエンジニアが作成したレスポンスのスキ ーマ { "ids": [ 1, 2 ], "names": [ "test1", "test2" ] } shimakaze-soft 9
10. フロントエンド側の整形処理がかなり大変になる { "ids": [ 1, 2 ], "names": [ "test1", "test2" ] } shimakaze-soft 10
11. shimakaze-soft 11
12. APIのスキーマをどうするかは揉めがち shimakaze-soft 12
13. API全般の開発の主導権はバックエンドエンジニアが持つ事が多い ビジネスロジックをどちらで持つかにも関わる パフォーマンスの観点で最適なスキーマもある バックエンド主導のスキーマに決まりやすい shimakaze-soft 13
14. フロントエンドとバックエンドのスキーマの違いがも たらす課題 バックエンドがAPIが完成するまでAPIを叩くところの実装を待たなければいけな い こういうレスポンスが返ってくる。こういうリクエストボディを投げるという想定 で実装しなければいけない 実際に作られたAPIのスキーマが事前に話し合われたものと違った shimakaze-soft 14
15. どう解決する？ shimakaze-soft 15
16. API設計書をExcelで作る？ API設計書と実際の実装が違っていたら？それをどうやって確認す る？ shimakaze-soft 16
17. OpenAPIによるスキーマ駆動開発 shimakaze-soft 17
18. OpenAPIとは shimakaze-soft 18
19. OpenAPIとは 旧称はSwaggerと呼ばれていた。 APIの設計、開発、および利用に関する標準化された仕様の一つ。 この仕様は、RESTfulなAPIの記述を可能にし、APIのエンドポイント、リクエスト・レ スポンスの形式、認証方法などを文書化するための仕様。 JSONやYAML形式でAPIの設計情報を表現し、開発者やクライアントが理解しやすい 形でAPIを提供することができます。 OpenAPIの仕様に基づいてドキュメントを生成す るツールも提供されている。 shimakaze-soft 19
20. /api/users というエンドポイントを想定 openapi: 3.0.0 info: title: Sample API Response version: 1.0.0 paths: /users: get: summary: Get Users responses: '200': description: Successful response content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer example: 1 name: type: string example: "test" shimakaze-soft 20
21. モックのAPIを構築できる OpenAPIのファイルを元にモックサーバーを構築できる version: "3" services: mock: image: stoplight/prism:3 container_name: auth_api_mock platform: linux/amd64 tty: true ports: - 7501:4010 volumes: - ./openapi/openapi.yml:/openapi.yml:cached command: | mock -h 0.0.0.0 /openapi.yml shimakaze-soft 21
22. 実際にAPIにリクエストを行う $ curl 'http://localhost:7501/users' エンドポイントで以下が返ってくる { users: [ {"id": 1, "name": "test"}, {"id": 2, "name": "test"}, ] } shimakaze-soft 22
23. フロントエンドエンジニアもAPI設計をする shimakaze-soft 23
24. 具体的な開発プロセス YMLでOpenAPI形式のAPIのスキーマを定義する そのファイルをGitHubのPRに出す shimakaze-soft 24
25. PRを出す際のルール フロントエンドの人が作成した場合はバックエンドの人がReview バックエンドの人が作成した場合はフロントエンドの人がReview 必ずバックエンドとフロントエンドの両者がPRを見る PRがマージされた = そのスキーマにお互いが合意した shimakaze-soft 25
26. 急遽スキーマを変更したくなる場合がある バックエンドの実装を修正せずに、スキーマを修正してフロントエンドの実装が 可能 shimakaze-soft 26
27. ymlのスキーマとバックエンドの実装の差分をどうす るか 設計書として作成したymlのスキーマとバックエンドの実際の実装に差分が出る可能性 の問題どうする？ shimakaze-soft 27
28. OpenAPIの差分比較ツールを使用 shimakaze-soft 28
29. oasdiff 二つのOpenAPI形式のファイルを比較して差分がないかをチェックしてくれるツール # Mac $ brew tap tufin/homebrew-tufin $ brew install oasdiff $ go install github.com/tufin/oasdiff@latest shimakaze-soft 29
30. バックエンドの実装からスキーマを取り出す 今回はFastAPIを想定 shimakaze-soft 30
31. FastAPIにはOpenAPIの機能がデフォルトである shimakaze-soft 31
32. FastAPIにはOpenAPIの機能がデフォルトである openapi.json をダウンロード' shimakaze-soft 32
33. oasdiffを使用して差分を比較する $ oasdiff diff openapi.json openapi.yml --format text shimakaze-soft 33
34. 実装とスキーマに差分が出る New Endpoints: 10 PUT /api/users GET /api/usrs Deleted Endpoints: None Modified Endpoints: None GET /api/users/{usre_id} Responses changed Modified response: 200 Content changed Modified media type: application/json Schema changed Properties changed Modified property: general Required changed New required property: stores Deleted required property: store Properties changed New property: stores Deleted property: store shimakaze-soft 34
35. apidog apidogというツールもおすすめ https://apidog.com/jp/ shimakaze-soft 35
36. エンジニア募集 技術スタック バックエンド: Django, FastAPI フロントエンド: Next.js, Typescript インフラ: AWS, Pulumi https://jobs.forkwell.com/recustomer/jobs/23462 shimakaze-soft 36