أفضل الممارسات

​

نظرة عامة

• وزّع مهام كرون الشاملة باستخدام تأخير عشوائي. يبدأ مشغّل كرون في كل مساحة عمل في الدقيقة نفسها، لذا يستنزف كل تثبيت الميزانية المشتركة دفعة واحدة. اجعل معالج كرون مقتصرًا على إدراج مهمة في قائمة الانتظار، مع delayMs عشوائي عبر نافذة كبيرة مثل ساعة واحدة. يُحدَّد أيضًا إدراج المهام في قائمة الانتظار بحد أقصى قدره 2,000 في الدقيقة لكل تسجيل تطبيق، ويتم تخطي نبضة كرون التي تتجاوز هذا الحد في مساحات العمل المتبقية، لذا اجعل عملية المسح متكررة آمنة ودع النبضة التالية تلحق بها.

import { defineLogicFunction } from 'twenty-sdk/define';
import { enqueueJobs } from 'twenty-sdk/logic-function';

const NIGHTLY_SWEEP = '3f9d1c02-8a44-4f0e-b1d7-9c2e5a7b4f10';
const SPREAD_WINDOW_MS = 60 * 60 * 1000;

export default defineLogicFunction({
  universalIdentifier: 'b7c2e4d1-0f5a-4c3e-9d8b-6a1f2e3c4d5b',
  name: 'enqueue-nightly-sweep',
  timeoutSeconds: 30,
  cronTriggerSettings: { pattern: '0 3 * * *' },
  handler: async () => {
    await enqueueJobs({
      logicFunctionUniversalIdentifier: NIGHTLY_SWEEP,
      jobs: [{ payload: {} }],
      delayMs: Math.floor(Math.random() * SPREAD_WINDOW_MS),
    });
  },
});

   pattern "0 3 * * *"                  the server, every minute
                                                  │
              ┌───────────────┬───────────────────┼───────────────┐
              ▼               ▼                   ▼               ▼
        workspace A     workspace B     workspace C   ...   workspace N
          03:00:00        03:00:00        03:00:00            03:00:00
              │               │                   │               │
              └───────────────┴─────────┬─────────┴───────────────┘
                                        ▼
                      500 requests per minute for the whole app
                                   N × calls  →  429

   pattern "0 3 * * *"  +  random delayMs in [0, 60 min)
                                                  │
              ┌───────────────┬───────────────────┼───────────────┐
              ▼               ▼                   ▼               ▼
        workspace A     workspace B     workspace C   ...   workspace N
          03:00:00        03:00:00        03:00:00            03:00:00
           + 12 min        + 41 min        + 03 min            + 27 min
              │               │                   │               │
              ▼               ▼                   ▼               ▼
          03:12:00        03:41:00        03:03:00            03:27:00
              │               │                   │               │
              └───────────────┴─────────┬─────────┴───────────────┘
                                        ▼
                      500 requests per minute for the whole app
                          N × calls spread over 60 minutes  →  OK

• جمّع مشغلات أحداث قاعدة البيانات على دفعات. تؤدي عملية كتابة مجمعة مثل مزامنة صندوق البريد إلى إصدار حدث واحد لكل سجل، أي آلاف الأحداث خلال ثوانٍ، وتعني عملية تشغيل واحدة لكل حدث طلبًا واحدًا لكل سجل. عيّن batchMode: true، وعرّف updatedFields، وقلّص الدفعة إلى سجلات مميزة قبل استدعاء واجهة API. راجع تجميع أحداث قاعدة البيانات على دفعات.
• قدّم طلبًا واحدًا لكل دفعة، وليس لكل سجل. يحتسب الحد الطلبات لا السجلات: إن createMany مع upsert: true يحمل 200 سجل هو طلب واحد، بينما 200 تحديث منفرد هي 200 طلب. اقرأ باستخدام عوامل التصفية in واكتب باستخدام createMany أو updateMany.
• اجمع التدفقات المفاجئة في مهمة واحدة مؤجلة. عندما تكشف الأحداث عن عمل أكبر من الحدث نفسه، فإن إدراجه في قائمة الانتظار مرة لكل حدث يضاعفه بحجم التدفق المفاجئ. أدرج مهمة واحدة في قائمة الانتظار باستخدام delayMs وjobId حتمي يتضمن نافذة زمنية؛ تتجاهل قائمة الانتظار معرّفًا تحتفظ به بالفعل. راجع اختيار معرّف المهمة الخاص بك.
• نظّم التوزيع المتشعب باستخدام delayMs. تصبح المهام المُدرجة في قائمة الانتظار دون تأخير مؤهلة كلها دفعة واحدة وتستنفد الميزانية في الدقيقة نفسها. جمّعها في خانات لكل دقيقة وأخّر الصفحة التالية بعدد الخانات المستخدمة. راجع المهام في الخلفية.
• أعِد محاولة 429 مع تراجع تدريجي، أو أعد إدراجها في قائمة الانتظار مع تأخير. تُطلق حزمة SDK للعميل استثناءً عند أي استجابة ليست 2xx، كما أن عملية التشغيل التي تنتظر في الداخل تستهلك مهلة الانتظار الخاصة بها. أعِد المحاولة بتراجع تدريجي أُسّي مع حد أقصى للمحاولات، أو أعد العمل إلى قائمة الانتظار مع تأخير.
• خزّن مؤقتًا ما لا يتغير. يتطلب البحث في كل حدث طلبًا لقيمة ثابتة عند وقت الاتصال، مثل هوية أو معرّف فريق. خزّنه في مخزن المفتاح والقيمة عند تسجيل الاتصال.
• جمّع الطلبات إلى واجهات API الخارجية على دفعات. للخدمة الخارجية حد معدل خاص بها، وللوظيفة المنطقية مهلة انتظار، لذا فإن n طلبات لكل عملية تشغيل تضاعف كليهما. عندما يوفّر المزوّد نقطة نهاية للدفعات، أرسل طلبًا واحدًا للدفعة بأكملها بدلًا من طلب واحد لكل سجل، وقسّم الدفعة إلى أجزاء وفق الحد الأقصى للمزوّد.
• اجعل المعلمات الافتراضية قابلة للتحرير من قبل المستخدم. تناسب القيمة المُضمّنة في التعليمات البرمجية ضمن وظيفة منطقية أو سير عمل، مثل عتبة أو حجم دفعة أو خيار افتراضي، مساحة عمل واحدة وتفرض إصدارًا جديدًا لكل مساحة عمل أخرى. عرّفها كمتغير تطبيق ذي قيمة افتراضية واقرأها وقت التشغيل، كي يتمكن مسؤولو مساحة العمل من ضبطها من إعدادات التطبيق. راجع تهيئة التطبيق.