useRequestFetch の補足解説：サーバーサイドフェッチでヘッダーを安全に転送する

Nuxt でサーバーサイドレンダリング（SSR）を行う際、API など外部リソースへのフェッチリクエストにおいて、クライアントからのリクエストヘッダーを適切に転送したいケースがよくあります。useRequestFetch はこの課題を解決するためのコンポーザブルで、SSR 時にリクエストコンテキストを引き継ぎつつ、必要なヘッダーだけを安全に転送できます。

この補足記事では、useRequestFetch の基本的な使い方だけでなく、実務での活用例や注意すべきポイントを丁寧に解説します。初〜中級の Nuxt ユーザーが SSR と CSR の違いを理解しつつ、より安全で効率的なデータフェッチを実現できるようになることを目指しています。

まず結論：useRequestFetch のポイント

• SSR 時にクライアントからのリクエストヘッダーを安全に転送できる
• 不要・危険なヘッダー（例：host、connection）は自動的に除外される
• クライアントサイドでは通常の $fetch と同様に動作し、違和感なく使える
• useFetch は内部的に useRequestFetch を利用しているため、基本的には useFetch で十分な場合も多い
• API サーバーや認証付きリクエストで特に有効で、SSR と CSR の境界を意識した設計が可能

いつ使うべきか？使わない方がよいケースは？

使うべきケース

• SSR 中にクライアントのリクエストヘッダー（Cookie や認証トークンなど）を API リクエストに引き継ぎたいとき
• サーバーサイドでユーザー固有の情報を取得する必要がある場合（例：ログイン状態の判定）
• API サーバーがヘッダー情報を元にレスポンスを変える設計になっている場合
• カスタムヘッダーを安全に転送しつつ、不要なヘッダーは除外したい場合

使わない方がよいケース

• クライアントサイドのみで完結するフェッチ（通常の $fetch で十分）
• SSR 時にヘッダー情報を引き継ぐ必要がない単純なデータ取得
• ヘッダーの転送が不要な静的コンテンツの取得や、パブリック API へのアクセス

実務でよくあるユースケースとサンプルコード

1. SSR でユーザーの Cookie を API に転送し認証情報を取得する

// サーバーサイドでリクエストヘッダーを引き継ぎ、認証済みユーザー情報を取得
const requestFetch = useRequestFetch()
const { data: user } = await useAsyncData(() => requestFetch('/api/user/profile'))

// server/api/user/profile.ts
export default defineEventHandler((event) => {
  const cookies = parseCookies(event)
  // Cookie に基づきユーザー認証処理を行う例
  if (cookies.authToken === 'valid-token') {
    return { name: 'Alice', role: 'admin' }
  }
  return { error: 'Unauthorized' }
})

2. SSR でカスタムヘッダーを転送し、API サーバーの挙動を制御する

const requestFetch = useRequestFetch()
const { data: result } = await useAsyncData(() =>
  requestFetch('/api/data', {
    headers: { 'X-Custom-Header': 'my-value' }
  })
)

3. クライアントサイドのナビゲーション時は通常の $fetch と同じ挙動

// クライアントサイドでは useRequestFetch は $fetch と同じ動作
const { data } = await useAsyncData(() => $fetch('/api/public-data'))

よくある落とし穴・注意点

1. 転送されないヘッダーがある

useRequestFetch はセキュリティ上の理由から、host、connection、transfer-encoding などのヘッダーを自動的に除外します。これらはサーバー間通信で不要かつ危険なためです。必要なヘッダーが転送されているかは必ず確認しましょう。

2. SSR と CSR の挙動の違いに注意

SSR 時はリクエストコンテキストを引き継ぎますが、クライアントサイドのナビゲーション時は通常の $fetch と同じ動作になります。これにより、ヘッダーの転送が不要な場合はパフォーマンスに影響しませんが、挙動の違いを理解しておくことが重要です。

3. Hydration 時のデータ不整合に注意

SSR で取得したデータとクライアントサイドで再フェッチしたデータが異なると、Hydration エラーや UI の不整合が起こる可能性があります。API のレスポンスがユーザーごとに変わる場合は特に注意し、必要に応じてキャッシュや状態管理を工夫しましょう。

4. パフォーマンスへの影響

ヘッダー転送は便利ですが、不要なヘッダーを大量に転送するとリクエストサイズが増え、パフォーマンスに悪影響を及ぼすことがあります。必要最低限のヘッダーだけを転送する設計を心がけてください。

まとめ

useRequestFetch は Nuxt の SSR 環境でクライアントのリクエストヘッダーを安全かつ簡単に転送できる強力なツールです。認証情報やユーザー固有のデータを API に渡す際に非常に役立ちますが、転送されないヘッダーや SSR と CSR の挙動の違いなど、理解しておくべきポイントも多いです。

実務では、useFetch と組み合わせて使うことが多く、API の設計やセキュリティ要件に応じて適切に使い分けることが重要です。この記事を参考に、より安全で効率的なデータフェッチを実現してください。