انتقل إلى المحتوى الرئيسي

أفضل الممارسات لقواعد MDC واستكشاف الأخطاء

تلميح

تساعدك قواعد MDC (النموذج الموجه للكود) على الحفاظ على جودة الكود المتسقة وأتمتة المهام المتكررة في Cursor.

فهم قواعد MDC​

قواعد MDC هي أدوات قوية تتيح لك:

  • فرض معايير الترميز
  • أتمتة تحويلات الكود
  • تنفيذ التحققات المخصصة
  • إنشاء إرشادات خاصة بالمشروع

إعداد قواعد MDC​

الهيكل الأساسي​

قم بإنشاء دليل .cursor/rules في مشروعك:

.cursor/
└── rules/
    ├── naming.json
    ├── formatting.json
    └── custom-rules.json

تكوين القاعدة​

هيكل القاعدة الأساسي:

.cursor/rules/naming.json
{
  "name": "اتفاقيات التسمية",
  "description": "يفرض تسمية متسقة عبر المشروع",
  "rules": [
    {
      "pattern": "^[A-Z][a-zA-Z]*Component$",
      "filePattern": "*.component.ts",
      "message": "يجب أن تكون أسماء المكونات بتنسيق PascalCase وتنتهي بـ 'Component'"
    }
  ]
}

أنواع القواعد الشائعة​

1. اتفاقيات التسمية​

{
  "rules": [
    {
      "pattern": "^[a-z][a-zA-Z]*Service$",
      "filePattern": "*.service.ts",
      "message": "يجب أن تكون أسماء الخدمات بتنسيق camelCase وتنتهي بـ 'Service'"
    },
    {
      "pattern": "^I[A-Z][a-zA-Z]*$",
      "filePattern": "*.interface.ts",
      "message": "يجب أن تبدأ أسماء الواجهات بـ 'I' وتستخدم تنسيق PascalCase"
    }
  ]
}

2. بنية الكود​

{
  "rules": [
    {
      "pattern": "^import.*from",
      "location": "top",
      "message": "يجب أن تكون عمليات الاستيراد في أعلى الملف"
    },
    {
      "maxLines": 300,
      "filePattern": "*.ts",
      "message": "يجب ألا تتجاوز الملفات 300 سطر"
    }
  ]
}

3. متطلبات التوثيق​

{
  "rules": [
    {
      "pattern": "^\\/\\*\\*[\\s\\S]*?\\*\\/",
      "filePattern": "*.ts",
      "message": "يجب أن تحتوي جميع الملفات على توثيق JSDoc"
    }
  ]
}

تكوين القواعد المتقدمة​

استخدام المتغيرات​

{
  "variables": {
    "COMPONENT_PREFIX": "App",
    "MAX_FILE_SIZE": 500
  },
  "rules": [
    {
      "pattern": "^${COMPONENT_PREFIX}[A-Z][a-zA-Z]*$",
      "filePattern": "*.component.ts",
      "message": "يجب أن تبدأ المكونات بـ '${COMPONENT_PREFIX}'"
    }
  ]
}

القواعد المتداخلة​

{
  "rules": {
    "naming": {
      "components": [
        {
          "pattern": "^[A-Z][a-zA-Z]*Component$",
          "severity": "error"
        }
      ],
      "services": [
        {
          "pattern": "^[a-z][a-zA-Z]*Service$",
          "severity": "warning"
        }
      ]
    }
  }
}

استكشاف المشكلات الشائعة وحلها​

القاعدة لا تعمل​

  1. تحقق من صياغة القاعدة

    {
      "rules": [
        {
          "pattern": "^[A-Z][a-zA-Z]*$", // نمط regex صالح
          "filePattern": "*.ts",         // نمط glob صالح
          "severity": "error"            // مستوى شدة صالح
        }
      ]
    }

  2. التحقق من مسار الملف

    # تأكد من أن القواعد في المكان الصحيح
    .cursor/
    └── rules/
        └── your-rule.json

مشكلات الأداء​

  1. تحسين الأنماط

    {
      "rules": [
        {
          "pattern": "^[A-Z]\\w*$", // أكثر كفاءة من ^[A-Z][a-zA-Z]*$
          "filePattern": "*.{ts,js}" // تجميع الامتدادات
        }
      ]
    }

  2. استخدام الاستثناءات

    {
      "exclude": [
        "node_modules/**",
        "dist/**",
        "build/**"
      ],
      "rules": [...]
    }

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

1. التنظيم​

.cursor/
└── rules/
    ├── naming/
    │   ├── components.json
    │   └── services.json
    ├── formatting/
    │   ├── spacing.json
    │   └── indentation.json
    └── documentation/
        └── jsdoc.json

2. توثيق القواعد​

{
  "name": "تسمية المكون",
  "description": "يفرض اتفاقيات تسمية المكونات المتسقة",
  "version": "1.0.0",
  "author": "فريقك",
  "rules": [...]
}

3. اختبار القواعد​

إنشاء ملفات الاختبار:

test/rules/naming.test.ts
describe('قواعد التسمية', () => {
  it('يجب التحقق من صحة أسماء المكونات', () => {
    // تنفيذ الاختبار
  });
});

التكامل مع CI/CD​

مثال على GitHub Actions​

name: التحقق من قواعد MDC
on: [push, pull_request]
jobs:
  check-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: تثبيت التبعيات
        run: npm install
      - name: التحقق من قواعد MDC
        run: npx cursor-rules check

التكامل مع GitLab CI​

stages:
  - test

mdc-rules:
  stage: test
  script:
    - npm install
    - npx cursor-rules check

استراتيجيات التصحيح التلقائي​

إعداد التصحيح التلقائي​

{
  "rules": [
    {
      "pattern": "console\\.log",
      "filePattern": "*.ts",
      "message": "لا تترك عبارات console.log في الكود",
      "autofix": {
        "find": "console\\.log\\(([^)]*)\\)",
        "replace": "// console.log($1)"
      }
    }
  ]
}

عمليات التحويل المعقدة​

.cursor/rules/transformers/format-imports.ts
export function formatImports(code) {
  // منطق مخصص لإعادة تنظيم الواردات
  return transformedCode;
}

حالات الاستخدام المتقدمة​

1. فرض تغطية الاختبار​

{
  "rules": [
    {
      "pattern": "it\\('.*'",
      "minCount": 1,
      "filePattern": "*.spec.ts",
      "message": "يجب أن تحتوي ملفات الاختبار على اختبار واحد على الأقل"
    }
  ]
}

2. التحقق من سلامة البيانات​

{
  "rules": [
    {
      "pattern": "sanitize\\(.*\\)",
      "filePattern": "*Service.ts",
      "near": "userInput",
      "message": "يجب تنظيف مدخلات المستخدم قبل المعالجة"
    }
  ]
}

3. فرض استخدام المكتبة​

{
  "rules": [
    {
      "pattern": "import.*@company/logger",
      "filePattern": "*.ts",
      "excludePattern": "test/**",
      "message": "استخدم مكتبة التسجيل الرسمية للشركة"
    }
  ]
}

إدارة قواعد الفريق​

1. مشاركة القواعد​

package.json
{
  "dependencies": {
    "company-mdc-rules": "^1.0.0"
  },
  "scripts": {
    "rules:update": "cursor-rules update"
  }
}

2. تمديد القواعد الأساسية​

.cursor/rules/config.json
{
  "extends": [
    "company-mdc-rules/base",
    "company-mdc-rules/typescript"
  ],
  "rules": {
    // قواعد خاصة بالمشروع
  }
}

الخلاصة​

تعد قواعد MDC في Cursor أداة قوية لتحسين جودة الكود وفرض معايير المشروع. من خلال اتباع أفضل الممارسات الموضحة في هذا الدليل، يمكنك تحقيق أقصى استفادة من هذه الميزة وتجنب المشكلات الشائعة.

للمزيد من المعلومات: