TypeScriptでAPI通信（Axios/Fetch）！外部データに安全に型をつける方法を初心者向けに徹底解説

1. API通信と外部データとは？

1. API通信と外部データとは？

まずは、パソコンの操作に慣れていない方に向けて、言葉の意味からお話しします。API通信とは、あなたが使っているパソコンやスマートフォンの画面から、インターネットの向こう側にある別のコンピューター（サーバーと呼びます）に必要な情報を頼んで、送ってもらう仕組みのことです。

たとえば、お天気アプリを開いたときに、今日の天気の情報が画面に表示されます。これは、アプリがインターネットを通じて「今日の天気を教えてください」とお願いし、データを受け取っているからです。このときに受け取るデータのことを外部データと呼びます。

この外部データは、自分のパソコンの中で作ったものではありません。そのため、どのような形のデータが送られてくるか、プログラムを実行してみるまで完全には分からないという性質を持っています。何かしらの原因でデータの形が急に変わってしまうこともあるため、慎重に扱う必要があります。

2. なぜ外部データに型をつける必要があるのか？

2. なぜ外部データに型をつける必要があるのか？

TypeScriptというプログラミング言語の最大の強みは、データに型という名前の透明なラベルを貼り付けて、中身が何であるかを厳しくチェックできることです。文字が入る場所には文字を、数字が入る場所には数字を、というルールを決めることで、間違った操作を防いでくれます。

しかし、インターネットから届く外部データには、最初からきれいなラベルが貼られているわけではありません。何が入っているか分からない箱のような状態です。もし中身が文字なのに、プログラムが数字だと思い込んで計算を始めてしまうと、コンピューターは混乱してしまい、画面が真っ白になったりエラーで動かなくなったりします。

このような事故を防ぐために、届いた不確定なデータに対して、プログラムの中で「これは確かに正しいデータである」と確認を行い、安全な型というラベルをしっかりと貼り付ける作業が不可欠になります。

3. 不確定なデータを表すunknown型とは？

3. 不確定なデータを表すunknown型とは？

TypeScriptには、中身が全く予想できないデータを表すための専用の仕組みが用意されています。それがunknown型です。日本語に訳すと「未知の型」や「まだ分からない型」という意味になります。

昔のプログラミングでは、何でも許してしまう魔法のような型が使われることもありましたが、それだとチェックが甘くなり、エラーを見逃す原因になっていました。一方で、この未知の型は非常に慎重な性格をしています。「中身が何であるかハッキリするまでは、このデータを使って計算をしたり、画面に表示したりすることは絶対に許しません」という強力な制限をかけてくれます。

インターネットからデータを受け取った直後は、まずこの未知の型として受け取ることが、安全なプログラムを作るための第一歩となります。

4. Fetchを使った基本的な通信とデータの受け取り方

4. Fetchを使った基本的な通信とデータの受け取り方

実際にインターネットからデータを取得してみましょう。まずは、標準的に用意されているFetchという機能を使います。これは、インターネットに手紙を出して返事をもらうための道具のようなものです。

以下のプログラムは、インターネットから利用者の情報を一人分だけもらってきて、その中身を安全に確認する準備をする例です。まだ型がはっきりしていないため、未知の型を指定して受け取っています。

async function getUserData() {
    const response = await fetch("https://api.example.com/user");
    const rawData: unknown = await response.json();
    console.log("データを取得しました");
}

上記のプログラムの中にあるasyncやawaitという言葉は、インターネットの通信が reduce 終わるのをじっと待つための命令です。通信にはほんの少し時間がかかるため、これらを使って「返事が届くまで次の行に進まないでください」とコンピューターに指示を出しています。そして、届いたデータを未知の型として変数に保存しています。

5. 型ガードを使ってデータの安全性を確かめる方法

5. 型ガードを使ってデータの安全性を確かめる方法

未知の型として受け取ったデータは、そのままでは中身を呼び出すことができません。そこで、データの形を一つずつ手作業で検査する仕組みを使います。これをプログラミングの用語で型ガードと呼びます。文字通り、不正なデータが入ってこないように門番のように守る仕組みです。

たとえば、届いたデータが本当に正しい箱の形をしていて、その中に名前という文字がしっかりと入っているかどうかを、条件分岐を使って細かく確認していきます。以下のプログラムでは、データが空っぽではなく、さらに中身が正しい形式であるかを検査しています。

function isUser(data: any): data is { name: string; age: number } {
    if (data !== null && typeof data === "object") {
        if (typeof data.name === "string" && typeof data.age === "number") {
            return true;
        }
    }
    return false;
}

このプログラムでは、いくつかの新しい道具が使われています。typeofというのは、データが文字なのか数字なのか、あるいは物体なのかを調べるための道具です。これを使って、名前が文字であること、年齢が数字であることを厳格に確認しています。すべての条件をクリアして、正しいと判断されたときだけ、この門番は合格の合図を出します。

6. 条件をクリアしたデータに安全に型を割り当てる

6. 条件をクリアしたデータに安全に型を割り当てる

門番の確認が見事に合格したら、いよいよそのデータに正式な型を割り当てて、プログラムの中で自由に使えるようにします。先ほど作成した門番の機能を、通信のプログラムと組み合わせてみましょう。

もしデータが予想と違っていた場合は、無理に処理を進めるのではなく、「データが壊れています」という警告を画面に出すようにします。これにより、予期せぬ原因でプログラムが突然停止する心配がなくなります。

async function showUserProfile() {
    const response = await fetch("https://api.example.com/user");
    const rawData: unknown = await response.json();

    if (isUser(rawData)) {
        console.log("名前は" + rawData.name + "です");
        console.log("年齢は" + rawData.age + "歳です");
    } else {
        console.log("エラー：届いたデータの形が正しくありませんでした");
    }
}

このプログラムを実行したとき、もしインターネットの向こう側から正しいデータが届いていれば、条件分岐の最初の部屋に入り、名前と年齢が画面に表示されます。万が一、名前が入っていないような不完全なデータが届いた場合は、自動的に安全なエラーの部屋に移動するため、パソコンがフリーズすることはありません。

7. Axiosを使った場合の通信と型安全の書き方

7. Axiosを使った場合の通信と型安全の書き方

ここまでは標準的な機能であるFetchを使って説明してきましたが、実際の開発ではAxiosという名前の、より便利な外部の道具が使われることも多いです。この道具を使うと、インターネットとの通信をより短い行数で、すっきりと書くことができるようになります。

ただし、この便利な道具も、初期状態では何でも受け入れる設定になっていることが多いため、油断は禁物です。Fetchのときと同じように、一度未知の型としてデータを受け取り、しっかりと門番を潜らせる書き方をするのが最も安全です。

import axios from "axios";

async function fetchUserWithAxios() {
    const response = await axios.get("https://api.example.com/user");
    const rawData: unknown = response.data;

    if (isUser(rawData)) {
        console.log("有効なユーザーデータを確認しました。名前：" + rawData.name);
    } else {
        console.log("データの検証に失敗しました。処理を中断します");
    }
}

このように、通信の道具がFetchからAxiosに変わったとしても、安全に型をつけるための基本的な考え方は全く同じです。外から来た怪しいデータは、必ず一度未知の型として受け止め、中身を自分の目で確かめてから、きれいなラベルを貼り直して使うという流れを徹底することが大切です。

8. 外部ライブラリを活用した高度な自動検証の紹介

8. 外部ライブラリを活用した高度な自動検証の紹介

最後に、少しだけ発展的なお話をしておきます。今回は手作業で一つひとつの項目を検査する門番のプログラムを書きましたが、確認したい項目が何十個も増えてくると、書くのが大変になってしまいます。パソコンの操作に慣れて、もっとたくさんのデータを扱いたくなったときのために、便利な補助ツールが存在します。

たとえば、データの形をあらかじめ定義しておくだけで、届いたデータがその形に合致しているかを自動的に超高速でチェックしてくれる、専用の部品が世界中で開発されています。これらを利用することで、手作業の書き間違いを防ぎ、さらに安全なプログラムを組み立てることができるようになります。

まずは今回紹介した、未知の型で受け取って条件分岐で確認するという基本の形をしっかりと頭に入れて、少しずつプログラミングの楽しさに触れていってください。