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(() => 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('en-US', {
        style: 'currency',
        currency: 'USD'
      }).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 });
	},
	onResponseError({ response }) {
		console.error("响应错误：", response.status, response.statusText);
	},
	onResponse({ response }) {
		console.log("收到响应：", 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 }
				});
			}
		}
	});
}