【TypeScript】fetchの使い方：基本の型定義・ラッパー作成・モックテスト

// ユーザー情報を取得する基本的なfetch関数
async function fetchUsers() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    
    // 【重要】HTTPステータスコードが200番台以外の場合はエラーを投げる
    if (!response.ok) {
      throw new Error(`HTTPエラー: ${response.status}`);
    }
    
    const data = await response.json();
    console.log('データ取得成功:', data);
    return data;
  } catch (error) {
    // ネットワークエラーや、上記で投げたHTTPエラーをここでキャッチ
    console.error('フェッチに失敗しました:', error);
  }
}

fetchUsers();

// --- GETリクエスト（クエリパラメータ付き）の例 ---
async function fetchUserById(userId: number) {
  // typescript fetch get with parameters
  // URLSearchParamsを使うとエンコードも自動で行われ安全です
  const params = new URLSearchParams({ id: userId.toString() });
  const url = `https://api.example.com/users?${params.toString()}`;

  // typescript fetch get example
  const response = await fetch(url);
  if (!response.ok) throw new Error('GET Request failed');
  return response.json();
}

// --- POSTリクエスト（ボディとヘッダー設定）の例 ---
interface CreateUserDto {
  name: string;
  email: string;
}

async function createUser(userData: CreateUserDto) {
  const url = 'https://api.example.com/users';
  
  // RequestInit型を指定することで、入力補完や型チェックが効く
  const options: RequestInit = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json', // JSON送信時には必須
      'Authorization': 'Bearer YOUR_TOKEN_HERE'
    },
    // 必ずJSON文字列に変換する
    body: JSON.stringify(userData),
  };

  const response = await fetch(url, options);
  if (!response.ok) throw new Error('POST Request failed');
  return response.json();
}

// 取得したいデータの型定義
interface User {
  id: number;
  name: string;
  email: string;
}

// ジェネリクス <T> を使った汎用的なfetchラッパー関数
async function fetchTypedData<T>(url: string, options?: RequestInit): Promise<T> {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  // ここでジェネリクスとして渡された型 T として解釈させる
  const data = await response.json();
  return data as T; 
}

// 実際の使用例
async function main() {
  try {
    // 呼び出し時に <User[]> と指定することで、戻り値に型がつく
    const users = await fetchTypedData<User[]>('https://jsonplaceholder.typicode.com/users');
    
    // usersは User[] 型として認識されるため、補完が効きミスを防げる
    users.forEach(user => {
      console.log(`ID: ${user.id}, Name: ${user.name}`);
      // console.log(user.age); // User型にageはないため、コンパイルエラーになる（安全！）
    });
  } catch (error) {
    console.error(error);
  }
}

/**
 * タイムアウト機能付きのfetch関数
 * @param url リクエストURL
 * @param options fetchのオプション
 * @param timeoutMs タイムアウト時間（ミリ秒） - デフォルトは8000ms
 */
async function fetchWithTimeout(
  url: string,
  options: RequestInit = {},
  timeoutMs: number = 8000
): Promise<Response> {
  // 通信を中断するためのコントローラーを作成
  const controller = new AbortController();
  const id = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal, // signalを渡すことで中断可能にする
    });
    
    // HTTPエラーのハンドリング
    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status}`);
    }
    
    return response;
  } catch (error: unknown) {
    if (error instanceof Error && error.name === 'AbortError') {
      throw new Error(`リクエストがタイムアウトしました (${timeoutMs}ms)`);
    }
    throw error;
  } finally {
    // 成功・失敗に関わらず、タイマーを確実にクリアする
    clearTimeout(id);
  }
}

// 実行例
// const data = await fetchWithTimeout('https://api.example.com/data', { method: 'GET' }, 5000);

// 独自のAPIエラークラス（ステータスコードなどを保持）
class ApiError extends Error {
  constructor(public status: number, public message: string, public data?: any) {
    super(message);
    this.name = 'ApiError';
  }
}

// 共通設定をまとめたAPIクライアントオブジェクト
const apiClient = {
  /**
   * ジェネリクス <T> を用いた汎用fetchメソッド
   */
  async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
    const baseUrl = 'https://api.example.com/v1';
    
    // デフォルトヘッダーの設定（認証トークンやContent-Typeなど）
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${localStorage.getItem('token') || ''}`,
      ...options.headers,
    };

    const response = await fetch(`${baseUrl}${endpoint}`, { ...options, headers });

    // 204 No Content（レスポンスボディがない場合）の処理
    if (response.status === 204) {
      return {} as T;
    }

    const data = await response.json().catch(() => null);

    // エラーハンドリング：ステータスコードとサーバーからの詳細なエラー情報を投げる
    if (!response.ok) {
      throw new ApiError(
        response.status,
        data?.message || 'APIリクエストに失敗しました',
        data
      );
    }

    // typescript fetch generic: 取得したデータを指定された型 T として返す
    return data as T;
  },

  // HTTPメソッドごとのショートカット（さらに使いやすくする）
  get<T>(endpoint: string, options?: RequestInit) {
    return this.request<T>(endpoint, { ...options, method: 'GET' });
  },
  
  post<T>(endpoint: string, body: any, options?: RequestInit) {
    return this.request<T>(endpoint, {
      ...options,
      method: 'POST',
      body: JSON.stringify(body),
    });
  },
};

// --- 使用例 ---
interface UserResponse {
  id: number;
  name: string;
}

async function fetchMyProfile() {
  try {
    // 呼び出し側は非常にシンプルになり、戻り値(user)にはUserResponse型がつく
    const user = await apiClient.get<UserResponse>('/users/me');
    console.log(`こんにちは、${user.name}さん！`);
  } catch (error) {
    if (error instanceof ApiError) {
      if (error.status === 401) {
        console.error('セッションが切れました。再ログインしてください。');
      } else {
        console.error(`サーバーエラー: ${error.message}`);
      }
    }
  }
}

import { useState, useEffect } from 'react';

// APIから取得するデータの型定義
interface User {
  id: number;
  name: string;
}

export const UserProfile = ({ userId }: { userId: number }) => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    // コンポーネントのアンマウント時に通信をキャンセルするためのコントローラー
    const abortController = new AbortController();

    const fetchUser = async () => {
      setLoading(true);
      try {
        // react typescript fetch example
        // signalオプションにコントローラーを渡すことでキャンセル可能にする
        const response = await fetch(`https://api.example.com/users/${userId}`, {
          signal: abortController.signal
        });

        if (!response.ok) throw new Error('ユーザー情報の取得に失敗しました');
        
        const data: User = await response.json();
        setUser(data);
      } catch (err: any) {
        // 【重要】キャンセルによるエラー（AbortError）の場合は無視する
        if (err.name === 'AbortError') {
          console.log('Fetch aborted: 別のページへ遷移しました');
          return;
        }
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchUser();

    // クリーンアップ関数：コンポーネントが破棄される時に通信をキャンセル
    return () => abortController.abort();
  }, [userId]); // userIdが変わるたびに再実行される

  if (loading) return <div>ローディング中...</div>;
  if (error) return <div>エラー: {error}</div>;
  return <div>ユーザー名: {user?.name}</div>;
};

interface Todo {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

// --- 1. 標準 fetch を使った場合（Node.js v18以降、またはブラウザ環境）---
async function getTodoWithFetch() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');
    
    // 【要注意】fetchの場合は自分でHTTPステータスをチェックし、手動でエラーを投げる
    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status}`);
    }
    
    // JSONへのパースも手動で行う必要がある
    const data = await response.json() as Todo;
    console.log('Fetch result:', data.title);
  } catch (error) {
    console.error('Fetch error:', error);
  }
}

// --- 2. Axios を使った場合（別途 npm install axios が必要）---
import axios from 'axios';

async function getTodoWithAxios() {
  try {
    // ジェネリクス <Todo> でレスポンスの型を直接指定できる
    const response = await axios.get<Todo>('https://jsonplaceholder.typicode.com/todos/1');
    
    // response.okのチェックは不要（404や500エラーは自動で下の catch へ飛ぶ）
    // JSONのパースも自動で行われ、実データは response.data に格納される
    console.log('Axios result:', response.data.title);
  } catch (error) {
    // Axios独自のエラーかどうかを型ガードで判定できる
    if (axios.isAxiosError(error)) {
      console.error('Axios error status:', error.response?.status);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

# typescript-fetch ジェネレーターを指定してAPIクライアントを出力
npx @openapitools/openapi-generator-cli generate -i ./openapi.yaml -g typescript-fetch -o ./generated-api

// 自動生成されたディレクトリから必要なクラスをインポート
import { Configuration, UsersApi } from './generated-api';

// 1. APIクライアントの設定（Configuration）を定義
// ここで認証トークンなどを一元管理することで、自動生成ファイルを汚さずに済む
const apiConfig = new Configuration({
  basePath: 'https://api.example.com/v1',
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token') || ''}`,
  },
  // fetchApiインターフェースを上書きして独自のラッパーを噛ませることも可能
});

// 2. 設定を渡してAPIクライアントのインスタンスを作成
const usersApi = new UsersApi(apiConfig);

// 3. 実際のデータ取得処理
async function fetchUserList() {
  try {
    // パラメータの型チェックから戻り値の型付けまで、すべて自動で補完・検証される
    const users = await usersApi.getUsers({ limit: 10, offset: 0 });
    console.log('取得したユーザー一覧:', users);
    return users;
  } catch (error) {
    console.error('ユーザー一覧の取得に失敗:', error);
  }
}

// テスト対象の関数（例として、先ほど作成したfetch関数を想定）
import { fetchUsers } from './api';

describe('fetchUsers API通信のテスト', () => {
  // テストケースごとにfetchのモックをリセットする（超重要！）
  afterEach(() => {
    jest.restoreAllMocks(); 
    // Vitestの場合は vi.restoreAllMocks();
  });

  it('【正常系】APIから正しくデータを取得し、JSONを返すこと', async () => {
    // 1. fetchをモック化し、ダミーの成功レスポンスを定義（jest mock fetch typescript）
    const mockResponse = [{ id: 1, name: 'Taro' }, { id: 2, name: 'Jiro' }];
    jest.spyOn(global, 'fetch').mockResolvedValue({
      ok: true,
      status: 200,
      json: async () => mockResponse,
    } as Response);
    // Vitestの場合は vi.spyOn(global, 'fetch').mockResolvedValue(...)

    // 2. 関数を実行
    const data = await fetchUsers();

    // 3. アサーション（検証）
    expect(global.fetch).toHaveBeenCalledTimes(1);
    expect(global.fetch).toHaveBeenCalledWith('https://jsonplaceholder.typicode.com/users');
    expect(data).toEqual(mockResponse);
  });

  it('【異常系】HTTPステータスが200番台以外の場合、エラーを投げること', async () => {
    // 1. fetchをモック化し、ダミーのエラーレスポンスを定義
    jest.spyOn(global, 'fetch').mockResolvedValue({
      ok: false,
      status: 404,
      statusText: 'Not Found',
    } as Response);

    // 2 & 3. エラーが正しくスローされるかを検証
    await expect(fetchUsers()).rejects.toThrow('HTTPエラー: 404');
    expect(global.fetch).toHaveBeenCalledTimes(1);
  });
});