aspidaで型安全にREST APIのバックエンドを呼び出したい

Transcript

1. aspidaで型安全にREST APIの バックエンドを呼び出したい ひがき 2024/07/20 PHP"オレ"カンファレンス神戸
2. 自己紹介 ひがき 💻 PHP書いたり、TypeScript書いたり、Terraform書いたりしてます！ 💻 バックエンド書くことが多いです 💻 最近関数型にすごく興味があります 💻 1年くらいPHP書いてなかったけど、これからPHP書く機会が増えそうなので参加しました！ 🗼 2020年 - 2021年 まで神戸の板宿に住んでおりました！（神戸いい街） ♠️‍ 最近ポーカー始めました、オールイン！！！ X @higaki_program
3. 目次 はじめに aspidaとは 今回使用するAPIの説明 aspidaを使わずにAPIを呼び出した場合（私がやっていたやり方） aspidaを使ってAPIを呼び出した場合 まとめ
4. はじめに PHPの話はあんまりないです、、、 aspidaがいいよーって話です 他のライブラリの話はしません
5. aspidaとは クライアント側で REST API を呼び出す時に便利なOSS！ リクエストのパラメータ、パス、レスポンスを型で担保してくれます（すごく嬉しい） axios / fetch / node-fetch の version があります 引用元：https://github.com/aspida/aspida/tree/main?tab=readme-ov-file#features
6. ちなみに axios: Node.jsやブラウザなど実行環境を意識せずに使用できるHTTPクライアントライブラリ fetch: ブラウザ標準のAPI node-fetch: ブラウザAPIのfetchをNode.jsで使用できるようにするためのライブラリ
7. こんなAPIがあったとします よくあるAPI GET: http://localhost/api/phpers PHPer一覧 GET: http://localhost/api/phpers/{id} PHPer詳細 POST: http://localhost/api/phpers PHPer登録 PUT: http://localhost/api/phpers/{id} PHPer更新 DELETE: http://localhost/api/phpers/{id} PHPer削除 GET: http://localhost/api/lunch-shops 神戸の美味しいランチのお店一覧 GET: http://localhost/api/lunch- shops/{id} 神戸の美味しいランチのお店の詳細
8. こんなAPIがあったとします
9. こんなAPIがあったとします
10. APIを呼び出す前の準備 を実行した後のdirectoryを想定しています $ yarn create react-app frontend-fetch . ├── node_modules │ ├── ... ├── README.md ├── package.json ├── public │ ├── ... ├── src │ ├── App.ts │ ├── index.ts │ ├── ... └── yarn.lock
11. 注意点!! ここから先ツッコミどころ満載かと思いますが、新喜劇を見る気持ちでお願いします
12. aspidaを使わずに呼び出す（私のやっていたやり方） App.tsx APIを呼び出すフロントエンドのファイル ... export const App = () => { const createPHPer = async () => { try { // FIXME ここでAPI呼び出す } catch (error) { // エラー処理 } }; return (...); }
13. aspidaを使わずに呼び出す（私のやっていたやり方） App.tsx APIを呼び出すフロントエンドのファイル // FIXME ここでAPI呼び出す ... export const App = () => { const createPHPer = async () => { try { } catch (error) { // エラー処理 } }; return (...); }
14. aspidaを使わずに呼び出す（私のやっていたやり方） よし、書いていくぞ！ // FIXME ここでAPI呼び出す
15. aspidaを使わずに呼び出す（私のやっていたやり方） axios 使って呼び出すぞ！！ const response = await axios.post();
16. aspidaを使わずに呼び出す（私のやっていたやり方） いいぞいいぞ！ const response = await axios.post(`http://localhost/api`);
17. aspidaを使わずに呼び出す（私のやっていたやり方） phper を作成するんだったな const response = await axios.post(`http://localhost/api/phper`);
18. aspidaを使わずに呼び出す（私のやっていたやり方） うわ、、、 any じゃん リクエストパラメータに何渡すんだっけ？ 名前 と メールアドレス だし phperName と email やったはず、、、 const response = await axios.post(`http://localhost/api/phper`, { phperName: "神戸 太郎", email: "kobe-taro@phper.com", });
19. aspidaを使わずに呼び出す（私のやっていたやり方） 出力して中身を見るとする また any かよ const response = await axios.post(`http://localhost/api/phper`, { phperName: "神戸 太郎", email: "kobe-taro@phper.com", }); console.log(response.data.);
20. aspidaを使わずに呼び出す（私のやっていたやり方） でけた！！！ ・・・・あれ？動かね、、、、 const response = await axios.post(`http://localhost/api/phper`, { phperName: "神戸 太郎", email: "kobe-taro@phper.com", }); console.log(response.data.phperName);
21. aspidaを使わずに呼び出す（私のやっていたやり方） うわ、色々ミスってるじゃん、、、 URL （誤）http://localhost/api/phper （正）http://localhost/api/phpers リクエストパラメータ （誤）phperName: "神戸 太郎", （正）familyName: "神戸", givenName: "太郎", レスポンス （誤）response.data.phperName （正）response.data.message const response = await axios.post(`http://localhost/api/phper`, { phperName: "神戸 太郎", email: "kobe-taro@phper.com", }); console.log(response.data.phperName);
22. aspidaを使わずに呼び出す（私のやっていたやり方） ここまでひどくはないと思いますが、 似たようなミスを経験した人いるんじゃないでしょうか
23. aspida を使用すると どうなるのか見てみましょう
24. aspidaを使って呼び出す（自力ファイル作成編） ... export const App = () => { const createPHPer = async () => { try { // FIXME ここでAPI呼び出す } catch (error) { // エラー処理 } }; return (...); } App.tsx
25. aspidaを使って呼び出す（自力ファイル作成編） aspidaクライアントを用いてAPIを呼び出します （作成方法は後述します） App.tsx import api from "./apiClient"; ... export const App = () => { const createPHPer = async () => {　 try { // FIXME ここでAPI呼び出す } catch (error) { // エラー処理 } }; return (...); }
26. aspidaを使って呼び出す（自力ファイル作成編） aspidaクライアントを用いてAPIを呼び出します （作成方法は後述します） App.tsx import api from "./apiClient"; // FIXME ここでAPI呼び出す ... export const App = () => { const createPHPer = async () => {　 try { } catch (error) { // エラー処理 } }; return (...); }
27. aspidaを使って呼び出す（自力ファイル作成編） 書いていく // FIXME ここでAPI呼び出す
28. aspidaを使って呼び出す（自力ファイル作成編） const response = await api.
29. aspidaを使って呼び出す（自力ファイル作成編） const response = await api.phpers.
30. aspidaを使って呼び出す（自力ファイル作成編） const response = await api.phpers.$post()
31. aspidaを使って呼び出す（自力ファイル作成編） const response = await api.phpers.$post({body: {}})
32. aspidaを使って呼び出す（自力ファイル作成編） const response = await api.phpers.$post({body: { email: "example@phper.com", family_name: "神戸", given_name: "太郎", }}); console.log(response.)
33. aspidaを使って呼び出す（自力ファイル作成編） おお！！ なんと便利なことか
34. どうやったらaspida使えるようになるの？？
35. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
36. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
37. aspidaを使って呼び出す（自力ファイル作成編） 1. aspida の インストール 今回は axios を使用してAPIを呼び出すことにします $ yarn add aspida @aspida/axios axios
38. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
39. aspidaを使って呼び出す（自力ファイル作成編） 2. aspida 設定ファイル作成 aspida.config.js を作成し、 input に (型定義のroot directory) を設定します 今回は src/api_type とします module.exports = { input: "src/api_type", }; │ ├── aspida.config.js . ├── ... │ ├── ... ├── src │ ├── App.ts │ ├── index.ts │ ├── ... └── yarn.lock
40. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
41. aspidaを使って呼び出す（自力ファイル作成編） 3. APIエンドポイントの型定義ファイル作成 型定義ファイルまでのディレクトリの階層構造がそのままAPI呼び出しのパスになります │ ├── api_type │ │ ├── lunch-shops │ │ │ ├── _id@number │ │ │ │ └── index.ts │ │ │ └── index.ts │ │ └── phpers │ │ ├── _id@number │ │ │ └── index.ts │ │ └── index.ts . ├── ... │ ├── ... ├── src │ │ ├── @types │ │ │ └── index.ts │ ├── App.ts │ ├── index.ts │ ├── aspida.config.js
42. aspidaを使って呼び出す（自力ファイル作成編） 3. APIエンドポイントの型定義ファイル作成 GET, POST: http://localhost/api/phpers src/api_type/phpers/index.ts post: { status: 201 resBody: { message: string } reqBody: { family_name: string given_name: string email: string attends?: { location: '北海道' | '関西' | '東京' | '小田原' | '香川 year: number }[] | null | undefined } } import type * as Types from '../@types' export type Methods = { get: { status: 200 resBody: Types.PHPerListResource[] // 説明省略 } // →　に記載 post: { ... } }
43. aspidaを使って呼び出す（自力ファイル作成編） 3. APIエンドポイントの型定義ファイル作成 GET: http://localhost/api/lunch-shops/{id} src/api_type/lunch-shops/_id@number/index.ts ※ パスパラメータは _ を先頭につける ※ @ で number 型 string 型を明示する（ @ 以降をつけない場合は number|string ） import type * as Types from '../../@types' export type Methods = { get: { status: 200 resBody: Types.LunchShopShowResource // → に詳細記載 } } // src/api_type/@types/index.ts export type LunchShopShowResource = { id: string name: string zip_code: string prefecture: string city: string address: string floor?: string | null | undefined }
44. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
45. aspidaを使って呼び出す（自力ファイル作成編） 4. ビルド package.json に ビルド用のコマンドを追加し、実行します "scripts": { ... "api:build": "aspida" // 追加 } これで (型定義のroot directory)/$api.ts が作成されます $ yarn api:build
46. aspidaを使って呼び出す（自力ファイル作成編） 4. ビルド │ │ ├── $api.ts . ├── ... │ ├── ... ├── src │ ├── api_type │ │ ├── @types │ │ │ └── index.ts │ │ ├── lunch-shops │ │ │ ├── _id@number │ │ │ │ └── index.ts │ │ │ └── index.ts │ │ └── phpers │ │ ├── _id@number │ │ │ └── index.ts │ │ └── index.ts │ ├── App.ts │ ├── index.ts │ ├── aspida.config.js │ ├── ... └── yarn.lock
47. aspidaを使って呼び出す（自力ファイル作成編） 手順 1. aspida の インストール 2. aspida 設定ファイル作成 3. APIエンドポイントの型定義ファイル作成 4. ビルド 5. aspidaクライアントを作成
48. aspidaを使って呼び出す（自力ファイル作成編） 5. aspidaクライアントを作成 ビルドで作成された $api.ts を用いて aspidaクライアントを作成します baseURL にはAPI呼び出し先のURLを記載します apiClient.ts import api from './api_type/$api'; import aspida from '@aspida/axios'; import axios from "axios"; const apiClient = api( aspida(axios, { baseURL: 'http://localhost/api', }) ); export default apiClient;
49. aspidaを使って呼び出す（自力ファイル作成編） 5. aspidaクライアントを作成 ビルドで作成された $api.ts を用いて aspidaクライアントを作成します baseURL にはAPI呼び出し先のURLを記載します apiClient.ts baseURL: 'http://localhost/api', import api from './api_type/$api'; import aspida from '@aspida/axios'; import axios from "axios"; const apiClient = api( aspida(axios, { }) ); export default apiClient;
50. aspidaを使って呼び出す（自力ファイル作成編） 5. aspidaクライアントを作成 │ ├── apiClient.ts . ├── ... │ ├── ... ├── src │ ├── api_type │ │ ├── $api.ts │ │ ├── @types │ │ │ └── index.ts │ │ ├── lunch-shops │ │ │ ├── _id@number │ │ │ │ └── index.ts │ │ │ └── index.ts │ │ └── phpers │ │ ├── _id@number │ │ │ └── index.ts │ │ └── index.ts │ ├── App.ts │ ├── index.ts │ ├── aspida.config.js │ ├── ... └── yarn.lock
51. aspidaを使って呼び出す（自力ファイル作成編） いや、でも APIエンドポイントの型定義ファイル作成を自力で作るのすごく面倒だな、、、 これ自動で作ってほしいな、、、
52. OpenAPI から自動で型情報ファイルを作成できます！！
53. aspidaを使って呼び出す（OpenAPI経由編） openapi2aspida を使用することで、 OpenAPI から自動で型情報ファイルを作成できます！！
54. aspidaを使って呼び出す（OpenAPI経由編） 手順 1. aspida の設定変更 2. openapi2aspida による型情報ファイルの作成
55. aspidaを使って呼び出す（OpenAPI経由編） 手順 1. aspida の設定変更 2. openapi2aspida による型情報ファイルの作成
56. aspidaを使って呼び出す（OpenAPI経由編） 1. aspida の設定変更 aspida.config.js に openapi を追加し、OpenAPIのjson、yamlファイルを指定します ※ OpenAPIのjsonファイルを返却するURLの指定でも大丈夫です openapi: { inputFile: "./openapi.yaml" }, module.exports = { input: "src/api_type", baseURL: "http://localhost/api", }; openapi: { inputFile: "http://localhost/docs/api.json" }, module.exports = { input: "src/api_type", baseURL: "http://localhost/api", };
57. aspidaを使って呼び出す（OpenAPI経由編） 手順 1. aspida の設定変更 2. openapi2aspida による型情報ファイルの作成
58. aspidaを使って呼び出す（OpenAPI経由編） 2. openapi2aspida による型情報ファイルの作成 openapi2aspida を呼び出すことで型情報ファイルが自動で作成されます $ npx openapi2aspida ※ openapi2aspida のパッケージをインストールして呼び出しても良いです
59. 自動で型情報作ってくれるのね！！ 良いじゃん！！！
60. 欲張り言いたい
61. エンドポイントが大量にあるシステムだと 可読性が悪くなったり、該当のAPI見つけるの大変かもーー
62. aspidaクライアントが呼び出すことができる エンドポイントを絞ることができます
63. aspidaを使って呼び出す（エンドポイント絞る編） 今回は、「神戸の美味しいランチのお店に関するエンドポイントのみ」 を呼び出すaspidaクライアントを作成します
64. aspidaを使って呼び出す（エンドポイント絞る編） 手順 1. aspida の設定変更 2. ビルド 3. エンドポイントを絞った aspida クライアントを作成 4. API呼び出し
65. aspidaを使って呼び出す（エンドポイント絞る編） 手順 1. aspida の設定変更 2. ビルド 3. エンドポイントを絞った aspida クライアントを作成 4. API呼び出し
66. aspidaを使って呼び出す（エンドポイント絞る編） 1. aspida の設定変更 aspida.config.js に outputEachDir を追加 outputEachDir: true, module.exports = { input: "src/api_type", baseURL: "http://localhost/api", openapi: { inputFile: "./openapi.yaml" }, };
67. aspidaを使って呼び出す（エンドポイント絞る編） 手順 1. aspida の設定変更 2. ビルド 3. エンドポイントを絞った aspida クライアントを作成 4. API呼び出し
68. aspidaを使って呼び出す（エンドポイント絞る編） 2. ビルド 設定変更後に、ビルドをすることでそれぞれのディレクトリに $api.ts が作成されます $ yarn api:build │ │ ├── lunch-shops │ │ │ ├── $api.ts │ │ └── phpers │ │ ├── $api.ts . ├── ... │ ├── ... ├── src │ ├── api_type │ │ ├── $api.ts │ │ ├── @types │ │ │ └── index.ts │ │ │ ├── _id@number │ │ │ │ └── index.ts │ │ │ └── index.ts │ │ ├── _id@number │ │ │ └── index.ts
69. aspidaを使って呼び出す（エンドポイント絞る編） 手順 1. aspida の設定変更 2. ビルド 3. エンドポイントを絞った aspida クライアントを作成 4. API呼び出し
70. aspidaを使って呼び出す（エンドポイント絞る編） 3. エンドポイントを絞った aspida クライアントを作成 呼び出したいエンドポイントのdirectoryにある $api.ts を用いて aspidaクライアントを作成します apiLunchShopClient.ts import api from './api_type/lunch-shops/$api'; import aspida from '@aspida/axios'; import axios from "axios"; const apiClient = api( aspida(axios, { baseURL: 'http://localhost/api', }) ); export default apiClient;
71. aspidaを使って呼び出す（エンドポイント絞る編） 3. エンドポイントを絞った aspida クライアントを作成 │ ├── apiLunchShopClient.ts . ├── ... │ ├── ... ├── src │ ├── api_type │ │ ├── ... │ ├── App.ts │ ├── index.ts │ ├── apiClient.ts │ ├── aspida.config.js │ ├── ... └── yarn.lock
72. aspidaを使って呼び出す（エンドポイント絞る編） 手順 1. aspida の設定変更 2. ビルド 3. エンドポイントを絞った aspida クライアントを作成 4. API呼び出し
73. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し App.tsx import lunchShopApi from "./apiLunchShopClient"; ... export const App = () => { const createPHPer = async () => { ... }; const fetchLunchShop = async () => { try { // FIXME ここでAPI呼び出す } catch (error) { // エラー処理 } }; return (...); }
74. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し App.tsx import lunchShopApi from "./apiLunchShopClient"; ... export const App = () => { const createPHPer = async () => { ... }; const fetchLunchShop = async () => { try { // FIXME ここでAPI呼び出す } catch (error) { // エラー処理 } }; return (...); }
75. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し App.tsx // FIXME ここでAPI呼び出す import lunchShopApi from "./apiLunchShopClient"; ... export const App = () => { const createPHPer = async () => { ... }; const fetchLunchShop = async () => { try { } catch (error) { // エラー処理 } }; return (...); }
76. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し 書いていく // FIXME ここでAPI呼び出す
77. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し const response = await lunchShopApi.
78. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し const response = await lunchShopApi._id.
79. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し const response = await lunchShopApi._id.
80. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し const response = await lunchShopApi._id.$get();
81. aspidaを使って呼び出す（エンドポイント絞る編） 4. API呼び出し const response = await lunchShopApi._id.$get(); console.log(response.)
82. エンドポイント絞れた！！
83. まとめ 👍 色々と型がついてくれるのは開発しやすい 👍 エンドポイント絞れるのも地味にありがたい エンドポイント多いと辿るのも大変だし 😭 aspidaクライアントに設定できる項目は適切ではないかも、、、 method 設定した場合、axiosだと無視されるがfetchだと無視されないなどがある 😭 OpenAPIを記述していない大きめなシステムだとaspida入れるの辛そう Laravelとかだと scramble で大雑把にOpenAPI導入して、細かい部分を後追いで修正していく感じにな りそう Scramble Scramble is OpenAPI (Swagger) documentation generator for Laravel. It generates API documentation for your project automatically without requiring you to manually write PHPDoc annotations. https://scramble.dedoc.co/
84. aspidaおすすめ！！！
85. おわり