v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:08:00.000Z▲ 0 upvotes

Zod 谈 API 路由 Next.js:严格、剥离以及实际防止额外字段的内容

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

我们要解决什么问题?

通常与严格验证一起讨论的两种攻击是:

  • 批量分配。 客户端将 {"name":"Ivan","role":"admin"} 发送到配置文件更新端点,服务器发送 db.user.update({ data: body })。 role 字段进入数据库。
  • 原型污染。主体包含键__proto__或constructor.prototype,代码通过自写的deepMerge递归地将其合并为对象,改变原型Object。

这两个漏洞都不是由于缺少 .strict() 引起的,而是由于服务器使用原始请求正文这一事实引起的。如果您通过 Zod 进行验证,然后仅使用 parse 的结果,即使没有 strict ,额外的键也不会到达那里:默认情况下,z.object 会丢弃它们(剥离模式)。

三种对象模式

import { z } from "zod";

const Base = { name: z.string().min(1).max(100) };

z.object(Base).parse({ name: "a", role: "admin" });
// { name: "a" } — role молча удалён

z.object(Base).strict().parse({ name: "a", role: "admin" });
// ZodError: unrecognized key "role"

z.object(Base).passthrough().parse({ name: "a", role: "admin" });
// { name: "a", role: "admin" } — опасно для входных данных

在 Zod 4 中,相同的模式可用作单独的构造函数 z.strictObject({...}) 和 z.looseObject({...});为了兼容性,保留了 .strict() 和 .passthrough() 方法。每个项目选择一种样式。

那为什么还要strict?它将无声删除变成明显错误。拼写错误字段名称(emial 而不是 email)的客户会收到 400 和密钥,而不是没有电子邮件的“成功”保存。对于内部 API 和表单,这可以节省数小时的调试时间。

处理程序模板

// app/api/profile/route.ts
import { z } from "zod";
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth";
import { db } from "@/lib/db";

const Address = z.strictObject({
  city: z.string().max(80),
  street: z.string().max(120),
});

const UpdateProfile = z.strictObject({
  name: z.string().trim().min(1).max(100).optional(),
  email: z.email().optional(),          // в Zod 3: z.string().email()
  address: Address.optional(),
});

export async function PATCH(req: Request) {
  const session = await getSession();
  if (!session) return NextResponse.json({ error: "unauthorized" }, { status: 401 });

  let json: unknown;
  try {
    json = await req.json();
  } catch {
    return NextResponse.json({ error: "invalid JSON" }, { status: 400 });
  }

  const parsed = UpdateProfile.safeParse(json);
  if (!parsed.success) {
    return NextResponse.json(
      { error: "validation", issues: parsed.error.issues.map(i => ({ path: i.path, message: i.message })) },
      { status: 400 }
    );
  }

  // только parsed.data, никогда json
  const user = await db.user.update({ where: { id: session.userId }, data: parsed.data });
  return NextResponse.json({ id: user.id, name: user.name, email: user.email });
}

经常被忽略的细节:

  • `strict` 不是递归的。 严格对象内的嵌套 z.object 仍处于剥离模式。因此,Address 被单独声明为严格的。
  • `req.json()` 对无效 JSON 抛出异常。如果没有 try/catch,客户端将收到 500 而不是 400。
  • `safeParse` 而不是 `parse` - 避免捕获正常用户错误的异常。
  • 响应也会被过滤。 返回一组显式字段,而不是带有密码哈希的整个用户对象。

查询参数及形式

来自 searchParams 和 FormData 的所有内容都是字符串。使用强制转换:

const ListQuery = z.strictObject({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  q: z.string().max(200).optional(),
});

const query = ListQuery.safeParse(Object.fromEntries(new URL(req.url).searchParams));

Object.fromEntries 丢失重复参数 (?tag=a&tag=b)。如果需要的话,通过searchParams.getAll("tag")单独收集数组。

如何诊断

  • 客户抱怨移动应用发布后出现400:新版本发送了额外的字段,但方案很严格。查看答案中的 issues - 密钥的路径将在那里。
  • 该字段“未保存”,没有错误:方案不严格,并且密钥的调用方式与您期望的不同。暂时启用 strict 并重试请求。
  • 在日志 __proto__ 中的键中 - 扫描仪查找原型污染。如果你使用parsed.data,它就是噪音;检查合并代码中是否有任何原始对象。

当严格阻碍时

外部服务(支付系统、即时通讯工具)的 Webhooks 定期添加新字段。对它们采取严格的方案会将无害的提供程序更新变成处理失败。对于此类输入,请使用条带模式并仅描述必要的字段。对于具有向后兼容性的公共 API 也是如此:对旧版本端点的严格方案可能会破坏从新版本发送字段的客户端。

Обсуждение (0)

Ещё на vbcd4u.com