#البرمجيات الوسيطة (Middleware)

البرمجيات الوسيطة (Middleware) في خادم NocoBase هي في جوهرها برمجيات Koa الوسيطة. يمكنك التعامل مع كائن ctx لمعالجة الطلبات والاستجابات تمامًا كما تفعل في Koa. ولكن نظرًا لأن NocoBase يحتاج إلى إدارة منطق طبقات الأعمال المختلفة، فإن وضع جميع البرمجيات الوسيطة معًا سيجعل صيانتها وإدارتها أمرًا صعبًا للغاية.

لهذا السبب، يقسم NocoBase البرمجيات الوسيطة إلى أربعة مستويات:

1. برمجيات وسيطة على مستوى مصدر البيانات: app.dataSourceManager.use() تؤثر فقط على طلبات مصدر بيانات معين، وتُستخدم عادةً لمنطق اتصالات قاعدة البيانات، أو التحقق من صحة الحقول، أو معالجة المعاملات لهذا المصدر.

2. برمجيات وسيطة على مستوى الموارد: app.resourceManager.use() تكون فعالة فقط للموارد المعرفة، وهي مناسبة لمعالجة المنطق على مستوى الموارد، مثل صلاحيات البيانات أو التنسيق.

3. برمجيات وسيطة على مستوى الصلاحيات: app.acl.use() تُنفذ قبل التحقق من الصلاحيات، وتُستخدم للتحقق من صلاحيات المستخدم أو أدواره.

4. برمجيات وسيطة على مستوى التطبيق: app.use() تُنفذ مع كل طلب، وهي مناسبة لتسجيل السجلات، ومعالجة الأخطاء العامة، ومعالجة الاستجابات، وما إلى ذلك.

#تسجيل البرمجيات الوسيطة

تُسجل البرمجيات الوسيطة عادةً في دالة load الخاصة بـ الإضافة، على سبيل المثال:

export class MyPlugin extends Plugin {
  load() {
    // برمجيات وسيطة على مستوى التطبيق
    this.app.use(async (ctx, next) => {
      console.log('App middleware');
      await next();
    });

    // برمجيات وسيطة لمصدر البيانات
    this.app.dataSourceManager.use(async (ctx, next) => {
      console.log('DataSource middleware');
      await next();
    });

    // برمجيات وسيطة للصلاحيات
    this.app.acl.use(async (ctx, next) => {
      console.log('ACL middleware');
      await next();
    });

    // برمجيات وسيطة للموارد
    this.app.resourceManager.use(async (ctx, next) => {
      console.log('Resource middleware');
      await next();
    });

  }
}

#ترتيب التنفيذ

ترتيب تنفيذ البرمجيات الوسيطة هو كما يلي:

1. تُنفذ أولاً البرمجيات الوسيطة الخاصة بالصلاحيات المضافة بواسطة acl.use()
2. ثم تُنفذ البرمجيات الوسيطة الخاصة بالموارد المضافة بواسطة resourceManager.use()
3. ثم تُنفذ البرمجيات الوسيطة الخاصة بمصدر البيانات المضافة بواسطة dataSourceManager.use()
4. أخيرًا تُنفذ البرمجيات الوسيطة الخاصة بالتطبيق المضافة بواسطة app.use()

#آلية الإدراج before / after / tag

للتحكم بمرونة أكبر في ترتيب البرمجيات الوسيطة، يوفر NocoBase المعاملات before و after و tag:

• tag: لوضع علامة على البرمجيات الوسيطة لاستخدامها كمرجع بواسطة البرمجيات الوسيطة اللاحقة.
• before: للإدراج قبل البرمجيات الوسيطة ذات العلامة المحددة.
• after: للإدراج بعد البرمجيات الوسيطة ذات العلامة المحددة.

مثال:

// برمجيات وسيطة عادية
app.use(m1, { tag: 'restApi' });
app.resourcer.use(m2, { tag: 'parseToken' });
app.resourcer.use(m3, { tag: 'checkRole' });

// سيتم وضع m4 قبل m1
app.use(m4, { before: 'restApi' });

// سيتم إدراج m5 بين m2 و m3
app.resourcer.use(m5, { after: 'parseToken', before: 'checkRole' });

#مثال على نموذج "حلقة البصل" (Onion Model)

يتبع ترتيب تنفيذ البرمجيات الوسيطة نموذج "حلقة البصل" (Onion Model) الخاص بـ Koa، حيث تدخل البرمجيات الوسيطة إلى المكدس أولاً وتخرج منه أخيرًا.

app.use(async (ctx, next) => {
  ctx.body = ctx.body || [];
  ctx.body.push(1);
  await next();
  ctx.body.push(2);
});

app.resourcer.use(async (ctx, next) => {
  ctx.body = ctx.body || [];
  ctx.body.push(3);
  await next();
  ctx.body.push(4);
});

app.acl.use(async (ctx, next) => {
  ctx.body = ctx.body || [];
  ctx.body.push(5);
  await next();
  ctx.body.push(6);
});

app.resourcer.define({
  name: 'test',
  actions: {
    async list(ctx, next) {
      ctx.body = ctx.body || [];
      ctx.body.push(7);
      await next();
      ctx.body.push(8);
    },
  },
});

أمثلة على ترتيب الإخراج عند الوصول إلى واجهات برمجة تطبيقات مختلفة:

• طلب عادي: /api/hello الإخراج: [1,2] (المورد غير معرف، لذا لا تُنفذ برمجيات resourceManager و acl الوسيطة)

• طلب مورد: /api/test:list الإخراج: [5,3,7,1,2,8,4,6] تُنفذ البرمجيات الوسيطة وفقًا لترتيب الطبقات ونموذج "حلقة البصل".

#ملخص

• البرمجيات الوسيطة في NocoBase هي امتداد لبرمجيات Koa الوسيطة.
• أربعة مستويات: التطبيق -> مصدر البيانات -> المورد -> الصلاحيات.
• يمكن استخدام before / after / tag للتحكم بمرونة في ترتيب التنفيذ.
• تتبع نموذج "حلقة البصل" الخاص بـ Koa، مما يضمن أن البرمجيات الوسيطة قابلة للتركيب والتداخل.
• البرمجيات الوسيطة على مستوى مصدر البيانات تؤثر فقط على طلبات مصدر البيانات المحدد، والبرمجيات الوسيطة على مستوى الموارد تؤثر فقط على طلبات الموارد المعرفة.