jsonv2.Marshal

تحويل قيمة إلى JSON (النسخة الثانية) jsonv2.Marshal

jsonv2.Marshal من حزمة encoding/json/v2 الجديدة (منذ Go 1.27) تحوّل قيمة Go إلى JSON بنفس فكرة json.Marshal القديمة، لكن بقواعد أدقّ وخيارات Options اختيارية — الحزمة القديمة تبقى مدعومة بالكامل.

encoding/json/v2 حزمة موازية جديدة، لا بديل إلزامي عن encoding/json — القديمة مدعومة بالكامل ولا خطة لإزالتها. jsonv2.Marshal تأخذ أي قيمة ومعاملات Options اختيارية (variadic) لضبط سلوك التحويل، وتعيد []byte و error بنفس شكل النسخة الأولى تمامًا للاستخدام الأساسي.

الفرق الجوهري بين النسختين ليس بـ Marshal نفسها بقدر ما هو بالتشدّد أثناء Unmarshal (رفض UTF-8 غير صالح، رفض مفاتيح مكرَّرة) — لكن نفس فريق الأداء يُحسِّن كلا الاتجاهين. أداء Marshal بالنسخة الثانية يبقى مكافئًا تقريبًا للأولى، بينما أداء Unmarshal أسرع بوضوح.

الصياغة

func Marshal(in any, opts ...Options) (out []byte, err error)

📄 مثال

import jsonv2 "encoding/json/v2"

type User struct {
  Name string `json:"name"`
}

data, err := jsonv2.Marshal(User{Name: "براء"})
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(data))   // {"name":"براء"}

أهم النقاط

العنصر	الوظيفة
in any	أي قيمة Go قابلة للتحويل — نفس أنواع الوسوم json:"..." المألوفة تعمل بلا تغيير
opts ...Options	معاملات اختيارية لضبط سلوك التحويل — يمكن تجاهلها تمامًا للاستخدام الأساسي

💡 نصائح عملية

استورد الحزمة بلقب صريح (import jsonv2 "encoding/json/v2") لتفادي التعارض مع encoding/json القياسية بنفس الملف
لمشروع قائم يعمل بشكل صحيح بـ encoding/json، لا داعي للترحيل الفوري — اختر v2 لمشروع جديد أو عند الحاجة الفعلية للتشدّد الإضافي

⚠️ أخطاء شائعة

افتراض أن jsonv2.Marshal تُخرج نصًّا مختلفًا شكليًا عن json.Marshal لنفس القيمة البسيطة — للاستخدام الأساسي المخرجات متطابقة تقريبًا، الفرق بالتشدّد أثناء القراءة (Unmarshal) لا الكتابة

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار GO الكامل بالعربي.