React / 系统课时

处理 POST 请求

处理 POST 请求

本课创建一个可接收 JSON 的 POST 接口,完成请求体解析、字段校验、资源创建和结果验证。你将学会区分无效 JSON、字段错误与成功创建,并返回符合语义的 HTTP 状态码。

学习目标

  • 使用 request.json() 读取并保护性解析请求体
  • 校验字段类型、必填项和数值范围
  • 返回 201、400、415 等明确响应

POST 处理链路

POST Route Handler 通常依次完成媒体类型检查、JSON 解析、字段校验、身份与权限判断、业务写入和响应构造。Route Handler 使用标准 Web Request/Response API,因此可以通过 request.headers、request.json() 和 Response.json() 完成基础接口处理。官方参考见 Next.js Route Handlers。

主示例:创建商品

以下两个文件组成一个可运行示例。内存数据只用于本地演示,生产项目应换成数据库并添加认证、事务与唯一约束。

ts
// app/api/products/store.ts
export type Product = {
  id: number
  name: string
  price: number
}

const store = globalThis as typeof globalThis & {
  __apiProducts?: Product[]
  __nextApiProductId?: number
}

store.__apiProducts ??= []
store.__nextApiProductId ??= 1

export function createProduct(input: Omit<Product, 'id'>): Product {
  const id = store.__nextApiProductId ?? 1
  const product = { id, ...input }

  store.__apiProducts?.push(product)
  store.__nextApiProductId = id + 1
  return product
}

export function listProducts(): Product[] {
  return [...(store.__apiProducts ?? [])]
}
ts
// app/api/products/route.ts
import {
  createProduct,
  listProducts,
} from './store'

type ProductBody = {
  name?: unknown
  price?: unknown
}

export async function GET() {
  return Response.json({ data: listProducts() })
}

export async function POST(request: Request) {
  const contentType = request.headers.get('content-type') ?? ''

  if (!contentType.includes('application/json')) {
    return Response.json(
      { error: 'CONTENT_TYPE_MUST_BE_JSON' },
      { status: 415 },
    )
  }

  let body: ProductBody

  try {
    body = (await request.json()) as ProductBody
  } catch {
    return Response.json(
      { error: 'INVALID_JSON' },
      { status: 400 },
    )
  }

  const name =
    typeof body.name === 'string' ? body.name.trim() : ''
  const price =
    typeof body.price === 'number' ? body.price : Number.NaN

  const fieldErrors: Record<string, string> = {}

  if (!name) {
    fieldErrors.name = '商品名称不能为空'
  } else if (name.length > 80) {
    fieldErrors.name = '商品名称不能超过 80 个字符'
  }

  if (!Number.isFinite(price) || price <= 0) {
    fieldErrors.price = '价格必须是大于 0 的数字'
  }

  if (Object.keys(fieldErrors).length > 0) {
    return Response.json(
      { error: 'VALIDATION_FAILED', fieldErrors },
      { status: 400 },
    )
  }

  const product = createProduct({ name, price })

  return Response.json(
    { data: product },
    {
      status: 201,
      headers: {
        Location: `/api/products/${product.id}`,
      },
    },
  )
}

启动项目后执行:

bash
curl -i \
  -X POST "http://localhost:3000/api/products" \
  -H "Content-Type: application/json" \
  -d '{"name":"Keyboard","price":399}'

curl "http://localhost:3000/api/products"

预期输出

text
HTTP/1.1 201 Created
Location: /api/products/<ID>
...
{"data":{"id":<ID>,"name":"Keyboard","price":399}}

{"data":[{"id":<ID>,"name":"Keyboard","price":399}]}

<ID> 由当前进程中的内存计数器生成,响应日期和其他框架头也可能不同。再次提交会得到新的标识。

解析与校验边界

request.json() 在请求体不是合法 JSON 时会抛出异常,因此应单独捕获并返回 400。解析成功也不代表字段可信,JSON 中的 name 可能是数组,price 可能是字符串或空值,必须逐字段检查类型。

示例要求价格直接使用 JSON 数字。如果接口允许字符串金额,应先定义明确格式,再转换为最小货币单位的整数,避免二进制浮点误差影响支付和结算。

状态码选择

成功创建资源使用 201 Created,并可在 Location 响应头中提供新资源地址。请求不是 JSON 时返回 415 Unsupported Media Type;JSON 语法或字段不合法时返回 400 Bad Request。

身份未认证通常返回 401,已认证但无权限返回 403,资源冲突可返回 409。状态码应与错误体中的稳定错误码一致,方便调用方实现重试、提示和监控。

生产实现检查

真实创建操作需要认证授权、数据库事务、唯一约束、审计日志和幂等策略。不要把用户提交对象直接传入 ORM 的批量赋值接口,应显式选择允许写入的字段,避免越权修改内部状态。

接口还应限制请求体大小、记录追踪标识并避免在错误响应中泄露堆栈、SQL 或密钥。外部接口一旦发布,应通过版本管理或兼容策略谨慎演进字段。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理 POST 请求

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

登录哪都通