tRPC End-to-End Type Safe APIs · درس

تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل

خصّص طريقة تشكيل أخطاء tRPC، واعرض للعميل رسائل تحقق واضحة على مستوى الحقل.

تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل درس مجاني في tRPC End-to-End Type Safe APIs على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في tRPC End-to-End Type Safe APIs، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة tRPC End-to-End Type Safe APIs 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Why Format Errors?

You can throw and catch tRPC errors. But clients often need structured error data, especially field-level messages from validation, to show next to form inputs.

The errorFormatter Option

tRPC lets you customize the error shape globally with errorFormatter when initializing.

const t = initTRPC.create({
  errorFormatter({ shape }) {
    return shape;
  },
});

Detecting Zod Errors

When a Zod input fails, tRPC attaches it as the error cause. You can detect and expose it.

import { ZodError } from "zod";

errorFormatter({ shape, error }) {
  const isZod = error.cause instanceof ZodError;
  return { ...shape, data: { ...shape.data, isZod } };
}

Adding Flattened Field Errors

Zod can flatten issues into a fieldErrors map that maps each field to its messages.

const zodError = error.cause instanceof ZodError
  ? error.cause.flatten().fieldErrors
  : null;
return { ...shape, data: { ...shape.data, zodError } };

What the Client Receives

The client now gets a structured object it can attach to form fields.

// e.g. { zodError: { email: ["Invalid email"] } }

Reading Errors on the Client

Catch the error and read the formatted data.

try {
  await client.signup.mutate(input);
} catch (err) {
  const fields = err.data?.zodError;
  // show fields.email next to the input
}

HTTP Status Codes

The shape includes a code that maps to an HTTP status, useful for clients reacting to UNAUTHORIZED vs BAD_REQUEST.

// shape.data.code === "BAD_REQUEST"
// shape.data.httpStatus === 400

Not Leaking Internals

Be careful: do not expose stack traces or internal messages in production. Format errors to reveal only safe, user-facing details.

Logging the Raw Error

Log the full error server-side for debugging while sending a sanitized version to the client.

errorFormatter({ shape, error }) {
  console.error(error); // full detail in server logs
  return shape;        // safe shape to client
}

Consistent Error Contract

A consistent error shape across all procedures means your frontend can handle errors with one reusable helper.

Reusing a Client Helper

Because every procedure shares the same error shape, write one helper that extracts fieldErrors and a top-level message for any failed call.

function parseError(err) {
  return { fields: err.data?.zodError, message: err.message };
}

Quick Check

Test your error formatting knowledge.

Recap

You learned to deliver great error feedback:

errorFormatter customizes the error shape globally
Detect ZodError causes and expose fieldErrors
Log full detail server-side, send a sanitized shape to clients

Well-shaped errors make forms and clients dramatically easier to build.

الأسئلة الشائعة

هل درس «تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل» مجاني؟

نعم — نص درس «تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة tRPC End-to-End Type Safe APIs، انتقل إلى CoddyKit PRO. تتضمن دورة tRPC End-to-End Type Safe APIs 4 دروس في المجموع.

ماذا ستتعلم في «تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل»؟

خصّص طريقة تشكيل أخطاء tRPC، واعرض للعميل رسائل تحقق واضحة على مستوى الحقل. تتمرن على tRPC End-to-End Type Safe APIs مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ tRPC End-to-End Type Safe APIs؟

لا تُشترط خبرة سابقة. tRPC End-to-End Type Safe APIs على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس tRPC End-to-End Type Safe APIs هذا؟

نعم. كل درس في tRPC End-to-End Type Safe APIs يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

معالجة أخطاء tRPC بسلاسة
أنواع الأخطاء المخصّصة
محولات البيانات للتسلسل
تنسيق الأخطاء وملاحظات التحقق على مستوى الحقل

← العودة إلى tRPC End-to-End Type Safe APIs