Go Academy · درس

الربط بالبُنى

ألغِ تسلسل الإعدادات

الربط بالبُنى درس مجاني في Go Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Go Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Go Academy 4 دروس في المجموع.

من مفاتيح مبعثرة إلى بنية

يؤدي استدعاء GetString في كل موضع إلى نشر مفاتيح نصية في أنحاء الشيفرة. ويمنحك إلغاء تسلسل الإعدادات في بنية ذات نوع محدد أسماء حقول أثناء الترجمة ومكانًا واحدًا لرؤية البنية.

تعريف بنية Config

صرّح عن بنية تحمل حقولها وسم mapstructure حتى يعرف Viper أي مفتاح إعدادات يرتبط بأي حقل. يتبع كل حقل وسم مثل `mapstructure:"host"`، ويُكتب هذا الوسم بين علامتي backquote في شيفرة Go الفعلية.

type ServerConfig struct {
    Host string // tag: mapstructure host
    Port int    // tag: mapstructure port
}

type Config struct {
    Server ServerConfig // tag: mapstructure server
    Debug  bool         // tag: mapstructure debug
}

استدعاء Unmarshal

بعد قراءة الإعدادات، فك ترميزها في بنيتك:

var cfg Config
if err := viper.Unmarshal(&cfg); err != nil {
    log.Fatalf("unable to decode config: %v", err)
}
fmt.Println(cfg.Server.Port)

لماذا mapstructure وليس json

يستخدم Viper مكتبة mapstructure لأن الإعدادات قد تأتي من صيغ متعددة، مثل YAML وenv وTOML، وليس من JSON وحده. وسم mapstructure مستقل عن الصيغة، ويفك الترميز من map عامة.

فك تسلسل فرع واحد

يمكنك فك تسلسل قسم واحد فقط باستخدام UnmarshalKey:

var sc ServerConfig
viper.UnmarshalKey("server", &sc)
fmt.Println(sc.Host, sc.Port)

الحقول المتداخلة وحقول الشرائح

يتعامل mapstructure تلقائيًا مع التداخل والشرائح:

تتوافق البنى المتداخلة مع أقسام الإعدادات المتداخلة
يتوافق الحقل []string مع مصفوفة YAML أو JSON

ويحمل حقل الشريحة وسم `mapstructure:"hosts"`، ويُكتب بين علامتي backquote في الشيفرة الفعلية.

type Config struct {
    Hosts []string // tag: mapstructure hosts
}

قيم الحقول الافتراضية

إذا كان المفتاح مفقودًا ولم تعيّن له قيمة افتراضية، فسيأخذ الحقل القيمة الصفرية في Go: 0 أو سلسلة فارغة أو false. ادمج ربط البنية مع SetDefault لضمان قيم سليمة.

التحقق من البنية المفكوكة

تحقق من البنية بعد فك تسلسلها. ومن الأنماط الشائعة تعريف دالة Validate() تُرجع خطأً عند وجود تركيبات غير ممكنة، مثل منفذ قيمته 0 أو مضيف فارغ.

func (c Config) Validate() error {
    if c.Server.Port == 0 {
        return fmt.Errorf("server.port is required")
    }
    return nil
}

أخطاء فك الترميز محددة النوع

إذا تعذّر وضع قيمة في نوع الحقل (مثل سلسلة نصية عندما يكون المتوقع قيمة من النوع int)، يعيد فك الترميز خطأً يصف الحقل. احرص دائمًا على التحقق منه وإظهاره بدلًا من تجاهله.

الفكرة نفسها مع encoding/json

يمكن للمكتبة القياسية فك ترميز JSON بالطريقة نفسها. فعند استخدام وسم struct صريح، تملأ الحقول ذات الأنواع المحددة؛ أما عند استخدام map، فتحصل على وصول عام إلى البيانات. يستخدم المثال القابل للتشغيل أدناه map متداخلًا، بحيث يمكن للاعب تنفيذه من دون استخدام وسوم struct.

قابل للتشغيل: فك ترميز إعدادات متداخلة

يفك هذا البرنامج المستقل JSON متداخلًا للإعدادات إلى map عامة، ثم يقرأ الحقول المتداخلة، محاكيًا الطريقة التي يملأ بها Unmarshal بنية struct.

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    raw := "{\"server\":{\"host\":\"localhost\",\"port\":8080},\"debug\":true}"
    var c map[string]any
    if err := json.Unmarshal([]byte(raw), &c); err != nil {
        panic(err)
    }
    srv := c["server"].(map[string]any)
    fmt.Printf("%v:%v debug=%v\n", srv["host"], srv["port"], c["debug"])
}

تحقق سريع

اختبر مدى فهمك لربط الإعدادات ببنى struct.

مراجعة

لقد تعلمت ربط الإعدادات ببنى struct:

استخدم وسوم mapstructure واستدعاء viper.Unmarshal(&cfg)
يفك UnmarshalKey ترميز شجرة فرعية واحدة
تُفك البنى المتداخلة وشرائح البيانات تلقائيًا
أضف طريقة Validate() لاكتشاف التركيبات غير الصحيحة مبكرًا

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

هل درس «الربط بالبُنى» مجاني؟

نعم — نص درس «الربط بالبُنى» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Go Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Go Academy 4 دروس في المجموع.

ماذا ستتعلم في «الربط بالبُنى»؟

ألغِ تسلسل الإعدادات تتمرن على Go Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Go Academy؟

لا تُشترط خبرة سابقة. Go Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «الربط بالبُنى»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Go Academy هذا؟

نعم. كل درس في Go Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Go Academy