مرجع المسارات

إعدادات مطابقة المسارات والتوزيع لـ⁦ServerBlock.routes⁩.

تُقيَّم المسارات بترتيب التصريح؛ أول مسار تتحقق جميع شروط ⁦match⁩ الخاصة به يوزع الطلب إلى ⁦handler⁩ الخاص به. الطلبات التي لا تطابق أي مسار تمر إلى ⁦ServerBlock.handler⁩ على مستوى الكتلة.

الوسيط على مستوى المسار ⁦middleware⁩ يلتف حول المعالج لذلك المسار فقط ويعمل بعد وسيط مستوى الكتلة. راجع ⁦Handler⁩ لأنواع المعالجات المتاحة و⁦Middleware⁩ للوسيط المتاح.

> هذه الصفحة مُولَّدة تلقائياً من مخطط ⁦PKL⁩. راجع الدليل لأمثلة الاستخدام.

الأنواع

`HttpMethod`

طرق طلب ⁦HTTP⁩ القياسية، تُستخدم بواسطة ⁦RouteMatch.methods⁩ لتقييد الطرق التي يطابقها المسار.

pkl

typealias HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE"

---

`RouteMatch`

شروط المطابقة للمسار. جميع الحقول غير ⁦null⁩ يجب أن تتطابق في وقت واحد (منطق ⁦AND⁩) لاختيار المسار. حذف حقل (تركه ⁦null⁩) يعني "مطابقة أي قيمة" لذلك البُعد.

دلالات مطابقة المسار:

⁦"/exact"⁩ — مطابقة مسار تامة ⁦"/prefix/"⁩ — مطابقة بادئة؛ ⁦⁩ يستهلك جزء مسار واحد بالضبط ⁦"/glob/"⁩ — نمط شامل؛ ⁦⁩ يستهلك صفراً أو أكثر من الأجزاء ⁦"/re:^/v\d"⁩ — تعبير نظامي (بادئة ⁦"re:"⁩)

⁦RouteMatch⁩ بجميع الحقول ⁦null⁩ يطابق كل طلب — مفيد كمسار شامل في نهاية القائمة.

الحقل	النوع	الافتراضي	الوصف
`path`	String?	`null`	نمط المسار للمطابقة مقابل مسار ⁦URI⁩ للطلب. ⁦`null`⁩ يطابق
`host`	String?	`null`	نمط اسم المضيف / المضيف الافتراضي. يدعم أنماط شاملة للنطاقات الفرعية
`methods`	Listing?	`null`	تقييد هذا المسار للطرق ⁦HTTP⁩ المُدرجة. ⁦`null`⁩ يطابق جميع
`headers`	Mapping?	`null`	ترويسات طلب مطلوبة. كل إدخال يجب أن يكون موجوداً بقيمة
`queryParams`	Mapping?	`null`	معاملات سلسلة استعلام مطلوبة. كل إدخال يجب أن يكون موجوداً

`path`

نمط المسار للمطابقة مقابل مسار ⁦URI⁩ للطلب. ⁦null⁩ يطابق جميع المسارات. راجع تعليق مستوى الصنف لصيغة الأنماط.

pkl

path = "/api/**"
path = "/re:^/users/[0-9]+"

`host`

نمط اسم المضيف / المضيف الافتراضي. يدعم أنماط شاملة للنطاقات الفرعية ذات أحرف البدل. ⁦null⁩ يطابق جميع المضيفين.

pkl

host = "api.example.com"
host = "*.example.com"

`methods`

تقييد هذا المسار للطرق ⁦HTTP⁩ المُدرجة. ⁦null⁩ يطابق جميع الطرق. الطلبات بطريقة غير مطابقة تستمر إلى المسار التالي (لا تتلقى ⁦405⁩).

pkl

methods { "GET"; "HEAD" }

`headers`

ترويسات طلب مطلوبة. كل إدخال يجب أن يكون موجوداً بقيمة مطابقة لمطابقة المسار. القيم تدعم ⁦*⁩ كحرف بدل.

pkl

headers { ["Accept"] = "application/json" }
headers { ["X-Feature-Flag"] = "*" }

`queryParams`

معاملات سلسلة استعلام مطلوبة. كل إدخال يجب أن يكون موجوداً بالقيمة المحددة لمطابقة المسار.

pkl

queryParams { ["format"] = "json" }

---

`Route`

مسار يقرن شروط المطابقة مع معالج ووسيط اختياري محدد بالمسار. تُقيَّم المسارات بالترتيب الذي تظهر به في ⁦ServerBlock.routes⁩؛ أول تطابق يفوز.

pkl

new Route {
  match = "/api/**"
  handler = new ReverseProxy { upstreams { "backend:9000" } }
  middleware { new RateLimit { requests = 100; window = 60.s } }
}

الحقل	النوع	الافتراضي	الوصف
`match`	(String\	RouteMatch)	`new RouteMatch {}`	الشروط التي تختار هذا المسار. يقبل اختصار نص المسار
`handler`	_handler.Handler	(مطلوب)	المعالج المُستدعى عند مطابقة هذا المسار. راجع ⁦`Handler`⁩ للأنواع
`middleware`	Listing<_middleware.Middleware>	(فارغ)	الوسيط المُطبق فقط على الطلبات المطابقة لهذا المسار. يعمل

`match`

الشروط التي تختار هذا المسار. يقبل اختصار نص المسار أو كائن ⁦RouteMatch⁩ كامل للمطابقة متعددة الأبعاد.

pkl

match = "/api/**"
match { path = "/api/**"; methods { "GET"; "POST" } }

⁦RouteMatch⁩ فارغ (الافتراضي) يطابق كل طلب — مفيد كمسار شامل في نهاية القائمة.

`handler`

المعالج المُستدعى عند مطابقة هذا المسار. راجع ⁦Handler⁩ للأنواع المتاحة (⁦StaticFiles⁩، ⁦ReverseProxy⁩، ⁦Redirect⁩، ⁦Cgi⁩، ⁦Respond⁩).

`middleware`

الوسيط المُطبق فقط على الطلبات المطابقة لهذا المسار. يعمل بعد ⁦ServerBlock.middleware⁩ على مستوى الكتلة ويلتف حول معالج هذا المسار. يُطبق بترتيب التصريح (الأول = الطبقة الخارجية).

---