api-skill: ساخت REST API لاراول با استانداردهای حرفهای
لاراول
هوش مصنوعی
پیاچپیخلاصهٔ کاملتر
استیو مکدوگال که توی جامعه لاراول بهخاطر تخصصش در طراحی API شناختهشدهست، یه پکیج جدید به اسم api-skill منتشر کرده. این پکیج در واقع یه skill برای Claude Code هست که تمام استانداردها و قراردادهای تیمی موردنظر استیو رو برای ساخت REST API در لاراول ۱۳+ تعریف میکنه.
ایده اصلی پشت skills اینه که وقتی نصب میشن، Claude Code بهصورت خودکار ازشون استفاده میکنه. یعنی دیگه لازم نیست هر بار اول session توضیح بدی که «من دوست دارم کنترلرها اینجوری باشن» یا «از این پترن استفاده کن» — skill همه اینا رو از قبل میدونه و سر هر پروژهای همون خط رو دنبال میکنه.
این skill خیلی opinionated و قاطعه. مثلاً ID اتوایکریمنت کلاً حذف شده و بهجاش HasUlids روی همه مدلها اجباریه. متد paginate() ممنوعه و باید از simplePaginate() استفاده بشه. همه پاسخهای خطا باید از استاندارد RFC 9457 Problem Details پیروی کنن.
در مورد کنترلرها هم سیاست مشخصه: فقط کنترلرهای final single-action invokable مجازن. هیچ resource controller یا کلاس چندمتدی قبول نمیشه. این رویکرد کد رو تمیزتر و قابلنگهداریتر میکنه.
برای مدیریت نسخههای قدیمی API هم یه راهحل هوشمندانه داره: بهجای اینکه یه endpoint یهدفعه حذف بشه، از RFC 8594 Sunset middleware استفاده میکنه که تاریخ حذف رو توی هدر جواب اعلام میکنه. اینجوری کلاینتها خبردار میشن و وقت دارن آماده بشن.
Routeها هم ساختار خاص خودشون رو دارن: بهازای هر resource یه فایل جداگانه زیر routes/api/ ساخته میشه، هیچ پیشوند گلوبال api نداریم، و throttle:api روی همه گروهها فعاله. احراز هویت با Sanctum و توکنهای stateless انجام میشه و مجوزدهی هم از طریق Laravel Policies داخل متد authorize() فرمریکوئست مدیریت میشه، نه داخل Action.
یه نکته جالب دیگه اینه که job های پسزمینه باید فوراً جواب ۲۰۲ Accepted برگردونن و پردازش سنگین synchronous فقط برای جریانهای احراز هویت مجازه. همچنین Model::shouldBeStrict() بهصورت گلوبال فعاله که از lazy loading، attribute های گمشده و مقادیر بیسروصدا دور ریختهشده جلوگیری میکنه. declare(strict_types=1) روی همه فایلها و final روی همه کلاسها هم از الزامات اینه.
نصبش هم سادهست: با یه git clone میشه هم سطح global نصبش کرد هم سطح پروژه. کنار فایل اصلی SKILL.md یه فایل references/CONVENTIONS.md هم هست که ساختار دایرکتوری، جداول نامگذاری و مثالهای کامل داره — هم برای یادگیری منطق پشتشون، هم بهعنوان پایهای برای ساخت skill شخصی خودت.
نکات کلیدی:
- api-skill یه Claude Code skill هست که قراردادهای API لاراول ۱۳+ رو خودکار اعمال میکنه
- ULID بهجای ID اتوایکریمنت، simplePaginate بهجای paginate
- پاسخهای خطا باید از استاندارد RFC 9457 پیروی کنن
- کنترلرها فقط به شکل final single-action invokable مجازن
- Sunset middleware برای اطلاعرسانی حذف نسخههای قدیمی API
- Model::shouldBeStrict() و strict_types=1 برای کد ایمنتر
- نصب با یه git clone در سطح گلوبال یا پروژه
