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

سلاسل البرمجيات الوسيطة المخصّصة

ابنوا برمجيات وسيطة مخصّصة لتسجيل الأحداث أو تحديد معدل الطلبات أو التخويل، واربطوها معًا.

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

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

Chain Multiple Middleware

In tRPC, middleware lets you run logic before your procedure executes. What if you need multiple checks, like logging, authentication, and validation, for a single API call?

This is where middleware chains come in handy! They allow you to stack multiple middleware functions, executing them one after another.

Benefits of Chaining

Chaining middleware offers several advantages:

Modularity: Each middleware focuses on a single responsibility (e.g., logging, auth).
Reusability: Create generic middleware that can be applied to different procedures or routers.
Order of Execution: Control the exact sequence of operations before your main procedure logic runs.
Early Exit: A middleware can stop the chain early if a condition isn't met (e.g., unauthorized access).

How `next()` Works

Recall that tRPC middleware receives a next function. Calling next() passes control to the next middleware in the chain, or to the actual procedure handler if it's the last middleware.

If a middleware doesn't call next(), the chain stops, and the procedure handler will not execute. This is crucial for checks like authentication!

First: Logging Middleware

Let's create a simple logging middleware. It will log when a request starts and how long it took. This is a common pattern for monitoring.

Notice how next() is awaited to ensure the procedure (and subsequent middleware) completes before logging the duration.

type Context = { userId: string | null };
const trpc = {
  middleware: (handler: any) => handler,
  procedure: {
    use: (mw: any) => ({
      query: (f: any) => f,
      mutation: (f: any) => f
    }),
    query: (f: any) => f,
    mutation: (f: any) => f
  },
  router: (cfg: any) => cfg,
};

const logMiddleware = trpc.middleware(async ({ path, type, next }) => {
  console.log(`[${type}] Request to ${path} started.`);
  const start = Date.now();
  const result = await next();
  const durationMs = Date.now() - start;
  console.log(`[${type}] Request to ${path} finished in ${durationMs}ms.`);
  return result;
});

const appRouter = trpc.router({
  example: trpc.procedure
    .use(logMiddleware)
    .query(() => "Data fetched!")
});

Second: Auth Middleware

Next, we'll build an authentication middleware. This middleware will check if a user is logged in (i.e., if ctx.userId exists). If not, it will throw an error, effectively stopping the procedure.

Remember, the ctx (context) object is passed to middleware, allowing access to request-specific data.

type Context = { userId: string | null };
const trpc = {
  middleware: (handler: any) => handler,
  procedure: {
    use: (mw: any) => ({
      query: (f: any) => f,
      mutation: (f: any) => f
    }),
    query: (f: any) => f,
    mutation: (f: any) => f
  },
  router: (cfg: any) => cfg,
};

const isAuthenticated = trpc.middleware(async ({ ctx, next }) => {
  if (!ctx.userId) {
    throw new Error("UNAUTHORIZED: Please log in.");
  }
  return next();
});

const appRouter = trpc.router({
  protected: trpc.procedure
    .use(isAuthenticated)
    .query(({ ctx }) => `Welcome, user ${ctx.userId}!`)
});

Building a Middleware Chain

Now, let's combine our logMiddleware and isAuthenticated middleware. The order matters: logging should happen first, then authentication.

We simply use .use() multiple times. tRPC will execute them in the order they are defined.

type Context = { userId: string | null };
const trpc = {
  middleware: (handler: any) => handler,
  procedure: {
    use: (mw: any) => ({
      query: (f: any) => f,
      mutation: (f: any) => f
    }),
    query: (f: any) => f,
    mutation: (f: any) => f
  },
  router: (cfg: any) => cfg,
};

const logMiddleware = trpc.middleware(async ({ path, type, next }) => {
  console.log(`[${type}] Request to ${path} started.`);
  const start = Date.now();
  const result = await next();
  const durationMs = Date.now() - start;
  console.log(`[${type}] Request to ${path} finished in ${durationMs}ms.`);
  return result;
});

const isAuthenticated = trpc.middleware(async ({ ctx, next }) => {
  if (!ctx.userId) {
    throw new Error("UNAUTHORIZED: Please log in.");
  }
  return next();
});

const appRouter = trpc.router({
  protectedData: trpc.procedure
    .use(logMiddleware)
    .use(isAuthenticated)
    .query(({ ctx }) => `Secret data for ${ctx.userId}!`)
});

Order of Execution

When a request hits protectedData:

logMiddleware runs first.
If logMiddleware calls next(), then isAuthenticated runs.
If isAuthenticated calls next(), then the actual query procedure handler runs.
If any middleware throws an error (like isAuthenticated), the chain stops immediately, and the error is returned.

Dynamic Middleware

What if you need different authorization levels? You can create a function that returns a middleware, allowing for dynamic configuration.

This pattern is called a middleware builder and is powerful for creating flexible and reusable middleware.

type Context = { userId: string | null; userRole: string | null };
const trpc = {
  middleware: (handler: any) => handler,
  procedure: {
    use: (mw: any) => ({
      query: (f: any) => f,
      mutation: (f: any) => f
    }),
    query: (f: any) => f,
    mutation: (f: any) => f
  },
  router: (cfg: any) => cfg,
};

const hasRole = (requiredRole: string) => {
  return trpc.middleware(async ({ ctx, next }) => {
    if (!ctx.userRole || ctx.userRole !== requiredRole) {
      throw new Error(`FORBIDDEN: ${requiredRole} role required.`);
    }
    return next();
  });
};

const appRouter = trpc.router({
  adminPanel: trpc.procedure
    .use(hasRole("admin"))
    .query(() => "Welcome, admin!")
});

Chaining Dynamic Middleware

You can mix and match static middleware (like our logger) with dynamic middleware builders (like our role checker) in the same chain.

This allows for highly flexible and secure API endpoints, where specific logic can be applied based on configuration or runtime values.

type Context = { userId: string | null; userRole: string | null };
const trpc = {
  middleware: (handler: any) => handler,
  procedure: {
    use: (mw: any) => ({
      query: (f: any) => f,
      mutation: (f: any) => f
    }),
    query: (f: any) => f,
    mutation: (f: any) => f
  },
  router: (cfg: any) => cfg,
};

const logMiddleware = trpc.middleware(async ({ path, type, next }) => {
  console.log(`[${type}] Request to ${path} started.`);
  const start = Date.now();
  const result = await next();
  const durationMs = Date.now() - start;
  console.log(`[${type}] Request to ${path} finished in ${durationMs}ms.`);
  return result;
});

const hasRole = (requiredRole: string) => {
  return trpc.middleware(async ({ ctx, next }) => {
    if (!ctx.userRole || ctx.userRole !== requiredRole) {
      throw new Error(`FORBIDDEN: ${requiredRole} role required.`);
    }
    return next();
  });
};

const appRouter = trpc.router({
  adminReport: trpc.procedure
    .use(logMiddleware)
    .use(hasRole("admin"))
    .query(() => "Sensitive admin report data.")
});

Middleware Chain Logic

Consider the following tRPC procedure definition:

// Assume logMiddleware and authMiddleware are defined
// authMiddleware throws if ctx.userId is null
// logMiddleware always calls next()
const myProcedure = trpc.procedure
  .use(logMiddleware)
  .use(authMiddleware)
  .query(({ ctx }) => `Hello ${ctx.userId}`);

If a request comes in with ctx.userId = null, what will happen?

Chains Recap

Great job! You've learned how to build and chain multiple custom middleware in tRPC.

Middleware chains allow you to apply multiple layers of logic (logging, authentication, validation) before a procedure executes.
The .use() method is used to add middleware, and they run in the order they are defined.
The next() function is key to passing control down the chain.
Middleware builders can create dynamic, configurable middleware for enhanced reusability.

This powerful pattern helps keep your tRPC API code clean, modular, and robust!

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

هل درس «سلاسل البرمجيات الوسيطة المخصّصة» مجاني؟

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

ماذا ستتعلم في «سلاسل البرمجيات الوسيطة المخصّصة»؟

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

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

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