前后端对接

機能説明

このスキルは、特にフロントエンドとバックエンドのAPI連携のチェックとデバッグに使用されます。内容は以下の通りです。

• フロントエンドとバックエンドのインターフェースドキュメントのチェック
• コード分析によるAPI仕様のまとめ
• リクエスト/レスポンス形式の一貫性の検証
• データ構造の正しいマッピングの確認
• ネットワーク呼び出し問題のデバッグ

使用場面

• "フロントエンドとバックエンドの連携が正しいか確認したい"
• "フロントエンドからバックエンドAPIを呼び出すとエラーが発生する"
• "フロントエンドとバックエンドのデータ形式の一貫性を確保したい"
• "インターフェース呼び出しの問題をデバッグしたい"
• "新しいAPIの連携作業"

対接フロー

第一歩：プロジェクト構造の確認

まず、プロジェクトのフロントエンドとバックエンドのディレクトリ構造を理解します。

# フロントエンドディレクトリの確認
ls frontend/src/
ls frontend/src/api/
ls frontend/src/stores/

# バックエンドディレクトリの確認
ls backend/
ls backend/app/

第二歩：APIドキュメントの検索または作成

既存のドキュメントを優先的に検索

# APIドキュメントの検索
find docs/ -name "*api*" -o -name "*API*" -o -name "*接口*"
find backend/docs/ -type f
find frontend/docs/ -type f

よくあるドキュメントの場所

• docs/api-reference.md - APIリファレンスドキュメント
• docs/frontend/ - フロントエンド関連ドキュメント
• backend/tests/test_*.py - バックエンドテストファイル（APIの動作を含む）
• backend/README.md - バックエンドの説明

第三歩：バックエンドAPI仕様の分析

1. バックエンドのメインエントリファイルを確認

# backend/app/main.py または類似ファイル
# 重点的に探すもの：
# - @app.get/post/put/delete デコレータで定義されたルート
# - response_model で指定されたレスポンス形式
# - パラメータ定義（query, path, body）

2. Schema定義の確認

# backend/app/schemas.py
# 重点的に探すもの：
# - Pydanticモデル定義
# - フィールドタイプと検証ルール
# - ApiResponse形式
# - PaginatedResponse形式

3. テストファイルの確認

# backend/tests/test_main.py
# 重点的に探すもの：
# - テストリクエストのパラメータ形式
# - 予想されるレスポンス形式
# - アサーションチェックのデータ構造

第四歩：フロントエンドAPI呼び出しの分析

1. APIのラップを確認

// frontend/src/api/index.js
// 重点的に探すもの：
// - baseURL設定
# - axiosインターセプター処理
# - 各APIメソッドのパラメータと戻り値

2. Store状態管理の確認

// frontend/src/stores/*.js
// 重点的に探すもの：
// - API呼び出し方法
# - レスポンスデータ処理方法
# - データ抽出パス（res.data vs res.items）

3. ページコンポーネントの確認

// frontend/src/views/*.vue
// 重点的に探すもの：
// - API呼び出しタイミング
# - データ使用方法
# - エラー処理

第五歩：比較検証

レスポンス形式対応表

ポート設定検証

バックエンド設定：

# backend/app/config.py
# host, port 設定を探す
# デフォルトは通常 0.0.0.0:8000

フロントエンドプロキシ設定：

// frontend/vite.config.js
// server.proxy['/api'] はバックエンドアドレスを指すべき
// 例：target: 'http://localhost:8000'

フロントエンドbaseURL：

// frontend/src/api/index.js
// baseURL は '/api'（プロキシ経由）であるべき

第六歩：チェックリスト

• [ ] バックエンドAPIエンドポイントパスとフロントエンドの呼び出しが一致している
• [ ] リクエストメソッド（GET/POST/PUT/DELETE）が一致している
• [ ] リクエストパラメータの名前とタイプが正しい
• [ ] レスポンス形式の処理が正しい（.data vs 直接アクセス）
• [ ] データフィールドのマッピングが正しい（ネストされたオブジェクト、配列）
• [ ] エラー処理が例外的な状況をカバーしている
• [ ] CORS設定がフロントエンドドメインを許可している

よくある問題

問題1：レスポンス形式の不一致

症状：フロントエンドでデータが取得できず、undefinedと表示される

原因：バックエンドの一部のAPIはApiResponseでラップして返し、一部は直接データを返す

解決策：

// バックエンドの戻り値形式を確認し、フロントエンドの処理を調整する
// ApiResponse形式の場合：
this.data = res.data

// 直接戻り値形式の場合：
this.data = res

問題2：CORSエラー

症状：ブラウザのコンソールにCORS policyエラーが表示される

解決策：

# backend/app/main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # フロントエンドアドレス
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

問題3：ポートの衝突

症状：フロントエンド起動後、バックエンドAPIにアクセスできない

解決策：

• バックエンドが正しいポートで実行されているか確認する（デフォルト8000）
• フロントエンドのvite.config.jsのproxy設定を確認する
• netstat -ano | findstr :8000を使用してポートの占有を確認する

問題4：フィールド名の不一致

症状：一部のデータが正常に表示されない

解決策：

• バックエンドのSchema定義とフロントエンドで使用するフィールドを比較する
• snake_case vs camelCase変換を確認する
• ネストされたオブジェクトのアクセスパスを確認する

実戦事例

事例：Vue3 + FastAPI 連携

バックエンド（FastAPI）：

@app.get("/api/articles", response_model=PaginatedResponse)
async def list_articles(page: int = 1, page_size: int = 20):
    # 戻り値形式：{items: [...], total: 100, page: 1, page_size: 20, total_pages: 5}
    return PaginatedResponse(...)

フロントエンド（Vue3 + Pinia）：

// stores/article.js
const res = await articleApi.getList({ page: 1, page_size: 20 })
// 直接アクセス。バックエンドがApiResponseではなくPaginatedResponseを返すため
this.articles = res.items || []
this.pagination = {
  total: res.total || 0,
  page: res.page || 1,
  // ...
}

事例：React + Node.js 連携

バックエンド（Express）：

res.json({
  success: true,
  data: { items: [...], total: 100 }
})

フロントエンド（React）：

const res = await api.get('/articles')
// .data.data.items にアクセスする必要がある
setItems(res.data.data.items)

ドキュメントテンプレート

API連携ドキュメントテンプレート

# 前后端API对接文档

## サービスアドレス
- フロントエンド：http://localhost:5173
- バックエンド：http://localhost:8000
- APIプロキシ：/api -> http://localhost:8000/api

## APIエンドポイントリスト

### 記事リスト
- **リクエスト**：`GET /api/articles?page=1&page_size=20`
- **レスポンス**：
  - 形式：直接 `PaginatedResponse`
  - フィールド：`{items, total, page, page_size, total_pages}`

### 記事詳細
- **リクエスト**：`GET /api/articles/{id}`
- **レスポンス**：
  - 形式：`ApiResponse {code, message, data}`
  - データは `data` フィールドにある

## データ構造

### 記事オブジェクト（リスト）
```javascript
{
  id: number,
  title: string,
  slug: string,
  summary: string | null,
  cover_image: string | null,
  category: { id, name, slug } | null,
  tags: [{ id, name, slug }],
  author_name: string,
  views: number,
  published_at: string | null
}

## 注意事項

1. **レスポンス形式の不統一**：多くのバックエンドフレームワークのリストインターフェースは直接ページネーションデータを返し、詳細インターフェースはラップされた形式を返す
2. **日付形式**：バックエンドは通常ISO形式の文字列を返し、フロントエンドは解析する必要がある
3. **空値処理**：フロントエンドはnullになる可能性のあるフィールドを処理する必要がある
4. **エラー処理**：インターセプターがHTTPエラーステータスを正しく処理することを確認する
5. **タイプセーフ**：TypeScriptを使用すると、タイプミスマッチを事前に発見できる

## ツール推奨

- **APIテスト**：Postman, curl, HTTPie
- **ネットワークキャプチャ**：ブラウザDevTools Networkパネル
- **ドキュメント生成**：FastAPI自動生成Swaggerドキュメント
- **タイプチェック**：TypeScriptインターフェース定義