React / 系统课时
实现公开页面
实现公开页面
公开页面需要完成首页入口、文章列表、关键词搜索和详情访问。本课使用一份最小数据仓储,打通从查询参数到服务端渲染结果的完整读取链路。
学习目标
- 使用 App Router 组织公开列表和动态详情路由
- 在服务端根据搜索词过滤文章并生成链接
- 对不存在或未发布的内容返回明确的未找到状态
规划公开访问链路
公开访问只读取 PUBLISHED 状态文章。首页负责提供入口和最新内容,列表页负责搜索与浏览,详情页根据 slug 查询单篇文章。任何公开查询都不能先查出草稿再依赖前端隐藏。
本课先使用内存数据完成页面行为,便于独立运行。接入数据库时,只需替换仓储函数,页面的输入和返回类型可以保持不变。
创建文章仓储
将下面文件保存为 src/lib/articles.ts。仓储集中处理“只返回已发布文章”的规则,避免列表页和详情页分别实现。
// src/lib/articles.ts
export type PublicArticle = {
slug: string
title: string
summary: string
content: string
publishedAt: string
}
const articles: PublicArticle[] = [
{
slug: 'nextjs-server-components',
title: '理解 Server Component',
summary: '了解服务端组件如何读取数据并减少客户端代码。',
content: 'Server Component 默认在服务端执行,适合读取数据库和组织页面数据。',
publishedAt: '2026-07-20',
},
{
slug: 'nextjs-route-handlers',
title: '使用 Route Handler',
summary: '使用标准 HTTP 方法实现服务端接口。',
content: 'Route Handler 位于 app 目录的 route.ts 文件中,可返回标准 Response。',
publishedAt: '2026-07-18',
},
]
export async function listPublishedArticles(
query: string,
): Promise<PublicArticle[]> {
const normalized = query.trim().toLocaleLowerCase()
return articles.filter((article) => {
if (!normalized) return true
return [article.title, article.summary]
.join(' ')
.toLocaleLowerCase()
.includes(normalized)
})
}
export async function findPublishedArticle(
slug: string,
): Promise<PublicArticle | null> {
return articles.find((article) => article.slug === slug) ?? null
}这是可运行的本地示例,数据会随代码发布而固定,不适合真实后台写入。生产项目应把同名函数改为数据库查询,并在 SQL 中直接附带发布状态条件。
实现列表与搜索
列表页读取 URL 中的 q 参数,由服务端完成过滤。表单使用 GET 方法,因此搜索地址可以复制、收藏和刷新。
// src/app/articles/page.tsx
import Link from 'next/link'
import { listPublishedArticles } from '@/lib/articles'
type PageProps = {
searchParams: Promise<{ q?: string }>
}
export default async function ArticlesPage({ searchParams }: PageProps) {
const { q = '' } = await searchParams
const articles = await listPublishedArticles(q)
return (
<main>
<h1>文章列表</h1>
<form action="/articles" method="get">
<label htmlFor="q">关键词</label>
<input
id="q"
name="q"
type="search"
defaultValue={q}
placeholder="搜索标题或摘要"
/>
<button type="submit">搜索</button>
</form>
{articles.length === 0 ? (
<p>没有找到匹配的文章。</p>
) : (
<ul>
{articles.map((article) => (
<li key={article.slug}>
<h2>
<Link href={`/articles/${article.slug}`}>
{article.title}
</Link>
</h2>
<p>{article.summary}</p>
<time dateTime={article.publishedAt}>
{article.publishedAt}
</time>
</li>
))}
</ul>
)}
</main>
)
}启动项目并访问列表页。
npm run dev预期结果
Local: http://localhost:3000实际启动日志和端口可能不同。打开 /articles?q=server 时,只显示标题或摘要包含 server 的文章;清空关键词后显示全部示例文章。
实现动态详情页
详情页从动态路由参数中读取 slug。查询结果为空时调用 notFound(),让框架返回项目的未找到页面和 404 状态。
// src/app/articles/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { findPublishedArticle } from '@/lib/articles'
type PageProps = {
params: Promise<{ slug: string }>
}
export default async function ArticleDetailPage({ params }: PageProps) {
const { slug } = await params
const article = await findPublishedArticle(slug)
if (!article) {
notFound()
}
return (
<article>
<h1>{article.title}</h1>
<p>{article.summary}</p>
<time dateTime={article.publishedAt}>{article.publishedAt}</time>
<div>{article.content}</div>
</article>
)
}验证详情和未找到分支。
curl -I http://localhost:3000/articles/nextjs-server-components
curl -I http://localhost:3000/articles/not-exists预期结果
HTTP/1.1 200 OK
...
HTTP/1.1 404 Not Found
...响应头顺序和其他字段可能不同,关键是两个地址分别返回 200 与 404。
补充首页入口
首页不需要复制完整列表逻辑,可以调用同一仓储函数后只展示前几篇文章。路由与数据规则应复用,不能让首页显示草稿而列表页不显示。
首页至少包含站点说明、文章列表入口和最新文章链接。搜索功能放在 /articles 即可,第一版不必在多个页面重复维护同一套表单。
关键边界
搜索词必须先去除首尾空白,并限制最大长度,避免无意义的大输入进入数据库。接入 SQL 后应使用参数化查询,不能拼接用户输入。
详情查询必须同时匹配 slug 和发布状态。仅凭页面没有草稿链接并不安全,因为用户仍可手动输入地址。文章正文若允许 Markdown 或 HTML,还需在渲染前采用可信解析与清理策略,防止脚本注入。