日本語

简体中文
English

日本語

简体中文
English

VJSP Vue3 フレームワーク API ドキュメント ​

概要 ​

VJSP Vue3 フレームワークは、企業向け中・バックオフィスアプリケーション開発のニーズをサポートする完全なインターフェース管理とリクエストカプセル化メカニズムを提供します。このフレームワークは Axios を基に深くカプセル化されており、統一されたリクエスト管理、エラーハンドリング、セキュリティ保護、パフォーマンス最適化機能を提供します。

1. インターフェース管理とリクエストカプセル化メカニズム ​

1.1 リクエストカプセル化アーキテクチャ ​

フレームワークは階層化アーキテクチャ設計を採用し、リクエスト処理を複数の層に分割します：

  • Axios インスタンス層 [axios/service.ts]：ベースリクエストインスタンスを設定し、リクエスト再試行やキャンセルなどのコア機能を含む
  • インターセプター層 [axios/config.ts]：リクエスト/レスポンスのインターセプトを処理し、統一されたエラーハンドリングとビジネスステータスコードの解析を実装
  • API サービス層 [axios/index.ts]：ビジネスインターフェースのカプセル化、統一されたリクエストメソッド呼び出しインターフェースを提供
  • 型定義層 [types/api]：TypeScript 型サポート、型安全性を確保

1.2 コアリクエストカプセル化 ​

フレームワークは、GET、POST、PUT、DELETE などの HTTP メソッドをサポートする統一されたリクエストカプセル化メカニズムを提供します：

リクエストメソッド使用メカニズム ​

フレームワークは、標準 HTTP メソッド呼び出しをサポートする統一された HTTP リクエストカプセル化メカニズムを提供します：

リクエストメソッドサポートメカニズム：

  1. GET リクエストメカニズム：クエリパラメータの受け渡しをサポートし、URL エンコーディングとパラメータシリアライゼーションを自動的に処理
  2. POST リクエストメカニズム：リクエストボディデータの受け渡しをサポートし、JSON シリアライゼーションとコンテンツタイプ設定を自動的に処理
  3. PUT リクエストメカニズム：リソース更新操作をサポートし、完全なデータ更新機能を提供
  4. DELETE リクエストメカニズム：リソース削除操作をサポートし、安全な削除確認メカニズムを提供

リクエスト処理フロー：

  1. リクエスト前処理：認証トークンを自動的に追加し、リクエストヘッダーを設定し、パラメータシリアライゼーションを処理
  2. リクエスト送信：基盤の HTTP クライアントを通じてサーバーにリクエストを送信
  3. レスポンス処理：レスポンスデータの統一処理、ステータスコード検証、エラーインターセプト
  4. 結果返却：フォーマットされたレスポンスデータを返却し、ビジネスステータスコードとデータ内容を含む

コア機能説明 ​

  1. セキュリティメカニズム

    • 自動レート制限：API リクエストが頻繁になりすぎるのを防止
    • CSRF 保護：機密操作に対するクロスサイトリクエストフォージェリ保護
    • トークン自動注入：リクエスト時にユーザー認証トークンを自動的に運ぶ

  2. エラーハンドリング

    • 統一されたエラーインターセプト：ネットワークエラーとビジネスエラーを自動的に処理
    • フレンドリーなプロンプト：メッセージマネージャーを使用してエラー情報を表示
    • 再試行メカニズム：失敗したリクエストの自動再試行

  3. 機能サポート

    • リクエストキャンセル：進行中のリクエストのキャンセルをサポート
    • ファイルアップロード：multipart/form-data 形式をサポート
    • 型安全性：完全な TypeScript 型サポート

1.3 ビジネスステータスコードシステム ​

フレームワークは、様々なビジネスシナリオの統一処理のための完全なビジネスステータスコードシステムを定義します。ステータスコード定義は src/constants/index.ts ファイルにあります。

コアステータスコード定義 ​

  • SUCCESS_CODE = 'A0000'：リクエスト成功
  • RATE_LIMIT_ERROR_CODE = 'A0006'：レート制限エラー
  • CSRF_VALIDATION_ERROR_CODE = 'A0007'：CSRF 検証失敗

ステータスコード処理メカニズム ​

フレームワークは、統一されたエラーハンドリングメカニズムを通じて様々なビジネスステータスコードを処理し、異なるシナリオでの良好なユーザーエクスペリエンスを確保します。

ステータスコード処理フロー：

  1. ステータスコード識別：レスポンス内のビジネスステータスコードに基づいてリクエスト結果を識別
  2. エラー分類処理：ステータスコードを成功、警告、エラーなどの異なるカテゴリに分類
  3. ユーザープロンプト表示：メッセージマネージャーを通じて適切なユーザープロンプト情報を表示
  4. ビジネスロジック処理：ステータスコードに基づいて対応するビジネスロジックを実行

コアステータスコード処理戦略：

  • 成功ステータスコード (A0000)：正常にデータを返却し、後続のビジネスロジックを継続
  • 認証関連エラーコード：自動的にログインページにリダイレクトし、ユーザーセッション情報をクリア
  • 権限関連エラーコード：権限不足のプロンプトを表示し、関連操作を制限
  • ビジネスロジックエラーコード：具体的なエラー情報を表示し、ユーザーに正しい操作を案内
  • システム保護エラーコード：システム保護プロンプトを表示し、悪意のあるリクエストを防止

1.4 型安全性サポート ​

フレームワークは、開発中の型安全性とコード品質を確保するための完全な TypeScript 型安全性サポートを提供します。

型定義メカニズム ​

  • モジュール型定義：各ビジネスモジュールに独立した型定義ファイル
  • リクエスト/レスポンス型：各 API インターフェースの完全なリクエストパラメータとレスポンスデータ型を定義
  • ビジネスエンティティ型：ユーザー、ロール、メニューなどのビジネスエンティティのデータ構造を定義

型安全性機能 ​

  1. コンパイル時型チェック：開発段階で型エラーを捕捉
  2. インテリジェントコードヒント：IDE が完全な型ヒントと自動補完を提供
  3. インターフェース契約保証：フロントエンドとバックエンドのインターフェースデータ形式の一貫性を確保
  4. リファクタリング安全性：型システムがコードの安全なリファクタリングを支援

型安全性メカニズム ​

フレームワークは、完全な TypeScript 型システムを通じてコンパイル時の型安全性保証を提供します：

型安全性メカニズム機能：

  1. インターフェース契約保証：型定義を通じてフロントエンドとバックエンドのインターフェースデータ形式の一貫性を確保
  2. コンパイル時チェック：開発段階で型エラーを捕捉し、実行時例外を回避
  3. インテリジェントヒントサポート：IDE が完全な型ヒントと自動補完機能を提供
  4. リファクタリング安全性：型システムがコードの安全なリファクタリングとモジュールの維持を支援

型安全性実装メカニズム：

  1. モジュール型定義：各ビジネスモジュールに独立した型定義ファイル
  2. リクエスト/レスポンス型マッピング：各 API インターフェースの完全なリクエストパラメータとレスポンスデータ型を定義
  3. ビジネスエンティティ型付け：ユーザー、ロール、メニューなどのビジネスエンティティのデータ構造を定義
  4. 型推論メカニズム：API 呼び出しのパラメータ型と戻り値型を自動的に推論

2. ビジネスモジュール開発ガイド ​

2.1 新しい API モジュールの開発 ​

ステップ 1：型定義の作成 ​

typescript
// src/types/api/module/product.d.ts
export interface ProductItem {
  id: string
  name: string
  price: number
  stock: number
  status: number
  category: string
  createTime: string
}

export interface ProductListRequest {
  pageNum: number
  pageSize: number
  name?: string
  category?: string
  status?: number
}

export interface ProductListResponse {
  list: ProductItem[]
  total: number
}

ステップ 2：API サービスの作成 ​

typescript
// src/api/product/index.ts
import request from '@/axios'
import type {
  ProductItem,
  ProductListRequest,
  ProductListResponse,
} from '@/types/api/module/product'

/**
 * 商品リストを取得
 * @param params
 * @returns
 */
export function getProductListApi(params: ProductListRequest) {
  return request.get({
    url: '/modules/product',
    params,
  })
}

/**
 * 商品を追加
 * @param data
 * @returns
 */
export function addProductApi(data: ProductItem) {
  return request.post({
    url: '/modules/product',
    data,
  })
}

/**
 * 商品を削除
 * @param id
 * @returns
 */
export function deleteProductApi(id: string) {
  return request.delete({
    url: `/modules/product/${id}`,
  })
}

/**
 * 商品を一括削除
 * @param ids
 * @returns
 */
export function batchDeleteProductApi(ids: string[]) {
  return request.delete({
    url: '/modules/product/batchRemove',
    data: ids,
  })
}

/**
 * 商品詳細を取得
 * @param id
 * @returns
 */
export function getProductApi(id: string) {
  return request.get<ProductItem>({
    url: `/modules/product/${id}`,
  })
}

/**
 * 商品を更新
 * @param data
 * @returns
 */
export function updateProductApi(data: ProductItem) {
  return request.put({
    url: `/modules/product/${data.id}`,
    data,
  })
}

2.2 コンポーネントでの API 使用 ​

基本使用法 ​

html
<template>
  <div>
    <el-table :data="productList" v-loading="loading">
      <el-table-column prop="name" label="商品名" />
      <el-table-column prop="price" label="価格" />
      <el-table-column prop="stock" label="在庫" />
    </el-table>

    <el-pagination
      v-model:current-page="currentPage"
      v-model:page-size="pageSize"
      :total="total"
      @current-change="handlePageChange"
    />
  </div>
</template>

<script setup lang="ts">
  import { ref, onMounted } from 'vue'
  import { getProductListApi } from '@/api/product'
  import type { ProductItem, ProductListRequest } from '@/types/api/module/product'

  const productList = ref<ProductItem[]>([])
  const loading = ref(false)
  const currentPage = ref(1)
  const pageSize = ref(10)
  const total = ref(0)

  // 商品リストを読み込む
  const loadProductList = async () => {
    loading.value = true
    try {
      const response = await getProductListApi({
        pageNum: currentPage.value,
        pageSize: pageSize.value,
      })
      productList.value = response.data.list
      total.value = response.data.total
    } catch (error) {
      console.error('商品リストの読み込みに失敗しました:', error)
    } finally {
      loading.value = false
    }
  }

  // ページネーション処理
  const handlePageChange = (page: number) => {
    currentPage.value = page
    loadProductList()
  }

  onMounted(() => {
    loadProductList()
  })
</script>

Composition API カプセル化の使用 ​

typescript
// composables/useProduct.ts
import { ref, computed } from 'vue'
import { getProductListApi, addProductApi, updateProductApi, deleteProductApi } from '@/api/product'
import type { ProductItem, ProductListRequest } from '@/types/api/module/product'

export function useProduct() {
  const productList = ref<ProductItem[]>([])
  const loading = ref(false)
  const currentPage = ref(1)
  const pageSize = ref(10)
  const total = ref(0)

  // 計算プロパティ
  const hasMore = computed(() => {
    return currentPage.value * pageSize.value < total.value
  })

  // 商品リストを読み込む
  const loadProductList = async (params?: Partial<ProductListRequest>) => {
    loading.value = true
    try {
      const response = await getProductListApi({
        pageNum: currentPage.value,
        pageSize: pageSize.value,
        ...params,
      })
      productList.value = response.data.list
      total.value = response.data.total
    } catch (error) {
      console.error('商品リストの読み込みに失敗しました:', error)
      throw error
    } finally {
      loading.value = false
    }
  }

  // 商品を作成
  const createProduct = async (data: ProductItem) => {
    try {
      await addProductApi(data)
      // リストを再読み込み
      await loadProductList()
    } catch (error) {
      console.error('商品の作成に失敗しました:', error)
      throw error
    }
  }

  // ページネーションをリセット
  const resetPagination = () => {
    currentPage.value = 1
    total.value = 0
  }

  return {
    productList,
    loading,
    currentPage,
    pageSize,
    total,
    hasMore,
    loadProductList,
    createProduct,
    resetPagination,
  }
}

2.3 ベストプラクティス ​

エラーハンドリングのベストプラクティス ​

フレームワークは、異なるシナリオでの良好なユーザーエクスペリエンスとシステム安定性を確保するための階層化エラーハンドリング戦略を推奨します。

コア処理戦略：

  1. 非同期操作ラッピング：すべての非同期 API 呼び出しを try-catch 構造でラップ
  2. 統一されたエラーハンドリング：メッセージマネージャーを通じてユーザーフレンドリーなエラー情報を表示
  3. エラーログ記録：デバッグのための詳細なエラー情報をコンソールに記録
  4. 重複防止：同じエラーメッセージの頻繁な表示を回避

処理フロー：

  1. 例外捕捉：API 呼び出し中に発生する可能性のある様々な例外を捕捉
  2. エラー分類：エラータイプに基づいて異なる処理
  3. ユーザープロンプト：メッセージマネージャーを通じて適切なユーザープロンプトを表示
  4. ログ記録：問題調査のための詳細なエラー情報を記録
  5. 状態回復：エラー後もアプリケーションが正常に動作し続けることを確保

リクエストキャンセルのベストプラクティス ​

フレームワークは、コンポーネントライフサイクルでの非同期リクエストを効果的に管理し、メモリリークと無効なリクエスト処理を回避するための完全なリクエストキャンセルメカニズムを提供します。

コアキャンセル戦略：

  1. コンポーネントライフサイクル管理：コンポーネントがアンマウントされるときに関連リクエストを自動的にキャンセル
  2. 精密キャンセル制御：特定のエンドポイントまたはすべてのリクエストのキャンセルをサポート
  3. エラータイプ識別：リクエストキャンセルエラーと他のエラータイプを区別
  4. リソースクリーンアップ：リクエストキャンセル後に関連リソースが適切に解放されることを確保

適用シナリオ：

  1. コンポーネントアンマウント：ユーザーがページを離れるときに進行中のリクエストをキャンセル
  2. 重複リクエスト：同じデータに対する重複リクエストの競合を回避
  3. ユーザー操作：ユーザーが長時間実行されるリクエストを積極的にキャンセル
  4. 条件変更：リクエスト条件が変更されたときに古いリクエストをキャンセル

実装メカニズム：

  1. リクエスト識別：精密なキャンセルのために各リクエストに一意の識別子を生成
  2. キャンセルトークン：AbortController を使用してリクエストキャンセル機能を実装
  3. 状態管理：リクエスト状態とキャンセルタイミングを追跡
  4. エラーハンドリング：リクエストキャンセルエラーと実際のエラー状況を区別

3. 認証認可とセキュリティメカニズム ​

3.1 認証メカニズム ​

ログイン認証フロー ​

フレームワークは、ユーザー身元確認のセキュリティと一貫性を確保するための標準化されたログイン認証フローを提供します。

認証フローメカニズム：

  1. 資格情報検証：ユーザーがユーザー名とパスワードを送信して身元確認
  2. トークン生成：検証成功後にサーバーがアクセストークンを生成
  3. トークン保存：トークンマネージャーを使用してトークン情報を安全に保存
  4. ユーザー情報管理：基本ユーザー情報を保存および同期
  5. 状態同期：アプリケーション認証状態とルート権限を更新

セキュリティ機能：

  1. 安全な送信：すべての認証リクエストが HTTPS 暗号化を通じて送信
  2. トークン保護：トークンマネージャーが安全なトークン保存メカニズムを提供
  3. セッション管理：セッション有効期限と自動更新をサポート
  4. エラーハンドリング：統一された認証失敗処理メカニズム

フロー制御：

  1. ログイン検証：ユーザー資格情報の有効性を検証
  2. 状態更新：グローバル認証状態を更新
  3. ルートナビゲーション：認証結果に基づいてページナビゲーション
  4. エラーフィードバック：明確なエラープロンプト情報を提供

トークン管理メカニズム ​

フレームワークは、専用のトークンマネージャーを通じてアクセストークンとリフレッシュトークンの完全なライフサイクル管理を実装する安全なトークン管理メカニズムを採用します。このメカニズムは、ユーザー認証状態のセキュリティと信頼性を確保します。

コア機能特徴：

  1. トークン保存セキュリティ

    • 安全な保存方法を使用してアクセストークンとリフレッシュトークンを管理
    • トークン有効期限の自動管理をサポート
    • トークン漏洩と不正アクセスを防止

  2. トークンライフサイクル管理

    • トークン有効期限状態を自動的に検出
    • トークン更新と自動延長をサポート
    • 完全なトークンクリーンアップメカニズムを提供

  3. セキュリティ保護対策

    • トークン保存暗号化保護
    • トークンリプレイ攻撃を防止
    • トークン無効化検出をサポート

作業メカニズムフロー：

  1. トークン取得：ユーザーログイン成功後にアクセストークンとリフレッシュトークンを取得
  2. トークン保存：トークン情報を安全に保存し、有効期限を記録
  3. トークン検証：各リクエスト前にトークンの有効性を検証
  4. トークン更新：トークン有効期限を検出したときにリフレッシュトークンを使用して新しいトークンを自動的に取得
  5. トークンクリーンアップ：ユーザーログアウト時または異常を検出したときにトークン情報を自動的にクリーンアップ

3.2 セキュリティ保護メカニズム ​

レート制限メカニズム ​

フレームワークは、RateLimiter クラスを通じてグローバル、ユーザー、エンドポイントレベルのリクエスト頻度制御を提供するマルチレベルレート制限メカニズムを実装します。このメカニズムは時間ウィンドウアルゴリズムに基づいており、最大リクエスト数と時間ウィンドウサイズの設定をサポートし、API 乱用と DDoS 攻撃を効果的に防止します。

コア機能：

  • マルチレベル制限：グローバル、ユーザー、エンドポイント、ユーザー-エンドポイントの4次元の頻度制御をサポート
  • 時間ウィンドウアルゴリズム：スライディング時間ウィンドウ統計に基づくリクエスト数
  • 自動クリーンアップ：期限切れのリクエストレコードを定期的にクリーンアップしてメモリリークを回避
  • 柔軟な設定：異なるエンドポイントに対して異なる制限戦略をサポート

CSRF 保護メカニズム ​

フレームワークは、ランダムトークンとリクエストヘッダー検証を通じてリクエストの正当性を確保する二重検証 CSRF 保護メカニズムを採用します。保護メカニズムには、トークン生成、保存、検証、自動更新機能が含まれます。

保護フロー：

  1. トークン生成：暗号的に安全な乱数生成器を使用して一意のトークンを作成
  2. トークン保存：クライアント側にトークンを保存し、合理的な有効期限を設定
  3. リクエスト検証：機密操作に対して CSRF トークンの有効性を検証
  4. 自動更新：トークンが期限切れになったときに新しいトークンを自動生成

セキュリティマネージャー ​

セキュリティマネージャーは、リクエスト権限チェック、CSRF ヘッダー生成、セキュリティポリシー設定など、すべてのセキュリティ関連機能を統一管理します。インターセプターメカニズムを通じて、リクエスト送信前にセキュリティチェックを実行し、システムセキュリティを確保します。

機能責任：

  • リクエスト権限検証：ユーザーのエンドポイントへのアクセス権限をチェック
  • セキュリティヘッダー管理：CSRF などのセキュリティ関連リクエストヘッダーを自動的に追加
  • ポリシー設定：すべてのセキュリティ関連設定パラメータを統一管理

3.3 エラーハンドリングメカニズム ​

統一されたエラーハンドリングメカニズム ​

VJSP Vue3 フレームワークは、レスポンスインターセプターを通じて統一されたビジネスステータスコード処理ロジックを実装する階層化エラーハンドリングメカニズムを採用します。このメカニズムは、異なるタイプのエラーをインテリジェントに識別し、対応するユーザープロンプトとシステム処理を提供できます。

処理層：

  1. ビジネスステータスコード処理：事前定義されたビジネスステータスコードに基づいて的を絞った処理
  2. HTTP ステータスコード処理：ネットワークレベルのエラー状態を処理
  3. 特別なシナリオ処理：ファイルストリーム、認証期限切れなどの特別なシナリオに対して異なる処理

コア機能：

  • ステータスコードマッピング：ビジネスステータスコードを特定のユーザープロンプトとシステム動作にマッピング
  • 自動ログアウト：認証期限切れを検出したときに自動的にログアウトプロセスを実行
  • エラー情報標準化：エラー情報形式と表示方法を統一
  • 重複防止：同じエラーメッセージの重複表示を回避

ネットワークエラーハンドリングメカニズム ​

フレームワークは、異なるタイプのネットワーク例外を識別し、フレンドリーなユーザープロンプトを提供できる完全なネットワークエラーハンドリングメカニズムを実装します。処理範囲には、リクエストタイムアウト、サーバーエラー、ネットワーク接続中断などの一般的なネットワーク問題が含まれます。

エラータイプ識別：

  • リクエストタイムアウト：ECONNABORTED エラーコード処理
  • サーバーエラー：HTTP 5xx ステータスコード処理
  • ネットワーク接続：オフライン状態検出と処理
  • 一般的なエラー：他のネットワーク例外の統一処理

メッセージマネージャーメカニズム ​

メッセージマネージャーは、時間間隔制御とメッセージ内容重複排除を通じて同じメッセージの頻繁な表示を回避する重複防止メカニズムを採用します。このメカニズムは Element Plus メッセージコンポーネントに基づいており、統一されたエラー、警告、成功、情報プロンプト管理を提供します。

コア機能：

  • メッセージ重複排除：同じメッセージは一定の時間間隔内に一度だけ表示
  • 優先度管理：異なるメッセージタイプの表示優先度制御
  • 状態追跡：メッセージ表示状態と頻度を記録
  • 柔軟な設定：カスタムメッセージ表示間隔とスタイルをサポート

4. パフォーマンス最適化とモニタリング ​

4.1 キャッシュ最適化 ​

一般キャッシュメカニズム ​

プロジェクトは、CacheUtil クラスを通じて標準化されたデータキャッシュ機能を提供する統一されたキャッシュ管理メカニズムを採用します。このメカニズムは、複数の保存戦略と高度な機能をサポートし、データセキュリティとパフォーマンスを確保します。

コア機能：

  • 保存戦略選択：localStorage と sessionStorage の両方の保存方法をサポート
  • データ暗号化：機密情報を保護するためのオプションのデータ暗号化機能
  • 有効期限管理：期限切れのキャッシュデータを自動的にクリーンアップ
  • 型安全性：完全な TypeScript 型サポートを提供

機能範囲：

  • キャッシュ設定：キャッシュ有効期限と暗号化オプションの設定をサポート
  • キャッシュ取得：データ復号と有効期限チェックを自動的に処理
  • キャッシュ管理：キャッシュ削除、クリア、状態チェック機能を提供
  • エラーハンドリング：完全なエラーハンドリングとログ記録

辞書データキャッシュメカニズム ​

プロジェクトの辞書データは、データキャッシュとリクエスト再試行機能を組み合わせた専門的なキャッシュメカニズムを採用し、辞書データの信頼性とパフォーマンスを確保します。

キャッシュ戦略：

  • 時間ウィンドウキャッシュ：5分の有効キャッシュ時間を設定
  • 状態管理：データ読み込み状態とエラー情報を追跡
  • インテリジェント更新：強制更新とキャッシュ有効性チェックをサポート

再試行メカニズム：

  • 指数バックオフ：再試行遅延が再試行回数に応じて指数関数的に増加
  • 最大再試行制限：無限再試行を回避するために最大3回の再試行
  • 状態リセット：データ取得成功後に再試行回数をリセット

コア機能：

  • 自動キャッシュ管理：時間ウィンドウに基づいてキャッシュ有効性を自動的に判断
  • 並行性制御：同じデータに対する重複リクエストを防止
  • エラー回復：ネットワーク例外の自動再試行メカニズム
  • 状態同期：データ読み込み状態の正確性を確保

4.2 リクエスト最適化 ​

リクエスト再試行メカニズム ​

プロジェクトは、インターセプターパターンを通じてネットワーク例外からの自動回復とパフォーマンス最適化を実現するインテリジェントなリクエスト再試行メカニズムを実装します。

再試行戦略：

  • 指数バックオフアルゴリズム：再試行遅延が再試行回数に応じて指数関数的に増加し、サーバー負荷を回避