NNext.js 中文网 GitHub

获取数据

了解如何获取数据以及流式传输依赖于数据的内容。

本页将带你了解如何在 Server 和 Client 组件中获取数据,以及如何流式传输依赖于未缓存数据的组件。

获取数据#

Server Components#

你可以在 Server Components 中使用任何异步 I/O 获取数据,例如:

  1. fetch API
  2. ORM 或数据库

使用 fetch API#

要使用 fetch API 获取数据,请将组件改为异步函数,并等待 fetch 调用。例如:

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

小知识:

  • React 组件树中相同的 fetch 请求默认会被记忆化,因此你可以在需要数据的组件中获取数据,而无需逐层传递 props。
  • fetch 请求默认不会被缓存,并且会阻塞页面渲染,直到请求完成。使用 use cache 指令来缓存结果,或将获取数据的组件包裹在 <Suspense> 中,以便在请求时流式传输最新数据。详情请参阅缓存。
  • 在开发过程中,你可以记录 fetch 调用,以便更好地观察和调试。请参阅 logging API 参考。

使用 ORM 或数据库#

由于 Server Components 在服务器上渲染,凭据和查询逻辑不会包含在客户端 bundle 中,因此你可以安全地使用 ORM 或数据库客户端进行数据库查询。

app/blog/page.tsx
import { db, posts } from '@/lib/db'

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

export default async function Page() {
  const allPosts = await db.select().from(posts)
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

你仍应确保请求经过正确的身份验证和授权。有关保护服务端数据访问的最佳实践,请参阅数据安全指南。

流式传输#

当你在 Server Components 中获取数据时,数据会针对每个请求在服务器上获取并渲染。如果有任何缓慢的数据请求,整个路由的渲染都会被阻塞,直到所有数据获取完成。

为了改善初始加载时间和用户体验,你可以将页面拆分成更小的块,并从服务器逐步将这些块发送到客户端。这称为流式传输。请参阅流式传输指南,深入了解流式传输的工作原理,包括 HTTP 约定、基础设施考虑因素和性能权衡。

你可以通过两种方式在应用中使用流式传输:

  1. 用 loading.js 文件包裹页面
  2. 用 <Suspense>包裹组件

小知识: 机器人和爬虫的接收方式与浏览器不同。Next.js 会等待数据获取完成后发送完全渲染的页面,而不是逐步流式传输。请参阅机器人和爬虫。

使用 loading.js#

你可以在页面所在文件夹中创建 loading.js 文件,以便在获取数据时流式传输整个页面。例如,要流式传输 app/blog/page.js,请将该文件添加到 app/blog 文件夹中。

app/blog/loading.tsx
export default function Loading() {
  // 在此定义 Loading UI
  return <div>Loading...</div>
}
app/blog/loading.js
export default function Loading() {
  // 在此定义 Loading UI
  return <div>Loading...</div>
}

在导航时,用户会立即看到布局和加载状态,同时页面正在渲染。渲染完成后,新内容将自动替换进来。

在幕后,loading.js 将嵌套在 layout.js 内,并自动将 page.js 文件及其下方所有子级包裹在一个 <Suspense> 边界中。

因此,访问未缓存数据或运行时数据(例如 cookies()、headers() 或未缓存的 fetch)的布局不会回退到同一路由段的 loading.js。相反,它会阻塞导航,直到布局渲染完成。Cache Components 通过构建时错误引导你,从而避免这种情况。

要解决此问题,请将未缓存的访问包裹在其自己的<Suspense>边界中并提供 fallback,或者将数据获取移入 page.js,以便 loading.js 能够覆盖它。有关更多详情,请参阅 loading.js。

因此,虽然 loading.js 很适合流式传输路由段,但建议在更接近运行时或未缓存数据访问的位置使用 <Suspense>。

使用 <Suspense>#

<Suspense> 使你可以更精细地控制页面中要流式传输的部分。例如,你可以立即显示 <Suspense> 边界之外的任何页面内容,并将边界内的博客文章列表流式传输进来。

app/blog/page.tsx
import { Suspense } from 'react'
import BlogList from '@/components/BlogList'
import BlogListSkeleton from '@/components/BlogListSkeleton'

export default function BlogPage() {
  return (
    <div>
      
      <header>
        <h1>Welcome to the Blog</h1>
        <p>Read the latest posts below.</p>
      </header>
      <main>
        
        <Suspense fallback={<BlogListSkeleton />}>
          <BlogList />
        </Suspense>
      </main>
    </div>
  )
}
app/blog/page.js
import { Suspense } from 'react'
import BlogList from '@/components/BlogList'
import BlogListSkeleton from '@/components/BlogListSkeleton'

export default function BlogPage() {
  return (
    <div>
      
      <header>
        <h1>Welcome to the Blog</h1>
        <p>Read the latest posts below.</p>
      </header>
      <main>
        
        <Suspense fallback={<BlogListSkeleton />}>
          <BlogList />
        </Suspense>
      </main>
    </div>
  )
}

创建有意义的加载状态#

即时加载状态是在导航后立即向用户显示的 fallback UI。为了获得最佳用户体验,我们建议设计有意义的加载状态,帮助用户理解应用正在响应。例如,你可以使用骨架屏和旋转指示器,或者未来界面中一小部分但有意义的内容,例如封面图片、标题等。

在开发中,你可以使用 React Devtools 预览和检查组件的加载状态。

Client Components#

在 Client Components 中获取数据有两种方式:

  1. React 的 use API
  2. 像 SWR 或 React Query 这样的社区库

使用 use API 流式传输数据#

你可以使用 React 的 use API 将数据从服务器流式传输到客户端。首先在 Server 组件中获取数据,然后将 promise 作为 prop 传递给 Client Component:

app/blog/page.tsx
import Posts from '@/app/ui/posts'
import { Suspense } from 'react'

export default function Page() {
  // 不要等待数据获取函数
  const posts = getPosts()

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Posts posts={posts} />
    </Suspense>
  )
}
app/blog/page.js
import Posts from '@/app/ui/posts'
import { Suspense } from 'react'

export default function Page() {
  // 不要等待数据获取函数
  const posts = getPosts()

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Posts posts={posts} />
    </Suspense>
  )
}

然后,在 Client Component 中,使用 use API 读取该 promise:

app/ui/posts.tsx
'use client'
import { use } from 'react'

export default function Posts({
  posts,
}: {
  posts: Promise<{ id: string; title: string }[]>
}) {
  const allPosts = use(posts)

  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
app/ui/posts.js
'use client'
import { use } from 'react'

export default function Posts({ posts }) {
  const allPosts = use(posts)

  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

在上面的示例中,<Posts> 组件被包裹在<Suspense> 边界中。这意味着在 promise 解析期间将显示 fallback。了解更多关于流式传输的信息。

你可以在服务器上使用 await 解析 promise,或在 Client Component 中使用 use() 解析。React 介绍了何时在 Server 或 Client Component 中解析 Promise。要与多个 Client Component 共享一个 promise 而不是将其作为 prop 传递,可以通过 context 提供它。请参阅在 Context Provider 中使用 React 的 use。

社区库#

你可以使用像 SWR 或 React Query 这样的社区库在 Client Components 中获取数据。这些库对于缓存、流式传输和其他功能有自己的语义。例如,使用 SWR:

app/blog/page.tsx
'use client'
import useSWR from 'swr'

const fetcher = (url) => fetch(url).then((r) => r.json())

export default function BlogPage() {
  const { data, error, isLoading } = useSWR(
    'https://api.vercel.app/blog',
    fetcher
  )

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {data.map((post: { id: string; title: string }) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
app/blog/page.js
'use client'

import useSWR from 'swr'

const fetcher = (url) => fetch(url).then((r) => r.json())

export default function BlogPage() {
  const { data, error, isLoading } = useSWR(
    'https://api.vercel.app/blog',
    fetcher
  )

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {data.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

请参阅客户端数据获取,了解直接从浏览器获取数据、从 Server Component 提供初始数据,以及协调库缓存与 Next.js 服务端和客户端缓存。

示例#

顺序数据获取#

当一个请求依赖于另一个请求的数据时,就会发生顺序数据获取。

例如,<Playlists> 只有在 getArtist() 解析后才能获取数据,因为它需要 artistID:

app/artist/[username]/page.tsx
export default async function Page({
  params,
}: {
  params: Promise<{ username: string }>
}) {
  const { username } = await params
  // 获取歌手信息
  const artist = await getArtist(username)

  return (
    <>
      <h1>{artist.name}</h1>
      
      <Suspense fallback={<div>Loading...</div>}>
        
        <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>
  )
}
app/artist/[username]/page.js
export default async function Page({ params }) {
  const { username } = await params
  // 获取歌手信息
  const artist = await getArtist(username)

  return (
    <>
      <h1>{artist.name}</h1>
      
      <Suspense fallback={<div>Loading...</div>}>
        
        <Playlists artistID={artist.id} />
      </Suspense>
    </>
  )
}

async function Playlists({ artistID }) {
  // 使用歌手 ID 获取播放列表
  const playlists = await getArtistPlaylists(artistID)

  return (
    <ul>
      {playlists.map((playlist) => (
        <li key={playlist.id}>{playlist.name}</li>
      ))}
    </ul>
  )
}

在此示例中,<Suspense> 允许播放列表在歌手数据加载后流式传输进来。但是,页面在显示任何内容之前仍会等待歌手数据。为避免这种情况,你可以将整个页面组件包裹在 <Suspense> 边界中(例如,使用 loading.js 文件),以立即显示加载状态。

确保你的数据源能够快速解析第一个请求,因为它会阻塞其他所有内容。如果无法进一步优化请求,且数据不经常变化,请考虑缓存结果。

并行数据获取#

当路由中的数据请求被急切地发起并同时开始时,就会发生并行数据获取。

默认情况下,布局和页面是并行渲染的。因此每个路由段都会尽快开始获取数据。

但是,在任何组件内,如果多个 async/await 请求一个接一个地放置,它们仍可能是顺序执行的。例如,getAlbums 将被阻塞,直到 getArtist 解析完成:

app/artist/[username]/page.tsx
import { getArtist, getAlbums } from '@/app/lib/data'

export default async function Page({ params }) {
  // 这些请求将是顺序执行的
  const { username } = await params
  const artist = await getArtist(username)
  const albums = await getAlbums(username)
  return <div>{artist.name}</div>
}

通过调用 fetch 发起多个请求,然后使用 Promise.all 等待它们。请求在调用 fetch 时立即开始。

app/artist/[username]/page.tsx
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,
}: {
  params: Promise<{ username: string }>
}) {
  const { username } = await params

  // 发起请求
  const artistData = getArtist(username)
  const albumsData = getAlbums(username)

  const [artist, albums] = await Promise.all([artistData, albumsData])

  return (
    <>
      <h1>{artist.name}</h1>
      <Albums list={albums} />
    </>
  )
}
app/artist/[username]/page.js
import Albums from './albums'

async function getArtist(username) {
  const res = await fetch(`https://api.example.com/artist/${username}`)
  return res.json()
}

async function getAlbums(username) {
  const res = await fetch(`https://api.example.com/artist/${username}/albums`)
  return res.json()
}

export default async function Page({ params }) {
  const { username } = await params

  // 发起请求
  const artistData = getArtist(username)
  const albumsData = getAlbums(username)

  const [artist, albums] = await Promise.all([artistData, albumsData])

  return (
    <>
      <h1>{artist.name}</h1>
      <Albums list={albums} />
    </>
  )
}

小知识: 使用 Promise.all 时,如果一个请求失败,整个操作都会失败。要处理这种情况,你可以改用 Promise.allSettled 方法。

使用 React.cache 复用数据#

对于不使用 fetch 的数据访问(例如 ORM 或数据库查询),请将函数包裹在 React.cache 中。这样多个组件可以在同一请求中调用该函数并共享同一个结果:

app/lib/user.ts
import { cache } from 'react'
import { db, eq, users } from '@/lib/db'

export const getUser = cache(async (id: string) => {
  return db.query.users.findFirst({
    where: eq(users.id, id),
  })
})
app/lib/user.js
import { cache } from 'react'
import { db, eq, users } from '@/lib/db'

export const getUser = cache(async (id) => {
  return db.query.users.findFirst({
    where: eq(users.id, id),
  })
})

Server Components 可以直接调用 getUser():

app/dashboard/page.tsx
import { getUser } from '../lib/user'

export default async function DashboardPage() {
  const user = await getUser('1')

  if (!user) {
    return null
  }

  return <h1>Dashboard for {user.name}</h1>
}
app/dashboard/page.js
import { getUser } from '../lib/user'

export default async function DashboardPage() {
  const user = await getUser('1')

  if (!user) {
    return null
  }

  return <h1>Dashboard for {user.name}</h1>
}

由于 getUser 用 React.cache 包裹,因此在同一请求中使用相同 id 的调用会返回相同的记忆化结果。

小知识: React.cache 仅作用于当前请求。每个请求都有自己独立的记忆化作用域,请求之间不会共享。

预加载数据#

当组件在其他阻塞工作之后渲染时,即使请求输入已经可用,它的数据请求也会较晚开始。预加载会更早地发起请求,使其能够与该项工作并行运行,从而避免请求瀑布。

要预加载数据,请在阻塞工作之前调用数据获取函数(不使用 await),然后在消费该结果的组件中调用同一个函数。

数据获取函数必须对匹配的调用进行去重,以便组件可以复用预加载期间发起的请求。请使用以下方法之一:

在生产环境中,对私有 Cache 函数的匹配调用可以在一个请求内复用相同的结果。这使组件能够复用预加载期间发起的请求,而无需将结果存储在跨请求的服务器缓存中。

将预加载函数放在消费数据的组件旁边。这样在移动或删除组件时,更容易发现这种依赖关系:

app/item/[id]/item.tsx
async function getItem(id: string) {
  const res = await fetch(`https://api.example.com/items/${id}`)
  return res.json()
}

export const preload = (id: string) => {
  void getItem(id)
}

export default async function Item({ id }: { id: string }) {
  const item = await getItem(id)
  return <div>{item.name}</div>
}
app/item/[id]/item.js
async function getItem(id) {
  const res = await fetch(`https://api.example.com/items/${id}`)
  return res.json()
}

export const preload = (id) => {
  void getItem(id)
}

export default async function Item({ id }) {
  const item = await getItem(id)
  return <div>{item.name}</div>
}

在另一个阻塞请求之前调用 preload(),以便更早地开始加载该项:

app/item/[id]/page.tsx
import Item, { preload } from './item'
import { checkIsAvailable } from '@/app/lib/data'

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  preload(id)
  const isAvailable = await checkIsAvailable(id)

  return isAvailable ? <Item id={id} /> : null
}
app/item/[id]/page.js
import Item, { preload } from './item'
import { checkIsAvailable } from '@/app/lib/data'

export default async function Page({ params }) {
  const { id } = await params

  preload(id)
  const isAvailable = await checkIsAvailable(id)

  return isAvailable ? <Item id={id} /> : null
}

在 checkIsAvailable() 运行期间,该项的请求会继续进行。如果页面渲染 <Item>,相同的 fetch 调用会复用 preload() 发起的请求。

Next.js 中文网