وثائق Go قابلة للتشغيل: JSON

Q: كيف أحوّل بنية إلى JSON في Go؟

استدعِ json.Marshal(v)، التي تعيد []byte وخطأ. لا تُضمَّن إلا الحقول المُصدَّرة (الأسماء التي تبدأ بحرف كبير). استخدم وسم بنية مثل json:"name" على الحقل للتحكّم في مفتاحه في JSON. وللمخرجات المزاحة استخدم json.MarshalIndent(v, "", " ").

Q: لماذا تختفي حقول بنيتي من مخرجات JSON؟

لا ترى encoding/json إلا الحقول المُصدَّرة. الحقل المسمّى name (بحرف صغير) غير مرئي لها، عند الترميز وعند فكّ الترميز. اجعل الحرف الأول كبيرًا واضبط مفتاح JSON بوسم مثل json:"name".

Q: ماذا يفعل omitempty في JSON في Go؟

يُسقط omitempty الحقل من المخرجات عندما يحمل قيمة فارغة: false أو 0 أو "" أو مؤشرًا أو واجهة nil أو شريحة أو خريطة فارغة. ولا يعامل البنية أو time.Time كفارغة. أضافت Go 1.24 الخيار omitzero، الذي يُسقط أي قيمة تساوي القيمة الصفرية لنوعها (أو يعيد تابعها IsZero() القيمة true)، بما في ذلك البنى وtime.Time.

Q: كيف أحلّل JSON ذا بنية مجهولة في Go؟

فكّ الترميز إلى map[string]any (أو any). تصبح الكائنات map[string]any، والمصفوفات []any، والنصوص string، والقيم المنطقية bool، وكل رقم float64. استخدم تأكيدات النوع لقراءة القيم، وDecoder.UseNumber إذا وجب أن تبقى الأعداد الصحيحة الكبيرة دقيقة.

Marshal وUnmarshal

تحوّل json.Marshal قيمة Go إلى بايتات JSON. وتملأ json.Unmarshal قيمة Go من بايتات JSON. وتختار وسوم البنى أسماء حقول JSON.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal:", err)
		return
	}
	fmt.Println(string(data))

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

يغيب Email عن المخرجات الأولى بسبب omitempty ونص فارغ. تحتاج Unmarshal مؤشرًا (&back)؛ وتمرير القيمة نفسها يعيد InvalidUnmarshalError.

وسوم البنى

صيغة الوسم هي json:"name,option,option".

الوسم	الأثر
`json:"user_id"`	استخدام `user_id` مفتاحًا
`json:"email,omitempty"`	الإسقاط عند false أو 0 أو "" أو nil أو شريحة أو خريطة فارغة
`json:",omitzero"` (Go 1.24)	الإسقاط عندما تكون القيمة صفرية، أو يعيد `IsZero()` القيمة true
`json:"-"`	عدم ترميز هذا الحقل أو فكّ ترميزه أبدًا
`json:"-,"`	استخدام المفتاح الحرفي `-`
`json:"count,string"`	ترميز رقم أو قيمة منطقية كنص JSON (`"42"`)
بلا وسم	المفتاح هو اسم الحقل في Go، `UserID`

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

لا تغادر كلمة المرور البنية أبدًا، ويوضع الرصيد بين علامتي اقتباس، ويختفي deleted_at بينما يطبع created_at الوقت الصفري 0001-01-01T00:00:00Z. هذا الفرق هو سبب إضافة omitzero: لم يعمل omitempty مع البنى قط، وهي مفاجأة قديمة مع time.Time. في Go 1.23 وما قبله استخدم *time.Time مع omitempty للحصول على الأثر نفسه.

تنتج MarshalIndent(v, prefix, indent) مخرجات مقروءة. استخدمها لملفات الإعدادات وتتبّع الأخطاء؛ أما الواجهات البرمجية فترسل JSON مضغوطًا عادة.

الحقول المُصدَّرة فقط

تستخدم encoding/json الانعكاس (reflection) ولا ترى إلا الحقول المُصدَّرة. هذا أشيع خطأ في JSON في Go:

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

لا خطأ ولا تحذير، فقط {} عند الإخراج وحقول باقية على الصفر عند الإدخال. اجعل الحروف الأولى كبيرة وأضف وسومًا للمفاتيح ذات الحروف الصغيرة.

كيف يطابق فكّ الترميز الحقول

عند فكّ الترميز إلى بنية:

تُطابق المفاتيح مع اسم الوسم، أو مع اسم الحقل، دون تمييز حالة الأحرف. يملأ {"NAME": "x"} حقلًا موسومًا بـ json:"name".
المفاتيح التي لا حقل مطابقًا لها تُتجاهل بصمت.
الحقول التي لا مفتاح مطابقًا لها تحتفظ بقيمتها الحالية. لا تعيد Unmarshal ضبطها، ففكّ الترميز إلى بنية فيها بيانات يدمج فيها.
عدم تطابق النوع (نص حيث في البنية int) يعيد *json.UnmarshalTypeError، لكن الحقول الأخرى تُملأ مع ذلك.

لرفض المفاتيح غير المتوقّعة، مثلًا في واجهة برمجية صارمة أو ملف إعدادات فيه أخطاء كتابة، استخدم Decoder مع DisallowUnknownFields:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

بنية مجهولة: map[string]any

عندما لا تعرف الشكل مسبقًا، فكّ الترميز إلى map[string]any أو any. التحويل ثابت:

JSON	Go
كائن	`map[string]any`
مصفوفة	`[]any`
نص	`string`
رقم	`float64`
true / false	`bool`
null	`nil`

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

يظهر فخّان في المخرجات. كل رقم float64، فتفشل m["stock"].(int). والأعداد الصحيحة الأكبر من 2^53 تفقد دقتها كـ float64: المعرّف 9007199254740993 يعود بالشكل ...992. يتجنّب UseNumber الأمرين.

إذا كنت تعرف جزءًا من البنية، ففكّ ترميز ذلك الجزء إلى بنية واستخدم json.RawMessage للباقي. يحمل البايتات الخام لحقل لتفكّ ترميزه لاحقًا، بعد أن تعرف نوعه.

الشرائح والخرائط والمؤشرات وnil

قيمة Go	JSON
شريحة `nil` (`var s []int`)	`null`
شريحة فارغة (`[]int{}`)	`[]`
خريطة `nil`	`null`
مؤشر `nil`	`null`
`[]byte`	نص بترميز base64
`map[string]T`	كائن، بمفاتيح مرتّبة
`map[int]T`	كائن بمفاتيح صحيحة مكتوبة كنصوص

الفرق بين الشريحة nil والشريحة الفارغة مهم لعملاء الواجهات البرمجية الذين يتوقّعون مصفوفة. هيّئ بـ []T{} أو make([]T, 0) عندما يجب أن يكون الحقل [].

استخدم حقل مؤشر (*int أو *bool) عندما تحتاج التمييز بين "غائب" و"صفر" في المدخلات. بعد فكّ الترميز يعني المؤشر nil أن المفتاح مفقود أو null؛ والمؤشر إلى 0 يعني أن العميل أرسل 0.

التدفّقات: Encoder وDecoder

تعمل json.Marshal وUnmarshal على شرائح بايتات كاملة. أما لـ io.Reader أو io.Writer (جسم HTTP، أو ملف، أو stdin) فاستخدم json.NewDecoder وjson.NewEncoder. ويستطيع الـ Decoder أيضًا قراءة سلسلة من قيم JSON واحدة تلو الأخرى:

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

يكتب Encoder.Encode سطرًا جديدًا بعد كل قيمة. افتراضيًا يهرّب كل من Marshal وEncoder الرموز < و> و& إلى \u003c و\u003e و\u0026، فيصبح JSON آمنًا للتضمين في HTML. ويعطّل SetEscapeHTML(false) ذلك. في معالجات HTTP يكون json.NewDecoder(r.Body).Decode(&v) وjson.NewEncoder(w).Encode(v) الثنائي المعتاد.

ترميز مخصّص

يستطيع النوع التحكّم في JSON الخاص به بتطبيق json.Marshaler وjson.Unmarshaler. حالة شائعة هي تعداد iota يجب أن يظهر كاسم لا كرقم:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

لـ MarshalJSON مستقبِل قيمة فتعمل مع القيم والمؤشرات؛ أما UnmarshalJSON فتحتاج مستقبِل مؤشر لأنها تعدّل القيمة. الأنواع التي تحتاج شكلًا نصيًا فقط يمكنها تطبيق encoding.TextMarshaler (MarshalText) بدلًا من ذلك، وهذا يجعلها صالحة أيضًا كمفاتيح خرائط.

أخطاء شائعة

أسماء حقول بحروف صغيرة. تُتخطّى بصمت.
تمرير قيمة إلى Unmarshal. تحتاج مؤشرًا.
تجاهل الخطأ. JSON المشوّه وعدم تطابق الأنواع لا يُبلَّغ عنهما إلا عبره.
افتراض أن الأرقام في map[string]any من النوع int. إنها float64.
توقّع أن يُسقط omitempty بنية فارغة أو time.Time صفريًا. استخدم omitzero في Go 1.24، أو مؤشرًا.
الاعتماد على ترتيب الحقول في الخرائط. تُرتَّب مفاتيح الخرائط عند الإخراج؛ وتحتفظ حقول البنى بترتيب تعريفها.

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

كيف أحوّل بنية إلى JSON في Go؟

استدعِ json.Marshal(v)، التي تعيد []byte وخطأ. لا تُضمَّن إلا الحقول المُصدَّرة (الأسماء التي تبدأ بحرف كبير). استخدم وسم بنية مثل json:"name" على الحقل للتحكّم في مفتاحه في JSON. وللمخرجات المزاحة استخدم json.MarshalIndent(v, "", " ").

لماذا تختفي حقول بنيتي من مخرجات JSON؟

لا ترى encoding/json إلا الحقول المُصدَّرة. الحقل المسمّى name (بحرف صغير) غير مرئي لها، عند الترميز وعند فكّ الترميز. اجعل الحرف الأول كبيرًا واضبط مفتاح JSON بوسم مثل json:"name".

ماذا يفعل omitempty في JSON في Go؟

يُسقط omitempty الحقل من المخرجات عندما يحمل قيمة فارغة: false أو 0 أو "" أو مؤشرًا أو واجهة nil أو شريحة أو خريطة فارغة. ولا يعامل البنية أو time.Time كفارغة. أضافت Go 1.24 الخيار omitzero، الذي يُسقط أي قيمة تساوي القيمة الصفرية لنوعها (أو يعيد تابعها IsZero() القيمة true)، بما في ذلك البنى وtime.Time.

كيف أحلّل JSON ذا بنية مجهولة في Go؟

فكّ الترميز إلى map[string]any (أو any). تصبح الكائنات map[string]any، والمصفوفات []any، والنصوص string، والقيم المنطقية bool، وكل رقم float64. استخدم تأكيدات النوع لقراءة القيم، وDecoder.UseNumber إذا وجب أن تبقى الأعداد الصحيحة الكبيرة دقيقة.

مفاهيم ذات صلة