在 Next.js 14 的 App Router API 路由中，直接 await request.json() 会触发 TypeScript 类型警告（Unsafe assignment of an any value），需结合运行时校验与静态类型推导实现真正安全的请求体处理。
在 next.js 14 的 app router api 路由中，直接 `await request.json()` 会触发 typescript 类型警告（`unsafe assignment of an any value`），需结合运行时校验与静态类型推导实现真正安全的请求体处理。
在构建面向 iOS 等外部客户端的 Next.js 14 API 接口时，仅依赖 TypeScript 接口（如 interface RequestBody）无法提供运行时保障——request.json() 返回类型为 any，TypeScript 不会阻止非法数据进入逻辑层，ESLint 报出 Unsafe assignment of an any value 正是对此类隐式类型风险的合理警示。
推荐方案：使用 Zod 进行声明式 Schema 校验
Zod 是轻量、零依赖、类型安全的运行时校验库，支持自动类型推导，完美契合 Next.js 的 TypeScript 开发流。它不仅能拦截非法输入，还能将校验结果无缝映射为精确的 TypeScript 类型，彻底消除 any 带来的安全隐患。
✅ 安装与基础配置：
npm install zod # 或 yarn add zod
✅ 定义校验 Schema 并自动推导类型：
// app/api/route/route.ts
import { z } from 'zod';
const RequestBodySchema = z.object({
name: z.string().min(1, 'Name is required').max(50, 'Name too long'),
});
// 自动推导出精确 TypeScript 类型：{ name: string }
type RequestBody = z.infer<typeof RequestBodySchema>;✅ 在 API Handler 中安全解析与校验：
import { NextResponse } from 'next/server';
import { z } from 'zod';
const RequestBodySchema = z.object({
name: z.string().min(1, 'Name is required'),
});
export async function POST(request: Request) {
try {
const rawBody = await request.json();
// ✅ safeParse 返回 { success: boolean; data?: RequestBody; error?: ZodError }
const result = RequestBodySchema.safeParse(rawBody);
if (!result.success) {
return NextResponse.json(
{ error: 'Validation failed', details: result.error.issues },
{ status: 400 }
);
}
// ✅ result.data 是完全类型安全的 RequestBody —— 无 any，无强制断言
const { name } = result.data;
return NextResponse.json({ message: `Hello, ${name}!` }, { status: 200 });
} catch (err) {
// 捕获 JSON 解析失败（如非 JSON 内容）等底层错误
return NextResponse.json({ error: 'Invalid JSON format' }, { status: 400 });
}
}? 关键优势说明：
-
safeParse避免抛出异常，便于统一错误处理； -
z.infer<typeof schema></typeof>自动生成精准类型，无需手动维护interface，保持类型与校验逻辑严格一致； - 支持丰富校验规则（
.email(),.url(),.optional(),.array(), 自定义谓词等），远超简单typeof判断； - 错误信息结构化（
error.issues），可直接用于前端提示或日志追踪。
⚠️ 注意事项：
- 切勿使用
as RequestBody强制类型断言——它绕过校验，使类型系统失效； -
request.json()本身可能抛出语法错误（如空体、非法 JSON），需包裹在try/catch中； - 若需兼容
GET查询参数或FormData，Zod 同样提供z.string().parse()和z.record(...).parse()等灵活适配方式。
通过 Zod，你获得的不只是“能用”的校验，而是端到端的类型安全：从网络字节流 → JSON 解析 → 运行时校验 → 类型精确注入 → 业务逻辑执行，每一步都受控、可预测、可测试。
