组合式 API useLazyFetch(key?, handler, options?) 以异步的方式获取数据，该方法默认会阻碍进行路由导航，直到异步请求的结果返回

该方法可以接收三个参数

• 第一个（可选）参数 key 字符串，表示这一次请求的唯一标识符，用于去重 de-duplicated，如果没有提供就会根据文件名称和该方法所在的行数自动生成一个 key
• 第一个参数 handler 是用于获取数据的处理函数（异步函数）
  该函数的入参是 nuxtApp 即运行时上下文（具体介绍可以查看另一篇笔记《Nuxt 3 简介》）
• 第二个（可选）参数 options 是配置对象，可以设置以下属性
  • server 属性：布尔值，是否可以在服务器/后端渲染时调用该方法。
    如果设置为 false 则该方法只有在客户端才会执行（获取数据），而且在 <script setup> 代码块初始化时，数据也依然为 null，要等到应用在前端 hydration complete 生成完成时，才会获取到数据
  • lazy 属性：布尔值，是否采用懒加载方式，即不阻碍路由导航
  • default 方法：工厂函数 factory function，设置默认值（当异步请求返回前，所采取的默认值）
  • transform 方法：对返回的结果进行进一步的转换处理
  • pick 属性：数组，从结果对象中取特定的属性
    异步获取的数据会作为页面的 payload，为了提升性能和加快页面的载入，应该通过设置该属性，从返回的结果中只提取出页面所需字段缓存起来
    vue

    <script setup>
    const { data: mountain } = await useFetch('/api/mountains/everest', { pick: ['title', 'description'] }) // 只提取出 title 和 description 属性的数据
    </script>
    
    <template>
      <!-- 该页面只需要使用 title 和 description 的属性值 -->
      <h1>{{ mountain.title }}</h1>
      <p>{{ mountain.description }}</p>
    </template>
    

  • watch 属性：监听响应式变量，当它们改变时自动 refresh 发送请求获取新的数据
  • immediate 属性：是否在创建监听器后先立即发送请求获取最新的数据 ❓

该方法的返回值是一个对象

• data 属性：结果数据
• pending 属性：一个布尔值，表示异步函数是否仍在等待结果的状态
• refresh 或 execute 方法：重新调用 handler 函数以获取数据
  说明

  默认情况下，Nuxt 会等待 refresh 函数执行完成后，才会执行下一次更新

• error 属性：当请求失败时所抛出的错误对象

最常见的场景是向后端 API 发送请求获取数据，推荐在处理函数中使用 $fetch 方法发送请求

const { data, pending, error, refresh } = await useAsyncData(
  // key
  'mountains',
  // handler
  () => $fetch('https://api.nuxtjs.dev/mountains')
)

组合式 API useLazyFetch() 也是以异步的方式获取数据，但是该方法默认不会阻碍进行路由导航

<template>
  <div>
    {{ pending ? 'Loading' : count }}
  </div>
</template>

<script setup lang="ts">
/**
 * Navigation will occur before fetching is complete.
 * Handle pending and error states directly within your component's template
 */
const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))

// 通过监听 count 等到它获取到数据时再执行相应的操作
watch(count, (newCount) => {
  // Because count starts out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

组合式 API useFetch(url, options?) 将 useAsyncData() 和 $fetch()进行封装，专门针对向后端 API 发送请求获取数据的场景，所以只需要传入 URL 即可（不需要繁琐地去设置 handler 处理函数，使用 $fetch() 作为 handler），该方法默认会阻碍进行路由导航，直到异步请求的结果返回

<script setup>
const result = await useFetch('/api/count')
</script>

<template>
  Page visits: {{ result.data.count }}
</template>

该方法可以接收两个参数

• 第一个参数 url 是需要请求的 API 地址
• 第二个（可选）参数 options 是配置对象，可以设置以下属性
  • key 属性：表示这一次请求的唯一标识符，用于去重 de-duplicated
  • method 属性：请求所使用的方法
  • query 属性：设置查询参数（Nuxt 会使用 ufo 依赖包对其进行处理）
  • params 属性：和 query 属性一样，别名
  • body 属性：请求体
  • headers 属性：请求头
  • baseURL 属性：base URL
  • server 属性：布尔值，是否可以在服务器/后端渲染时调用该方法。
    如果设置为 false 则该方法只有在客户端才会执行（发送请求获取数据），而且在 <script setup> 代码块初始化时，数据也依然为 null，要等到应用在前端 hydration complete 生成完成时，才会获取到数据
  • lazy 属性：布尔值，是否采用懒加载方式，即不阻碍路由导航
  • default 方法：工厂函数 factory function，设置默认值（当异步请求返回前，所采取的默认值）
  • transform 方法：对返回的结果进行进一步的转换处理
  • pick 属性：数组，从结果对象中取特定的属性
  • watch 属性：监听响应式变量，当它们改变时自动 refresh 发送请求获取新的数据
  • immediate 属性：是否在创建监听器后先立即发送请求获取最新的数据 ❓
  说明

  第二个（可选）参数 options 是扩展自 unjs/ofetch 依赖包所支持的选项

  所以除了以上属性，还可以使用 unjs/ofetch 依赖包所提供的选项，例如可以为请求和响应设置拦截器 interceptors

  ts

  const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
    onRequest({ request, options }) {
      // Set the request headers
      options.headers = options.headers || {}
      options.headers.authorization = '...'
    },
    onRequestError({ request, options, error }) {
      // Handle the request errors
    },
    onResponse({ request, response, options }) {
      // Process the response data
      return response._data
    },
    onResponseError({ request, response, options }) {
      // Handle the response errors
    }
  })
  

该方法最后返回值是一个对象

• data 属性：响应的结果数据
• pending 属性：一个布尔值，表示请求是否仍在执行
• refresh 或 execute 方法：重新获取数据
  说明

  默认情况下，Nuxt 会等待 refresh 函数执行完成后，才会执行下一次更新

• error 属性：当请求失败时所抛出的错误对象

以下是一些示例

• 只读取响应对象中的特定属性
  ts

  const { data, pending, error, refresh } = await useFetch('https://api.nuxtjs.dev/mountains',{
      // 只读取响应对象的 title 属性
      pick: ['title']
  })
  

• 设置请求参数

const param1 = ref('value1')
const { data, pending, error, refresh } = await useFetch('https://api.nuxtjs.dev/mountains',{
    query: { param1, param2: 'value2' }
})
// 最终请求的 URL 是 https://api.nuxtjs.dev/mountains?param1=value1&param2=value2

组合式 API useLazyFetch() 也是专门针对向后端 API 发送请求获取数据的场景，但是采用「懒加载」的方式，即不会阻碍进行路由导航

<template>
  <!-- you'll need to handle a loading state -->
  <div v-if="pending">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>

<script setup lang="ts">
/**
 * Navigation will occur before fetching is complete.
 * Handle pending and error states directly within your component's template
 */
const { pending, data: posts } = useLazyFetch('/api/posts')

watch(posts, (newPosts) => {
  // Because posts starts out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

• 重新获取/更新数据
  有时候在页面加载数据后，可能需要进行更新，例如服务器的数据可能更新了、用户切换分页、用户使用其他的查询参数等。
  虽然可以再一次调用相应的组合式 API 重新发送请求（但是可能因为 de-duplicate 去重的功能，而只读取缓存的数据），更推荐的做法还可以使用以上它们在返回对象中所提供的 refresh() 方法
  说明

  默认情况下，调用 refresh() 时会将其他处于 pending 的请求取消掉，以 refresh() 的结果作为最新的数据。

  可以向该方法传入配置对象 refresh({ dedupe: true}) 以取消这种默认行为，这样就会采用当前处于 pending 的请求的最终返回结果，作为最新的数据

  
  调用该方法会再次向原有的 URL（如果 URL 是拼接而成的，也是采用当前的参数更新 URL，则不一定与原来的 URL 相同）发送请求，并将获取的的新数据更新到页面上
  vue

  <script setup lang="ts">
  const page = ref(1);
  
  const { data:users, loading, refresh, error } = await useFetch(
    () => `users?page=${page.value}&take=6`, { baseURL: config.API_BASE_URL }
  );
  
  // 用户向前或向后翻页时
  // 通过调用 refresh() 再次向相应的 URL 发送请求，以获取新的数据
  function previous(){
    page.value--;
    refresh();
  }
  
  function next() {
    page.value++;
    refresh();
  }
  </script>
  

  提示

  如果页面使用了缓存，可以通过 refreshNuxtData(keys?) 方法强行进行刷新（重新发出请求获取数据）

  vue

  <template>
    <div>
      {{ pending ? 'Loading' : count }}
    </div>
    <button @click="refresh">Refresh</button>
  </template>
  
  <script setup>
  const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))
  
  const refresh = () => refreshNuxtData('count')
  // 可以指定 key 以刷新（在使用 useAsyncData() 和 useLazyAsyncData() 时所设置的 `key`）指定需要刷新的数据
  // key 可以是单个字符串，或是一系列字符串构成的数组
  // 如果不指定 key 就会刷新当前页面所有通过 useAsyncData()、useLazyAsyncData()、useFetch() 和 useLazyFetch() 方法所获取的数据
  </script>
  

• 清除数据
  使用方法 clearNuxtData(keys?) 清空该页面使用 useAsyncData()、useLazyAsyncData()、useFetch() 和 useLazyFetch() 方法获取数据时，所产生的缓存、错误信息、pending 状态等
  该方法接受（可选）参数 key，它可以是单个字符串，或是一系列字符串构成的数组，以便指定需要清除哪些数据
• 设置请求头
  发送请求的一个常见需求是设置请求的头部信息，Nuxt 3 提供了一个组合式 API useRequestHeaders() 用于设置请求头
  vue

  <script setup>
  // 在头部添加代理 proxy cookie 以便服务器可以读取与用户相关的信息 ❓
  const headers = useRequestHeaders(['cookie'])
  const { data } = await useFetch('/api/me', { headers })
  </script>
  

  注意

  并非所有的头部信息都可以安全地绕过 bypassed ，手动设置可能会引入非预期结果。

  以下是不应该代理 proxied 的常见头部列表

  • host、accept
  • content-length、content-md5、content-type
  • x-forwarded-host、x-forwarded-port、x-forwarded-proto
  • cf-connecting-ip、cf-ray
• 附带 Cookie
  在 SSR 服务端渲染过程中，其实方法 $fetch 只是模拟发送请求（节省性能和带宽 ❓），实际调用相应的方法来获取数据。
  所以在 SSR 时需要手动将 Cookie 附加到返回的结果中
  composables/fetch.ts

  ts

  // 自定义一个组合式 API
  // 用于在 SSR 时将头部信息（这里针对的是 cookie）整合到返回的结果中
  export const fetchWithCookie = async (event: H3Event, url: string) => {
    // 使用方法 $fetch.raw() 异步获取数据
    const res = await $fetch.raw(url)
    // 从响应头部中获取 cookies
    const cookies = (res.headers.get('set-cookie') || '').split(',')
    for (const cookie of cookies) {
      // 将这些 cookies 附加到事件对象中 ❓❓❓
      appendHeader(event, 'set-cookie', cookie)
    }
    // 最后返回响应的数据
    return res._data
  }
  

  vue

  <script setup lang="ts">
  // This composable will automatically pass cookies to the client
  const event = useRequestEvent()
  // 异步获取数据，该方法还会将返回的 cookie 设置到页面上
  const result = await fetchWithCookie(event, '/api/with-cookie')
  onMounted(() => console.log(document.cookie)) // 打印出该页面的 cookie
  </script>