التعامل مع JSON

حزمة encoding/json

import "encoding/json"

من بنية إلى JSON (Marshal)

type User struct {
  Name  string `json:"name"`
  Email string `json:"email"`
  Age   int    `json:"age"`
}

u := User{Name: "براء", Email: "b@mail.com", Age: 25}
data, _ := json.Marshal(u)
fmt.Println(string(data))
// {"name":"براء","email":"b@mail.com","age":25}

من JSON إلى بنية (Unmarshal)

jsonStr := `{"name":"سارة","age":22}`
var u User
json.Unmarshal([]byte(jsonStr), &u)
fmt.Println(u.Name)   // سارة

وسوم مفيدة

type Product struct {
  ID    int     `json:"id"`
  Name  string  `json:"name"`
  Price float64 `json:"price,omitempty"`  // يُحذف إن كان صفرًا
  Note  string  `json:"-"`                 // يُتجاهل دائمًا
}

تنسيق مقروء

data, _ := json.MarshalIndent(u, "", "  ")

JSON ديناميكي

عند عدم معرفة البنية:

var result map[string]any
json.Unmarshal(data, &result)

💡 الحقول المُصدَّرة (بحرف كبير) فقط تُحوَّل — الخاصّة تُتجاهل.

الجيل الثاني من الحزمة: encoding/json/v2 — منذ Go 1.27

كل ما سبق (json.Marshal و json.Unmarshal) يبقى يعمل بلا أي تغيير — الحزمة القديمة مدعومة بالكامل ولا حاجة للترحيل عنها. لكن منذ Go 1.27، توجد حزمة موازية جديدة encoding/json/v2 بنفس فكرة Marshal/Unmarshal لكن بقواعد أدقّ وأداء unmarshal أسرع ملحوظًا:

import jsonv2 "encoding/json/v2"

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

u := User{Name: "براء", Email: "b@mail.com"}
data, err := jsonv2.Marshal(u)   // نفس شكل json.Marshal تقريبًا

الفرق الجوهري: encoding/json/v2 أكثر صرامة من النسخة الأولى — ترفض نصوص UTF-8 غير صالحة داخل قيم JSON، وترفض تكرار نفس المفتاح مرّتين بنفس كائن JSON بدل تجاهل التكرار بصمت كما كانت النسخة الأولى تفعل. هذا مفيد تحديدًا عند التعامل مع JSON قادم من مصدر خارجي غير موثوق.

💡 لو مشروعك جديد ولا يعتمد على سلوك النسخة الأولى الدقيق، encoding/json/v2 خيار جيد بدءًا من الآن. لو عندك كود قائم يعمل بالنسخة الأولى، لا داعي للترحيل فورًا — Go فريق يضمن استمرار دعم encoding/json القديمة.

🎯 التالي: بناء خادم ويب.