www.dntips.ir
مطالب
نویسندگان
گروه‌های مطالب
نقشه‌های راه
دوره‌ها
اشتراک‌ها
پرسش‌ها
عنوان:

‫تفکیک دستورالعمل‌های مبتنی بر مسیر (Path-Specific Instructions) در پروژه‌های بزرگ NET.


نویسنده: وحید نصیری
تاریخ: ۱۴۰۵/۰۵/۲۹ ۱۲:۴۱
آدرس: www.dntips.ir
در یک راه‌حل (Solution) جامع دات‌نت، الزامات مهندسی لایه‌های مختلف یکسان نیستند؛ قوانینی که برای یک Controller در لایه Web API اعمال می‌شوند، با قواعد یک Migration در EF Core یا یک کلاس تست در لایه Unit Test تفاوت‌های بنیادین دارند. اگر تمام این قوانین در یک فایل سراسری تجمیع شوند، نه تنها حجم کانتکست ورودی بی‌دلیل افزایش می‌یابد، بلکه ممکن است هوش مصنوعی دچار تعارض قوانین شود.
قابلیت دستورالعمل‌های مبتنی بر مسیر (.instructions.md) به شما امکان می‌دهد با استفاده از فیلد applyTo و الگوهای Globbing، رفتارهای Copilot را دقیقاً متناسب با پوشه یا فایل در حال ویرایش تنظیم کنید.

ساختار پوشه‌بندی و معماری راهنماها

ساختار پیشنهادی استاندارد در مسیر .github/ برای یک پروژه چندلایه‌ای دات‌نت:
.github/
├── copilot-instructions.md          # قوانین عمومی و زبان C#
└── instructions/
    ├── api.instructions.md         # لایه ارائه و Web API
    ├── data.instructions.md        # لایه دسترسی به داده و EF Core
    └── tests.instructions.md       # لایه آزمون‌ها و Mocking

نمونه پیاده‌سازی فایل‌های راهنمای لایه‌ای

۱. راهنمای لایه کنترلرها و API (api.instructions.md)
---
applyTo: "**/Controllers/**/*.cs"
---
# استانداردهای کنترلرهای Web API
- کنترلرها باید باریک (Thin) باشند؛ هیچ‌گونه منطق بیزینس یا کوئری مستقیم دیتابیس نباید در کنترلر قرار گیرد.
- همیشه از DTOها و رکوردهای صریح برای ورودی و خروجی استفاده کن.
- پاسخ‌های HTTP باید کدهای وضعیت متناسب (200, 201, 400, 404, 422) داشته باشند.
- ویژگی‌های امنیت و دسترسی (Authorization Attributes/Policies) را حفظ کن.
- تمامی اکشن‌ها باید پارامتر `CancellationToken` را بپذیرند.

۲. راهنمای لایه دسترسی به داده و ریپازیتوری‌ها (data.instructions.md)
---
applyTo: "**/Infrastructure/Data/**/*.cs"
---
# استانداردهای لایه دسترسی به داده و EF Core
- کوئری‌های خواندنی را ملزم به استفاده از `.AsNoTracking()` کن.
- از بارگذاری‌های تکراری و مشکلات N+1 با به‌کارگیری دقیق `.Include()` و `.ThenInclude()` یا Projection مستقیم پرهیز کن.
- هرگز موجودیت‌ها (Entities) را مستقیماً از طریق متدهای دسترسی بدون تبدیل (Map) در لایه‌های دیگر افشا نکن.
- تغییرات ساختار دیتابیس در Migrationها باید بدون حذف ناخواسته ستون‌ها (Lossless) تولید شوند.

۳. راهنمای لایه آزمون‌ها (tests.instructions.md)
---
applyTo: "**/*Tests.cs"
---
# استانداردهای تست‌نویسی
- فریم‌ورک تست: xUnit و اعتبارسنجی با FluentAssertions.
- ساختار تمام تست‌ها باید مبتنی بر الگوی Arrange-Act-Assert (AAA) باشد.
- تمرکز تست‌ها باید روی «رفتار و خروجی نهایی» باشد، نه جزئیات پیاده‌سازی داخلی متدها.
- حالت‌های مرزی (مقادیر صفر، اعداد منفی، رشته‌های خالی و استثناها) باید پوشش داده شوند.

مزایای فنی تفکیک دستورالعمل‌ها

  • بهینه‌سازی مصرف Token و Context Window: تنها قوانینی به هوش مصنوعی تزریق می‌شوند که با فایل جاری مرتبط هستند.
  • کاهش خطاهای تداخل الگوها: هوش مصنوعی در فایل تست، قواعد مربوط به پاسخ‌های HTTP یا تراکنش‌های دیتابیس را اشتباهاً اعمال نخواهد کرد.
  • تسهیل همکاری تیمی در Solutionهای بزرگ: تیم‌های مسئول لایه داده، معماری یا فرانت‌اند/API می‌توانند بدون اثرگذاری منفی بر بخش‌های دیگر، فایل‌های راهنمای لایه خود را توسعه دهند.

قاعده کلیدی: یک Solution دات‌نت از اجزای متفاوتی تشکیل شده است؛ با تفکیک دستورالعمل‌ها بر اساس مسیر، استانداردهای متناسب با هر لایه را به شکلی هدفمند و بدون هم‌پوشانی تضمین کنید.
مطالب مشابه