获取数据
了解如何获取数据以及流式传输依赖于数据的内容。
本页将带你了解如何在 Server 和 Client 组件中获取数据,以及如何流式传输依赖于未缓存数据的组件。
获取数据#
Server Components#
你可以在 Server Components 中使用任何异步 I/O 获取数据,例如:
使用 fetch API#
要使用 fetch API 获取数据,请将组件改为异步函数,并等待 fetch 调用。例如:
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>
)
}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调用,以便更好地观察和调试。请参阅loggingAPI 参考。
使用 ORM 或数据库#
由于 Server Components 在服务器上渲染,凭据和查询逻辑不会包含在客户端 bundle 中,因此你可以安全地使用 ORM 或数据库客户端进行数据库查询。
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>
)
}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 约定、基础设施考虑因素和性能权衡。
你可以通过两种方式在应用中使用流式传输:
- 用
loading.js文件包裹页面 - 用
<Suspense>包裹组件
小知识: 机器人和爬虫的接收方式与浏览器不同。Next.js 会等待数据获取完成后发送完全渲染的页面,而不是逐步流式传输。请参阅机器人和爬虫。
使用 loading.js#
你可以在页面所在文件夹中创建 loading.js 文件,以便在获取数据时流式传输整个页面。例如,要流式传输 app/blog/page.js,请将该文件添加到 app/blog 文件夹中。
export default function Loading() {
// 在此定义 Loading UI
return <div>Loading...</div>
}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> 边界之外的任何页面内容,并将边界内的博客文章列表流式传输进来。
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>
)
}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 中获取数据有两种方式:
- React 的
useAPI - 像 SWR 或 React Query 这样的社区库
使用 use API 流式传输数据#
你可以使用 React 的 use API 将数据从服务器流式传输到客户端。首先在 Server 组件中获取数据,然后将 promise 作为 prop 传递给 Client Component:
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>
)
}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:
'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>
)
}'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:
'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>
)
}'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:
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>
)
}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 解析完成:
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 时立即开始。
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} />
</>
)
}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 中。这样多个组件可以在同一请求中调用该函数并共享同一个结果:
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),
})
})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():
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>
}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),然后在消费该结果的组件中调用同一个函数。
数据获取函数必须对匹配的调用进行去重,以便组件可以复用预加载期间发起的请求。请使用以下方法之一:
- 对于
fetch,相同的请求会自动被记忆化。 - 对于 ORM 或数据库,请将数据获取函数包裹在
React.cache中。 - 使用 Cache Components 时,在数据获取函数中添加
'use cache'。如果该函数读取cookies()或headers()等请求 API,请使用'use cache: private'。
在生产环境中,对私有 Cache 函数的匹配调用可以在一个请求内复用相同的结果。这使组件能够复用预加载期间发起的请求,而无需将结果存储在跨请求的服务器缓存中。
将预加载函数放在消费数据的组件旁边。这样在移动或删除组件时,更容易发现这种依赖关系:
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>
}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(),以便更早地开始加载该项:
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
}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() 发起的请求。