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。
主示例:创建商品
以下两个文件组成一个可运行示例。内存数据只用于本地演示,生产项目应换成数据库并添加认证、事务与唯一约束。
// 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 ?? [])]
}// 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}`,
},
},
)
}启动项目后执行:
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"预期输出
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 或密钥。外部接口一旦发布,应通过版本管理或兼容策略谨慎演进字段。