النقاط الأساسية لتصميم عقود بيانات JSON API

الخلاصة: اقفل غلاف الاستجابة، وصيغة الأخطاء، وتمثيل المعرف والوقت، ودلالات null مقابل الغياب في العقد قبل مناقشة تفاصيل الترقيم والتسمية؛ وغلّف المستوى الأعلى دائماً في غلاف data حتى يمكن إضافة الترقيم ومعرفات التتبع لاحقاً دون كسر المستدعين الحاليين.

لا توجد إجابات قياسية في تصميم API، لكن توجد بعض القرارات "الصعب استرجاعها بعد الاختيار" التي يُستحسن التفكير فيها قبل كتابة أول سطر كود.

1. تغليف الاستجابة أم لا

ثلاثة أنماط:

复制// النمط A: استجابة عارية
{ "id": 1, "name": "张三" }

// النمط B: غلاف data
{ "data": { "id": 1, "name": "张三" } }

// النمط C: data + metadata
{ "data": { "id": 1, "name": "张三" }, "meta": { "requestId": "a1b2" } }

التوصية: استخدم غلاف data بشكل موحّد للقوائم والتفاصيل معاً، ولا تجعل المستوى الأعلى مصفوفة أبداً. بذلك لا تكسر إضافة الترقيم أو معرفات التتبع العقد لاحقاً.

2. صيغة الأخطاء: انسخ RFC 9457

اختراع بنية أخطاء خاصة بك مصدر ضخم لتكلفة التعاون. يحدد RFC 9457 (الذي يحل محل RFC 7807) نوع application/problem+json:

复制{
  "type": "https://bbdrug.com/problems/insufficient-balance",
  "title": "余额不足",
  "status": 422,
  "detail": "账户余额 12.00 元，本次扣款需要 30.00 元",
  "instance": "/accounts/A1001/payments/p-889",
  "balance": "12.00",
  "required": "30.00"
}

حقول الامتداد (مثل balance / required أعلاه) تسمح بها المواصفات، ويمكن للواجهة استخدامها لرسائل دقيقة بدلاً من تحليل نص detail.

3. الترقيم: المؤشر أفضل من الإزاحة

复制// ترقيم بالإزاحة
{ "data": [], "page": { "offset": 40, "limit": 20, "total": 137 } }

// ترقيم بالمؤشر
{ "data": [], "page": { "nextCursor": "eyJpZCI6MTAwfQ", "hasMore": true } }

التوصية: استخدم ترقيم الإزاحة لجداول الإدارة (التي تحتاج قفزات صفحات ومجاميع)، وترقيم المؤشر لخلاصات المستخدمين اللانهائية.

4. المعرفات والوقت

4.1 استخدم النصوص دائماً للمعرفات

جاء المنطق في مقالة الأنواع: على جانب JavaScript، تفقد القيم فوق 2^53 دقتها بصمت. وحتى لو كان المعرف الحالي عدداً صحيحاً صغيراً يتزايد تلقائياً، فإن استخدام النصوص يترك مجالاً للتحول لاحقاً إلى معرفات snowflake.

复制{ "id": "1000000000000000001" }

4.2 استخدم نصوص RFC 3339 للوقت

复制{
  "createdAt": "2026-10-30T10:41:45+08:00",
  "updatedAt": "2026-10-30T02:41:45Z"
}

• لا تستخدم طوابع زمنية رقمية بالميلي ثانية: فهي صعبة القراءة، والوحدة (ثوانٍ/ميلي ثانية) تُخطأ كثيراً؛
• حدد المنطقة الزمنية صراحةً: إما بـZ أو بإزاحة؛ ولا تستخدم أبداً "وقت محلي بلا منطقة زمنية"؛
• سمّ الحقول بشكل موحّد xxxAt حتى يتضح من النظرة الأولى أنه نقطة زمنية.

5. null والغياب

يجب أن تختار واحدة وتكتبها في الوثائق:

مشكلة النهج A أن "محذوف" و"مرسل كـnull" يعنيان شيئين مختلفين في PATCH، وهو أمر يسهل إساءة تفسيره؛ ومشكلة النهج B أن JSON.stringify في الواجهة يُسقط الحقول التي قيمتها undefined، وهو ما يصادف تطابق الدلالات.

التوصية العملية:

• استخدم النهج A لأجسام الاستجابة (null يعني بوضوح لا قيمة، والواجهة لا تحتاج إلى تمييز undefined)؛
• استخدم النهج B لأجسام الطلب (خصوصاً PATCH)، مع Merge Patch أو JSON Patch لجعل الدلالات صريحة.

6. تسمية الحقول والبنية

إعادة [] بدلاً من null للمصفوفات الفارغة مهمة جداً: فلن يتعطل data.items.map(...) في الواجهة بسبب null.

7. استراتيجية التطور

ثلاث قواعد انضباط:

1. يجب أن يكون العملاء متسامحين مع الحقول غير المعروفة (لا تحصر نفسك بـadditionalProperties: false)؛
2. يجب أن يكون لدى العملاء فرع بديل لقيم enum غير المعروفة؛
3. احتفظ بالحقول المهجورة لمدة إصدار رئيسي واحد على الأقل، وعلّمها بـDeprecation في ترويسات الاستجابة أو الوثائق.

8. مثال كامل

复制{
  "data": [
    {
      "id": "1001",
      "name": "JSON 权威指南",
      "price": "89.50",
      "tags": ["json", "spec"],
      "publishedAt": "2026-09-01T00:00:00+08:00",
      "author": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req-7f3a", "tookMs": 12 }
}

تعكس هذه الاستجابة كل الاتفاقيات أعلاه: غلاف data، معرفات نصية، مبالغ كنصوص، طوابع زمنية بمنطقة زمنية، null بمعنى مفقود، مصفوفة فارغة، ترقيم بالمؤشر، وmeta لمعلومات القابلية للملاحظة.

9. قائمة الفحص

• [ ] المستوى الأعلى ليس مصفوفة؛ استخدم غلاف data بشكل موحّد؛
• [ ] استجابات الأخطاء تتبع RFC 9457 وتشمل type ثابتاً؛
• [ ] شكل الترقيم يطابق سيناريو الأعمال؛
• [ ] المعرفات نصوص، والوقت يستخدم RFC 3339؛
• [ ] دلالات null والغياب مكتوبة في الوثائق؛
• [ ] أسلوب التسمية موحّد في المشروع، وenums تستخدم نصوصاً صغيرة؛
• [ ] العميل لديه بدائل للحقول غير المعروفة وقيم enum غير المعروفة؛
• [ ] التغييرات الكاسرة تمر عبر إصدارات أو انتقال dual-write.

FAQ

كيف أصمم JSON API قابلة للتطور؟

غلّف القوائم والتفاصيل بشكل موحّد في غلاف data ولا تجعل المستوى الأعلى مصفوفة أبداً، حتى يمكن إضافة الترقيم ومعرفات التتبع دون كسر العقد. استخدم معرفات نصية وطوابع زمنية RFC 3339، واكتب دلالات null مقابل الغياب في الوثائق. أبقِ الحقول الجديدة اختيارية ومستقلة دلالياً، وامنح العملاء بدائل للحقول غير المعروفة وقيم enum.

لماذا لا أبتكر صيغة أخطاء مخصصة؟

اختراع بنية أخطاء خاصة بك مصدر ضخم لتكلفة التعاون. انسخ application/problem+json من RFC 9457، وحدد المشكلات بـtype ثابت، واسمح بحقول امتداد مثل balance وrequired، حتى تبني الواجهة رسائل دقيقة دون تحليل نص detail.

هل يجب أن يستخدم كل endpoint ترقيم المؤشر؟

لا. جداول الإدارة تحتاج قفزات صفحات ومجاميع، لذا يناسبها ترقيم الإزاحة أكثر؛ وخلاصات المستخدمين اللانهائية يجب أن تستخدم ترقيم المؤشر، الذي يبقى مستقراً في الصفحات العميقة ويتجنب التكرارات أو الفجوات عند تغيّر البيانات. اختر بناءً على ما إذا كان السيناريو يحتاج قفزات صفحات ومجاميع.