نظرة سريعة#
الأسماء على الشبكة بحروف صغيرة بصيغة snake_case. يرفض وقت التشغيل خاصية بصيغة camelCase في جسم الطلب، فالتعريف الذي يعلنها يصف طلباً يفشل. ويُولَّد ملف OpenAPI الخاص بالمنصة من الأسماء نفسها التي يقرؤها وقت التشغيل ويكتبها.
| الموضع | الصيغة | مثال |
|---|---|---|
| خاصية JSON | snake_case | customer_id وcreated_at |
| معامل الاستعلام | snake_case | per_page وsort_by |
| جزء المسار | kebab-case بحروف صغيرة | kyc-kyb وplatform-subscriptions |
| متغيّر المسار | snake_case | {order_id} |
| قيمة التعداد | snake_case، أو UPPER_SNAKE_CASE إن كانت تطابق تعداد Java | shipped وIN_REVIEW |
| اسم الترويسة | Hyphen-Case كما يكتبه HTTP | Idempotency-Key وAccept-Language |
| رمز الخطأ | snake_case | quota_exceeded |
الخصائص والمعاملات#
الاسم بحروف صغيرة مع أرقام وشرطة سفلية واحدة بين الكلمات، ويبدأ بحرف. تُرفض الأسماء orderId وOrderID وorder-id وorder__id.
{
"order_id": "ord_1042",
"customer_id": "cus_77",
"item_count": 3,
"created_at": "2026-10-17T09:30:00Z"
}الطوابع الزمنية بصيغة ISO 8601 بالتوقيت العالمي. يحمل المبلغ عملته في خاصية مجاورة، مثل amount وcurrency بقيمة مثل SAR.
قيم التعداد#
يستخدم التعداد الجديد قيماً بصيغة snake_case. أما التعداد الذي يطابق تعداد Java فيحتفظ بصيغة UPPER_SNAKE_CASE الخاصة به: تحمل تعريفات المنصة نفسها عدة مئات من هذه القيم. الصيغتان مقبولتان. تُرفض صيغة kebab-case وcamelCase والحروف المختلطة والقيم التي فيها مسافات.
المسارات#
جزء المسار اسم جمع بصيغة kebab-case بحروف صغيرة. ومتغيّر المسار هو الاسم المفرد للمعرّف بصيغة snake_case. متغيّر المسار موضعي على الشبكة، فاختلاف الصيغة فيه لا يكسر عميلاً أبداً؛ وتبلغ عنه القواعد كتلميح للمزوّد لأن العملاء المولَّدة تستخدم الاسم لوسائطها.
تتحقق منه#
| القاعدة | الشدة | ما تتحقق منه |
|---|---|---|
api360-property-snake-case | error | كل اسم خاصية في المخطط |
api360-query-param-snake-case | error | كل اسم معامل استعلام |
api360-path-param-snake-case | hint | كل اسم متغيّر مسار (معطّلة لتعريفات المنصة نفسها) |
api360-enum-value-case | warn | كل قيمة نصية في تعداد |
api360-path-kebab-case | warn | كل جزء حرفي من المسار |
انظر أيضاً#
- فحص تعريف الواجهة: شغّل القواعد على ملفك.
- الأخطاء: رمز الخطأ وجسمه بصيغة
snake_case.