React / 系统课时
创建 GET 接口
创建 GET 接口
本课使用 App Router 的 route.ts 创建列表与详情 GET 接口。完成后,你可以通过浏览器或 curl 获取 JSON 数据,并正确处理查询参数、动态路径和资源不存在的响应。
学习目标
- 在
app目录中创建 Route Handler - 读取查询参数和动态路径参数
- 返回 JSON、状态码与 404 响应
Route Handler 的位置
Route Handler 使用 Web 标准的 Request 和 Response API,并放在 app 目录下的 route.ts 或 route.js 文件中。一个路由段不能同时存在 page.tsx 与同级 route.ts 来处理同一路径,但可以把接口放在 /api 子路径。官方说明见 Next.js Route Handlers。
本课创建两个地址:GET /api/products 返回列表并支持 q 查询,GET /api/products/<ID> 返回单个商品。
主示例:列表与详情接口
以下三个文件属于同一个可运行示例,单个文件是依赖其他文件的片段示例。
// app/api/products/data.ts
export type Product = {
id: number
name: string
price: number
}
export const products: Product[] = [
{ id: 1, name: 'Keyboard', price: 399 },
{ id: 2, name: 'Mouse', price: 199 },
]// app/api/products/route.ts
import { NextRequest } from 'next/server'
import { products } from './data'
export async function GET(request: NextRequest) {
const keyword = request.nextUrl.searchParams
.get('q')
?.trim()
.toLowerCase()
const result = keyword
? products.filter((product) =>
product.name.toLowerCase().includes(keyword),
)
: products
return Response.json({
data: result,
total: result.length,
})
}// app/api/products/[id]/route.ts
import { products } from '../data'
type Context = {
params: Promise<{ id: string }>
}
export async function GET(_request: Request, context: Context) {
const { id } = await context.params
const productId = Number(id)
if (!Number.isInteger(productId) || productId <= 0) {
return Response.json(
{ error: 'INVALID_PRODUCT_ID' },
{ status: 400 },
)
}
const product = products.find((item) => item.id === productId)
if (!product) {
return Response.json(
{ error: 'PRODUCT_NOT_FOUND' },
{ status: 404 },
)
}
return Response.json({ data: product })
}启动项目后执行:
curl "http://localhost:3000/api/products?q=key"
curl "http://localhost:3000/api/products/1"
curl -i "http://localhost:3000/api/products/99"预期输出
{"data":[{"id":1,"name":"Keyboard","price":399}],"total":1}
{"data":{"id":1,"name":"Keyboard","price":399}}
HTTP/1.1 404 Not Found
...
{"error":"PRODUCT_NOT_FOUND"}响应头中的日期、连接方式和其他框架字段会因环境不同而变化,因此示例使用省略号表示非关键动态内容。
响应设计
列表接口通常返回数组以及分页或总数信息,详情接口返回单个对象。即使当前数据量很小,也应保持响应结构稳定,避免有一条数据时返回对象、多条时返回数组。
错误响应应同时使用合适状态码和稳定错误码。400 表示请求参数本身无效,404 表示参数合法但资源不存在。不要所有失败都返回 200,否则调用方无法使用标准 HTTP 语义判断结果。
查询参数与动态参数
查询参数适合筛选、排序和分页,不应承担资源身份。资源标识放在路径中更清晰,例如 /api/products/1。动态参数仍是字符串,使用前必须转换并校验,不能把 Number(id) 的结果直接带入数据库查询。
过滤关键字要限制长度,并根据数据源选择大小写、转义和索引策略。真实数据库中不要把未经处理的用户输入拼进 SQL,应使用参数化查询或 ORM 条件构造器。
缓存与权限边界
GET 并不代表可以公开访问。用户资料、订单和后台数据仍需认证与授权。权限判断应在读取数据之前执行,返回内容也要避免泄露内部字段。
接口是否缓存取决于当前 Next.js 缓存配置和数据读取方式。对实时性有要求的资源,应明确设计缓存策略,而不是假设所有 GET 都自动实时或自动缓存。文件约定参考 route.ts。