ABOUT ARCHIVE
Hero Image
TAG CATEGORY
円

【TypeScript】LaravelとのAPI型定義共有戦略 - フロントエンドとバックエンドの一貫性を実現

【TypeScript】LaravelとのAPI型定義共有戦略 - フロントエンドとバックエンドの一貫性を実現

2024-10-26

2024-10-26

LaravelとTypeScriptの型定義共有の重要性

LaravelでバックエンドのAPIを構築し、TypeScriptを使ったフロントエンドと連携する際、APIでやり取りするデータの型定義が統一されていないと、データ構造に関するバグや開発効率の低下につながります。型定義を共有することで、LaravelのバックエンドとTypeScriptのフロントエンド間でデータの一貫性が確保され、型の変化に伴う影響も軽減されます。本記事では、LaravelとTypeScriptでAPI型定義を共有するための具体的な戦略を解説します。

LaravelとTypeScriptでの型定義共有方法

LaravelとTypeScript間で型定義を共有するには、以下の2つのアプローチが一般的です：

  1. OpenAPIを用いた型定義の自動生成
    APIの仕様をOpenAPIで定義し、その仕様からTypeScript用の型を自動生成します。
  2. LaravelとTypeScript間での独自型定義ファイルの共有
    Laravelで作成した型定義ファイルやDTO（Data Transfer Object）をTypeScript用に変換して共有します。

OpenAPIによる型定義共有の自動化

OpenAPIは、APIの仕様をJSONやYAMLで記述し、それをもとにフロントエンドとバックエンド間で型定義を共有できる仕様です。OpenAPIで型定義を記述することで、LaravelとTypeScript間で自動生成した型を用いてデータの整合性を保つことが可能になります。

Step 1: LaravelでOpenAPIの設定

LaravelでAPIの仕様を管理するために、zircote/swagger-phpなどのライブラリを用いてOpenAPIドキュメントを生成します。

composer require zircote/swagger-php

次に、APIエンドポイントに対するドキュメントをコントローラ上に記述します。

// app/Http/Controllers/Api/UserController.php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
/
 * @OA\Get(
 *     path="/api/users",
 *     tags={"Users"},
 *     summary="Get list of users",
 *     @OA\Response(
 *         response=200,
 *         description="List of users",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/User")
 *         )
 *     )
 * )
 */
public function index() {
    return User::all();
}

Step 2: OpenAPIドキュメントのエクスポート

Swaggerコマンドを使ってOpenAPIドキュメントをエクスポートし、フロントエンドが参照できるようにします。

php artisan swagger:generate

この手順で生成されたJSONファイルは、フロントエンドで型定義を生成するための基礎になります。

Step 3: TypeScript用の型定義の生成

OpenAPIドキュメントをもとにTypeScript用の型を自動生成するには、openapi-generator-cliなどのツールを利用します。

npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli generate -i ./path/to/openapi.json -g typescript-fetch -o ./src/api

このコマンドにより、OpenAPI仕様からTypeScriptの型定義やAPIクライアントが生成され、フロントエンドで利用可能な型安全なインターフェースが自動的に作成されます。

LaravelとTypeScript間での型定義ファイルの共有

OpenAPIを用いず、LaravelとTypeScript間で型定義を直接共有する方法もあります。Laravel側で作成したDTOやリクエストの型定義をフロントエンドと同期させることで、APIの型安全性を確保します。

Step 1: LaravelでDTOや型定義ファイルの作成

Laravelでは、ユーザー情報やAPIのリクエスト/レスポンスの型定義をDTO（Data Transfer Object）として管理できます。

// app/DTOs/UserDTO.php
namespace App\DTOs;
class UserDTO {
    public string $name;
    public string $email;
    public function __construct(string $name, string $email) {
        $this->name = $name;
        $this->email = $email;
    }
}

Step 2: 型定義ファイルのエクスポートと同期

DTOや型定義ファイルをエクスポートするには、LaravelでDTOの構造をTypeScript形式で自動生成するスクリプトを作成し、tsgenなどのTypeScript用生成ツールを活用します。これにより、LaravelとTypeScriptの型が同期され、フロントエンドで利用可能になります。

// types/UserDTO.ts (`TypeScript`でエクスポートされた型)
export interface UserDTO {
  name: string;
  email: string;
}

Step 3: 型の同期とインポート

エクスポートした型定義をフロントエンド側でインポートし、APIデータの型チェックに使用します。これにより、TypeScriptの型チェック機能が利用でき、Laravelでの変更が反映されていない場合にはエラーが表示されます。

// src/api/UserService.ts
import { UserDTO } from "../types/UserDTO";
export const fetchUsers = async (): Promise<UserDTO[]> => {
  const response = await fetch("/api/users");
  return await response.json();
};

型定義共有のメリットと注意点

メリット

  • データの一貫性
    バックエンドとフロントエンドで同じ型定義を共有することで、データ構造が一致し、バグが発生しにくくなります。

  • メンテナンスの効率化
    型定義が共有されていると、Laravelで型を変更した場合に、フロントエンドにも自動的に型チェックが反映され、コードの整合性が保たれます。

  • 開発効率の向上
    フロントエンドでの型補完が有効になり、データの扱いやすさが向上します。

注意点

  • バージョン管理の重要性
    型定義を更新する際には、常にバージョン管理を行い、フロントエンドとバックエンドのバージョンが同期するようにします。
  • 自動生成ツールの選定
    OpenAPIやTypeScriptの型生成ツールにはさまざまなオプションがあるため、プロジェクトに最適なツールを選定する必要があります。

まとめ

LaravelとTypeScriptのAPI型定義を共有することで、フロントエンドと バックエンドのデータの一貫性が保たれ、開発効率とコードの信頼性が向上します。OpenAPIによる型の自動生成やDTOの共有を活用し、プロジェクト全体の型安全性を確保しながら、より効率的でスケーラブルな開発体制を構築しましょう。

参照:

Laravelと`TypeScript`のAPI型定義共有ガイド | Learn `TypeScript` with Laravel
Coding TypeScript

Recommend

categories
tags