Nuxt 4：$fetch、useFetch、useAsyncData - データ取得完全ガイド

// app/pages/posts.vue
<script setup lang="ts">
  // リクエストを一度（サーバー上で）実行し、状態を転送します。
  const { data: posts } = await useFetch('/api/posts')
</script>

// pages/dashboard.vue
<script setup lang="ts">
// 詳細な状態管理を備えた最適化されたロード
const {
  data: dashboard,
  pending,
  error,
  refresh
} = await useAsyncData('dashboard', async () => {
  // より良いパフォーマンスのための並列呼び出し
  const [user, stats, notifications] = await Promise.all([
    $fetch('/api/user/profile'),
    $fetch('/api/analytics/stats'),
    $fetch('/api/notifications/unread')
  ])

  return {
    user,
    stats,
    notifications
  }
}, {
  // 高度なオプション
  server: true,        // サーバー上で実行
  lazy: false,         // レンダリング前に待機
  default: () => ({    // ロード中のデフォルト値
    user: null,
    stats: { views: 0, users: 0 },
    notifications: []
  })
})

// デバウンスを使用した手動更新
const debouncedRefresh = useDebounceFn(refresh, 300)

// 自動更新のためのWatch
watch(() => route.path, debouncedRefresh)
</script>

// components/ContactForm.vue
<script setup lang="ts">
const formData = ref({
  name: '',
  email: '',
  message: ''
})

const isSubmitting = ref(false)
const submitError = ref<string | null>(null)

async function submitForm() {
  isSubmitting.value = true
  submitError.value = null

  try {
    const response = await $fetch('/api/contact', {
      method: 'POST',
      body: formData.value,
      // 追加オプション
      timeout: 10000,
      retry: 2,
      retryDelay: 1000
    })

    // 成功処理
    await navigateTo('/thank-you')
  } catch (error) {
    if (error.data?.message) {
      submitError.value = error.data.message
    } else {
      submitError.value = 'フォームの送信中にエラーが発生しました。もう一度お試しください。'
    }
  } finally {
    isSubmitting.value = false
  }
}
</script>

// pages/products/[id].vue
<script setup lang="ts">
interface Product {
  id: number
  name: string
  price: number
  description: string
  category: string
}

interface ProductWithDetails extends Product {
  formattedPrice: string
  isInStock: boolean
  relatedProducts: Product[]
}

const { data: product, pending } = await useFetch<ProductWithDetails>(
  `/api/products/${route.params.id}`,
  {
    // データ変換
    transform: (data: Product) => ({
      ...data,
      formattedPrice: new Intl.NumberFormat('ja-JP', {
        style: 'currency',
        currency: 'JPY'
      }).format(data.price),
      isInStock: data.price > 0,
      relatedProducts: [] // 後で埋められます
    }),
    // 高度なキャッシング
    server: true,
    key: `product-${route.params.id}`,
    // キャッシュオプション
    getCachedData: (key) => {
      // カスタムキャッシュロジック
      return nuxtApp.staticData[key] || nuxtApp.payload.data[key]
    }
  }
)

// 関連製品を後でロード
watchEffect(async () => {
  if (product.value?.category) {
    const { data: related } = await $fetch<Product[]>(`/api/products/related/${product.value.category}`)
    product.value.relatedProducts = related
  }
})
</script>

// ✅ キーイングのベストプラクティス
const { data } = await useAsyncData(`user-${userId}`, () => $fetch(`/api/users/${userId}`));

// 複数のパラメータに依存するデータの場合
const { data } = await useAsyncData(`search-${searchTerm}-${page}-${category}`, () =>
	$fetch("/api/search", {
		query: { q: searchTerm, page, category }
	})
);

// components/DataLoader.vue
<script setup lang="ts">
interface AsyncDataState<T> {
  data: Ref<T | null>
  pending: Ref<boolean>
  error: Ref<Error | null>
  refresh: () => Promise<void>
}

// 再利用可能なコンポーザブル
function useAsyncDataWithState<T>(
  key: string,
  handler: () => Promise<T>
): AsyncDataState<T> {
  const { data, pending, error, refresh } = useAsyncData(key, handler)

  return {
    data,
    pending,
    error,
    refresh
  }
}

// コンポーネントでの使用
const { data: posts, pending, error } = useAsyncDataWithState(
  'posts',
  () => $fetch('/api/posts')
)
</script>

<template>
  <div>
    <div v-if="pending" class="loading">
      投稿を読み込んでいます...
    </div>

    <div v-else-if="error" class="error">
      エラー: {{ error.message }}
      <button @click="refresh">再試行</button>
    </div>

    <div v-else-if="data" class="posts">
      <PostCard
        v-for="post in data"
        :key="post.id"
        :post="post"
      />
    </div>
  </div>
</template>

// 後でロードできる重要でないデータの場合
const { data: comments } = await useLazyFetch(`/api/posts/${postId}/comments`, {
	server: false, // クライアントのみ
	lazy: true // レンダリングをブロックしない
});

// 頻繁に更新されるデータの場合
const { data: liveScore } = await useFetch("/api/live-score", {
	server: false,
	refresh: {
		// 30秒ごとに更新
		interval: 30000
	}
});

// Nuxt 4では、これはデフォルトでshallowRefです
const { data } = await useAsyncData("large-dataset", () => $fetch("/api/large-dataset"));

// 深いリアクティビティが必要な場合（慎重に使用）
const { data } = await useAsyncData("deep-reactive", () => $fetch("/api/nested-data"), {
	deep: true // 深いリアクティビティを有効にする
});

// コンポーネントレベルのキャッシュ
const { data } = await useFetch("/api/config", {
	key: "app-config",
	// 5分間キャッシュ
	server: true,
	transform: data => {
		// データはキャッシュされたままになります
		return data;
	}
});

// 条件付きキャッシュ
const { data } = await useFetch("/api/user-preferences", {
	key: `user-prefs-${userId}`,
	server: false,
	// エラーがない場合のみキャッシュ
	getCachedData: key => {
		const cached = nuxtApp.staticData[key] || nuxtApp.payload.data[key];
		return cached && !cached.error ? cached : null;
	}
});

// types/api.ts
export interface User {
  id: number
  name: string
  email: string
  avatar?: string
}

export interface ApiResponse<T> {
  data: T
  message: string
  success: boolean
}

// pages/users/[id].vue
<script setup lang="ts">
const route = useRoute()
const { data: user } = await useFetch<ApiResponse<User>>(`/api/users/${route.params.id}`)

// 型安全なアクセス
if (user.value?.data) {
  console.log(user.value.data.name) // TypeScriptは型を知っています
}
</script>

// composables/useDashboard.ts
export interface DashboardData {
	user: User;
	stats: {
		views: number;
		clicks: number;
		conversions: number;
	};
	recentActivity: Activity[];
}

export function useDashboardData() {
	return useAsyncData<DashboardData>("dashboard", async () => {
		const [userResponse, statsResponse, activityResponse] = await Promise.all([$fetch<ApiResponse<User>>("/api/user/profile"), $fetch<ApiResponse<Stats>>("/api/analytics/stats"), $fetch<ApiResponse<Activity[]>>("/api/activity/recent")]);

		return {
			user: userResponse.data,
			stats: statsResponse.data,
			recentActivity: activityResponse.data
		};
	});
}

// 開発中のデバッグモードを有効にする
const { data } = await useFetch("/api/debug-example", {
	// コンソールにデバッグ情報を表示
	onRequestError({ request, error }) {
		console.error("Request error:", { request, error });
	},
	onResponseError({ response }) {
		console.error("Response error:", response.status, response.statusText);
	},
	onResponse({ response }) {
		console.log("Response received:", response._data);
	}
});

// パフォーマンスを測定するコンポーザブル
function useTrackedFetch<T>(url: string, options = {}) {
	const startTime = Date.now();

	return useFetch<T>(url, {
		...options,
		onResponse() {
			const duration = Date.now() - startTime;
			console.log(`${url}へのフェッチに${duration}msかかりました`);

			// 遅い場合は分析に送信
			if (duration > 1000) {
				$fetch("/api/analytics/slow-request", {
					method: "POST",
					body: { url, duration }
				});
			}
		}
	});
}