Menu

数据获取与缓存

示例

本指南将介绍 Next.js 中数据获取和缓存的基础知识，提供实用示例和最佳实践。

这是一个最简单的 Next.js 数据获取示例：

app/page.tsx
TypeScript
export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

这个示例演示了在异步 React 服务器组件中使用 fetch API 进行基本的服务端数据获取。

参考资料

示例

使用 fetch API 在服务端获取数据

这个组件将获取并显示博客文章列表。来自 fetch 的响应将被自动缓存。

app/page.tsx
TypeScript
export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

如果你在这个路由的其他地方没有使用任何动态 API，它将在 next build 时被预渲染为静态页面。然后可以使用增量静态再生成更新数据。

如果你不想缓存来自 fetch 的响应，你可以这样做：

let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' })

使用 ORM 或数据库在服务端获取数据

这个组件将获取并显示博客文章列表。来自数据库的响应默认不会被缓存，但可以通过额外配置实现缓存。

app/page.tsx
TypeScript
import { db, posts } from '@/lib/db'
 
export default async function Page() {
  let allPosts = await db.select().from(posts)
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

如果你在这个路由的其他地方没有使用任何动态 API，它将在 next build 时被预渲染为静态页面。然后可以使用增量静态再生成更新数据。

要阻止页面预渲染，你可以在文件中添加以下内容：

export const dynamic = 'force-dynamic'

但是，你通常会使用 cookies、headers 或从页面 props 读取传入的 searchParams 等函数，这些会自动使页面动态渲染。在这种情况下，你不需要显式使用 force-dynamic。

在客户端获取数据

我们建议首先尝试在服务端获取数据。

然而，在某些情况下，客户端数据获取是有意义的。在这些场景中，你可以在 useEffect 中手动调用 fetch (不推荐)，或者使用社区中流行的 React 库（如 SWR 或 React Query）进行客户端获取。

app/page.tsx
TypeScript
'use client'
 
import { useState, useEffect } from 'react'
 
export function Posts() {
  const [posts, setPosts] = useState(null)
 
  useEffect(() => {
    async function fetchPosts() {
      let res = await fetch('https://api.vercel.app/blog')
      let data = await res.json()
      setPosts(data)
    }
    fetchPosts()
  }, [])
 
  if (!posts) return <div>Loading...</div>
 
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

使用 ORM 或数据库缓存数据

你可以使用 unstable_cache API 来缓存响应，允许页面在运行 next build 时被预渲染。

app/page.tsx
TypeScript
import { unstable_cache } from 'next/cache'
import { db, posts } from '@/lib/db'
 
const getPosts = unstable_cache(
  async () => {
    return await db.select().from(posts)
  },
  ['posts'],
  { revalidate: 3600, tags: ['posts'] }
)
 
export default async function Page() {
  const allPosts = await getPosts()
 
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

这个示例将数据库查询的结果缓存 1 小时（3600 秒）。它还添加了缓存标签 posts，可以通过增量静态再生成进行失效处理。

跨多个函数重用数据

Next.js 使用了像 generateMetadata 和 generateStaticParams 这样的 API，在这些情况下，你需要使用在 page 中获取的相同数据。

如果你使用 fetch，请求会自动被记忆化。这意味着你可以安全地使用相同的 URL 和相同的选项调用多次，只会发出一个请求。

app/page.tsx
TypeScript
import { notFound } from 'next/navigation'
 
interface Post {
  id: string
  title: string
  content: string
}
 
async function getPost(id: string) {
  let res = await fetch(`https://api.vercel.app/blog/${id}`)
  let post: Post = await res.json()
  if (!post) notFound()
  return post
}
 
export async function generateStaticParams() {
  let posts = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )
 
  return posts.map((post: Post) => ({
    id: post.id,
  }))
}
 
export async function generateMetadata({ params }: { params: { id: string } }) {
  let post = await getPost(params.id)
 
  return {
    title: post.title,
  }
}
 
export default async function Page({ params }: { params: { id: string } }) {
  let post = await getPost(params.id)
 
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

如果你不使用 fetch，而是直接使用 ORM 或数据库，你可以用 React cache 函数包装你的数据获取。这将去重并只进行一次查询。

import { cache } from 'react'
import { db, posts, eq } from '@/lib/db' // 使用 Drizzle ORM 的示例
import { notFound } from 'next/navigation'
 
export const getPost = cache(async (id) => {
  const post = await db.query.posts.findFirst({
    where: eq(posts.id, parseInt(id)),
  })
 
  if (!post) notFound()
  return post
})

重新验证缓存数据

了解更多关于使用增量静态再生成重新验证缓存数据。

模式

并行和顺序数据获取

在组件中获取数据时，你需要了解两种数据获取模式：并行和顺序。

顺序和并行数据获取
  • 顺序：组件树中的请求相互依赖。这可能导致加载时间更长。
  • 并行：路由中的请求会立即开始，并且会同时加载数据。这减少了加载数据所需的总时间。

顺序数据获取

如果你有嵌套组件，且每个组件都获取自己的数据，那么如果这些数据请求没有被记忆化，数据获取将按顺序进行。

在某些情况下，你可能需要这种模式，因为一个获取依赖于另一个的结果。例如，Playlists 组件只有在 Artist 组件完成数据获取后才会开始获取数据，因为 Playlists 依赖于 artistID prop：

app/artist/[username]/page.tsx
TypeScript
export default async function Page({
  params: { username },
}: {
  params: { username: string }
}) {
  // 获取艺术家信息
  const artist = await getArtist(username)
 
  return (
    <>
      <h1>{artist.name}</h1>
      {/* 在 Playlists 组件加载时显示后备 UI */}
      <Suspense fallback={<div>Loading...</div>}>
        {/* 将艺术家 ID 传递给 Playlists 组件 */}
        <Playlists artistID={artist.id} />
      </Suspense>
    </>
  )
}
 
async function Playlists({ artistID }: { artistID: string }) {
  // 使用艺术家 ID 获取播放列表
  const playlists = await getArtistPlaylists(artistID)
 
  return (
    <ul>
      {playlists.map((playlist) => (
        <li key={playlist.id}>{playlist.name}</li>
      ))}
    </ul>
  )
}

你可以使用 loading.js（用于路由段）或 React <Suspense>（用于嵌套组件）来显示即时加载状态，同时 React 流式传输结果。

这将防止整个路由被数据请求阻塞，用户将能够与页面中准备就绪的部分进行交互。

并行数据获取

默认情况下，布局和页面段会并行渲染。这意味着请求会并行发起。

然而，由于 async/await 的特性，同一段或组件中的一个被等待的请求会阻塞其下的请求。

要并行获取数据，你可以通过在组件外部定义请求来提前发起它们。这通过并行发起两个请求来节省时间，但是用户在两个 Promise 都解决之前不会看到渲染结果。

在下面的示例中，getArtist 和 getAlbums 函数在 Page 组件外部定义，并在组件内部使用 Promise.all 发起：

app/artist/[username]/page.tsx
TypeScript
import Albums from './albums'
 
async function getArtist(username: string) {
  const res = await fetch(`https://api.example.com/artist/${username}`)
  return res.json()
}
 
async function getAlbums(username: string) {
  const res = await fetch(`https://api.example.com/artist/${username}/albums`)
  return res.json()
}
 
export default async function Page({
  params: { username },
}: {
  params: { username: string }
}) {
  const artistData = getArtist(username)
  const albumsData = getAlbums(username)
 
  // 并行发起两个请求
  const [artist, albums] = await Promise.all([artistData, albumsData])
 
  return (
    <>
      <h1>{artist.name}</h1>
      <Albums list={albums} />
    </>
  )
}

此外，你可以添加一个 Suspense 边界 来分解渲染工作，并尽快显示部分结果。

预加载数据

防止瀑布流的另一种方法是使用预加载模式，即创建一个你可以在阻塞请求之前提前调用的工具函数。例如，checkIsAvailable() 阻塞了 <Item/> 的渲染，所以你可以在它之前调用 preload() 来提前开始 <Item/> 的数据依赖。当 <Item/> 被渲染时，它的数据已经被获取了。

注意 preload 函数不会阻塞 checkIsAvailable() 的执行。

components/Item.tsx
TypeScript
import { getItem } from '@/utils/get-item'
 
export const preload = (id: string) => {
  // void 计算给定表达式并返回 undefined
  // https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/void
  void getItem(id)
}
export default async function Item({ id }: { id: string }) {
  const result = await getItem(id)
  // ...
}
app/item/[id]/page.tsx
TypeScript
import Item, { preload, checkIsAvailable } from '@/components/Item'
 
export default async function Page({
  params: { id },
}: {
  params: { id: string }
}) {
  // 开始加载项目数据
  preload(id)
  // 执行另一个异步任务
  const isAvailable = await checkIsAvailable()
 
  return isAvailable ? <Item id={id} /> : null
}

值得注意的是： "preload" 函数可以有任何名称，因为它是一个模式，而不是 API。

将 React cache 和 server-only 与预加载模式结合使用

你可以将 cache 函数、预加载模式和 server-only 包结合起来，创建一个可以在整个应用中使用的数据获取工具。

utils/get-item.ts
import { cache } from 'react'
import 'server-only'
 
export const preload = (id: string) => {
  void getItem(id)
}
 
export const getItem = cache(async (id: string) => {
  // ...
})
utils/get-item.js
import { cache } from 'react'
import 'server-only'
 
export const preload = (id) => {
  void getItem(id)
}
 
export const getItem = cache(async (id) => {
  // ...
})

使用这种方法，你可以提前获取数据、缓存响应，并确保这种数据获取只发生在服务器上。

布局、页面或其他组件可以使用 utils/get-item 导出的函数，使它们能够控制项目数据的获取时机。

值得注意的是：

  • 我们推荐使用 server-only 包来确保服务器数据获取函数永远不会在客户端使用。

防止敏感数据泄露到客户端

我们推荐使用 React 的污染 API，taintObjectReference 和 taintUniqueValue，来防止整个对象实例或敏感值被传递到客户端。

要在你的应用中启用污染功能，将 Next.js 配置中的 experimental.taint 选项设置为 true：

next.config.js
module.exports = {
  experimental: {
    taint: true,
  },
}

然后将你想要污染的对象或值传递给 experimental_taintObjectReference 或 experimental_taintUniqueValue 函数：

app/utils.ts
import { queryDataFromDB } from './api'
import {
  experimental_taintObjectReference,
  experimental_taintUniqueValue,
} from 'react'
 
export async function getUserData() {
  const data = await queryDataFromDB()
  experimental_taintObjectReference(
    '不要将整个用户对象传递给客户端',
    data
  )
  experimental_taintUniqueValue(
    "不要将用户的地址传递给客户端",
    data,
    data.address
  )
  return data
}
app/utils.js
import { queryDataFromDB } from './api'
import {
  experimental_taintObjectReference,
  experimental_taintUniqueValue,
} from 'react'
 
export async function getUserData() {
  const data = await queryDataFromDB()
  experimental_taintObjectReference(
    '不要将整个用户对象传递给客户端',
    data
  )
  experimental_taintUniqueValue(
    "不要将用户的地址传递给客户端",
    data,
    data.address
  )
  return data
}
app/page.tsx
TypeScript
import { getUserData } from './data'
 
export async function Page() {
  const userData = await getUserData()
  return (
    <ClientComponent
      user={userData} // 这会因为 taintObjectReference 而导致错误
      address={userData.address} // 这会因为 taintUniqueValue 而导致错误
    />
  )
}