aspida is 何
端的に言うと、aspidaとは API のリクエスト/レスポンスに型を付与するライブラリのことです！！
API通信に型がつけられるのは画期的ですね。
aspidaを使えばどんな良いことがあるの？
最近のフロントエンド環境でREST APIリクエストを行う場合、axiosかfetchを使うことが多いかなと思います。
今回は型がつけられるメリットとして、axiosを使いながら例を出していきます。
その前に、そもそもaxiosって？
非同期のHTTP通信を簡単に実装することが出来る、Javascriptのライブラリのことです。
基本的なメソッドである、get,post,delete,putが用意されており便利です。
大体、Vue.jsを使ってる会社はこいつを使ってるなあという印象(前職も、現職も使ってる箇所があった)です。
aspidaを使わない場合
例を出していきます。
以下のようにaxiosで /blogs/:BlogID/?user={userId} をGETするケースを考えます。
interface Blog {
id: number
title: string
}
const blogID = 1
const userId = 2
const { data } = await axios.get<Blog>(
`/blog/${blogID}`,
{ params: { userId } }
)
axios.getで型引数がBlog型であることがわかると思います。
しかし、上記はurlに文字列を使用しているため型的に安全ではありません。
上記では2箇所ほどミスがあります。
interface Blog {
id: number
title: string
}
const blogID = 1
const userId = 2
const { data } = await axios.get<Blog>(
`/blog/${blogID}`, // params: { user: userID } } が正しい
{ params: { userId } } // blogではなくblog"s" タイプミス
)
axiosでは静的に上記のミスを検査することは不可能です。
axiosでGETする際のそもそもの問題点として
APIのパスをベタ打ちしているので、タイプミスに気づかないレスポンスの型がわからない。ジェネリクスを使わないとTypescriptでもanyになってしまう
といったものが大きいですし、解消することができません。
レスポンスの型についてはジェネリクスを使用して定義をしていますが、そもそもaspida
を使ってしまえばライブラリとしてサポートしてくれるので楽です！
実際にaspidaを使ってみよう
では使っていきましょう。
import { DefineMethods } from 'aspida'
type Blog = {
id: number
title: string
}
export type BlogInfo = DefineMethods<{
get: {
query: {
user: number
}
resBody: Blog
}
}>
上のような型定義をすることによって、/api以降のファイル名上をと含めて制約を作成することが出来ます。
- URLは
/blogs/:blogId - レスポンスはBlog型
- blogIdはnumber型
- Queryにnumber型のuserが必須
というHTTPクライアントが自動生成されます。
問題点で挙げた
APIのパスをベタ打ちしているので、タイプミスに気づかないレスポンスの型がわからない。ジェネリクスを使わないとTypescriptでもanyになってしまう
について解決できますね！
導入方法については上記URLのREAD.mdのGetting Startedを確認してください！
それでは、リクエスト方法について説明します！
const blogId = 1
const userId = 2
const blog = await aspida.blogs._blogID(blogId).$get({ query: { user: userId } })
上記の場合、blogIDやqueryの型を間違えるとエディタ上でエラーになります。
これならidとtitleの入力ミスも起きませんし、blogsをblogのタイポが起きず、queryのプロパティも間違えることがありません。
aspidaを使うことによってジェネリクスも独自関数も使用することなく型安全なAPIリクエストを行うことが出来ます！！
因みにメソッドの$を消すとステータスコードやヘッダも取得できます。
最後に
API通信で型定義出来るのは画期的だなあと思い、まとめさせて頂きました。
REST APIの型の安全性を担保するといった面でGraphQLとライバル的関係になるのかなと勝手に思ってます。
いつか、GraphQLについても記事でまとめてaspidaとの比較もしてみます！！
最後まで見て頂いてありがとうございました！
参考 記事/レポジトリ
HTTP通信をラクに実装できる「axios」の基本
TypeScript製REST APIクライアント「aspida」
aspidaのGithub