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

Zod على API Routes 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 بالمفتاح، بدلاً من الحفظ "الناجح" بدون بريد إلكتروني. بالنسبة لواجهات برمجة التطبيقات والنماذج الداخلية، يؤدي ذلك إلى توفير ساعات من تصحيح الأخطاء.

قالب المعالج

// 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 للخدمات الخارجية (أنظمة الدفع والمراسلة الفورية) حقولًا جديدة بانتظام. سيؤدي اتباع نظام صارم عليهم إلى تحويل تحديث الموفر غير الضار إلى فشل في المعالجة. بالنسبة لمثل هذه المدخلات، استخدم وضع الشريط ووصف الحقول الضرورية فقط. الأمر نفسه بالنسبة لواجهات برمجة التطبيقات العامة ذات التوافق مع الإصدارات السابقة: يمكن لنظام صارم على الإصدارات القديمة من نقاط النهاية أن يعطل العملاء الذين يرسلون الحقول من الإصدارات الجديدة.

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

Ещё на vbcd4u.com