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> 返回单个商品。

主示例:列表与详情接口

以下三个文件属于同一个可运行示例,单个文件是依赖其他文件的片段示例。

ts
// 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 },
]
ts
// 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,
  })
}
ts
// 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 })
}

启动项目后执行:

bash
curl "http://localhost:3000/api/products?q=key"
curl "http://localhost:3000/api/products/1"
curl -i "http://localhost:3000/api/products/99"

预期输出

text
{"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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建 GET 接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通