حوّل JSON إلى هياكل Go!

أدخل JSON لتحويله إلى هياكل Go مع وسوم json! يدعم Go (Golang) struct, json tags.
JSON
النتيجة

حوّل JSON إلى هياكل Go!

حوّل JSON إلى تعريفات struct في Go مع وسوم encoding/json. تتبع أسماء الحقول قاعدة الأسماء المُصدَّرة في Go وقائمة الاختصارات في golint (ID، URL، API، ...)، وتُحاذى الأعمدة كما لو مرّ الكود عبر gofmt.

يفيد عندما تحتاج إلى نوع تُجري عليه json.Unmarshal لـ payload من webhook أو استجابة API، أو struct لجسم الطلب في handlers من net/http أو Gin أو Echo، أو struct إعدادات لأداة CLI.

طريقة الاستخدام

  1. الصق JSON. مع مصفوفة من عدة صفوف، تُكتشف الحقول الغائبة في بعض الصفوف وتُوسم بـ omitempty.
  2. أدخل اسم الـ struct على المستوى الأعلى في اسم الهيكل (الافتراضي Root)؛ ويبقى في الرابط على شكل ?name=.
  3. الصق النتيجة في ملف .go وأضف عبارة package. إذا عُثر على حقول زمنية، يُضمَّن import "time".
  4. استخدمه بالشكل var ev WebhookEvent; err := json.Unmarshal(body, &ev).

مثال

المدخلات (JSON)
{
  "event_id": "evt_1Pq",
  "type": "invoice.paid",
  "created_at": "2024-05-01T03:15:00Z",
  "amount_cents": 4999,
  "customer": { "id": "cus_9", "email": "kim@example.com" },
  "retry_count": null
}
المخرجات (Go)
import "time"

type WebhookEvent struct {
	EventID     string    `json:"event_id"`
	Type        string    `json:"type"`
	CreatedAt   time.Time `json:"created_at"`
	AmountCents int       `json:"amount_cents"`
	Customer    Customer  `json:"customer"`
	RetryCount  any       `json:"retry_count,omitempty"`
}

type Customer struct {
	ID    string `json:"id"`
	Email string `json:"email"`
}

يصبح event_id هو EventID وفق قاعدة الاختصارات في golint، ويُستنتج created_at، وهو سلسلة RFC 3339، على أنه time.Time، ما يضيف import "time". أما retry_count فقيمته null، فنوعه مجهول: يصبح any مع omitempty.

الميزات المدعومة

  • وسم json:"originalKey" على كل حقل، إضافة إلى ,omitempty للحقول الغائبة في بعض الصفوف أو التي تحوي null.
  • أنواع القيم الاختيارية (int، string، bool، الـ structs، time.Time) تصبح مؤشرات (*int) ليختلف "الغياب" عن القيمة الصفرية. أما الـ slices وany فهي قابلة لـ nil أصلًا وتبقى دون مؤشر.
  • الأرقام: int للأعداد الصحيحة ضمن 32 بت، وint64 لما يتجاوزها، وfloat64 حين تظهر أعداد عشرية.
  • سلاسل RFC 3339 مثل 2024-05-01T03:15:00Z تُستنتج على أنها time.Time.
  • تبقى الاختصارات الشائعة بأحرف كبيرة (user_id → UserID، home_url → HomeURL)؛ والمفاتيح التي تبدأ برقم تحصل على البادئة Field.
  • المفاتيح التي لا يمكن أن تظهر في وسم json في Go، مثل ""، تُتخطى وتُدرج في تعليق فوق الـ struct.
  • مصفوفة الكائنات على المستوى الأعلى تصبح struct للعنصر مع تعليق يشير إلى إجراء unmarshal إلى []Root.

حالات الاستخدام

مستقبلات الـ webhooks

ابنِ struct من حدث نموذجي ترسله خدمة دفع أو استضافة Git وفك ترميزه بـ json.NewDecoder(r.Body).Decode(&ev)، بدلًا من تأكيدات النوع المتكررة على map[string]any.

ربط الطلبات في Gin أو Echo

ولّد الـ struct الخاص بـ c.ShouldBindJSON(&req) من عيّنة طلب العميل، ثم أضف وسوم binding:"required" حيث يلزم.

أدوات CLI التي تقرأ إعدادات JSON

حوّل config.json إلى struct مرة واحدة، فيعطيك استدعاء json.Unmarshal واحد بعد os.ReadFile الإعدادات كلها كقيم ذات أنواع.

ملاحظات وقيود

  • لا يُستنتج time.Time إلا لسلاسل RFC 3339؛ القيم مثل 2024-05-01 03:15:00 أو طوابع Unix الزمنية تبقى string أو int.
  • يتجاهل json.Unmarshal المفاتيح المجهولة ويطابق المفاتيح دون تمييز حالة الأحرف افتراضيًا. استخدم Decoder.DisallowUnknownFields() إن أردت فك ترميز صارمًا.
  • النوع int بطول 64 بت على المنصات 64 بت، لكن int64 لا يُكتب إلا حين تتجاوز قيمة في العيّنة 32 بت. للمعرّفات التي قد تكبر، الأكثر أمانًا أن تنتقل إلى int64 بنفسك.
  • تُعرَّف كل الـ structs المتداخلة كأنواع مستقلة على المستوى الأعلى؛ ولا تُستخدم structs مضمّنة مجهولة.
  • القيم مختلطة الأنواع والقيم التي لا تكون إلا null تصبح any؛ استبدلها ما إن يُعرف النوع الحقيقي.

الأسئلة الشائعة

لماذا الحقول الاختيارية مؤشرات مثل *int؟

حقل int عادي يكون 0 حين يغيب المفتاح، ولا يمكن تمييزه عن 0 حقيقي. أما المؤشر فيكون nil حين يغيب المفتاح أو يكون null، ومع omitempty يُحذف المفتاح عند إعادة الـ marshaling.

هل يمكنني جعل أسماء الحقول بأحرف صغيرة؟

لا يقرأ encoding/json ولا يكتب إلا الحقول المُصدَّرة (التي تبدأ بحرف كبير)؛ أما الحقول بأحرف صغيرة فتُتجاهل حتى مع وجود وسم. في Go تبقى الأسماء بحرف كبير ويوضع مفتاح JSON في الوسم.

حقل null مثل retry_count خرج على شكل any.

حين لا يوجد في العيّنة إلا null فلا شيء يُستنتج منه النوع. أضف استجابة أخرى بقيمة حقيقية إلى مصفوفة وحوّل الاثنتين، أو غيّره يدويًا إلى شيء مثل *int.

هل يمكنني تحويل struct في Go مجددًا إلى JSON نموذجي؟

نعم. الصق الـ struct في تبويب Go struct → JSON في الأعلى؛ فيقرأ الوسوم ويُنتج JSON نموذجيًا.