إذا كنا بحاجة إلى عرض البيانات بتنسيقات منظمة مثل التقارير النصية أو صفحات HTML، فإن قوالب لغة جو توفر حلًا فعالًا. تتضمن مكتبة لغة جو القياسية حزمتين تسمحان لأي برنامج مكتوب في هذه اللغة بتقديم البيانات بطريقة منسقة بدقة، وهما text/template و html/template.

يمكننا باستخدام هذه الحزم إنشاء قوالب نصية وتمرير البيانات فيها لتصيير render مستندات مصممة خصيصًا لمتطلباتنا. توفر القوالب المرونة في التكرار على البيانات باستخدام الحلقات وتطبيق المنطق الشرطي لتحديد محتوى ومظهر كل عنصر. نستكشف في هذا المقال كيفية استخدام كلتا حزم القوالب. نستخدم في البداية حزمة text/template لإنشاء تقرير نصي عادي من خلال الاستفادة من الحلقات والعبارات الشرطية والدوال المخصصة. نستخدم بعد ذلك html/template لتصيير مستند HTML مع ضمان الحماية ضد الثغرات الأمنية في إدخال التعليمات البرمجية.

المتطلبات الأولية

1لمتابعة هذا المقال التعليمي، سنحتاج إلى:

• إصدار مُثبّت من جو 1.16 أو أعلى، ويمكنك الاستعانة بمقال تثبيت لغة جو Go وإعداد بيئة برمجة محلية على أبونتو Ubuntu لإعداده.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على نظام ماك macOS.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على ويندوز.
• إنشاء البنى Structs في لغة جو وتعريف التوابع في لغة جو.

الخطوة 1- استيراد حزمة text/template

لنفترض أننا نريد إنشاء تقرير بسيط عن بيانات الكلاب التي لدينا. تنسيق التقرير المطلوب هو كما يلي:

---
Name:  Jujube

Sex:   Female (spayed)

Age:   10 months

Breed: German Shepherd/Pitbull

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd/Border Collie

نحتاج لإنشاء هذا التقرير باستخدام حزمة text/template إلى استيراد الحزمة اللازمة وإعداد المشروع. يتألف التقرير من نص ثابت في القالب (العناصر على اليسار) وبيانات ديناميكية نمررها إلى القالب لتقديمها (على اليمين). يمكن تخزين القوالب مثل متغيرات من النوع string ضمن الشيفرة أو ملفات منفصلة خارج الشيفرة. تحتوي القوالب على نص ثابت معياري متداخل مع عبارات شرطية else و if وعبارات التحكم في التدفق (الحلقات) واستدعاءات الدوال، وكلها محاطة داخل أقواس معقوصة {{. . .}}. أخيرًا يمكننا إنشاء المستند النهائي من خلال توفير البيانات للقالب كما في المثال أعلاه.

ننتقل الآن إلى مساحة العمل الخاصة بنا "go env GOPATH" وننشئ مجلدًا جديدًا لهذا المشروع، ثم ننتقل إليه. يمكن إجراء ذلك من خلال التعليمات التالية بالترتيب:

$ cd `go env GOPATH`
$ mkdir pets
$ cd pets

باستخدام محرر نانو nano أو أي محرر آخر تريده، نفتح ملفًا جديدًا يسمى "pets.go":

$ nano pets.go

ونضع فيه التعليمات التالية:

package main

import (
    "os"
    "text/template"
)

func main() {
}

تنتمي الشيفرة السابقة إلى الحزمة main، وتتضمّن الدالة main التي تسمح بتنفيذ الشيفرة باستخدام الأمر go run. تستورد الشيفرة حزمتين، هما: text/template من مكتبة جو القياسية، والتي نستخدمها لكتابة القالب وعرضه، وحزمة os للتفاعل مع نظام التشغيل من خلال الدوال التي توفرها.

بذلك تكون الأمور جاهزة لبدء كتابة المنطق اللازم لإنشاء التقرير المطلوب باستخدام حزمة text/template.

الخطوة 2- إنشاء بيانات القالب

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

. . .
type Pet struct {
    Name   string
    Sex    string
    Intact bool
    Age    string
    Breed  string
}

نُنشئ أيضًا شريحةً من Pet لتخزين معلومات كلبين:

func main() {
    dogs := []Pet{
        {
            Name:   "Jujube",
            Sex:    "Female",
            Intact: false,
            Age:    "10 months",
            Breed:  "German Shepherd/Pitbull",
        },
        {
            Name:   "Zephyr",
            Sex:    "Male",
            Intact: true,
            Age:    "13 years, 3 months",
            Breed:  "German Shepherd/Border Collie",
        },
    }
} // end main

عرّفنا البنية Pet بحقول تمثل الخصائص المختلفة للحيوان الأليف. نستخدم هذه البنى للاحتفاظ ببيانات كل كلب في التقرير. تتضمن الحقول: اسم الحيوان الأليف Name وجنس الحيوان الأليف Sex وقيمة منطقية تشير إلى ما إذا كان الحيوان الأليف سليم Intact وعمر الحيوان الأليف Age والسلالة Breed.

أنشأنا داخل الدالة main شريحة Pet باسم dogs وملأناها بنموذجين من كلاب مختلفة. الكلب الأول يُسمّى Jujube والكلب الثاني Zephyr. من المهم ملاحظة أنه في سيناريو العالم الحقيقي يمكن جلب بيانات القالب من قاعدة بيانات أو الحصول عليها من واجهة برمجة تطبيقات خارجية أو توفيرها من خلال إدخال المستخدم، لكن هنا أدخلنا البيانات يدويًا.

يمكننا الآن المتابعة إلى الخطوة التالية لكتابة القالب وعرضه.

الخطوة 3- تنفيذ وعرض بيانات القالب

حان الوقت الآن لاستكشاف كيفية استخدام حزمة text/template لتوليد مستند من قالب، ولكي نتأكد من أن الأمور تعمل بنجاح، سننشئ ملف قالب فارغ ثم نمرّر البيانات إلى القالب لتنفيذه. على الرغم من أن النموذج الأولي لن يعرض سوى النص "Nothing here yet"، إلا أنه سيكون بمثابة نقطة بداية لتوضيح دوال الحزمة text/template.

ننشئ ملف باسم pets.tmpl بالمحتوى التالي:

Nothing here yet.

نحفظ القالب ونخرج من المحرر. في حالة المحرر نانو nano، نضغط على المفتاحين "CTRL + X" ثم المفتاح "Y" و "ENTER" لتأكيد التغييرات. نضيف الآن مقتطف الشفرة التالي داخل main:

. . .
    var tmplFile = “pets.tmpl”
    tmpl, err := template.New(tmplFile).ParseFiles(tmplFile)
    if err != nil {
        panic(err)
    }
    err = tmpl.Execute(os.Stdout, dogs)
    if err != nil {
        panic(err)
    }
} // main نهاية الدالة 

صرّحنا ضمن الدالة main عن المتغير tmplFile وأسندنا له القيمة “pets.tmpl”، والتي تمثل اسم ملف القالب. استخدمنا بعد ذلك الدالة template.New لإنشاء قالب من template، مع تمرير tmplFile اسمًا للقالب. استدعينا بعد ذلك ParseFiles في القالب الذي أنشأناه حديثًا، مع تمرير tmplFile مثل ملف لتحليله. تربط هذه الخطوة ملف القالب بالقالب.

تحققنا بعد ذلك من أية أخطاء حدثت أثناء تحليل القالب. نلتقط الخطأ في حالة حدوثه، وتنتج لدينا حالة هلع panic في البرنامج.

الآن لتنفيذ القالب نستدعي التابع Execute، ونمرر له وسيط أول os.Stdout ليكون وجهة الخرج ووسيط ثان dogs ليمثّل البيانات الممررة إلى القالب. يمثل os.Stdout (أو أي شيء آخر يحقق الواجهة io.Writer، أي ملف مثلًا) الخرج القياسي الذي سيطبع في هذه الحالة التقرير المُنشأ على الطرفية.

سيؤدي تنفيذ القالب في هذه المرحلة إلى عرض النص المذكور أنفًا، وذلك لأننا لا نستخدم بيانات ديناميكية في القالب.

ستكون الشيفرة كاملة كما يلي:

package main

import (
    "os"
    "text/template"
)

type Pet struct {
    Name   string
    Sex    string
    Intact bool
    Age    string
    Breed  string
}

func main() {
    dogs := []Pet{
        {
            Name:   "Jujube",
            Sex:    "Female",
            Intact: false,
            Age:    "10 months",
            Breed:  "German Shepherd/Pitbull",
        },
        {
            Name:   "Zephyr",
            Sex:    "Male",
            Intact: true,
            Age:    "13 years, 3 months",
            Breed:  "German Shepherd/Border Collie",
        },
    }
    var tmplFile = “pets.tmpl”
    tmpl, err := template.New(tmplFile).ParseFiles(tmplFile)
    if err != nil {
        panic(err)
    }
    err = tmpl.Execute(os.Stdout, dogs)
    if err != nil {
        panic(err)
    }
} // main نهاية الدالة 

لنُشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

Nothing here yet.

لا يطبع البرنامج البيانات حتى الآن، ولكن على الأقل يعمل بطريقة صحيحة. لنكتب الآن قالبًا.

الخطوة 3- كتابة قالب

القالب هو أكثر من مجرد نص عادي بترميز UTF-8، إذ يحتوي القالب على نص ثابت إضافةً إلى الإجراءات التي توجّه محرك القالب حول كيفية معالجة البيانات وإنشاء المخرجات. تُغلّف الإجراءات بأقواس معقوصة {{ <action> }}، وتعمل على البيانات باستخدام تدوين النقطة (.).

من الشائع استخدام بُنى البيانات القابلة للتكرار عند تمرير البيانات إلى قالب، مثل الشرائح أو المصفوفات أو الروابط maps. سنستكشف في هذه الخطوة كيفية التكرار على شريحة في القالب باستخدام range.

التكرار على شريحة

يمكننا استخدام الكلمة المفتاحية range في لغة جو داخل حلقة for للتكرار على شريحة، وكذلك هو الحال في القوالب؛ إذ يمكننا استخدام الإجراء range لتحقيق نفس النتيجة، ولكن بصيغة مختلفة قليلًا؛ فبدلًا من استخدام كلمة مفتاحية for، يمكن ببساطة استخدام range متبوعًا بالبيانات القابلة للتكرار، وتغلق الحلقة بالتعليمة {{ end }}.

لنعدّل ملف "pets.tmpl" عن طريق استبدال محتوياته بما يلي:

{{ range . }}
---
(Pet will appear here...)
{{ end }}

يتخذ الإجراء range النقطة (.) وسيطًا له، والذي يمثل كامل شريحة dogs، ثم نُغلق الحلقة باستخدام {{ end }}. نضع ضمن الحلقة نصًا ثابتًا سيُعرض لكل حيوان أليف. في هذه المرحلة عمومًا، لن تُعرض أية معلومات عن الكلاب في الخرج.

احفظ الملف "pets.tmpl" وشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

---
(Pet will appear here...)

---
(Pet will appear here...)

يُطبع النص الثابت مرتين نظرًا لوجود كلبين في الشريحة. دعونا الآن نستبدل هذا ببعض النصوص الثابتة المفيدة، إلى جانب بيانات الكلاب.

عرض حقل

عند استخدام range مع النقطة . في القالب السابق، إذ تشير النقطة إلى العنصر الحالي في الشريحة أثناء كل تكرار للحلقة وعندما يكون هناك عنصر واحد في الشريحة فهو يشير إلى كامل الشريحة. يتيح ذلك الوصول إلى الحقول المُصدّرة لكل حيوان أليف مباشرةً باستخدام تدوين النقطة دون الحاجة إلى الإشارة إلى فهارس الشريحة. بالتالي لكي نعرض حقل، يمكن ببساطة تغليفه بأقواس معقوصة وإسباقه بنقطة. لنحّدث ملف "pets.tmpl" بالشيفرة التالية:

{{ range . }}
---
Name:  {{ .Name }}

Sex:   {{ .Sex }}

Age:   {{ .Age }}

Breed: {{ .Breed }}
{{ end }}

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

لنُشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

---
Name:  Jujube

Sex:   Female

Age:   10 months

Breed: German Shepherd/Pitbull

---
Name:  Zephyr

Sex:   Male

Age:   13 years, 3 months

Breed: German Shepherd/Border Collie

يبدو الأمر جيدًا. الآن دعونا نرى كيفية استخدام المنطق الشرطي لعرض الحقل الخامس.

استخدام الشروط

تجاهلنا الحقل Intact في القالب السابق؛ لإبقاء التقرير أكثر سهولة للقراءة، فبدلًا من عرض القيمة المنطقية مباشرةً true أو false، يمكننا استخدام إجراء if-else لتخصيص الخرج بناءً على قيمة الحقل، وتقديم معلومات أوضح وأكثر سهولة للفهم من مجرد وضع true أو false.

نفتح ملف "pets.tmpl" مجددًا ونعدّل القالب على النحو التالي:

{{ range . }}
---
Name:  {{ .Name }}

Sex:   {{ .Sex }} ({{ if .Intact }}intact{{ else }}fixed{{ end }})

Age:   {{ .Age }}

Breed: {{ .Breed }}
{{ end }}

يشتمل القالب الآن على عبارة if-else للتحقق من قيمة الحقل Intact. إذا كان الحقل true، فإنه يطبع (intact)، وإلا فإنه يطبع (fixed). يمكننا أيضًا تحسين الخرج أكثر؛ من خلال عرض المصطلحات الخاصة بالجنس لكلب حالته fixed، مثل spayed أو neutered، بدلًا من استخدام المصطلح العام fixed. لتحقيق ذلك يمكننا إضافة عبارة if متداخلة داخل كتلةelse:

{{ range . }}
---
Name:  {{ .Name }}

Sex:   {{ .Sex }} ({{ if .Intact }}intact{{ else }}{{ if (eq .Sex "Female") }}spayed{{ else }}neutered{{ end }}{{ end }})

Age:   {{ .Age }}

Breed: {{ .Breed }}
{{ end }}

مع هذا التعديل؛ يتحقق القالب أولًا مما إذا كان الحيوان الأليف سليمًا. إذا لم يكن الأمر كذلك، فإنه يتحقق أيضًا مما إذا كان الحيوان الأليف أنثى Female. يسمح هذا بمعلومات أكثر دقة في التقرير.

احفظ ملف القالب وشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

سيكون الخرج:

---
Name:  Jujube

Sex:   Female (spayed)

Age:   10 months

Breed: German Shepherd/Pitbull

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd/Border Collie

لدينا كلبان وثلاث حالات محتملة لعرض Intact. دعونا نضيف كلبًا آخر إلى الشريحة في pets.go لتغطية الحالات الثلاث:

. . .
func main() {
    dogs := []Pet{
        {
            Name:   "Jujube",
            Sex:    "Female",
            Intact: false,
            Age:    "10 months",
            Breed:  "German Shepherd/Pitbull",
        },
        {
            Name:   "Zephyr",
            Sex:    "Male",
            Intact: true,
            Age:    "13 years, 3 months",
            Breed:  "German Shepherd/Border Collie",
        },
        {
            Name:   "Bruce Wayne",
            Sex:    "Male",
            Intact: false,
            Age:    "3 years, 8 months",
            Breed:  "Chihuahua",
        },
    }
. . .

لنُشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

ليكون الخرج:

---
Name:  Jujube

Sex:   Female (spayed)

Age:   10 months

Breed: German Shepherd/Pitbull

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd/Border Collie

---
Name:  Bruce Wayne

Sex:   Male (neutered)

Age:   3 years, 8 months

Breed: Chihuahua

رائع، يبدو كما هو متوقع.

الآن دعونا نناقش دوال القالب، مثل الدالة eq التي استخدمناها للتو.

استخدام دوال القالب

توفر الحزمة text/template -إضافةً إلى الدالة eq التي استخدمناها سابقًا- العديد من الدوال الأخرى لمقارنة قيم الحقول وإرجاع النتائج المنطقية، مثل gt (أكبر من) و ne (عدم تساوي) و le (أقل من أو يساوي) والمزيد. يمكن استدعاء هذه الدوال بطريقتين مختلفتين:

1. كتابة اسم الدالة متبوعة بمعامل واحد أو أكثر ومفصولة بمسافات. هذه هي الطريقة التي استخدمنا بها الدالة eq في هذا المقال:"eq .Sex "Female.
2. كتابة معامل واحد متبوع برمز الأنبوب |، ثم اسم الدالة والمعلمات الإضافية إذا لزم الأمر. يسمح هذا بربط استدعاءات عدة دوال معًا، مع جعل خرج كل دالة مدخلًا للتالية. هذا مشابه لكيفية عمل أنابيب الأوامر في سطر أوامر Unix.

مثلًا يمكن كتابة عملية المقارنة السابقة باستخدام الدالة eq في القالب بالشكل: "Sex | eq "Female.، وهذا يُكافئ التعبير "eq .Sex "Female.

دعونا الآن نستخدم الدالة len لعرض عدد الكلاب في الجزء العلوي من التقرير. نفتح ملف "pets.tmpl" ونضيف الشيفرة التالية في البداية:

Number of dogs: {{ . | len -}}

{{ range . }}
. . .

يمكنك أيضًا كتابتها بالشكل {{ - . len }}. تحسب هذه الدالة طول البيانات المُمررة في .، وهي في هذه الحالة شريحة الكلاب. بالتالي سنتمكن من عرض عدد الكلاب في أعلى التقرير من خلال تضمين هذه الدالة في القالب.

لاحظ الشَرطة - بجانب الأقواس المزدوجة المعقوصة، وتمنع هذه الشرطة طباعة الأسطر الجديدة n\ بعد الإجراء. يمكن أيضًا استخدامها لمنع طباعة السطر الجديد قبل الإجراء من خلال وضعها قبل الإجراء، أي في البداية {{ - . len - }}.

لنُشغّل ملف البرنامج "pets.go" من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

Number of dogs: 3
---
Name:  Jujube

Sex:   Female (spayed)

Age:   10 months

Breed: German Shepherd & Pitbull

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd & Border Collie

---
Name:  Bruce Wayne

Sex:   Male (neutered)

Age:   3 years, 8 months

Breed: Chihuahua

باستخدام الشرطة في {{- len | .}}، لا توجد أسطر فارغة بين جملة Number of dogs وتفاصيل الكلب الأول.

تجدر الإشارة إلى أن الدوال المضمنة في حزمة text/template محدودة، ومع ذلك يمكن استخدام أي دالة في لغة جو مع القوالب طالما أنها تُرجع قيمة واحدة أو قيمتين، إذ تكون الثانية قيمةً من نوع خطأ error. يسمح هذا بتوسيع دوال القوالب التي يمكن استخدامها من خلال دمج دوال خاصة.

استخدام دوال لغة جو مع القوالب

لنفترض أننا نريد كتابة قالب يأخذ شريحة من الكلاب ويعرض فقط الكلب الأخير. يمكننا في قوالب لغة جو استخراج مجموعة فرعية من شريحة باستخدام الدالة المبنية مسبقًا slice، والتي تعمل بطريقة تشبه [mySlice [x:y في لغة جو. إذا كنا نريد مثلًا استرداد العنصر الأخير من شريحة مكونة من ثلاثة عناصر، فيمكن استخدام {{ slice . 2 }}. من المهم ملاحظة أن slice تُرجع شريحةً أخرى، وليس عنصرًا فرديًا. لذا، {{slice. 2}} تكافئ [:slice [2، وليس [slice [2. يمكن أيضًا أن تقبل الدالة slice عدة فهارس، مثل{{ slice. 0 2 }}لاسترداد الشريحة [slice [0: 2، لكننا لن نستخدم ذلك في هذا السيناريو.

يظهر التحدي عندما نريد الإشارة إلى الفهرس الأخير للشريحة داخل القالب الخاص بنا. على الرغم من أن الدالة len متاحة، إلا أن العنصر الأخير في الشريحة موجود في الفهرس len - 1، وللأسف، لا تدعم القوالب العمليات الحسابية. هنا يمكننا إنشاء دالة مخصصة للتغلب على هذا القيد، وذلك من خلال كتابة دالة تُنقص قيمة عدد صحيح مُمرر لها.

بدايةً ننشئ ملف قالب جديد. نفتح ملفًا جديدًا يسمى "lastPet.tmpl" ونضع المحتوى التالي:

{{- range (len . | dec | slice . ) }}
---
Name:  {{ .Name }}

Sex:   {{ .Sex }} ({{ if .Intact }}intact{{ else }}{{ if ("Female" | eq .Sex) }}spayed{{ else }}neutered{{ end }}{{ end }})

Age:   {{ .Age }}

Breed: {{ .Breed }}
{{ end -}}

يستخدم هذا القالب إجراء range مع الشريحة المُعدّلة للتكرار على آخر كلب في الشريحة المحددة. نُطبّق الدالة المخصصة dec الموجودة في السطر الأول لتقليل طول الشريحة، مما يسمح لنا بالوصول إلى الفهرس الأخير. يعرض القالب بعد ذلك المعلومات ذات الصلة بالكلب الأخير، بما في ذلك الاسم والجنس والعمر والسلالة.

لتعريف الدالة dec المخصصة وتمريرها إلى القالب، نُجري التغييرات التالية داخل الدالة main في الملف "pets.go" -بعد شريحة الكلاب وقبل استدعاء ()tmpl.Execute- كما هو موضح أدناه:

. . .
    funcMap := template.FuncMap{
        "dec": func(i int) int { return i - 1 },
    }
    var tmplFile = “lastPet.tmpl”
    tmpl, err := template.New(tmplFile).Funcs(funcMap).ParseFiles(tmplFile)
    if err != nil {
        panic(err)
    }
    . . .

صرّحنا عن FuncMap على أنها رابط map للدوال، إذ تمثِّل أزواج (المفتاح، القيمة) أسماء الدوال والتطبيق المقابلة لها. نُعرّف في هذه الحالة الدالة dec على أنها دالة مجهولة تطرح 1 من عدد صحيح وتعيد النتيجة.

نُغيّر بعد ذلك اسم ملف القالب إلى "lastPet.tmpl". أخيرًا نستدعي التابع Funcs من القالب، قبل استدعاء ParseFiles، ونمرر له funcMap لإتاحة الدالة dec داخل القالب. من المهم ملاحظة أنه يجب استدعاء Funcs قبل ParseFiles لتسجيل الدالة المخصصة بطريقة صحيحة مع القالب.

دعونا نفهم بدايةً ما يحدث في الإجراء range:

{{- range (len . | dec | slice . ) }}

يجري في هذا السطر الحصول على طول شريحة الكلاب باستخدام . len، ثم تمرير النتيجة إلى الدالة dec المخصصة لطرح قيمة 1 من المتغير المُمرر لها len . | dec، ثم تمرير النتيجة مثل معاملٍ ثانٍ إلى الدالة slice. لذلك، بعبارات أبسط، بالنسبة لشريحة مكونة من ثلاثة كلاب، فإن range تعادل:

{{- range (slice . 2) }}

لنُشغّل ملف البرنامج "pets.go" بعد حفظه من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

---
Name:  Bruce Wayne

Sex:   Male (neutered)

Age:   3 years, 8 months

Breed: Chihuahua

يبدو هذا جيدًا. ماذا لو أردنا إظهار آخر كلبين بدلًا من آخر كلب فقط؟ نُحرّر الملف "lastPet.tmpl" ونضيف استدعاءً آخرًا للدالة dec:

{{- range (len . | dec | dec | slice . ) }}
. . .

لنُشغّل ملف البرنامج "pets.go" بعد حفظه من خلال الأمر go run:

$ go run pets.go

ليكون الخرج على النحو التالي:

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd/Border Collie

---
Name:  Bruce Wayne

Sex:   Male (neutered)

Age:   3 years, 8 months

Breed: Chihuahua

يمكن تحسين الدالة dec من خلال جعلها تأخذ معاملًا واحدًا ونغيّر اسمها بحيث نكتب minus 2 بدلًا من dec | dec.

لنفرض أننا أردنا عرض الكلاب الهجينة مثل "Zephyr" بطريقة مختلفة، وذلك باستبدال الشرطة المائلة بعلامة العطف &. لحسن الحظ لن نضطر لكتابة دالة خاصة لذلك، إذ يمكننا الاستفادة من دالة موجودة في الحزمة strings، لكن نحتاج إلى إجراء بعض التغييرات على ملف "pets.go" قبل ذلك. نستورد أولًا الحزمة strings مع الحزم الأخرى في أعلى الملف. نُحدِّث بعد ذلك المتغير funcMap داخل الدالة main لتضمين دالة ReplaceAll من حزمة strings:

package main

import (
    "os"
    "strings"
    "text/template"
)
. . .
func main() {
    . . .
    funcMap := template.FuncMap{
        "dec":     func(i int) int { return i - 1 },
        "replace": strings.ReplaceAll,
    }
    . . .
} // main نهاية الدالة

من خلال إضافة strings.ReplaceAll إلى funcMap، نكون قد جعلناها متاحةً في القالب تحت الاسم replace. نفتح ملف "lastPet.tmpl" ونعدّله لاستخدام replace:

{{- range (len . | dec | dec | slice . ) }}
---
Name:  {{ .Name }}

Sex:   {{ .Sex }} ({{ if .Intact }}intact{{ else }}{{ if ("Female" | eq .Sex) }}spayed{{ else }}neutered{{ end }}{{ end }})

Age:   {{ .Age }}

Breed: {{ replace .Breed “/” “ & ” }}
{{ end -}}

لنُشغّل ملف البرنامج "pets.go" بعد حفظه من خلال الأمر go run:

$ go run pets.go

سيكون الخرج على النحو التالي:

---
Name:  Zephyr

Sex:   Male (intact)

Age:   13 years, 3 months

Breed: German Shepherd & Border Collie

---
Name:  Bruce Wayne

Sex:   Male (neutered)

Age:   3 years, 8 months

Breed: Chihuahua

تحتوي سلالة Zephyr الآن على علامة عطف بدلًا من شرطة مائلة. أجرينا هذا التعديل على حقل Breed داخل القالب بدلًا من تعديل البيانات في pets.go. يتبع هذا المبدأ القائل بأن عرض البيانات هو مسؤولية القوالب وليس الشيفرة.

تجدر الإشارة إلى أن بعض بيانات الكلاب، مثل حقل Breed، تحتوي على بعض المظاهر التي قد لا تكون طريقة عرض المعلومات فيها مثالية في هندسة البرمجيات عمومًا، إذ يمكن أن يؤدي التنسيق الحالي لتخزين سلالات متعددة في سلسلة واحدة مفصولة بشرطة مائلة / إلى اختلافات في عملية إدخال البيانات، مما يؤدي إلى تنسيقات غير متسقة في قاعدة البيانات (على سبيل المثال، Labrador/Poodle و Labrador & Poodleو Labrador, Poodleو Labrador-Poodle mix، إلخ).

لمعالجة هذه المشكلة وتحسين المرونة في البحث حسب السلالة وتقديم البيانات، قد يكون من الأفضل تخزين حقل Breed مثل شريحة من السلاسل (string[]) بدلًا من سلسلة واحدة. سيؤدي هذا التغيير إلى إزالة الغموض في التنسيق ويسمح بمعالجة أسهل في القوالب. يمكن بعد ذلك استخدام دالة strings.Join ضمن القالب لربط جميع السلالات، جنبًا إلى جنب مع ملاحظة إضافية من خلال الحقل Breed. بحيث تشير إلى ما إذا كان الكلب سلالة أصيلة (purebred) أو سلالة هجينة (mixed breed).

دعونا في الختام نعرض نفس البيانات في مستند HTML ونرى لماذا يجب علينا دائمًا استخدام حزمة html/template عندما يكون ناتج القالب الخاصة بنا بتنسيق HTML.

الخطوة 5- كتابة قالب HTML

في حين أن الحزمة text/template مناسبة لطباعة الخرج بدقة (سواءً من سطر الأوامر أو مكان آخر) وإنشاء ملفات منظّمة من البرامج الدفعية Batch program (برامج تعالج سلسلة من المهام أو الأوامر دفعة واحدة أو بطريقة غير تفاعلية)، إلا أنه من الشائع استخدام قوالب لغة جو لتصيير صفحات HTML في تطبيقات الويب. على سبيل المثال، يعتمد مُنشئ الموقع الثابت (أداة تساعد في إنشاء ملفات HTML ثابتة بناءً على القوالب والمحتوى. يبسط عملية إنشاء مواقع الويب وإدارتها عن طريق تحويل القوالب والمحتوى والموارد الأخرى إلى موقع ويب ثابت جاهز للنشر) هوغو Hugo على كل من text/template و html/template مثل أساس لنظام القوالب الخاص به. تتيح هذه الحزم للمستخدمين تحديد القوالب ذات معاملات النوع وإدراج البيانات ديناميكيًا فيها، مما يتيح إنشاء صفحات HTML لمواقع الويب.

تقدم لغة HTML ميزات فريدة لا نراها مع النص العادي، إذ تستخدم أقواس الزاوية لتغليف العناصر (<td>) وعلامات العطف لتمييز الكيانات (;nbsp&) وعلامات الاقتباس لتغليف قيم أو سمات الوسوم (<"/a href="https://www.digitalocean.com>). عند إدخال البيانات التي تحتوي على هذه الأحرف باستخدام حزمة text/template، يمكن أن ينتج عن ذلك HTML تالف أو حتى حقن شيفرة Code injection (ثغرة أمنية يتمكن منها المهاجم من إدخال التعليمات البرمجية الضارة وتنفيذها داخل تطبيق أو نظام).

تعالج حزمة html/template هذه التحديات، بحيث تهرب تلقائيًا من المحارف التي قد تخلق إشكالية، وتستبدلها بكيانات HTML الآمنة. تُصبح علامة العطف في البيانات (;amp&) وقوس الزاوية اليسرى (;It&) وهكذا.

دعونا نواصل استخدام نفس بيانات الكلاب، لإثبات خطورة استخدام text/template مع HTML. نفتح "pets.go" ونعدّل حقل Name على النحو التالي:

. . .
    dogs := []Pet{
        {
            Name:   "<script>alert(\"Gotcha!\");</script>Jujube",
            Sex:    "Female",
            Intact: false,
            Age:    "10 months",
            Breed:  "German Shepherd/Pit Bull",
        },
        {
            Name:   "Zephyr",
            Sex:    "Male",
            Intact: true,
            Age:    "13 years, 3 months",
            Breed:  "German Shepherd/Border Collie",
        },
        {
            Name:   "Bruce Wayne",
            Sex:    "Male",
            Intact: false,
            Age:    "3 years, 8 months",
            Breed:  "Chihuahua",
        },
    }
        . . .

نُنشئ الآن قالب HTML في ملف جديد يسمى "petsHtml.tmpl":

<p><strong>Pets:</strong> {{ . | len }}</p>
{{ range . }}
<hr />
<dl>
    <dt>Name</dt>
    <dd>{{ .Name }}</dd>
    <dt>Sex</dt>
    <dd>{{ .Sex }} ({{ if .Intact }}intact{{ else }}{{ if (eq .Sex "Female") }}spayed{{ else }}neutered{{ end }}{{ end }})</dd>
    <dt>Age</dt>
    <dd>{{ .Age }}</dd>
    <dt>Breed</dt>
    <dd>{{ replace .Breed “/” “ & ” }}</dd>
</dl>
{{ end }}

نحفظ قالب HTML. نحتاج إلى تعديل المتغير tmpFile قبل تشغيل "pets.go"، ولكن دعونا أيضًا نُعدّل البرنامج لإخراج القالب إلى ملف بدلًا من الطرفية. نفتح الملف "pets.go" ونضيف الشيفرة التالية داخل الدالة main:

. . .
    funcMap := template.FuncMap{
        "dec":     func(i int) int { return i - 1 },
        "replace": strings.ReplaceAll,
    }
    var tmplFile = "petsHtml.tmpl"
    tmpl, err := template.New(tmplFile).Funcs(funcMap).ParseFiles(tmplFile)
    if err != nil {
        panic(err)
    }
    var f *os.File
    f, err = os.Create("pets.html")
    if err != nil {
        panic(err)
    }
    err = tmpl.Execute(f, dogs)
    if err != nil {
        panic(err)
    }
    err = f.Close()
    if err != nil {
        panic(err)
    }
} // end main

نفتح ملف File جديد يسمى "pets.html" ونمرّره (بدلًا من os.Stdout) إلى tmpl.Execute، ثم نغلق الملف عند الانتهاء.

لنُشغّل ملف البرنامج "pets.go" من خلال الأمر go run لإنشاء ملف HTML. نفتح بعد ذلك صفحة الويب المحلية هذه في المتصفح:

$ go run pets.go

شغّل المتصفح البرنامج النصي المحقون، وهذا هو السبب في أنه لا يجب أبدًا استخدام حزمة text/template لإنشاء HTML، خاصةً عندما لا يمكن الوثوق تمامًا بمصدر بيانات القالب.

بصرف النظر عن محارف الهروب في HTML، تعمل حزمة html /template تمامًا مثل text/template ولها نفس الاسم الأساسي ("قالب" template)، مما يعني أن كل ما علينا فعله لجعل القالب آمنًا هو استبدال استيراد text/template مع html /template. لنعدّل ملف "pets.go" وفقًا لذلك الآن:

package main

import (
    "os"
    "strings"
    "html/template"
)
. . .

نحفظ الملف لتعديل بيانات "pets.html" ونشغّله مرةً أخيرة. ثم نعيد تحميل ملف HTML في المتصفح:

صيّرت حزمة html/template النص المُدخل على أنه نص فقط في صفحة الويب. نفتح الملف "pets.html" في محرر النصوص (أو نعرض مصدر الصفحة في المتصفح) وننظر إلى أول كلب Jujube:

. . .
<dl>
        <dt>Name</dt>
        <dd>&lt;script&gt;alert(&#34;Gotcha!&#34;);&lt;/script&gt;Jujube</dd>
        <dt>Sex</dt>
        <dd>Female (spayed)</dd>
        <dt>Age</dt>
        <dd>10 months</dd>
        <dt>Breed</dt>
        <dd>German Shepherd &amp; Pit Bull</dd>
</dl>
. . .

استبدلت حزمة html أقواس الزاوية ومحارف الاقتباس في اسم Jujube، وكذلك علامة العطف في السلالة.

الخاتمة

توفر قوالب لغة جو حلًا متعدد القدرات لدمج البيانات في تنسيقات نصية متنوعة. يمكن استخدام القوالب في أدوات سطر الأوامر لتنسيق الخرج، وكذلك في تطبيقات الويب لإنشاء صفحات HTML. تعلمنا خلال هذا المقال كيفية الاستفادة من حزم القوالب المضمنة في لغة جو لإنتاج نص جيد التنظيم وعرض HTML باستخدام نفس البيانات.

ترجمة -وبتصرف- للمقال How To Use Templates in Go لصاحبه Kristin Davidson.

اقرأ أيضًا

• المقال السابق كيفية استخدام الأنواع المعممة Generics في لغة جو Go.
• كيفية استخدام القوالب في تطبيقات فلاسك Flask.
• مكونات الويب: عناصر HTML المخصصة وقوالبها.

قدمت لغة جو في الإصدار 1.18 ميزةً جديدة تُعرف باسم الأنواع المُعمّمة generic types -أو اختصارًا generics- والتي كانت في قائمة أمنيات مُطوّري هذه اللغة لبعض الوقت. والنوع المُعمّم في لغات البرمجة، هو نوع يمكن استخدامه مع أنواع متعددة أخرى.

سابقًا، عندما كنا نرغب في استخدام نوعين مختلفين لنفس المتغير في لغة جو، كنا نحتاج إما لاستخدام واجهة مُعرّفة بأسلوب معين مثل io.Reader، أو استخدام {}interface الذي يسمح باستخدام أي قيمة. المشكلة في أن استخدام {}interface يجعل التعامل مع تلك الأنواع صعبًا، لأنه يجب التحويل بين العديد من الأنواع الأخرى المحتملة للتفاعل معها (عليك تحويل القيم بين أنواع مختلفة من البيانات للتعامل معها). على سبيل المثال، إذا كان لدينا قيمة من {}interface تمثل عددًا، يجب علينا تحويلها إلى int قبل أن تتمكن من إجراء العمليات الحسابية عليها. هذه العملية قد تكون معقدة وتستلزم كتابة الكثير من التعليمات الإضافية للتعامل مع تحويل الأنواع المختلفة، أما الآن وبفضل الأنواع المُعمّمة، يمكننا التفاعل مباشرةً مع الأنواع المختلفة دون الحاجة للتحويل بينها، مما يؤدي إلى شيفرة نظيفة سهلة القراءة.

نُنشئ في هذا المقال برنامجًا يتفاعل مع مجموعة من البطاقات، إذ سنبدأ بإنشائها بحيث تستخدم {}interface للتفاعل مع البطاقات الأخرى، ثم نُحدّثها من أجل استخدام الأنواع المُعمّمة، ثم سنضيف نوعًا ثانيًا من البطاقات باستخدام الأنواع المُعمّمة، ثم سنُحدّثها لتقييد نوعها المُعمّم، بحيث تدعم أنواع البطاقات فقط. نُنشئ أخيرًا دالةً تستخدم البطاقات الخاصة بنا وتدعم الأنواع المُعمّمة.

المتطلبات الأولية

لمتابعة هذا المقال التعليمي، سنحتاج إلى:

• إصدار مُثبّت من جو 1.16 أو أعلى، ويمكنك الاستعانة بمقال تثبيت لغة جو Go وإعداد بيئة برمجة محلية على أبونتو Ubuntu لإعداده.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على نظام ماك macOS.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على ويندوز.
• فهم قوي لأساسيات لغة جو، مثل المتغيرات والدوال وأنواع البيانات والشرائح والحلقات ..إلخ. كل الأساسيات ومقالات أخرى متقدمة في هذه اللغة تجدها هنا.

التجميعات Collections في لغة جو بدون استخدام الأنواع المعممة

يشير مصطلح التجميعة Collection في هذا السياق إلى حاوية بيانات يمكن أن تحتوي على قيم أو عناصر متعددة، وهو مفهوم ذو مستوى أعلى يشمل أنواعًا مختلفة من هياكل البيانات، مثل المصفوفات والقوائم والمجموعات والروابط maps، مما يسمح بتخزين وتنظيم عدة قيم مرتبطة معًا. توفر التجميعات عمليات وتوابع للوصول إلى العناصر التي تحتويها ومعالجتها وتكرارها. نستخدم مصطلح "التجميعة" هنا لوصف الهيكل أو الحاوية المستخدمة لتخزين وإدارة أوراق اللعب في البرنامج.

تتمتع لغة جو بميزة قوية تتمثّل في قدرتها على تمثيل العديد من الأنواع بطريقة مرنة باستخدام الواجهات interfaces. يمكن للكثير من الشيفرات المكتوبة بلغة جو أن تعمل جيدًا باستخدام دوال الواجهات المتاحة، وهذا هو أحد الأسباب التي جعلت اللغة موجودةً لفترة طويلة دون دعم الأنواع المُعمّمة.

نُنشئ في هذا المقال برنامجًا يحاكي عملية الحصول على بطاقة لعب عشوائية PlayingCard من مجموعة بطاقات Deck. سنستخدم في هذا القسم {}interface للسماح للدستة Deck بالتفاعل مع أي نوع من البطاقات. نُعدّل لاحقًا البرنامج لاستخدام الأنواع المُعمّمة لنتمكن من فهم الفروق بينهما والتعرف على الحالات التي تكون فيها الأنواع المُعمّمة خيارًا أفضل من غيرها.

يمكن تصنيف أنظمة النوع type systems في لغات البرمجة عمومًا إلى فئتين مختلفتين: النوع typing والتحقق من النوع type checking. تُشير الفئة الأولى إلى كيفية التعامل مع الأنواع في اللغة وكيفية تعريف وتمثيل أنواع البيانات المختلفة. هناك نوعان رئيسيان من أنظمة "النوع": النوع القوي strong والنوع الضعيف weak وكذلك الثابت static والديناميكي dynamic. تُطبّق قواعد صارمة في النوع القوي تضمن توافق الأنواع وعدم وجود تضارب بينها. على سبيل المثال، لا يمكن تخزين قيمة من نوع بيانات ما في متغير من نوع بيانات آخر (لا يمكن تخزين قيمة int في متغير string) إلا إذا كانت هناك توافقية بينهما. أما في النوع الضعيف، فقد تسمح اللغة بتحويل تلقائي للأنواع من خلال عمليات تحويل ضمنية.

أما بالنسبة "للتحقق من النوع"، فهذا يشير إلى كيفية التحقق من صحة استخدام الأنواع في البرنامج. هناك نوعان رئيسيان من أنظمة التحقق من النوع: التحقق الثابت statically-checked والتحقق الديناميكي dynamically-checked. تُفحص الأنواع في التحقق الثابت خلال عملية التصريف ويُفحص توافقها وصحتها والتأكد من عدم وجود أخطاء في النوع قبل تنفيذ البرنامج. أما في التحقق الدينامكي، فإن الفحص يجري أثناء تنفيذ البرنامج نفسه، ويمكن للأنواع أن تتغير وتحول ديناميكيًا خلال تنفيذ البرنامج.

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

لبدء إنشاء البرنامج باستخدام {}interface لتمثيل البطاقات، نحتاج إلى مجلد للاحتفاظ بمجلد البرنامج فيه، وليكن باسم "projects". أنشئ المجلد وانتقل إليه:

$ mkdir projects
$ cd projects

نُنشئ الآن مجلدًا للمشروع، وليكن باسم "generics" ثم ننتقل إليه:

$ mkdir generics
$ cd generics

من داخل هذا المجلد، نفتح الملف "main.go" باستخدام محرر نانو nano أو أي محرر آخر تريده:

$ nano main.go

نضع مقتطف الشيفرة التالي داخل هذا الملف، إذ نُصرّح عن الحزمة package لإخبار المُصرّف أن يحوّل البرنامج إلى ملف ثنائي لتتمكّن من تشغيله مباشرةً. نستورد أيضًا الحزم اللازمة عن طريق تعليمة import:

package main

import (
    "fmt"
    "math/rand"
    "os"
    "time"
)

نُعرّف النوع PlayingCard والدوال والتوابع المرتبطة به:

...

type PlayingCard struct {
    Suit string
    Rank string
}

func NewPlayingCard(suit string, card string) *PlayingCard {
    return &PlayingCard{Suit: suit, Rank: card}
}

func (pc *PlayingCard) String() string {
    return fmt.Sprintf("%s of %s", pc.Rank, pc.Suit)
}

عرّفنا بنية بيانات تُسمى PlayingCard مع الخصائص نوع البطاقة Suit وترتيبها Rank لتمثيل مجموعة ورق اللعب Deck المكونة من 52 بطاقة. يكون Suit أحد القيم التالية: Diamonds أو Hearts أو Clubs أو Spades. أما Rank يكون أما A أو 2 أو 3، وهكذا حتى K.

عرّفنا أيضًا دالة NewPlayingCard لتكون باني constructor لبنية البيانات PlayingCard، وتابع String ليُرجع ترتيب ونوع البطاقة باستخدام fmt.Sprintf.

ننشئ الآن النوع Deck بالدوال AddCard و RandomCard، إضافةً إلى الدالة NewPlayingCardDeck لإنشاء Deck* مملوء بجميع بطاقات اللعبة التي عددها 52.

...

type Deck struct {
    cards []interface{}
}

func NewPlayingCardDeck() *Deck {
    suits := []string{"Diamonds", "Hearts", "Clubs", "Spades"}
    ranks := []string{"A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"}

    deck := &Deck{}
    for _, suit := range suits {
        for _, rank := range ranks {
            deck.AddCard(NewPlayingCard(suit, rank))
        }
    }
    return deck
}

func (d *Deck) AddCard(card interface{}) {
    d.cards = append(d.cards, card)
}

func (d *Deck) RandomCard() interface{} {
    r := rand.New(rand.NewSource(time.Now().UnixNano()))

    cardIdx := r.Intn(len(d.cards))
    return d.cards[cardIdx]
}

في البنية Deck المُعرّفة أعلاه، أنشأنا حقلًا يُسمّى cards لاحتواء مجموعة ورق اللعب. نظرًا لأننا نرغب في أن تكون مجموعة البطاقات قادرة على استيعاب أنواع متعددة مختلفة من البطاقات، فلا يمكن تعريفها فقط على أنها PlayingCard*. لذا عرّفناها على أنها {}interface[] حتى نتمكن من استيعاب أي نوع من البطاقات التي قد نُنشئها مستقبلًا. بالإضافة إلى الحقل {}interface[] في Deck، أنشأنا التابع AddCard الذي يقبل قيمة من نفس نوع interface{} لإضافة بطاقة إلى حقل البطاقات في Deck.

أنشأنا أيضًا التابع RandomCard الذي يُرجع بطاقةً عشوائية من cards في Deck. يستخدم هذا التابع حزمة math/rand لإنشاء رقم عشوائي بين 0 وعدد البطاقات في المجموعة. يُنشئ سطر rand.New مولد رقم عشوائي جديد باستخدام الوقت الحالي مثل مصدر للعشوائية، وإلا فإن الرقم العشوائي يمكن أن يكون نفسه في كل مرة. يستخدم السطر ((r.Intn(len(d.cards مولد الأرقام العشوائية لإنشاء قيمة صحيحة بين 0 والعدد المُقدم. نظرًا لأن التابع Intn لا يشمل قيمة المعامل ضمن نطاق الأرقام الممكنة، فلا حاجة لطرح 1 من الطول لمعالجة فكرة البدء من 0 (إذا كان لدينا مجموعة ورق لعب تحتوي على 10 عناصر، فالأرقام الممكنة ستكون من 0 إلى 9). لدينا أيضًا RandomCard تُرجع قيمة البطاقة في الفهرس المحدد بالرقم العشوائي.

تحذير: كن حذرًا في اختيار مولد الأرقام العشوائية الذي تستخدمه في برامجك. ليست حزمة math/rand آمنة من الناحية التشفيرية ولا ينبغي استخدامها في البرامج التي تتعلق بالأمان. توفر حزمة crypto/rand مولد أرقام عشوائية يمكن استخدامه لهذه الأغراض.

بالنسبة للدالة NewPlayingCardDeck فهي تُرجع القيمة Deck* مملوءة بجميع البطاقات الموجودة في دستة بطاقات اللعب. نستخدم شريحتين، واحدة تحتوي على جميع الأشكال المتاحة وأخرى تحتوي على جميع الرتب المتاحة، ثم نكرر فوق كل قيمة لإنشاء PlayingCard* جديدة لكل تركيبة قبل إضافتها إلى المجموعة باستخدام AddCard. تُرجع القيمة بمجرد إنشاء بطاقات مجموعة ورق اللعب.

بعد إعداد Deck و PlayingCard، يمكننا إنشاء الدالة main لاستخدامها لسحب البطاقات:

...

func main() {
    deck := NewPlayingCardDeck()

    fmt.Printf("--- drawing playing card ---\n")
    card := deck.RandomCard()
    fmt.Printf("drew card: %s\n", card)

    playingCard, ok := card.(*PlayingCard)
    if !ok {
        fmt.Printf("card received wasn't a playing card!")
        os.Exit(1)
    }
    fmt.Printf("card suit: %s\n", playingCard.Suit)
    fmt.Printf("card rank: %s\n", playingCard.Rank)
}

أنشأنا بدايةً مجموعةً جديدة من البطاقات باستخدام الدالة NewPlayingCardDeck ووضعناها في المتغير deck، ثم استخدمنا fmt.Printf لطباعة جملة تدل على أننا نسحب بطاقة. نستخدم التابع RandomCard من deck للحصول على بطاقة عشوائية من المجموعة. نستخدم بعد ذلك fmt.Printf مرةً أخرى لطباعة البطاقة التي سحبناها من المجموعة.

نظرًا لأن نوع المتغير card هو {}interface، سنحتاج إلى استخدام توكيد النوع type assertion للحصول على مرجع إلى البطاقة بنوعها الأصلي PlayingCard*. إذا كان النوع في المتغير card ليس نوع PlayingCard*، الذي يجب أن يكون عليه وفقًا لطريقة كتابة البرنامج الحالية، ستكون قيمة ok تساوي false وسيطبع البرنامج رسالة خطأ باستخدام fmt.Printf ويخرج مع شيفرة خطأ 1 باستخدام os.Exit. إذا كان النوع PlayingCard* سيطبع البرنامج قيمتي Suit و Rank من playingCard باستخدام fmt.Printf.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

يُفترض أن نرى في الخرج بطاقة مُختارة عشوائيًا من المجموعة، إضافةً إلى نوع البطاقة وترتيبها:

--- drawing playing card ---
drew card: Q of Diamonds
card suit: Diamonds
card rank: Q

قد تكون النتيجة المطبوعة مختلفةً عن النتيجة المعروضة أعلاه، لأن البطاقة مسحوبة عشوائيًا من المجموعة، لكن يجب أن تكون مشابهة. يُطبع السطر الأول قبل سحب البطاقة العشوائية من المجموعة، ثم يُطبع السطر الثاني بمجرد سحب البطاقة. يمكن رؤية خرج البطاقة باستخدام القيمة المُرجعة من التابع String من PlayingCard. يمكننا أخيرًا رؤية سطري النوع والرتبة المطبوعة بعد تحويل قيمة {}interface المستلمة إلى قيمة PlayingCard* مع الوصول إلى حقول Suit و Rank.

أنشأنا في هذا القسم مجموعة Deck تستخدم قيم {}interface لتخزين والتفاعل مع أي قيمة، وأيضًا نوع PlayingCard ليكون بمثابة البطاقات داخل هذه الدستة Deck، ثم استخدمنا Deck و PlayingCard لاختيار بطاقة عشوائية من المجموعة وطباعة معلومات حول تلك البطاقة.

للوصول إلى معلومات محددة تتعلق بقيمة PlayingCard* التي سُحبت، كُنّا بحاجة لعمل إضافي يتجلى بتحويل النوع {}interface إلى النوع PlayingCard* مع الوصول إلى حقول Suit و Rank. ستعمل الأمور في المجموعة Deck جيدًا بهذه الطريقة، ولكن قد ينتج أخطاء إذا أُضيفت قيمة أخرى غير PlayingCard* إلى المجموعة Deck.

سنُعدّل في القسم التالي المجموعة Deck، بحيث يمكننا الاستفادة من خصائص الأنواع القوية والتحقق الثابت للأنواع في لغة جو، مع الاحتفاظ بالمرونة في قبول قيم {}interface، وذلك من خلال استخدام الأنواع المعممة.

التجميعات في لغة جو مع استخدام الأنواع المعممة

أنشأنا في القسم السابق تجميعةً باستخدام شريحة من أنواع {}interface، ولكن كان علينا إتمام عمل إضافي لاستخدام تلك القيم يتجلى بتحويل القيم من نوع {}interface إلى النوع الفعلي لتلك القيم. يمكننا باستخدام الأنواع المعممة إنشاء معامل واحد أو أكثر للأنواع، والتي تعمل تقريبًا مثل معاملات الدالة، ولكن يمكن أن تحتوي على أنواع بدلًا من بيانات. توفر الأنواع المعممة بهذا الأسلوب طريقةً لاستبدال نوع مختلف من معاملات الأنواع في كل مرة يجري فيها استخدام النوع المعمم. هنا يأتي اسم الأنواع المعممة؛ فبما أن النوع المعمم يمكن استخدامه مع أنواع متعددة، وليس فقط نوع محدد مثل io.Reader أو {}interface، يكون عامًا بما يكفي ليناسب عدة حالات استخدام.

نُعدّل في هذا القسم مجموعة ورق اللعب Deck لتكون من نوع معمم يمكنه استخدام أي نوع محدد للبطاقة عند إنشاء نسخة من Deck بدلًا من استخدام {}interface.

نفتح ملف "main.go" ونحذف استيراد حزمة os:

package main

import (
    "fmt"
    "math/rand"
    // "os" حذف استيراد 
    "time"
)

لن نحتاج بعد الآن إلى استخدام دالة os.Exit، لذا فمن الآمن حذف هذا الاستيراد. نُعدّل البنية Deck الآن لتكون نوعًا معممًا:

...

type Deck[C any] struct {
    cards []C
}

يقدم هذا التحديث الصيغة الجديدة لتعريف البنية Deck، بحيث نجعلها تحقق مفهوم النوع المُعمم، وذلك من خلال استخدام مفهوم "الموضع المؤقت Placeholder" أو "معاملات النوع Type parameters". يمكننا التفكير في هذه المعاملات بطريقة مشابهة للمعاملات التي نُضمّنُها في دالة؛ فعند استدعاء دالة، تُقدم قيمًا لكل معامل في الدالة. وهنا أيضًا، عند إنشاء قيمة من النوع المعمم، نُقدّم أنواعًا لمعاملات الأنواع.

نلاحظ بعد اسم البنية Deck أننا أضفنا عبارة داخل قوسين مربعين ([])، إذ تسمح هذه الأقواس المعقوفة لنا بتحديد معامل أو أكثر من هذه المعاملات للبنية.

نحتاج في حالتنا للنوع Deck إلى معامل نوع واحد فقط، يُطلق عليه اسم C، لتمثيل نوع البطاقات في المجموعة deck. من خلال كتابتنا C any نكون قد صرّحنا عن معامل نوع باسم C يمكننا استخدامه في البنية struct ليُمثّل أي نوع (any). ينوب any عن الأنواع المختلفة، أي يُعرف نوعه في الزمن الحقيقي، أي وقت تمرير قيمته، فإذا كانت القيمة المُمررة سلسلة يكون سلسلة، وإذا كانت عددًا صحيحًا يكون صحيحًا.

يُعد النوع any في حقيقة الأمر اسمًا بديلًا للنوع {}interface، وهذا ما يجعل الأنواع المعممة أكثر سهولة للقراءة، فنحن بغنى عن كتابة {}C interface ونكتب C any فقط. يحتاج deck الخاص بنا إلى نوع معمم واحد فقط لتمثيل البطاقات، ولكن إذا كنا نحتاج إلى أنواع معممة إضافية، فيمكن إضافتها من خلال فصلها بفواصل، مثل F any, C any. يمكن أن يكون اسم المعامل المُستخدم لمعاملات النوع أي شيء نرغب فيه إذا لم يكن محجوزًا، ولكنها عادةً قصيرة وتبدأ بحرف كبير.

عدّلنا أيضًا نوع الشريحة cards في البنية Deck ليكون من النوع C. عند استخدام مفهوم الأنواع المعممة، يمكننا استخدام معاملات النوع لتنوب عن أي نوع، أي يمكننا وضعها في نفس الأماكن التي نضع فيها أنواع البيانات عادةً. في حالتنا، نريد أن يمثل المعامل C كل بطاقة في الشريحة، لذا نضع اسم الشريحة ثم [] ثم المعامل C الذي سينوب عن النوع.

نُعدّل الآن التابع AddCard لاستخدام النوع المعمّم الذي عرّفناه، لكن سنتخطى تعديل دالة NewPlayingCardDeck حاليًا:

...

func (d *Deck[C]) AddCard(card C) {
    d.cards = append(d.cards, card)
}

تضمّن التحديث الخاص بالتابع AddCard في Deck، إضافة المعامل المُعمّم [C] إلى المستقبل الخاص بالتابع. يُخبر هذا لغة جو باسم المعامل المُعمّم الذي سنستخدمه في أماكن أخرى في تصريح التابع، ويتيح لنا ذلك معرفة النوع المُمرّر مثل قيمة إلى معامل النوع C عند استخدام التابع. يتبع هذا النوع من الكتابة بأقواس معقوفة نفس طريقة التصريح عن بنية struct، إذ يُعرّف معامل النوع داخل الأقواس المعقوفة بعد اسم الدالة والمستقبل. لا نحتاج في حالتنا إلى تحديد أي قيود لأنها مُحددة فعلًا في تصريح Deck. عدّلنا أيضًا معامل الدالة card لاستخدام معامل النوع C بدلًا من النوع الأصلي {}interface، وهذا يتيح للدالة استخدام النوع C الذي سيُعرف ما هو لاحقًا.

بعد تعديل التابع AddCard، نُعدّل التابع RandomCard لاستخدام النوع المعمم C أيضًا:

...

func (d *Deck[C]) RandomCard() C {
    r := rand.New(rand.NewSource(time.Now().UnixNano()))

    cardIdx := r.Intn(len(d.cards))
    return d.cards[cardIdx]
}

بدلًا من استخدام نوع معمّم C مثل معامل دالة، عدّلنا التابع ()RandomCard ليعيد قيمةً من النوع المُعمّم C بدلًا من معامل الدالة {}interface. هذا يعني أنه عند استدعاء هذا التابع، سنحصل على قيمة من النوع C المحدد، بدلًا من الحاجة إلى تحويل القيمة إلى نوع محدد بواسطة "تأكيدات النوع type assertion". عدّلنا أيضًا المستقبل الخاص بالدالة ليتضمن [C]، وهو ما يخبر لغة جو بأن الدالة هي جزء من Deck التي تستخدم النوع المعمم C مثل معامل. لا نحتاج إلى أي تحديثات أخرى في الدالة. حقل cards في Deck مُعدّل فعلًا في تصريح البنية struct ليكون من النوع C[]، مما يعني أنه عندما يعيد التابع قيمة من cards، فإنه يعيد قيمةً من النوع C المحدد، وبالتالي لا حاجة لتحويل النوع بعد ذلك.

بعد تعديلنا للنوع Deck لاستخدام الأنواع المعممة، نعود للدالة NewPlayingCardDeck لجعلها تستخدم النوع المعمم Deck مع الأنواع PlayingCard*:

...

func NewPlayingCardDeck() *Deck[*PlayingCard] {
    suits := []string{"Diamonds", "Hearts", "Clubs", "Spades"}
    ranks := []string{"A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"}

    deck := &Deck[*PlayingCard]{}
    for _, suit := range suits {
        for _, rank := range ranks {
            deck.AddCard(NewPlayingCard(suit, rank))
        }
    }
    return deck
}

...

تبقى معظم الشيفرة في NewPlayingCardDeck كما هي، باستثناء بعض التغييرات البسيطة، ولكن الآن نستخدم إصدارًا مُعمّمًا من Deck، ويجب علينا تحديد النوع الذي نرغب في استخدامه مع C عند استخدام Deck. نفعل ذلك عن طريق الإشارة إلى نوع Deck بالطريقة المعتادة، سواء كان Deck نفسه أو مرجعًا مثل Deck*، ثم تقديم النوع الذي يجب استبدال C به باستخدام نفس الأقواس المعقوفة التي استخدمناها عند التصريح عن معاملات النوع في البداية. بمعنى آخر، عندما نُعرّف متغير من نوع Deck المعمّم، يجب علينا تحديد النوع الفعلي للمعامل C؛ فإذا كانت Deck من النوع Deck*، يجب أن نُوفّر النوع الفعلي الذي يجب استبدال C به في الأقواس المعقوفة مثل [PlayingCard*]. هكذا نحصل على نسخة محددة من Deck لنوع البطاقات التي ترغب في استخدامها، والتي في هذه الحالة هي PlayingCard*.

يمكن تشبيه هذه العملية لإرسال قيمة لمعامل دالة عند استدعاء الدالة؛ فعند استخدامنا لنوع Deck المعمّم، فإننا نمرر النوع الذي نرغب في استخدامه مثل معامل لهذا النوع.

بالنسبة لنوع القيمة المُعادة في NewPlayingCardDeck، نستمر في استخدام Deck* كما فعلت من قبل، لكن هذه المرة، يجب أن تتضمن الأقواس المعقوفة و PlayingCard* أيضًا؛ فمن خلال تقديم [PlayingCard*] لمعامل النوع، فأنت تقول أنك ترغب في استخدام النوع PlayingCard* في تصريح Deck والتوابع الخاصة به ليحل محل قيمة C، وهذا يعني أن نوع حقل cards في Deck يتغير فعليًا من C[] إلى PlayingCard*[].

بمعنى آخر، عندما ننشئ نسخةً جديدةً من Deck باستخدام NewPlayingCardDeck، فإننا نُنشئ Deck يمكنه تخزين أي نوع محدد من PlayingCard*. هذا يتيح لنا استخدام مجموعة متنوعة من أنواع البطاقات في Deck بدلًا من الاعتماد على {}interface. بالتالي يمكننا الآن التعامل مباشرةً مع البطاقات بنوعها الفعلي بدلًا من الحاجة إلى استبدال الأنواع والتحويلات التي كنا نستخدمها مع {}interface في الإصدار السابق من Deck.

بالمثل، عند إنشاء نسخة جديدة من Deck، يجب علينا أيضًا توفير النوع الذي يحل محل C. نستخدم عادةً {}Deck& لإنشاء مرجع جديد إلى Deck، ولكن بدلًا من ذلك يجب علينا تضمين النوع داخل الأقواس المعقوفة للحصول على {}[PlayingCard*]&.

الآن بعد أن عدّلنا الأنواع الخاصة بنا لاستخدام الأنواع المُعمّمة، نُعدّل الدالة main للاستفادة منها:

...

func main() {
    deck := NewPlayingCardDeck()

    fmt.Printf("--- drawing playing card ---\n")
    playingCard := deck.RandomCard()
    fmt.Printf("drew card: %s\n", playingCard)
    // Code removed
    fmt.Printf("card suit: %s\n", playingCard.Suit)
    fmt.Printf("card rank: %s\n", playingCard.Rank)
}

أزلنا هذه المرة بعض التعليمات، لأنه لم تعد هناك حاجة لتأكيد قيمة {}interface على أنها PlayingCard*. عندما عدّلنا التابع RandomCard في Deck لإعادة النوع C و NewPlayingCardDeck لإعادة [Deck[*PlayingCard*، نكون قد عدّلنا التابع RandomCard بجعله يعيد PlayingCard* بدلًا من {}interface. هذا يعني أن نوع playingCard هو PlayingCard* أيضًا بدلًا من interface{} ويمكننا الوصول إلى حقول Suit و Rank مباشرةً.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سنشاهد خرجًا مشابهًا لما سبق، ولكن البطاقة المسحوبة قد تكون مختلفة:

--- drawing playing card ---
drew card: 8 of Hearts
card suit: Hearts
card rank: 8

على الرغم من أن الخرج هو نفسه مثل الإصدار السابق من البرنامج عندما استخدمنا {}interface، إلا أن الشيفرة أنظف وتتجنب الأخطاء المحتملة. لم يعد هناك حاجةٌ لتأكيد النوع PlayingCard*، مما يُجنّبنا التعامل مع الأخطاء الإضافية، كما أنّه من خلال تحديد أن نسخة Deck يمكن أن تحتوي فقط على PlayingCard*، لن يكون هناك أي احتمال لوجود قيمة أخرى غير PlayingCard* تُضاف إلى مجموعة البطاقات.

عدّلنا في هذا القسم البنية Deck لتكون نوعًا مُعمّمًا، مما يوفر مزيدًا من السيطرة على أنواع البطاقات التي يمكن أن تحتويها كل نسخة من مجموعة أوراق اللعب. عدّلنا أيضًا التابعين AddCard و RandomCard إما لقبول وسيط مُعمم أو لإرجاع قيمة مُعممة. عدّلنا أيضًا NewPlayingCardDeck لإرجاع Deck* يحتوي على بطاقات PlayingCard*. أخيرًا أزلنا التعامل مع الأخطاء في الدالة main لأنه لم يعد هناك حاجة لذلك.

الآن بعد تعديل Deck ليكون مُعممًا، يمكننا استخدامه لاحتواء أي نوع من البطاقات التي نرغب. سنستفيد في القسم التالي من هذه المرونة من خلال إضافة نوع جديد من البطاقات إلى البرنامج.

استخدام أنواع مختلفة مع الأنواع المعممة

يمكننا -بإنشاء نوع مُعمّم مثل النوع Deck- استخدامه مع أي نوع آخر؛ فعندما نُنشئ نسخةً من Deck، ونرغب باستخدامها مع أنواع PlayingCard*، فإن الشيء الوحيد الذي نحتاجه هو تحديد هذا النوع عند إنشاء القيمة، وإذا أردنا استخدام نوع آخر، نُبدّل نوع PlayingCard* بالنوع الجديد الذي نرغب باستخدامه.

نُنشئ في هذا القسم بنية بيانات جديدة تُسمى TradingCard لتمثيل نوع مختلف من البطاقات، ثم نُعدّل البرنامج لإنشاء Deck يحتوي على عدة TradingCard*.

لإنشاء النوع TradingCard، نفتح ملف "main.go" مرةً أخرى ونضيف التعريف التالي:

...

import (
    ...
)

type TradingCard struct {
    CollectableName string
}

func NewTradingCard(collectableName string) *TradingCard {
    return &TradingCard{CollectableName: collectableName}
}

func (tc *TradingCard) String() string {
    return tc.CollectableName
}

النوع TradingCard مشابه لنوع PlayingCard، ولكن بدلًا من وجود حقول Suit و Rank، يحتوي على حقل CollectableName لتتبع اسم بطاقة التداول، كما يتضمن دالة الباني NewTradingCard والتابع String، أي بطريقة مشابهة للنوع PlayingCard.

نُنشئ الآن الدالة البانية NewTradingCardDeck لإنشاء Deck مُعبأة بقيم TradingCards*:

...

func NewPlayingCardDeck() *Deck[*PlayingCard] {
    ...
}

func NewTradingCardDeck() *Deck[*TradingCard] {
    collectables := []string{"Sammy", "Droplets", "Spaces", "App Platform"}

    deck := &Deck[*TradingCard]{}
    for _, collectable := range collectables {
        deck.AddCard(NewTradingCard(collectable))
    }
    return deck
}

عند إنشاء أو إرجاع Deck* في هذه الحالة، فإننا نُبدّل قيم PlayingCard* بقيم TradingCard*، وهذا هو الأمر الوحيد الذي نحتاج إلى تغييره في Deck. هناك مجموعة من البطاقات الخاصة، والتي يمكننا المرور عليها لإضافة كل TradingCard* إلى Deck. يعمل التابع AddCard في Deck بنفس الطريقة كما في السابق، لكن هذه المرة يقبل قيمة TradingCard* من NewTradingCard. إذا حاولنا تمرير قيمة من NewPlayingCard، سيُعطي المُصرّف خطأ لأنه يتوقع TradingCard* وليس PlayingCard*.

نُعدّل الدالة main لإنشاء Deck جديدة من أجل عدة TradingCard*، وسحب بطاقة عشوائية باستخدام RandomCard، وطباعة معلومات البطاقة:

...

func main() {
    playingDeck := NewPlayingCardDeck()
    tradingDeck := NewTradingCardDeck()

    fmt.Printf("--- drawing playing card ---\n")
    playingCard := playingDeck.RandomCard()
    ...
    fmt.Printf("card rank: %s\n", playingCard.Rank)

    fmt.Printf("--- drawing trading card ---\n")
    tradingCard := tradingDeck.RandomCard()
    fmt.Printf("drew card: %s\n", tradingCard)
    fmt.Printf("card collectable name: %s\n", tradingCard.CollectableName)
}

أنشأنا مجموعة جديدة من بطاقات التداول باستخدام NewTradingCardDeck وخزّناها في tradingDeck. نظرًا لأننا لا نزال نستخدم نفس النوع Deck كما كان من قبل، يمكننا استخدام RandomCard للحصول على بطاقة تداول عشوائية من Deck وطباعة البطاقة. يمكننا أيضًا الإشارة إلى وطباعة حقل CollectableName مباشرةً من tradingCard لأن Deck المُعمّم الذي نستخدمه قد عرّف C على أنه TradingCard*.

يُظهر هذا التحديث أيضًا قيمة استخدام الأنواع المُعمّمة. لدعم نوع بطاقة جديد تمامًا، لم نحتاج إلى تغيير Deck إطلاقًا، فمن خلال معاملات النوع في Deck تمكّننا من تحديد نوع البطاقة الذي نريده، وبدءًا من هذه النقطة فصاعدًا، يُستخدم النوع TradingCard* بدلًا من النوع PlayingCard* في أية تفاعلات مع قيم Deck.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

ليكون الخرج على النحو التالي:

--- drawing playing card ---
drew card: Q of Diamonds
card suit: Diamonds
card rank: Q
--- drawing trading card ---
drew card: App Platform
card collectable name: App Platform

يجب أن نرى نتيجةً مشابهة للنتيجة الموضحة أعلاه (مع بطاقات مختلفة بسبب العشوائية) بعد انتهاء تشغيل البرنامج. تظهر بطاقتين مسحوبتين: البطاقة الأصلية للّعب وبطاقة التداول الجديدة المُضافة.

أضفنا في هذا القسم النوع TradingCard الجديد لتمثيل نوع بطاقة مختلف عن نوع البطاقة الأصلية PlayingCard. بمجرد إضافة نوع البطاقة TradingCard،أنشأنا الدالة NewTradingCardDeck لإنشاء وملء مجموعة ورق اللعب ببطاقات التداول. أخيرًا عدّلنا الدالة main لاستخدام مجموعة ورق التداول الجديدة وطباعة معلومات مُتعلقة بالبطاقة العشوائية المستخرجة.

بصرف النظر عن إنشاء دالة جديدة NewTradingCardDeck لملء الدستة ببطاقات مختلفة، لم نحتاج إلى إجراء أي تحديثات أخرى على مجموعة ورق اللعب لدعم نوع بطاقة جديد تمامًا. هذه هي قوة الأنواع المُعمّمة؛ إذ يمكننا كتابة الشيفرة مرةً واحدةً فقط واستخدامها متى أردنا لأنواع مختلفة من البيانات المماثلة أيضًا. هناك مشكلة واحدة في Deck الحالي، وهي أنه يمكن استخدامه لأي نوع، بسبب التصريح C any الذي لدينا. قد يكون هذا هو ما نريده حتى نتمكن من إنشاء مجموعة ورق لعب للقيم int بكتابة {}[Deck[int&، ولكن إذا كنا نرغب في أن يحتوي Deck فقط على بطاقات، سنحتاج إلى طريقة لتقييد أنواع البيانات المسموح بها مع C.

القيود على الأنواع المعممة

غالبًا لا نرغب أو نحتاج إلى أي قيود على الأنواع المستخدمة في الأنواع المُعمّمة لأننا قد لا نهتم بنوع البيانات المُستخدمة، لكن قد نحتاج في أحيان أخرى إلى القدرة على تقييد الأنواع المستخدمة بواسطة الأنواع المُعمّمة. على سبيل المثال، إذا كُنّا نُنشئ نوعًا مُعمّمًا Sorter، قد نرغب في تقييد أنواعه المُعمّمة لتلك التي تحتوي على تابع Compare (أي تقييد الأنواع المستخدمة معه، بحيث تكون فقط الأنواع القابلة للمقارنة)، حتى يتمكن Sorter من مقارنة العناصر التي يحتوي عليها. بدون هذا القيد، فقد لا تحتوي القيم على التابع Compare، ولن يعرف Sorter كيفية مقارنتها.

نُنشئ في هذا القسم واجهةً جديدة تسمى Card، ثم نُعدّل Deck للسماح فقط بإضافة أنواع Card.

لتطبيق التحديثات، افتح ملف "main.go" وضِف الواجهة Card:

...

import (
...
)

type Card interface {
    fmt.Stringer

    Name() string
}

واجهة Card مُعرّفة بنفس طريقة تعريف أي واجهة أخرى في لغة جو؛ وليس هناك متطلبات خاصة لاستخدامها مع الأنواع المُعمّمة. نحن نقول في واجهة Card هذه، أنه لكي نعد شيئًا ما بطاقة Card، يجب أن يُحقق النوع fmt.Stringer (يجب أن يحتوي على تابع String الذي تحتويه البطاقات فعلًا)، ويجب أيضًا أن يحتوي على تابع Name الذي يعيد قيمة من نوع string.

نُعدّل الآن أنواع TradingCard و PlayingCard لإضافة التابع Name الجديد، إضافةً إلى التابع String الموجود فعلًا، لكي نستوفي شروط تحقيق الواجهة Card:

...

...

type TradingCard struct {
    ...
}

...

func (tc *TradingCard) Name() string {
    return tc.String()
}

...

type PlayingCard struct {
    ...
}

...

func (pc *PlayingCard) Name() string {
    return pc.String()
}

يحتوي كُلًا من TradingCard و PlayingCard فعليًا على تابع String الذي يُحقق الواجهة fmt.Stringer. لذا، لتحقيق الواجهة Card، نحتاج فقط إلى إضافة التابع الجديد Name. بما أن fmt.Stringer يمكنها إرجاع أسماء البطاقات، يمكننا ببساطة إرجاع نتيجة التابع String في التابع Name.

نُعدّل الآن Deck، بحيث يُسمح فقط باستخدام أنواع Card مع C:

...

type Deck[C Card] struct {
    cards []C
}

كان لدينا C any قبل هذا التحديث مثل قيد نوع type constraint والمعروف أيضًا بتقييد النوع type restriction، وهو ليس قيدًا صارمًا. بما أن any هو اسم {}interface البديل (له نفس المعنى)، فقد سمح باستخدام أي نوع في جو بمثابة قيمة للمعامل C. الآن بعدما عوّضنا any بالواجهة Card الجديدة، سيتحقق المُصرّف في جو أن أي نوع مستخدم مع C يُحقق واجهة Card عند تصريف البرنامج.

يمكننا الآن بعد وضع هذا القيد، استخدام أي توابع تقدمها الواجهة Card داخل توابع النوع Deck. إذا أردنا من RandomCard طباعة اسم البطاقة المسحوبة، ستتمكن من الوصول إلى التابع Name لأنها جزء من الواجهة Card. سنرى ذلك في الجزء التالي.

هذه التحديثات القليلة هي التحديثات الوحيدة التي نحتاج إليها لتقييد النوع Deck، بحيث يستخدم فقط لقيم Card.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيكون الخرج:

--- drawing playing card ---
drew card: 5 of Clubs
card suit: Clubs
card rank: 5
--- drawing trading card ---
drew card: Droplets
card collectable name: Droplets

نلاحظ أن الناتج لم يتغير من حيث الشكل العام، فنحن لم نُعدّل بالوظيفة الرئيسية للبرنامج؛ وضعنا فقط قيودًا على الأنواع، إذ أضفنا في هذا الجزء الواجهة Card الجديدة وعدّلنا كلًا من TradingCard و PlayingCard لتحقيق هذه الواجهة. عدّلنا أيضًا Deck بهدف تقييد الأنواع التي يتعامل معها، بحيث يكون النوع المستخدم يُحقق الواجهة Card.

كل ما فعلناه إلى الآن هو إنشاء نوع بيانات جديد من خلال مفهوم البنى struct وجعله مُعمّمًا، لكن لغة جو تسمح أيضًا بإنشاء دوال مُعممة، إضافةً إلى إنشاء أنواع مُعممة.

إنشاء دوال معممة

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

نُنشئ في هذا الجزء دالة مُعممة جديدة باسم printCard، ونستخدم تلك الدالة لطباعة اسم البطاقة المقدمة.

نفتح ملف "main.go" ونجري التحديثات التالية:

...

func printCard[C any](card C) {
    fmt.Println("card name:", card.Name())
}

func main() {
    ...
    fmt.Printf("card collectable name: %s\n", tradingCard.CollectableName)

    fmt.Printf("--- printing cards ---\n")
    printCard[*PlayingCard](playingCard)
    printCard(tradingCard)
}

نلاحظ أن التصريح عن الدالة printCard مألوف من ناحية تعريف معاملات النوع (أقواس معقوفة تحتوي على معاملات النوع المعممة. تحدد هذه المعاملات النوع الذي سيجري استخدامه في الدالة)، تليها المعاملات العادية للدالة داخل قوسين، ثم في دالة main، تستخدم الدالة printCard لطباعة كل من PlayingCard* و TradingCard*.

قد نلاحظ أن أحد استدعاءات printCard يتضمن معامل النوع [PlayingCard*]، بينما الاستدعاء الثاني لا يحتوي على نفس معامل النوع [TradingCard*]. يمكن لمُصرّف لغة جو أن يستدل على معامل النوع المقصود من القيمة التي نمررها إلى المعاملات، لذلك في حالات مثل هذه، تكون معاملات النوع اختيارية. يمكننا أيضًا إزالة معامل النوع [PlayingCard*].

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيظهر هذه المرة خطأ في التصريف:

# وسطاء سطر الأوامر
./main.go:87:33: card.Name undefined (type C has no field or method Name)

عند استخدامنا للشيفرة المذكورة أعلاه وتصريفها تظهر رسالة الخطأ "card.Name undefined"، وتعني أن Name غير معرفة في النوع C. هذا يحدث لأننا استخدمنا any قيدًا للنوع في معامل النوع C في دالة printCard. تعني any أن أي نوع يمكن استخدامه مع C، ولكنه لا يعرف عنه أي شيء محدد مثل وجود التابع Name في النوع.

لحل هذه المشكلة والسماح بالوصول إلى Name، يمكننا استخدام الواجهة Card قيدًا للنوع في C. تحتوي الواجهة Card على التابع Name ونُطبقها في النوعين TradingCard و PlayingCard. وبذلك تضمن لنا لغة جو أن يكون لدى C التابع Name وبالتالي يتيح لنا استخدامها في الدالة printCard دون وجود أخطاء في وقت التصريف.

نُعدّل ملف "main.go" لآخر مرة لاستبدال القيد any بالقيد Card:

...

func printCard[C Card](card C) {
    fmt.Println("card name:", card.Name())
}

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيكون الخرج:

--- drawing playing card ---
drew card: 6 of Hearts
card suit: Hearts
card rank: 6
--- drawing trading card ---
drew card: App Platform
card collectable name: App Platform
--- printing cards ---
card name: 6 of Hearts
card name: App Platform

نلاحظ سحب البطاقتين كما اعتدنا سابقًا، ولكن تطبع الآن الدالة printCard البطاقات وتستخدم التابع Name للحصول على الاسم لتجري طباعته.

أنشأنا في هذا القسم دالةً جديدة مُعممة printCard قادرة على أخذ أي قيمة Card وطباعة الاسم. رأينا أيضًا أن استخدام قيد النوع any بدلًا من Card أو قيمةً أخرى محددة يؤثر على التوابع المتاحة.

الخاتمة

أنشأنا في هذا المقال برنامجًا جديدًا يحتوي على بنية اسمها Deck تُمثّل نوعًا يمكن أن يُعيد بطاقة عشوائية من مجموعة ورق اللعب بصيغة {}interface، وأنشأنا النوع PlayingCard لتمثيل بطاقة اللعب في المجموعة، ثم عدّلنا النوع Deck لدعم مفهوم النوع المُعمّم وتمكنّا من إزالة بعض عمليات التحقق من الأخطاء لأن النوع المُعمّم يضمن عدم ظهور ذلك النوع من الأخطاء. أنشأنا بعد ذلك نوعًا جديدًا يسمى TradingCard لتمثيل نوع مختلف من البطاقات التي يمكن أن تدعمها Deck، وكذلك أنشأنا مجموعة ورق لعب لكل نوع من أنواع البطاقات وأرجعنا بطاقةً عشوائيةً من كل مجموعة. أضفنا أيضًا قيدًا للنوع إلى البنية Deck لضمان أنه يمكن إضافة أنواع تُحقق الواجهة Card فقط إلى مجموعة ورق اللعب. أنشأنا أخيرًا دالة مُعمّمة تسمى printCard يمكنها طباعة اسم أي قيمة من نوع Card باستخدام التابع Name.

يمكن أن يُقلل استخدام الأنواع المُعمّمة في الشيفرة الخاصة بنا إلى حد كبير عدد الأسطر البرمجية اللازمة لدعم أنواع متعددة لنفس الشيفرة. يجب أن نُحقق التوازن بين الأداء وسهولة قراءة الشيفرة عند استخدام الأنواع المُعمّمة؛ إذ يؤثر استخدام الأنواع المُعمّمة على الأداء، لكنه يُسهّل القراءة. من جهة أخرى، استخدام الواجهات بدلًا من الأنواع المُعمّمة أفضل من ناحية الأداء، لكنه أسوأ في القراءة. بالتالي، إذا كان بإمكاننا استخدام الواجهة بدلًا من الأنواع المُعمّمة فمن الأفضل استخدام الواجهة.

ترجمة -وبتصرف- للمقال How To Make HTTP Requests in Go لصاحبه Kristin Davidson.

اقرأ أيضًا

• المقال السابق كيفية إنشاء طلبات HTTP في لغة جو Go.
• مقدمة إلى مفهوم الأنواع المعممة Generic Types في لغة Rust.
• مفهوم البرمجة المعممة Generic Programming

يُعد بروتوكول HTTP الخيار الأفضل غالبًا عندما يحتاج المطورون إلى إنشاء اتصال بين البرامج. تقدم لغة جو (المعروفة بمكتبتها القياسية الشاملة) دعمًا قويًا لبروتوكول HTTP من خلال حزمة net/http الموجودة في المكتبة القياسية. لا تتيح هذه الحزمة إنشاء خوادم HTTP فحسب، بل تتيح أيضًا إجراء طلبات HTTP مثل عميل.

سننشئ في هذه المقالة برنامجًا يتفاعل مع خادم HTTP من خلال إجراء أنواع مختلفة من الطلبات. سنبدأ بطلب GET باستخدام عميل HTTP الافتراضي في لغة جو، ثم سنعمل على تحسين البرنامج ليشمل طلب POST مع متن الطلب. أخيرًا نُخصص طلب POST من خلال دمج ترويسة HTTP وتحقيق آلية المهلة، للتعامل مع الحالات التي تتجاوز فيها مدة الطلب حدًا معينًا.

المتطلبات الأولية

لمتابعة هذا المقال التعليمي، سنحتاج إلى:

• إصدار مُثبّت من جو 1.16 أو أعلى، ويمكنك الاستعانة بمقال تثبيت لغة جو Go وإعداد بيئة برمجة محلية على أبونتو Ubuntu لإعداده.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على نظام ماك macOS.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على ويندوز.
• معرفة بكيفية إنشاء خادم HTTP في لغة جو.
• فهم لتنظيمات جو goroutines والقنوات channels. يمكنك الاطلاع على مقالة كيفية تشغيل عدة دوال على التساير في لغة جو Go.
• الإلمام بكيفية إنشاء طلبات HTTP وإرسالها (موصى به).

تقديم طلب GET

نناقش في هذه الفقرة كيفية تقديم طلب GET باستخدام حزمة net/http مثل عميل، إذ توفّر لنا هذه الحزمةطرقًا وخيارات متنوعة للتفاعل مع موارد HTTP. أحد الخيارات الشائعة هو استخدام عميل "HTTP عام" مع دوال مثل http.Get، التي تسمح بإنشاء طلب GET سريعًا باستخدام عنوان URL ومتن فقط. يمكننا أيضًا إنشاء http.Request للحصول على مزيد من التحكم وتخصيص جوانب معينة من الطلب. سنبدأ في هذا القسم بإنشاء برنامج أولي يستخدم http.Get لتقديم طلب HTTP، ونعدّله لاحقًا لاستخدام http.Request مع عميل HTTP الافتراضي.

استخدام دالة http.Get لتقديم طلب

نستخدم الدالة http.Get في الإصدار الأولي من البرنامج لإرسال طلب إلى خادم HTTP داخل البرنامج، إذ تُعد هذه الدالة مناسبة لأنها تتطلب الحد الأدنى من التهيئة، أي أنها لا تحتاج إلى الكثير من التفاصيل والإعدادات، وهذا ما يجعلها مثالية لتقديم طلب واحد مباشر. بالتالي، يكون استخدام الدالة http.Get هو الأسلوب الأنسب عندما نحتاج إلى تنفيذ طلب سريع لمرة واحدة فقط.

كما هو معتاد، سنحتاج لبدء إنشاء برامجنا إلى إنشاء مجلد للعمل ووضع الملفات فيه، ويمكن وضع المجلد في أي مكان على الحاسب، إذ يكون للعديد من المبرمجين عادةً مجلدٌ يضعون داخله كافة مشاريعهم. سنستخدم في هذا المقال مجلدًا باسم "projects"، لذا فلننشئ هذا المجلد وننتقل إليه:

$ mkdir projects
$ cd projects

ننشئ مجلدًا للمشروع وننتقل إليه. لنسميه مثلًا "httpclient":

$ mkdir httpclient
$ cd httpclient

نستخدم الآن محرر نانو nano أو أي محرر آخر تريده لفتح ملف "main.go":

$ nano main.go

نضع بداخله الشيفرة التالية:

package main

import (
    "errors"
    "fmt"
    "net/http"
    "os"
    "time"
)

const serverPort = 3333 // ضبط منفذ الخادم على 3333

أضفنا في الشيفرة السابقة الحزمة main لضمان إمكانية تصريف البرنامج وتنفيذه. نستورد أيضًا عدة حزم لاستخدامها في البرنامج. نُعّرف ثابت const اسمه serverPort بقيمة 3333، سيجري استخدامه مثل منفذ لخادم HTTP والعميل.

ننشئ دالة main ضمن الملف "main.go" ونبدأ بإعداد خادم HTTP مثل تنظيم goroutine:

func main() {
    // مثل تنظيم جو HTTP نبدأ تشغيل خادم
    go func() {
        // نُنشئ جهاز توجيه جديد
        mux := http.NewServeMux()

        // معالجة مسار الجذر "/" وطباعة معلومات الطلب
        mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            fmt.Printf("Server: %s /\n", r.Method)
        })

        // HTTP  تهيئة خادم
        server := http.Server{
            Addr:    fmt.Sprintf(":%d", serverPort),
            Handler: mux,
        }

        //  بدء تشغيل الخادم، ومعالجة الأخطاء المحتملة
        if err := server.ListenAndServe(); err != nil {
            if !errors.Is(err, http.ErrServerClosed) {
                fmt.Printf("Error running HTTP server: %s\n", err)
            }
        }
    }()

    // الانتظار لمدة قصيرة للسماح للخادم بالبدء
    time.Sleep(100 * time.Millisecond)
}

تعمل الدالة main بمثابة نقطة دخول للبرنامج، ونستخدم الكلمة المفتاحية go للإشارة إلى أن خادم HTTP سيجري تشغيله ضمن تنظيم جو goroutine. نعالج مسار الجذر /، ونطبع معلومات الطلب باستخدام fmt.Printf، ونُهيّئ خادم HTTP بالعنوان والمعالج المحددين.

يبدأ الخادم بالاستماع إلى الطلبات باستخدام الدالة ListenAndServe، ويجري التعامل مع أية أخطاء محتملة؛ فإذا حدث خطأ ولم يكن هذا الخطأ هو http.ErrServerClosed (إغلاق طبيعي تحدثنا عنه في المقال السابق)، ستُطبع رسالة خطأ. نستخدم الدالة time.Sleep للسماح للخادم بوقت كافٍ لبدء التشغيل قبل تقديم الطلبات إليه.

نجري الآن بعض التعديلات الإضافية على الدالة mian من خلال إعداد عنوان URL للطلب، وذلك بدمج اسم المضيف http://localhost مع قيمة serverPort باستخدام fmt.Sprintf. نستخدم بعد ذلك الدالة http.Get لتقديم طلب إلى عنوان URL هذا:

...
    requestURL := fmt.Sprintf("http://localhost:%d", serverPort)
    res, err := http.Get(requestURL)
    if err != nil {
        fmt.Printf("error making http request: %s\n", err)
        os.Exit(1)
    }

    fmt.Printf("client: got response!\n")
    fmt.Printf("client: status code: %d\n", res.StatusCode)
}

يرسل البرنامج طلب HTTP باستخدام عميل HTTP الافتراضي إلى عنوان URL المحدد عند استدعاء http.Get، ويعيد http.Response في حالة نجاح الطلب أو ظهور قيمة خطأ في حالة فشل الطلب. في حال حدوث خطأ، يطبع البرنامج رسالة الخطأ ويخرج من البرنامج باستخدام os.Exit مع شيفرة خطأ 1. إذا نجح الطلب، يطبع البرنامج رسالةً تشير إلى تلقي استجابة، جنبًا إلى جنب مع شيفرة حالة HTTP للاستجابة.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيكون الخرج على النحو التالي:

server: GET /
client: got response!
client: status code: 200

يشير السطر الأول من الخرج إلى أن الخادم تلقى طلب GET من العميل على المسار /. يشير السطران التاليان إلى أن العميل قد تلقى استجابة من الخادم بنجاح وأن شيفرة حالة الاستجابة كان 200.

على الرغم من أن الدالة http.Get ملائمة لإجراء طلبات HTTP سريعة مثل تلك الموضحة في هذا القسم، لكن استخدامhttp.Request يوفر نطاقًا أوسع من الخيارات لتخصيص الطلب.

استخدام دالة http.Request لتقديم طلب

توفّر لنا http.Request مزيدًا من التحكم في الطلب أكثر من مجرد استخدام تابع HTTP (على سبيل المثال، GET و POST) وعنوان URL فقط. على الرغم من أننا لن نستخدم ميزات إضافية في الوقت الحالي، يسمح لنا استخدام http.Request بإضافة تخصيصات في أقسام لاحقة من هذا المقال.

يتضمن التحديث الأولي تعديل معالج خادم HTTP لإرجاع استجابة تتضمّن بيانات جسون JSON وهمية باستخدام fmt.Fprintf. تُنشأ هذه البيانات ضمن خادم HTTP مكتمل باستخدام حزمة encoding/json. لمعرفة المزيد حول العمل مع بيانات جسون في لغة جو، يمكن الرجوع إلى المقال "كيفية استخدام جسون JSON في لغة جو". نحتاج أيضًا إلى استيراد io/ioutil لاستخدامه في تحديث لاحق.

نفتح ملف "main.go" لتضمينhttp.Request كما هو موضح أدناه:

package main

import (
    ...
    "io/ioutil"
    ...
)

...

func main() {
    ...
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Printf("server: %s /\n", r.Method)
        fmt.Fprintf(w, `{"message": "hello!"}`)
    })
    ...

هدفنا هو استبدال استخدام http.Get، من خلال استخدام كل من الدالة http.NewRequest من الحزمة net/http -لإنشاء http.Request جديد، والذي يمثل طلب HTTP يمكن إرساله إلى الخادم - و http.DefaultClient ليكون عميل HTTP افتراضي يوفر لنا استخدام التابع Do لإرسال http.Request إلى الخادم واسترداد http.Response المقابل. يسمح هذا التغيير بمزيد من التحكم في الطلب وإجراء تعديلات عليه قبل الإرسال إلى الخادم:

...
    requestURL := fmt.Sprintf("http://localhost:%d", serverPort)
    req, err := http.NewRequest(http.MethodGet, requestURL, nil)
    if err != nil {
        fmt.Printf("client: could not create request: %s\n", err)
        os.Exit(1)
    }

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Printf("client: error making http request: %s\n", err)
        os.Exit(1)
    }

    fmt.Printf("client: got response!\n")
    fmt.Printf("client: status code: %d\n", res.StatusCode)

    resBody, err := ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Printf("client: could not read response body: %s\n", err)
        os.Exit(1)
    }
    fmt.Printf("client: response body: %s\n", resBody)
}

نبدأ باستخدام الدالة http.NewRequest لإنشاء قيمة http.Request. نحدد تابع HTTP للطلب على أنه GET باستخدام http.MethodGet. نُنشئ أيضًا عنوان URL للطلب من خلال دمج اسم المضيف http://localhost مع قيمة serverPort باستخدام fmt.Sprintf. نفحص أيضًا متن الطلب إذا كان فارغًا (أي قيمة nil) لنتعامل أيضًا مع أي خطأ محتمل قد يحدث أثناء إنشاء الطلب.

بخلاف http.Get الذي يرسل الطلب على الفور، فإنhttp.NewRequest يُجهّز الطلب فقط ولا يرسله مباشرةً، ويتيح لنا ذلك تخصيص الطلب كما نريد قبل إرساله فعليًا.

بمجرد إعداد http.Request، نستخدم(http.DefaultClient.Do (req لإرسال الطلب إلى الخادم باستخدام عميل HTTP الافتراضي http.DefaultClient. يبدأ التابع Do الطلب ويعيد الاستجابة المستلمة من الخادم مع أي خطأ محتمل.

بعد الحصول على الرد نطبع معلومات عنه، إذ نعرض أن العميل قد تلقى استجابة بنجاح، إلى جانب شيفرة حالة HTTP للاستجابة.

نقرأ بعد ذلك متن استجابة HTTP باستخدام الدالة ioutil.ReadAll. يُمثّل متن الاستجابة على أنه io.ReadCloser، والذي يجمع بين io.Reader و io.Closer. نستخدم ioutil.ReadAll لقراءة جميع البيانات من متن الاستجابة حتى النهاية أو حدوث خطأ. تُعيد الدالة البيانات بقيمة byte[]، والتي نطبعها مع أي خطأ مصادف.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

الخرج مشابه لما سبق مع إضافة بسيطة:

server: GET /
client: got response!
client: status code: 200
client: response body: {"message": "hello!"}

يُظهر السطر الأول أن الخادم لا يزال يتلقى طلب GET إلى المسار /. يتلقى العميل استجابة من الخادم برمز الحالة 200. يقرأ العميل متن استجابة الخادم ويطبعها أيضًا، والتي تكون في هذه الحالة {" message ":" hello! "}. يمكننا معالجة استجابة جسون هذه أيضًا باستخدام حزمة encoding/json، لكن لن ندخل في هذه التفاصيل الآن.

طورّنا في هذا القسم برنامج باستخدام خادم HTTP وقدمنا طلبات HTTP إليه باستخدام طرق مختلفة. استخدمنا في البداية الدالة http.Get لتنفيذ طلب GET للخادم باستخدام عنوان URL الخاص بالخادم فقط. حدّثنا بعد ذلك البرنامج لاستخدام http.NewRequest لإنشاء قيمة http.Request، ثم استخدمنا التابع Do لعميل HTTP الافتراضيhttp.DefaultClient، لإرسال الطلب وطباعة متن الاستجابة.

تُعد طلبات GET مفيدةً لاسترداد المعلومات من الخادم، لكن بروتوكول HTTP يوفر طرقًا أخرى متنوعة للاتصال بين البرامج. إحدى هذه الطرق هي طريقة POST، والتي تتيح لك إرسال معلومات من برنامجك إلى الخادم.

إرسال طلب POST

يُستخدم طلب GET في واجهة برمجة تطبيقات REST، فقط لاسترداد المعلومات من الخادم، لذلك لكي يُشارك البرنامج بالكامل في REST، يحتاج أيضًا إلى دعم إرسال طلبات POST، وهو عكس طلب GET تقريبًا، إذ يرسل العميل البيانات إلى الخادم داخل متن الطلب.

سنُعدّل في هذا القسم البرنامج لإرسال طلب POST بدلُا من طلب GET، إذ سيتضمن طلب POST متنًا للطلب، وسنُعدّل الخادم لتوفير معلومات أكثر تفصيلًا حول الطلبات الواردة من العميل.

نفتح ملف "main.go" ونُضمّن الحزم الإضافية التالية:

...

import (
    "bytes"
    "errors"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"
    "strings"
    "time"
)

...

ثم نُعدّل دالة المعالجة لطباعة معلومات متنوعة حول الطلب الوارد، مثل قيم سلسلة الاستعلام وقيم الترويسة ومتن الطلب:

...
  mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
      fmt.Printf("server: %s /\n", r.Method)
      fmt.Printf("server: query id: %s\n", r.URL.Query().Get("id"))
      fmt.Printf("server: content-type: %s\n", r.Header.Get("content-type"))
      fmt.Printf("server: headers:\n")
      for headerName, headerValue := range r.Header {
          fmt.Printf("\t%s = %s\n", headerName, strings.Join(headerValue, ", "))
      }

      reqBody, err := ioutil.ReadAll(r.Body)
      if err != nil {
             fmt.Printf("server: could not read request body: %s\n", err)
      }
      fmt.Printf("server: request body: %s\n", reqBody)

      fmt.Fprintf(w, `{"message": "hello!"}`)
  })
...

أضفنا في هذا التحديث لمعالج طلب HTTP الخاص بالخادم تعليمات fmt.Printf لتوفير مزيد من المعلومات حول الطلب الوارد. يُستخدم التابع r.URL.Query ().Get لاسترداد قيمة سلسلة الاستعلام المسماة id. يُستخدم التابع r.Header.Get للحصول على قيمة الترويسة content-type. تتكرر حلقة for معr.Header فوق كل ترويسة HTTP يستقبلها الخادم وتطبع اسمها وقيمتها. يمكن أن تكون هذه المعلومات ذات قيمة لأغراض استكشاف الأخطاء وإصلاحها في حالة ظهور أي مشكلات مع سلوك العميل أو الخادم. تُستخدم أيضًا الدالة ioutil.ReadAll لقراءة متن الطلب من r.Body.

بعد تحديث دالة المعالجة للخادم، نُعدّل شيفرة الطلب في الدالة main، بحيث ترسل طلب POST مع متن الطلب:

...
 time.Sleep(100 * time.Millisecond)

 jsonBody := []byte(`{"client_message": "hello, server!"}`)
 bodyReader := bytes.NewReader(jsonBody)

 requestURL := fmt.Sprintf("http://localhost:%d?id=1234", serverPort)
 req, err := http.NewRequest(http.MethodPost, requestURL, bodyReader)
...

في هذا التعديل قُدّم متغيران جديدان: يمثل الأول jsonBody بيانات جسون مثل قيم من النوع byte[] بدلًا من سلسلة string. يُستخدم هذا التمثيل لأنه عند ترميز بيانات جسون باستخدام حزمة encoding/json، فإنها تُرجع byte[] بدلًا من سلسلة.

المتغير الثاني bodyReader، هو bytes.Reader مُغلّف ببيانات jsonBody. يتطلب http.Request أن يكون متن الطلب من النوع io.Reader. نظرًا لأن قيمة jsonBody هي byte[] ولا تُحقق io.Reader مباشرةً، يُستخدم bytes.Reader لتوفير واجهة io.Reader الضرورية، مما يسمح باستخدام قيمة jsonBody على أنها متن الطلب.

نُعدّل أيضًا المتغير requestURL لتضمين قيمة سلسلة الاستعلام id = 1234، وذلك لتوضيح كيف يمكن تضمين سلسلة استعلام في عنوان URL للطلب إلى جانب مكونات عنوان URL القياسية الأخرى. أخيرًا نُعدّل استدعاء الدالة http.NewRequest لاستخدام التابع POST مع http.MethodPost، وضبط متن الطلب على bodyReader، وهو قارئ بيانات جسون.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيكون الخرج بالتأكيد أطول من السابق، بسبب طباعة معلومات إضافية:

server: POST /
server: query id: 1234
server: content-type: 
server: headers:
        Accept-Encoding = gzip
        User-Agent = Go-http-client/1.1
        Content-Length = 36
server: request body: {"client_message": "hello, server!"}
client: got response!
client: status code: 200
client: response body: {"message": "hello!"}

يُظهر الخرج السلوك المُحدّث للخادم والعميل بعد إجراء التغييرات لإرسال طلب POST؛ إذ يشير السطر الأول إلى أن الخادم قد تلقى طلب POST للمسار /؛ ويعرض السطر الثاني قيمة سلسلة الاستعلام id، والتي تحمل القيمة 1234 في هذا الطلب؛ بينما يعرض السطر الثالث قيمة ترويسة Content-Type، وهي فارغة في هذه الحالة.

قد يختلف ترتيب الترويسات المطبوعة من r.Headers أثناء التكرار عليها باستخدام range في كل مرة نُشغّل فيها البرنامج، فبدءًا من إصدار جو 1.12، لا يمكن ضمان أن يكون الترتيب الذي يجري فيه الوصول إلى العناصر هو نفس الترتيب الذي تُدرج في العناصر في الرابط map، وهذا لأن لغة جو تُحقق الروابط باستخدام بنية لا تحافظ على ترتيب الإدراج، لذلك قد يختلف ترتيب طباعة الترويسات عن الترتيب الذي جرى استلامها به فعليًا في طلب HTTP. الترويسات الموضحة في المثال هي Accept-Encoding و User-Agent و Content-Length. قد نرى أيضًا قيمة مختلفة للترويسة User-Agent عما رأيناه أعلاها اعتمادًا على إصدار جو المُستخدم.

يعرض السطر التالي متن الطلب الذي استلمه الخادم، وهو بيانات جسون التي يرسلها العميل. يمكن للخادم بعد ذلك استخدام حزمة encoding/json لتحليل بيانات جسون هذه التي أرسلها العميل وصياغة استجابة. تمثل الأسطر التالية خرج العميل، مما يشير إلى أنه تلقى استجابةً مع رمز الحالة 200. يحتوي متن الاستجابة المعروض في السطر الأخير على بيانات جسون أيضًا.

أجرينا في القسم السابق العديد من التحديثات لتحسين البرنامج. أولًا، استبدلنا طلب GET بطلب POST، مما يتيح للعميل إرسال البيانات إلى الخادم في متن الطلب، إذ أنجزنا هذا عن طريق تحديث شيفرة الطلب وتضمين متن الطلب باستخدام byte[]. عدّلنا أيضًا دالة معالجة الطلب الخاصة بالخادم لتوفير معلومات أكثر تفصيلًا حول الطلبات الواردة، مثل قيمة سلسلة الاستعلام id وترويسة Content-Type وجميع الترويسات المستلمة من العميل.

تجدر الإشارة إلى أنه في الخرج المعروض، لم تكن ترويسة Content-Type موجودة في طلب HTTP، مما يشير عادةً إلى نوع المحتوى المُرسل في المتن. سنتعلم في القسم التالي المزيد عن كيفية تخصيص طلب HTTP، بما في ذلك ضبط ترويسة Content-Type لتحديد نوع البيانات المُرسلة.

تخصيص طلب HTTP

يسمح تخصيص طلب HTTP بنقل مجموعة واسعة من أنواع البيانات بين العملاء والخوادم. كان بإمكان عملاء HTTP سابقًا افتراض أن البيانات المستلمة من خادم HTTP هي HTML غالبًا، أما اليوم يمكن أن تشمل البيانات تنسيقات مختلفة، مثل جسون والموسيقى والفيديو وغيرهم. لنقل معلومات إضافية متعلقة بالبيانات المرسلة، يشتمل بروتوكول HTTP على العديد من الترويسات، أهمها الترويسة Content-Type، التي تُخبر الخادم (أو العميل، اعتمادًا على اتجاه البيانات) بكيفية تفسير البيانات التي يتلقاها.

سنعمل في القسم التالي على تحسين البرنامج عن طريق ضبط الترويسة Content-Type في طلب HTTP للإشارة إلى أن الخادم يجب أن يتوقع بيانات جسون. ستتاح لنا الفرصة أيضًا لاستخدام عميل HTTP مخصص بدلًا من http.DefaultClient الافتراضي، مما يتيح لنا تخصيص إرسال الطلب وفقًا للمتطلبات المحددة.

نفتح ملف "main.go" لإجراء التعديلات الجديدة على الدالة main:

...

  req, err := http.NewRequest(http.MethodPost, requestURL, bodyReader)
  if err != nil {
         fmt.Printf("client: could not create request: %s\n", err)
         os.Exit(1)
  }
  req.Header.Set("Content-Type", "application/json")

  client := http.Client{
     Timeout: 30 * time.Second,
  }

  res, err := client.Do(req)
  if err != nil {
      fmt.Printf("client: error making http request: %s\n", err)
      os.Exit(1)
  }

...

بدايةً، جرى النفاذ إلى ترويسات http.Request باستخدام req.Header وضبطنا ترويسة Content-Type على application/json، إذ يُمثّل ضبط هذه الترويسة إشارةً للخادم إلى أن البيانات الموجودة في متن الطلب مُنسّقة بتنسيق جسون، وهذا يساعد الخادم في تفسير متن الطلب ومعالجته بطريقة صحيحة.

أنشأنا أيضًا نسخة خاصة من البنية http.Client في المتغير client. يتيح لنا هذا مزيدًا من التحكم في سلوك العميل. يمكننا في هذه الحالة ضبط قيمة المهلة Timeout للعميل على 30 ثانية؛ وهذا يعني أنه إذا لم يجري تلقي الرد في غضون 30 ثانية، سيستسلم العميل ويتوقف عن الانتظار. هذا مهم لمنع البرنامج من إهدار الموارد بإبقاء الاتصالات مفتوحة إلى أجل غير مسمى.

من خلال إنشاء http.Client خاص بنا مع مهلة محددة، فإننا تتأكد من أن البرنامج لديه حد محدد للمدة التي سينتظرها الرد، ويختلف هذا عن استخدام http.DefaultClient الافتراضي، والذي لا يحدد مهلة وسينتظر إلى أجل غير مسمى. لذلك يعد تحديد المهلة أمرًا بالغ الأهمية لإدارة الموارد بفعالية وتجنب مشكلات الأداء المحتملة.

أخيرًا عدّلنا الطلب لاستخدام التابع Do من المتغير client. هذا التغيير واضح ومباشر لأننا كنا نستخدم التابع Do في جميع أنحاء البرنامج، سواء مع العميل الافتراضي أو العميل المخصص. الاختلاف الوحيد الآن هو أننا أنشأنا صراحةً متغيرًا من http.Client.

توفر هذه التحديثات مزيدًا من التحكم والمرونة لبرنامجنا، مما يسمح بضبط ترويسات محددة وإدارة المهلات الزمنية بالطريقة المناسبة. من خلال فهم وتخصيص هذه الجوانب لطلب HTTP، يمكننا ضمان الأداء الأمثل والتواصل الموثوق مع الخادم.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

يجب أن تكون مخرجاتك مشابهة جدًا للإخراج السابق ولكن مع مزيد من المعلومات حول نوع المحتوى:

server: POST /
server: query id: 1234
server: content-type: application/json
server: headers:
        Accept-Encoding = gzip
        User-Agent = Go-http-client/1.1
        Content-Length = 36
        Content-Type = application/json
server: request body: {"client_message": "hello, server!"}
client: got response!
client: status code: 200
client: response body: {"message": "hello!"}

يمكننا ملاحظة أن الخادم قد استجاب بقيمة الترويسة Content-Type المُرسلة من قِبل العميل وهي من النوع application/json، ونلاحظ القيمة content-type وهي أيضًا application/json.

يسمح وجود Content-Type بالمرونة في التعامل مع أنواع مختلفة من واجهات برمجة التطبيقات في وقت واحد، إذ يمكّن الخادم من التمييز بين الطلبات التي تحتوي على بيانات جسون والطلبات التي تحتوي على بيانات XML. يصبح هذا التمييز مهمًا خاصةً عند التعامل مع واجهات برمجة التطبيقات التي تدعم تنسيقات بيانات مختلفة.

لفهم كيفية عمل مهلة العميل Timeout، يمكننا تعديل الشيفرة لمحاكاة سيناريو يستغرق فيه الطلب وقتًا أطول من المهلة المحددة، وذلك لكي نتمكن من ملاحظة تأثير المهلة.

يمكننا إضافة استدعاء دالة time.Sleep ضمن دالة المعالجة لخادم HTTP، إذ تؤدي هذه الدالة إلى تأخير مُصطنع في استجابة الخادم. للتأكد من أن التأخير يتجاوز قيمة المهلة التي حددناها، نجعل time.Sleep يستمر لمدة 35 ثانية، وبالتالي سيظهر الخادم وكأنه غير مستجيب، مما يتسبب في انتظار العميل للاستجابة:

...

func main() {
    go func() {
        mux := http.NewServeMux()
        mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            ... 
            fmt.Fprintf(w, `{"message": "hello!"}`)
            time.Sleep(35 * time.Second)
        })
        ...
    }()
    ...
}

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

عند تنفيذ البرنامج مع إضافة (time.Sleep (35 * time.Second في دالة المعالجة، سيتغير سلوك العميل والخادم، وذلك بسبب التأخير المصطنع الذي حدث في استجابة الخادم. نلاحظ أيضًا أن البرنامج يستغرق وقتًا أطول للخروج مقارنةً بالسابق، وذلك لأن البرنامج ينتظر انتهاء طلب HTTP قبل الإنهاء. الآن مع الانتظار الجديد الذي أضفناه، لن يكتمل طلب HTTP حتى تصل الاستجابة أو نتجاوز المهلة المحددة البالغة 30 ثانية، ونظرًا لأن الخادم متوقف مؤقتًا لمدة 35 ثانية، متجاوزًا مدة المهلة، فسيلغي العميل الطلب بعد 30 ثانية، وستجري عملية معالجة خطأ المهلة الزمنية:

server: POST /
server: query id: 1234
server: content-type: application/json
server: headers:
        Content-Type = application/json
        Accept-Encoding = gzip
        User-Agent = Go-http-client/1.1
        Content-Length = 36
server: request body: {"client_message": "hello, server!"}
client: error making http request: Post "http://localhost:3333?id=1234": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
exit status 1

نلاحظ تلقي الخادم طلب POST بطريقة صحيحة إلى المسار /، والتقط أيضًا معامل الاستعلام id بقيمة1234. حدد الخادم نوع محتوى الطلب content-type على أنه application/json بناءً على ترويسة نوع المحتوى، كما عرض الخادم الترويسات التي تلقاها. طبع الخادم أيضًا متن الطلب.

نلاحظ حدوث خطأ context deadline exceeded من جانب العميل أثناء طلب HTTP كما هو متوقع. تشير رسالة الخطأ إلى أن الطلب تجاوز المهلة الزمنية البالغة 30 ثانية (الخادم تلقى الطلب وعالجه، لكنه بسبب وجود تعليمة انتظار من خلال استدعاء دالة time.Sleep، سيبدو وكأنه لم ينتهي من معالجته). بالتالي سيفشل استدعاء التابع client.Do، ويخرج البرنامج مع رمز الحالة 1 باستخدام (os.Exit (1.

يسلط هذا الضوء على أهمية ضبط قيم المهلة الزمنية بطريقة مناسبة لضمان عدم تعليق الطلبات إلى أجل غير مسمى.

أجرينا خلال هذا القسم تعديلات على البرنامج لتخصيص طلب HTTP من خلال إضافة ترويسة Content-Type إليه. عدّلنا البرنامج أيضًا من خلال إنشاء http.Client جديد مع مهلة زمنية 30 ثانية، والتي استخدمناها لاحقًا لتنفيذ طلب HTTP. فحصنا أيضًا تأثير المهلة من خلال استخدام التعليمة time.Sleep داخل معالج طلب HTTP. سمح لنا هذا بملاحظة أن استخدام عميل http.Client مع المهلات الزمنية المضبوطة بدقة أمرٌ بالغ الأهمية لمنع الطلبات من الانتظار إلى أجل غير مسمى. بالتالي اكتسبنا رؤى حول أهمية ضبط المهلات المناسبة لضمان معالجة الطلب بكفاءة ومنع المشكلات المحتملة مع الطلبات التي قد تظل خاملة.

الخاتمة

اكتسبنا خلال هذا المقال فهمًا شاملًا للعمل مع طلبات HTTP في لغة جو باستخدام حزمة net/http؛ إذ بدأنا بتقديم طلب GET إلى خادم HTTP باستخدام كل من دالة http.Get و http.NewRequest مع عميل HTTP الافتراضي؛ ثم وسّعنا بعد ذلك معرفتنا عن طريق إجراء طلب POST مع متن طلب باستخدام bytes.NewReader.

تعلمنا كيفية تخصيص الطلب عن طريق ضبط ترويسة Content-Type باستخدام التابع Set في حقل ترويسة http.Request.اكتشفنا أهمية ضبط المهلات للتحكم في مدة الطلبات من خلال إنشاء عملي http.Client.

تجدر الإشارة إلى أن حزمة net/http توفر دوال أكثر مما غطيناه في هذا المقال، فعلى سبيل المثال يمكن استخدام دالة http.Post لتقديم طلبات POST والاستفادة من ميزات مثل إدارة ملفات تعريف الارتباط.

من خلال إتقان هذه المفاهيم، نكون قد زودنا أنفسنا بالمهارات الأساسية للتفاعل مع خوادم HTTP وإنشاء أنواع مختلفة من الطلبات باستخدام لغة جو.

ترجمة -وبتصرف- للمقال How To Make HTTP Requests in Go لصاحبه Kristin Davidson.

اقرأ أيضًا

• المقال السابق كيفية إنشاء خادم HTTP في لغة Go
• إنشاء طلبات HTTP وإرسالها
• كيفية استخدام صيغة JSON في لغة Go

يكرّس العديد من المطورين جزءًا من وقتهم لبناء خوادم تُسهّل توزيع المحتوى عبر الإنترنت. يُعد بروتوكول النقل التشعبي Hypertext Transfer Protocol-أو اختصارًا HTTP- من أهم الوسائل المستخدمة لتوزيع المحتوى مهما كان نوع البيانات عبر الإنترنت. تتضمّن مكتبة لغة جو القياسية وظائفًا مدمجة لإنشاء خادم HTTP لتخديّم محتوى الويب، أو إنشاء طلبات HTTP للتواصل مع هذه الخوادم.

سنتعلم في هذا المقال كيفية إنشاء خادم HTTP باستخدام مكتبة لغة جو القياسية، وكيفية توسيع وظائف الخادم لاستخراج البيانات من أجزاء مختلفة من طلب HTTP، مثل سلسلة الاستعلام والمتن Body وبيانات النموذج في الطلب. سنتعلّم أيضًا كيفية تعديل استجابة الخادم عن طريق إضافة ترويسات HTTP ورموز حالة مخصصة status codes، وبالتالي السماح للمطورين بتخصيص سلوك الخادم الخاص بهم.

توضيح بعض المصطلحات:

في سياق إنشاء خادم HTTP باستخدام مكتبة جو القياسية، تشير المصطلحات "سلسلة استعلام الطلب" و"المتن" و"بيانات النموذج" إلى أجزاء مختلفة من طلب HTTP.

1. سلسلة الاستعلام: هي جزء من عنوان URL الذي يأتي بعد رمز علامة الاستفهام (?). يحتوي عادةً على أزواج ذات قيمة مفتاح مفصولة بعلامات &.
2. المتن أو النص الأساسي: يحتوي متن طلب HTTP على البيانات التي يرسلها العميل إلى الخادم، مثل JSON أو XML أو النص العادي. يُستخدم بكثرة في طلبات من نوع POSTو PUT و PATCH لإرسال البيانات إلى الخادم.
3. بيانات النموذج: تُرسل عادةً بيانات النموذج مثل جزء من طلب POST مع ضبط ترويسة "نوع المحتوى" على "application/x-www-form-urlencoded" أو "multipart/form-data". وهو يتألف من أزواج مفتاح - قيمة على غرار سلسلة الاستعلام، ولكن يُرسل في متن الطلب.

بروتوكول HTTP

هو بروتوكول يعمل على مستوى التطبيقات، ويستخدم لنقل مستندات الوسائط التشعبية، مثل صفحات HTML عبر الإنترنت. يعمل HTTP بمثابة أساس لاتصالات البيانات على شبكة الويب العالمية.

يتبع HTTP نموذج خادم-العميل، إذ يرسل العميل (عادةً متصفح ويب) طلبًا إلى الخادم، ويستجيب الخادم بالمعلومات المطلوبة. تُستخدم بعض الدوال، مثل GET و POSTو PUT و DELETE لتسهيل عملية الاتصال بين العميل والخادم.

يمكنك الاطلاع على مقال مدخل إلى HTTP على أكاديمية حسوب لمزيدٍ من المعلومات حول بروتوكول HTTP.

المتطلبات الأولية

لمتابعة هذا المقال التعليمي، سنحتاج إلى:

• إصدار مُثبّت من جو 1.16 أو أعلى، ويمكنك الاستعانة بمقال تثبيت لغة جو Go وإعداد بيئة برمجة محلية على أبونتو Ubuntu لإعداده.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على نظام ماك macOS.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على ويندوز.
• القدرة على استخدام أداة curl لإجراء طلبات ويب.
• إلمام بكيفية استخدام جسون JSON في لغة جو.
• معرفة بكيفية استخدام السياقات Contexts في لغة جو Go.
• فهم لتنظيمات جو goroutines والقنوات channels. يمكنك الاطلاع على مقالة كيفية تشغيل عدة دوال على التساير في لغة جو Go.
• الإلمام بكيفية إنشاء طلبات HTTP وإرسالها (موصى به).

إعداد المشروع

تتوفّر معظم وظائف HTTP التي تسمح لنا بإجراء الطلبات من خلال حزمة net/http الموجودة في المكتبة القياسية في لغة جو، بينما تتولى حزمة net بقية عمليات الاتصال بالشبكة. توفّر حزمة net/http أيضًا خادم HTTP يمكن استخدامه لمعالجة تلك الطلبات.

سننشئ في هذا القسم برنامجًا يستخدم الدالة http.ListenAndServe لتشغيل خادم HTTP يستجيب للطلبات ذات المسارات / و hello/، ثم سنوسّع البرنامج لتشغيل خوادم HTTP متعددة في نفس البرنامج.

كما هو معتاد، سنحتاج لبدء إنشاء برامجنا إلى إنشاء مجلد للعمل ووضع الملفات فيه، ويمكن وضع المجلد في أي مكان على الحاسب، إذ يكون للعديد من المبرمجين عادةً مجلدٌ يضعون داخله كافة مشاريعهم. سنستخدم في هذا المقال مجلدًا باسم "projects"، لذا فلننشئ هذا المجلد وننتقل إليه:

$ mkdir projects
$ cd projects

الآن من داخل هذا المجلد، سنشغّل الأمر mkdir لإنشاء مجلد "httpserver" ثم سنستخدم cd للانتقال إليه:

$ mkdir httpserver
$ cd httpserver

الآن، بعد أن أنشأنا مجلدًا للبرنامج وانتقلنا إليه، يمكننا البدء في تحقيق خادم HTTP.

الاستماع إلى الطلبات وتقديم الردود

يتضمّن مخدّم HTTP في لغة جو مكونين رئيسيين: المخدّم الذي يستمع إلى الطلبات القادمة من العميل الذي يرسل طلبات HTTP (عميل HTTP أو عملاء HTTP) ومُعالج طلبات (أو أكثر) يستجيب لتلك الطلبات. سنبدأ حاليًا في استخدام الدالة http.HandleFunc التي تخبر المُخدّم بالدالة التي يجب استدعاؤها لمعالجة الطلب، ثم سنستخدم الدالة http.ListenAndServe لتشغيل الخادم وإخباره بالتحضير للاستماع إلى طلب HTTP جديد وتخديمه من خلال معالجته بدوال المعالجة Handler functions التي نُنشئها مُسبقًا.

بما أننا الآن داخل مجلد "httpserver"، يمكننا فتح ملف "main.go" باستخدام محرر نانو nano أو أي محرر آخر تريده:

$ nano main.go

سننشئ داخل هذا الملف دالتين getRoot و getHello سيمثلان دوال المعالجة الخاصة بنا، ثم سننشئ دالةً رئيسية main لاستخدامها في إعداد معالجات الطلبات من خلال الدالة http.HandleFunc، وذلك بتمرير المسار / الخاص بالدالة getRoot والمسار hello/ الخاص بالدالة getHello. بمجرد أن ننتهي من إعداد دوال المعالجة الخاصة بنا، يمكننا استدعاء http.ListenAndServe لبدء تشغيل المخدّم والاستماع للطلبات. دعنا نضيف التعليمات البرمجية التالية إلى الملف لبدء تشغيل البرنامج وإعداد المعالجات:

package main

import (
    "errors"
    "fmt"
    "io"
    "net/http"
    "os"
)

func getRoot(w http.ResponseWriter, r *http.Request) {
    fmt.Printf("got / request\n")
    io.WriteString(w, "This is my website!\n")
}
func getHello(w http.ResponseWriter, r *http.Request) {
    fmt.Printf("got /hello request\n")
    io.WriteString(w, "Hello, HTTP!\n")
}

أعددنا في البداية الحزمة الخاصة بالبرنامج package مع استيراد الحزم المطلوبة من خلال تعليمة import، كما أنشأنا الدالتين getRoot و getHello، ونلاحظ أن لهما نفس البصمة Signature، إذ تقبلان نفس الوسيطين، هما: قيمة http.ResponseWriter وقيمة http.Request*. هاتان الدالتان لهما بصمة تطابق النوع http.HandlerFunc، والذي يشيع استخدامه لتعريف دوال معالجة HTTP. عند تقديم طلب إلى الخادم، فإنه يُزوِّد هاتين القيمتين بمعلومات حول الطلب الحالي، ثم يستدعي دالة المعالج التي تتوافق مع هذه القيم.

تُستخدم القيمة http.ResponseWriter (االمُسماة w) ضمن http.HandlerFunc للتحكّم بمعلومات الاستجابة التي يُعاد كتابتها إلى العميل الذي قدّم الطلب، مثل متن الاستجابة response body (جزء من استجابة HTTP ويحمل الحمولة الفعلية أو المعلومات التي طلبها العميل أو التي يوفرها الخادم) أو رموز الحالة status codes، وهي معلومات حول نتيجة الطلب والحالة الحالية للخادم، وهي جزء من بروتوكول HTTP يجري تضمينها في ترويسة الاستجابة، وتشير إلى ما إذا كان الطلب ناجحًا أو واجه خطأً أو يتطلب إجراءً إضافيًا. بعد ذلك، تُستخدم القيمة http.Request* (المسماة r) للحصول على معلومات حول الطلب الذي جاء إلى الخادم، مثل المتن المُرسل في حالة طلب POST أو معلومات حول العميل الذي أجرى الطلب.

في كل من معالجات HTTP التي أنشأناها، يمكننا استخدام الدالة fmt.Printf للطباعة، وذلك عندما يأتي طلب لدالة المعالجة، ثم نستخدم http.ResponseWriter لإرسال نص ما إلى متن الاستجابة. http.ResponseWriter هي واجهة في حزمة http تمثل الاستجابة التي سترسل مرةً أخرى إلى العميل عند تقديم طلب إلى الخادم، وهي io.Writer مما يعني أنها توفر إمكانية كتابة البيانات. نستخدم http.ResponseWriterفي الشيفرة السابقة مثل وسيطw في دوال المعالجة (getRoot و getHello)، للسماح بالتحكم في الرد المرسل إلى العميل، وبالتالي إمكانية كتابة متن الاستجابة، أو ضبط الترويسات headers، أو تحديد رمز الحالة باستخدامها. نستخدم الدالة io.WriteString لكتابة الاستجابة ضمن متن الرسالة.

لنضيف الآن الدالة main إلى الشيفرة السابقة:

...
func main() {
    http.HandleFunc("/", getRoot)
    http.HandleFunc("/hello", getHello)

    err := http.ListenAndServe(":3333", nil)
...

تكون الدالة الرئيسية main في جزء الشيفرة السابق، مسؤولةً عن إعداد خادم HTTP وتحديد معالجات الطلب. هناك استدعاءان إلى الدالة http.HandleFunc، بحيث يربط كل استدعاء لها دالة معالجة من أجل مسار طلب محدد ضمن مجمّع الخادم الافتراضي default server multiplexer. يتطلب الأمر وسيطين: الأول هو مسار الطلب (في هذه الحالة / ثم hello/) ودالة المعالجة (getRoot ثم getHello على التوالي). الدالتان getRoot و getHello هما دوال المعالجة التي سيجري استدعاؤها عند تقديم طلب إلى المسارات المقابلة (/ و hello/). للدالتين توقيع مماثل للدالة http.HandlerFunc التي تقبلhttp.ResponseWriter و http.Request* مثل وسطاء.

تُستخدم الدالة http.ListenAndServe لبدء تشغيل خادم HTTP للاستماع إلى الطلبات الواردة. يتطلب الأمر وسيطين، هما: عنوان الشبكة للاستماع عليه (في هذه الحالة 3333:) ومعالج اختياري http.Handler. يحدد 3333: في برنامجنا أن الخادم يجب أن يستمع إلى المنفذ 3333، ونظرًا لعدم تحديد عنوان IP، سيستمع إلى جميع عناوين IP المرتبطة بالحاسب. يمثّل منفذ الشبكة network port -مثل "3333"- طريقةً تمكّن جهاز الحاسوب من أن يكون لديه عدة برامج تتواصل مع بعضها بنفس الوقت، بحيث يستخدم كل برنامج منفذه المخصص، وبالتالي عند اتصال العميل مع منفذ معين يعلم الحاسوب إلى أي منفذ سيُرسل. إذا كنت تريد قصر الاتصالات على المضيف المحلي localhost فقط، فيمكنك استخدام ‎127.0.0.1:3333.

تمرّر الدالة http.ListenAndServe قيمة nil من أجل المعامل http.Handler، وهذا يخبر دالة ListenAndServe بأنك تريد استخدام مجمّع الخادم الافتراضي وليس أي مجمّع ضبطه سابقًا.

الدالة ListenAndServe هي استدعاء "حظر"، مما يعني أنها ستمنع تنفيذ التعليمات البرمجية الأخرى حتى يُغلق الخادم. تُعيد هذه الدالة خطًأ إذا فشلت عملية بدء تشغيل الخادم أو إذا حدث خطأ أثناء التشغيل. من المهم تضمين عملية معالجة الأخطاء بعد استدعاء http.ListenAndServe، وذلك لأن الدالة يمكن أن تفشل، بالتالي من الضروري التعامل مع الأخطاء المحتملة. يُستخدم المتغير err لالتقاط أي خطأ يُعاد بواسطة ListenAndServe. يمكننا إضافة شيفرة معالجة الأخطاء بعد هذا السطر لمعالجة أي أخطاء محتملة قد تحدث أثناء بدء تشغيل الخادم أو تشغيله كما سنرى.

لنضيف الآن شيفرة معالجة الأخطاء إلى دالة ListenAndServe ضمن دالة main الرئيسية كما يلي:

...

func main() {
    ...
    err := http.ListenAndServe(":3333", nil)
  if errors.Is(err, http.ErrServerClosed) {
        fmt.Printf("server closed\n")
    } else if err != nil {
        fmt.Printf("error starting server: %s\n", err)
        os.Exit(1)
    <^>}
}

بعد استدعاء http.ListenAndServe، يجري تخزين الخطأ المُعاد في المتغير err. تجري عملية فحص الخطأ الأولى باستخدام (errors.Is(err, http.ErrServerClosed، إذ يجري التحقق ما إذا كان الخطأ هو http.ErrServerClosed، والذي يُعاد عندما يُغلق الخادم أو يجري إيقاف تشغيله. يعني ظهور هذا الخطأ أن الخادم قد أُغلق بطريقة متوقعة، بالتالي طباعة الرسالة "server closed".

يُنجز فحص الخطأ الثاني باستخدام Err != nil. يتحقق هذا الشرط مما إذا كان الخطأ ليس nil، مما يشير إلى حدوث خطأ أثناء بدء تشغيل الخادم أو تشغيله. إذا تحقق الشرط، فهذا يعني حدوث خطأ غير متوقع، وبالتالي طباعة رسالة خطأ مع تفاصيل الخطأ باستخدام fmt.Printf، كما يجري إنهاء البرنامج مع شيفرة الخطأ 1 باستخدام (os.Exit (1 للإشارة إلى حدوث خطأ.

تجدر الإشارة إلى أن أحد الأخطاء الشائعة التي قد تواجهها هو أن العنوان قيد الاستخدام فعلًا address already in use. يحدث هذا عندما تكون الدالة ListenAndServe غير قادرة على الاستماع إلى العنوان أو المنفذ المحدد للخادم لأنه قيد الاستخدام فعلًا من قبل برنامج آخر، أي إذا كان المنفذ شائع الاستخدام أو إذا كان برنامج آخر يستخدم نفس العنوان أو المنفذ.

ملاحظة: عند ظهور هذا الخطأ، يجب التأكد من إيقاف أي مثيلات سابقة للبرنامج ثم محاولة تشغيله مرة أخرى. إذا استمر الخطأ يجب علينا محاولة استخدام رقم منفذ مختلف لتجنب التعارضات، فمن المحتمل أن برنامجًا آخر يستخدم المنفذ المحدد. يمكن اختيار رقم منفذ مختلف (أعلى من 1024 وأقل من 65535) وتعديل الشيفرة وفقًا لذلك.

على عكس برامج لغة جو الأخرى؛ لن يُنهى البرنامج فورًا من تلقاء نفسه. لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

بما أن البرنامج يبقى قيد التشغيل في الطرفية الحالية، فسنحتاج إلى فتح نافذة أخرى للطرفية لكي نتفاعل مع الخادم (ستظهر الأوامر بلون مختلف عن الطرفية الأولى).

ضمن الطرفية الثانية التي فتحناها، نستخدم الأمر curl لتقديم طلب HTTP إلى خادم HTTP الخاص بنا. curl هي أداة مُثبّتة افتراضيًا على العديد من الأنظمة التي يمكنها تقديم طلبات للخوادم من أنواع مختلفة، وسنستخدمها في هذا المقال لإجراء طلبات HTTP. يستمع الخادم إلى الاتصالات على المنفذ 3333 لجهاز الحاسوب، لذا يجب تقديم الطلب للمضيف المحلي على نفس المنفذ:

$ curl http://localhost:3333

سيكون الخرج على النحو التالي:

This is my website!

العبارة This is my website ناتجة عن الدالة getRoot، وذلك لأنك استخدمت المسار / على خادم HTTP. دعونا الآن نستخدم المسار hello/ على نفس المضيف والمنفذ، وذلك بإضافة المسار إلى نهاية أمر curl:

$ curl http://localhost:3333/hello

ليكون الخرج هذه المرة:

Hello, HTTP!

نلاحظ أن الخرج السابق كان نتيجةً لاستدعاء الدالة getHello. إذا عدنا إلى المحطة الطرفية الأولى التي يعمل عليها خادم HTTP، نلاحظ وجود سطرين أنتجهما الخادم الخاص بنا: واحد للطلب / والآخر للطلب hello/.

got / request
got /hello request

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "Ctrl+C".

لقد أنشأنا برنامجًا يمثل خادم HTTP، لكنه يستخدم مجمّع خادم افتراضي وخادم HTTP افتراضي أيضًا. يمكن أن يؤدي الاعتماد على القيم الافتراضية أو العامة Global إلى حدوث أخطاء يصعب تكرارها أو يصعب إنتاجها باستمرار Reproduce consistently، إذ يمكن أن تُعدِّل أجزاءً مختلفة من البرنامج هذه القيم العامة في أوقات مختلفة، مما يؤدي إلى حالة غير صحيحة أو غير متسقة. يصبح تحديد مثل هذه الأخطاء أمرًا صعبًا لأنها قد تحدث فقط في ظل ظروف معينة أو إذا جرى استدعاء وظائف معينة بترتيب معين.

معالجات طلبات التجميع

عند بدء تشغيل خادم HTTP سابقًا؛ استخدمنا مجمّع خادم افتراضي عن طريق تمرير قيمة صفرية (أي nil) للمعامل http.Handler في دالة ListenAndServe. رأينا أيضًا أن هناك بعض المشاكل التي قد تطرأ في حالة استخدام المعاملات الافتراضية. بما أن http.Handler هو واجهة interface، فهذا يعني أنه لدينا الخيار لإنشاء بنية مخصصة تحقق هذه الواجهة. هناك طبعًا حالات نحتاج فيها فقط إلى http.Handler الافتراضي الذي يستدعي دالة واحدة لمسار طلب معين، أي كما في حالة مجمّع الخادم الافتراضي، لكن هناك حالات قد تتطلّب أكثر من ذلك؛ هذا ما نناقشه تاليًا.

لنعدّل البرنامج الآن لاستخدام http.ServeMux، إنها أداة تعمل مثل مجمّع للخادم، وهي مسؤولة عن التوجيه والتعامل مع طلبات HTTP الواردة بناءً على مساراتها. تحقّقhttp.ServeMux الواجهة http.Handler المؤمنة من قِبل حزمة net/http، مما يعني قدرتها على التعامل مع طلبات HTTP وإنشاء الاستجابات المناسبة. بالتالي مزيد من التحكم في التوجيه والتعامل مع مسارات الطلبات المختلفة، وإتاحة الفرصة لتحديد دوال أو معالجات محددة لكل مسار. بالتالي نكون قد اتبعنا نهجًا أكثر تنظيمًا وقابلية للتخصيص للتعامل مع طلبات HTTP في البرنامج.

يمكن تهيئة بنية http.ServeMux بطريقة مشابهة للمجمّع الافتراضي، لذا لن نحتاج إلى إجراء العديد من التغييرات على البرنامج لبدء استخدام مجمّع الخادم المخصّص بدلًا من الافتراضي. لتحديث البرنامج وفقًا لذلك، نفتح ملف "main.go" مرةً أخرى ونجري التعديلات اللازمة لاستخدام http.ServeMux:

...

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", getRoot)
    mux.HandleFunc("/hello", getHello)

    err := http.ListenAndServe(":3333", mux)

    ...
}

أنشأنا http.ServeMux جديد باستخدام باني http.NewServeMux وأسندناه إلى المتغير mux، ثم عدّلنا استدعاءات http.HandleFunc لاستخدام المتغير mux بدلًا من استدعاء حزمة http مباشرة. أخيرًا، عدّلنا استدعاء http.ListenAndServe لتزويده بالمعالج http.Handler الذي أنشأنه mux بدلًا من nil.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

سيستمر البرنامج في العمل كما في المرة السابقة، لذا نحتاج إلى تشغيل أوامر في طرفية أخرى للتفاعل مع الخادم. أولًا، نستخدم curl لطلب المسار /:

$ curl http://localhost:3333

سيكون الخرج على النحو التالي:

This is my website!

الخرج كما هو في المرة السابقة. دعونا الآن نستخدم المسار hello/ على نفس المضيف والمنفذ، وذلك بإضافة المسار إلى نهاية أمر curl:

$ curl http://localhost:3333/hello

سيكون الخرج كما يلي:

Hello, HTTP!

نلاحظ أن الخرج السابق كان كما المرة السابقة أيضًا.

إذا عدنا الآن إلى الطرفية الأولى، فسنرى مخرجات كل من / و hello / كما كان من قبل:

got / request
got /hello request

نلاحظ أن التعديلات التي أجريناها لا تغيّر في وظيفة البرنامج، وإنما فقط بدلنا مجمّع الخادم الافتراضي بآخر مخصص.

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "Ctrl+C".

تشغيل عدة خوادم في وقت واحد

سنجري خلال هذا القسم تعديلات على البرنامج لاستخدام عدة خوادم HTTP في نفس الوقت باستخدام http.Server التي توفرها حزمة net/http. يمكننا بالحالة الافتراضية تشغيل خادم HTTP واحد فقط في البرنامج، لكن قد تكون هناك سيناريوهات نحتاج فيها إلى تخصيص سلوك الخادم أو تشغيل عدة خوادم في نفس الوقت، مثل استضافة موقع ويب عام Public website وموقع ويب إداري خاص Private admin website داخل نفس البرنامج. لأجل ذلك سنعدّل ملف "main.go" لإنشاء نسخ متعددة من http.Server لأغراض مختلفة، إذ سيكون لكل خادم التهيئة والإعدادات الخاصة به. يتيح لك هذا مزيدًا من التحكم في سلوك الخادم ويمكّنك من التعامل مع وظائف خادم متعددة داخل نفس البرنامج.

سنعدّل أيضًا دوال المعالجة لتحقيق إمكانية الوصول إلى Context.Context المرتبط مع http.Request*؛ أي إمكانية الوصول إلى سياق الطلبات الواردة، إذ يمكننا من خلال هذا السياق تمييز الخادم الذي يأتي الطلب منه. إذًا من خلال تخزين هذه المعلومات في متغير السياق، يصبح بمقدورنا استخدامها داخل دالة المعالجة لتنفيذ إجراءات محددة أو تخصيص الاستجابة بناءً على الخادم الذي أنشأ الطلب.

لنفتح ملف "main.go" ونعدّله بالتالي:

package main

import ( 
// os لاحظ أننا حذفنا استيراد 
    "context"
    "errors"
    "fmt"
    "io"
    "net"
    "net/http"
)

const keyServerAddr = "serverAddr"

func getRoot(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    fmt.Printf("%s: got / request\n", ctx.Value(keyServerAddr))
    io.WriteString(w, "This is my website!\n")
}
func getHello(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    fmt.Printf("%s: got /hello request\n", ctx.Value(keyServerAddr))
    io.WriteString(w, "Hello, HTTP!\n")
}

عدّلنا بيان الاستيراد import لتضمين الحزم المطلوبة، ثم أنشأنا سلسلة نصية ثابتة const string تسمى keyServerAddr لتعمل مثل مفتاح لقيمة عنوان خادم HTTP في سياق http.Request، ثم عدّلنا دوال المعالجة getRoot و getHello للوصول إلى قيمة Context.Context التابعة إلى http.Request. بعد الحصول على القيمة يمكننا تضمين عنوان خادم HTTP في خرج fmt.Printf حتى نتمكن من معرفة أي من الخادمين تعامل مع طلب HTTP.

لنعدّل الآن الدالة main بإضافة قيمتي http.Server:

...
func main() {
    ...
    mux.HandleFunc("/hello", getHello)

    ctx, cancelCtx := context.WithCancel(context.Background())
    serverOne := &http.Server{
        Addr:    ":3333",
        Handler: mux,
        BaseContext: func(l net.Listener) context.Context {
            ctx = context.WithValue(ctx, keyServerAddr, l.Addr().String())
            return ctx
        },
    }

التغيير الأول الذي أجريناه هو إنشاء قيمة Context.Context جديدة مع دالة متاحة هي الدالة `cancelCtx'. هذا يسمح لنا بإلغاء السياق عند الحاجة.

عرّفنا أيضًا نسخةً تسمى serverOne من http.Server، وهو مشابه لخادم HTTP الذي كنا نستخدمه، ولكن بدلًا من تمرير العنوان والمعالج مباشرةً إلى http.ListenAndServe، يمكن إسنادهما مثل قيم Addr و Handler في بنية http.Server.

تعديل آخر كان بإضافة دالة BaseContext، وهي دالة تسمح بتعديل أجزاء من Context.Context الذي جرى تمريره إلى دوال المعالجة عند استدعاء التابع Context من http.Request*. أضفنا في الشيفرة السابقة عنوان الاستماع الخاص بالخادم إلى السياق باستخدام المفتاح serverAddr، وهذا يعني أن العنوان الذي يستمع فيه الخادم للطلبات الواردة مرتبط بمفتاح serverAddr في السياق. عندما نستدعي الدالة BaseContext، فإنها تتلقى net.Listener، والذي يمثل مستمع الشبكة الأساسي الذي يستخدمه الخادم.

بالنسبة لبرنامجنا: من خلال استدعاء ()l.Addr(). String، نكون قد حصلنا على عنوان شبكة المستمع. يتضمن هذا عادةً عنوان IP ورقم المنفذ الذي يستمع الخادم عليه. بعد ذلك نضيف العنوان الذي حصلنا عليه إلى السياق باستخدام الدالة Context.WithValue، والتي تتيح لنا تخزين أزواج المفتاح والقيمة في السياق. في هذه الحالة يكون المفتاح هو serverAddr، والقيمة المرتبطة به هي عنوان الاستماع الخاص بالخادم.

لنعرّف الآن الخادم الثاني serverTwo:

...

func main() {
    ...
    serverOne := &http.Server {
        ...
    }

    serverTwo := &http.Server{
        Addr:    ":4444",
        Handler: mux,
        BaseContext: func(l net.Listener) context.Context {
            ctx = context.WithValue(ctx, keyServerAddr, l.Addr().String())
            return ctx
        },
    }

نعرّف الخادم الثاني بنفس طريقة تعريف الأول، لكن نضع حقل العنوان على 4444: بدلًا من 3333:، وذلك لكي يستمع الخادم الأول على للاتصالات على المنفذ 3333 ويستمع الخادم الثاني على المنفذ 4444.

لنعدّل الآن البرنامج من أجل استخدام الخادم الأول serverOne وجعله يعمل مثل تنظيم جو goroutine:

...

func main() {
    ...
    serverTwo := &http.Server {
        ...
    }

    go func() {
        err := serverOne.ListenAndServe()
        if errors.Is(err, http.ErrServerClosed) {
            fmt.Printf("server one closed\n")
        } else if err != nil {
            fmt.Printf("error listening for server one: %s\n", err)
        }
        cancelCtx()
    }()

نستخدم تنظيم goroutine لبدء تشغيل الخادم الأول serverOne باستخدام الدالة ListenAndServe كما فعلنا سابقًا، لكن هذه المرة دون أي معاملات لأن قيم http.Server جرى تهيئتها مسبقًا باستخدام العنوان والمعالج المطلوبين.

تجري عملية معالجة الأخطاء كما في السابق؛ فإذا كان الخادم مغلقًا، فإنه يطبع رسالة تشير إلى أن "الخادم الأول" أصبح مغلقًا؛ وإذا كان هناك خطأ آخر بخلاف http.ErrServerClosed، فستظهر رسالة خطأ.

تُستدعى أخيرًا الدالة CancelCtx لإلغاء السياق الذي قدمناه لمُعالجات HTTP ودوال BaseContext لكلا الخادمين. بالتالي إنهاء أي عمليات جارية تعتمد عليه بأمان. هذا يضمن أنه إذا انتهى الخادم لأي سبب، فسيُنهى أيضًا السياق المرتبط به.

لنعدّل الآن البرنامج لاستخدام الخادم الثاني، بحيث يعمل مثل تنظيم جو :

...

func main() {
    ...
    go func() {
        ...
    }()
    go func() {
        err := serverTwo.ListenAndServe()
        if errors.Is(err, http.ErrServerClosed) {
            fmt.Printf("server two closed\n")
        } else if err != nil {
            fmt.Printf("error listening for server two: %s\n", err)
        }
        cancelCtx()
    }()

    <-ctx.Done()
}

تنظيم جو هنا هو نفسه الأول من الناحية الوظيفية، فهو يُشغّل serverTwo فقط بدلًا من serverOne. بعد بدء تشغيل serverTwo، يصل التنظيم الخاص بالدالة main إلى السطر ctx.Done. ينتظر هذا السطر إشارةً من قناة ctx.Done، والتي تُعاد عند إلغاء السياق أو الانتهاء منه. من خلال هذا الانتظار نكون قد منعنا تنظيم الدالة الرئيسية من الخروج من الدالة main حتى تنتهي تنظيمات جو لكلا الخادمين من العمل. إذًا، الغرض من هذا الأسلوب هو التأكد من استمرار تشغيل البرنامج حتى انتهاء كلا الخادمين أو مواجهة خطأ.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

نُشغّل الآن أوامر curl (في الطرفية الثانية) لطلب المسار / والمسارhello/ من الخادم الذي يستمع على 3333، مثل الطلبات السابقة:

$ curl http://localhost:3333
$ curl http://localhost:3333/hello

سيكون الخرج كما في المرات السابقة:

This is my website!
Hello, HTTP!

لنشغّل الأوامر نفسها مرة أخرى، ولكن هذه المرة مع المنفذ 4444 الذي يتوافق مع serverTwo:

$ curl http://localhost:4444
$ curl http://localhost:4444/hello

سيبقى الخرج نفسه كما في المرة السابقة أيضًا:

This is my website!
Hello, HTTP!

لنلقي نظرةً الآن على الطرفية الأولى حيث يعمل الخادم:

[::]:3333: got / request
[::]:3333: got /hello request
[::]:4444: got / request
[::]:4444: got /hello request

الخرج مشابه لما رأيناه من قبل، لكنه يعرض هذه المرة الخادم الذي استجاب للطلب. يظهِر الطلبان الأولان أنهما جاءا من الخادم الذي يستمع على المنفذ 3333 أي serverOne، والطلبان الثانيان جاءا من الخادم الذي يستمع على المنفذ 4444 أي serverTwo. إنها القيم التي جرى استردادها من قيمة serverAddr في BaseContext. قد يكون الخرج مختلفًا قليلًا عن الخرج أعلاه اعتمادًا على ما إذا كان جهاز الحاسب المُستخدم يستخدم IPv6 أم لا. إذا كان الحاسب يستخدم IPv6 فسيكون الخرج كما أعلاه، وإلا سنرى 0.0.0.0 بدلًا من [::]. السبب في ذلك هو أن جهاز الحاسب سيتواصل مع نفسه عبر IPv6، و [::] هو تدوين IPv6 والذي يُقابل 0.0.0.0 في IPv4. بعد الانتهاء نضغط "CONTROL+C" لإنهاء الخادم.

تعرفنا في هذا القسم على عملية إنشاء برنامج خادم HTTP وتحسينه تدريجيًا للتعامل مع السيناريوهات المختلفة. بدأنا بتهيئة الخادم الافتراضي باستخدام http.HandleFunc و http.ListenAndServe. بعد ذلك عدّلناه لاستخدام http.ServeMux مثل مجمّع خادم، مما يسمح لنا بالتعامل مع معالجات طلبات متعددة لمسارات مختلفة. وسّعنا البرنامج أيضًا لاستخدام http.Server، مما يمنحنا مزيدًا من التحكم في تهيئة الخادم ويسمح لنا بتشغيل خوادم HTTP متعددة في نفس الوقت داخل نفس البرنامج.

على الرغم من أن البرنامج يعمل، إلا أنه يفتقر إلى التفاعل الذي يتجاوز تحديد المسارات المختلفة. لمعالجة هذا القيد، يركز القسم التالي على دمج قيم سلسلة الاستعلام query string values في وظائف الخادم، مما يتيح للمستخدمين التفاعل مع الخادم باستخدام معاملات الاستعلام.

فحص سلسلة الاستعلام الخاصة بالطلب

ينصب التركيز في هذا القسم على دمج قيم سلسلة الاستعلام في وظائف خادم HTTP. سلسلة الاستعلام هي مجموعة من القيم الملحقة بنهاية عنوان URL، تبدأ بالمحرف ? وتستخدم المُحدّد & للقيم الإضافية. توفر قيم سلسلة الاستعلام وسيلة للمستخدمين للتأثير على الاستجابة التي يتلقونها من خادم HTTP عن طريق تخصيص النتائج أو تصفيتها، فمثلًا قد يستخدم أحد الخوادم قيمة results للسماح للمستخدم بتحديد شيء مثل results = 10 ليقول إنه يرغب في رؤية 10 عناصر في قائمة النتائج.

لتحقيق هذه الميزة نحتاج إلى تحديث دالة المعالجة getRoot في ملف "main.go" للوصول إلى قيم سلسلة الاستعلام http.Request* باستخدام التابع r.URL.Query، ثم طباعتها بعد ذلك على الخرج. نزيل أيضًا serverTwo وكل الشيفرات المرتبطة به من الدالة main، لأنها لم تعد مطلوبة للتغييرات القادمة:

...

func getRoot(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    hasFirst := r.URL.Query().Has("first")
    first := r.URL.Query().Get("first")
    hasSecond := r.URL.Query().Has("second")
    second := r.URL.Query().Get("second")

    fmt.Printf("%s: got / request. first(%t)=%s, second(%t)=%s\n",
        ctx.Value(keyServerAddr),
        hasFirst, first,
        hasSecond, second)
    io.WriteString(w, "This is my website!\n")
}
...

يمكننا في دالة getRoot المحدَّثة استخدام الحقل r.URL الذي يتبع إلى http.Request* للوصول إلى الخصائص المتعلقة بعنوان URL المطلوب. باستخدام التابع Query في الحقل r.URL، يمكننا الوصول إلى قيم سلسلة الاستعلام المرتبطة بالطلب. هناك طريقتان يمكن استخدامهما للتفاعل مع بيانات سلسلة الاستعلام:

1. يتحقق التابع Has ما إذا كانت سلسلة الاستعلام تحتوي على قيمة بمفتاح معين، مثل"first" أو "second". يعيد التابع قيمة بوليانية bool تشير إلى وجود المفتاح.
2. يسترد التابع Get القيمة المرتبطة بمفتاح معين من سلسلة الاستعلام وتكون من نوع string، وإذا لم يعثر على المفتاح، يعيد عادةً سلسلة فارغة.

نظريًّا يمكننا دائمًا استخدام Get لاسترداد قيم سلسلة الاستعلام لأنها ستعيد دائمًا إما القيمة الفعلية للمفتاح المحدد أو سلسلة فارغة إذا كان المفتاح غير موجود. هذا جيد في كثير من الحالات، ولكن في بعض الحالات الأخرى، قد نرغب في معرفة الفرق بين المستخدم الذي يقدم قيمة فارغة أو عدم تقديم قيمة إطلاقًا. إذًا، بناءً على حالة الاستخدام الخاصة بنا، قد يكون من المهم التمييز بين المستخدم الذي يقدم قيمة فارغة للمرشّح أو عدم تقديم مرشح filter إطلاقًا:

• يُقدّم المستخدم قيمة فارغة للمرشح filter: هنا يحدد المستخدم صراحة قيمة المرشح، ولكنه يضبطها على قيمة فارغة. قد يشير هذا إلى اختيار متعمد لاستبعاد نتائج معينة أو تطبيق شرط مرشحfilter معين. مثلًا، إذا كانت لدينا دالة بحث وقدم المستخدم قيمة فارغة للمرشح، فيمكننا تفسيرها على أنها "إظهار كافة النتائج".
• لا يوفر المستخدم مرشّح إطلاقًا: هنا لم يقدّم المستخدم مرشّحًا في الطلب. هذا يعني عادةً أن المستخدم يريد استرداد جميع النتائج دون تطبيق أي تصفية محددة. يمكن عدّه سلوكًا افتراضيًا، إذ لا تُطبّق شروط ترشيح محددة.

يسمح لك استخدام Has و Get بالتمييز بين الحالات التي يقدم فيها المستخدم صراحة قيمةً فارغة والحالات التي لا تُقدّم فيها قيمة إطلاقًا. بالتالي إمكانية التعامل مع السيناريوهات المختلفة اعتمادًا على حالة الاستخدام المحددة الخاصة بنا.

يمكنك تحديث دالة getRoot لعرض قيم Has و Get من أجل قيمتي سلسلة الاستعلام first و second.

لنعدّل الدالة main بحيث نستخدم خادم واحد مرة أخرى:

...

func main() {
    ...
    mux.HandleFunc("/hello", getHello)

    ctx := context.Background()
    server := &http.Server{
        Addr:    ":3333",
        Handler: mux,
        BaseContext: func(l net.Listener) context.Context {
            ctx = context.WithValue(ctx, keyServerAddr, l.Addr().String())
            return ctx
        },
    }

    err := server.ListenAndServe()
    if errors.Is(err, http.ErrServerClosed) {
        fmt.Printf("server closed\n")
    } else if err != nil {
        fmt.Printf("error listening for server: %s\n", err)
    }
}

نلاحظ ضمن الدالة main إزالة المراجع والشيفرات المرتبطة بالخادم الثاني serverTwo، لأننا لم نعد بحاجة إلى خوادم متعددة. نقلنا أيضًا تنفيذ الخادم (serverOne سابقًا) خارج التنظيم goroutine وإلى الدالة main. هذا يعني أنه سيجري بدء تشغيل الخادم بطريقة متزامنة، و ينتظر التنفيذ حتى يُغلق الخادم قبل المتابعة.

تغيير آخر كان باستخدام الدالة server.ListenAndServe؛ فبدلًا من استخدام http.ListenAndServe، يمكن الآن استخدامserver.ListenAndServe لبدء الخادم. يتيح ذلك الاستفادة من تهيئة http.Server وأي تخصيصات أجريناها. كذلك أضفنا شيفرة لمعالجة الأخطاء، وذلك للتحقق ما إذا كان الخادم مغلقًا أو واجه أي خطأ آخر أثناء الاستماع. إذا كان الخطأ هو http.ErrServerClosed، فهذا يعني أن عملية الإغلاق عن قصد (إغلاق طبيعي)، وخلاف ذلك ستجري طباعة الخطأ. بإجراء هذه التغييرات سيُشغّل برنامجنا الآن خادم HTTP واحد باستخدام وفقًا لتهيئةhttp.Server ليبدأ في الاستماع للطلبات الواردة، ولن تحتاج إلى تحديثات أخرى من أجل تخصيصات للخادم مستقبلًا.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

نُشغّل الآن أوامر curl (في الطرفية الثانية). هنا نحتاج إلى إحاطة عنوان URL بعلامات اقتباس مفردة (')، وإلا فقد تُفسر صدفة الطرفية (أي Shell) الرمز & في سلسلة الاستعلام على أنه ميزة "تشغيل الأمر في الخلفية". ضمن عنوان URL نضيف first=1 إلى first و =second إلى second:

$ curl 'http://localhost:3333?first=1&second='

سيكون الخرج على النحو التالي:

This is my website!

لاحظ أن الخرج لم يتغير عن المرة السابقة، لكن إذا عدنا إلى خرج برنامج الخادم، فسنرى أن الخرج الجديد يتضمن قيم سلسلة الاستعلام:

[::]:3333: got / request. first(true)=1, second(true)=

يظهِر خرج قيمة سلسلة الاستعلام first أن التابع Has أعاد true لأن first لها قيمة، وأيضًا التابع Get أعاد القيمة 1. يُظهر ناتج second أنه قد أعاد true لأننا ضمّنّا second، لكن التابع Get لم يُعيد أي شيء إلا سلسلة فارغة. يمكننا أيضًا محاولة إجراء طلبات مختلفة عن طريق إضافة وإزالة first و second أو إسناد قيم مختلفة لنرى كيف تتغير النتائج.

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "Ctrl+C".

حدّثنا في هذا القسم البرنامج لاستخدام http.Server واحد فقط مرةً أخرى، لكن أضفنا أيضًا دعمًا لقراءة قيم first و second من سلسلة الاستعلام لدالة المعالجة getRoot.

ليس استخدام سلسلة الاستعلام الطريقة الوحيدة للمستخدمين لتقديم مدخلات إلى خادم HTTP، فهناك طريقة أخرى شائعة لإرسال البيانات إلى الخادم وهي تضمين البيانات في متن الطلب. سنعدّل في القسم التالي البرنامج لقراءة نص الطلب من بيانات http.Request*.

قراءة متن الطلب

عند إنشاء واجهة برمجة تطبيقات مبنية على HTTP، مثل واجهة برمجة تطبيقات REST، قد تكون هناك حالات تتجاوز فيها البيانات المُرسلة قيود تضمينها في عنوان URL نفسه، مثل الطول الأعظمي للعنوان. قد نحتاج أيضًا إلى تلقي بيانات لا تتعلق بكيفية تفسير البيانات، وهذا يشير إلى الحالات التي لا ترتبط فيها البيانات المرسلة في متن الطلب ارتباطًا مباشرًا بالمحتوى نفسه. بمعنى آخر: لا توفر هذه البيانات الإضافية إرشادات أو بيانات وصفية حول المحتوى، ولكنها تتضمن معلومات تكميلية تحتاج إلى المعالجة بطريقة منفصل. تخيل صفحة بحث، يمكن فيها للمستخدمين إدخال كلمات للبحث عن عناصر محددة. تمثل كلمات البحث نفسها تفسير المحتوى المقصود، ومع ذلك قد تكون هناك بيانات إضافية في متن الطلب، مثل تفضيلات المستخدم أو الإعدادات، والتي لا ترتبط مباشرةً باستعلام البحث نفسه ولكنها لا تزال بحاجة إلى النظر فيها أو معالجتها بواسطة الخادم. للتعامل مع مثل هذه السيناريوهات، يمكننا تضمين البيانات في متن طلب HTTP باستخدام توابع مثل POST أو PUT.

تُستخدم قيمة http.Request* في http.HandlerFunc للوصول إلى معلومات متعلقة بالطلب الوارد، بما في ذلك متن الطلب، والذي يمكن الوصول إليه من خلال حقل Body.

سنعدّل في هذا القسم دالة المعالجة getRoot لقراءة نص الطلب. لنفتح ملف main.go ونعدّل getRoot لاستخدام ioutil.ReadAll لقراءة حقلr.Body للطلب:

package main

import (
    ...
    "io/ioutil"
    ...
)

...

func getRoot(w http.ResponseWriter, r *http.Request) {
    ...
    second := r.URL.Query().Get("second")

    body, err := ioutil.ReadAll(r.Body)
    if err != nil {
        fmt.Printf("could not read body: %s\n", err)
    }

    fmt.Printf("%s: got / request. first(%t)=%s, second(%t)=%s, body:\n%s\n",
        ctx.Value(keyServerAddr),
        hasFirst, first,
        hasSecond, second,
        body)
    io.WriteString(w, "This is my website!\n")
}

...

تُستخدم الدالة ioutil.ReadAll لقراءة r.Body من http.Request* لاسترداد بيانات متن الطلب. ioutil.ReadAll هي أداة مساعدة تقرأ البيانات من io.Reader حتى تنتهي من القراءة أو ظهور خطأ. نظرًا لأن r.Body هو io.Reader، فيمكن استخدامه لقراءة متن الطلب. نعدّل العبارة fmt.Printf بعد قراءة النص لتضمين محتوى المتن في الخرج.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

نُشغّل الآن أوامر curl (في الطرفية الثانية)، لتقديم طلب POST مع خيار X POST- وتحديد أن طريقة الطلب يجب أن تكون POST، ومتن طلب باستخدام الخيار b-. يُضبط متن الطلب على السلسلة النصيّة المقدمة، والتي في هذه الحالة هي "This is the body":

$ curl -X POST -d 'This is the body' 'http://localhost:3333?first=1&second='

ليكون الخرج:

This is my website!

خرج دالة المعالجة هو نفسه، لكن سنرى تسجيلات الخادم الخاصة بك قد حُدّثت. سيُرسل طلب POST عندما نشغّل هذا الأمر إلى الخادم المحلي الذي يعمل على المنفذ 3333 مع محتوى المتن المحدد ومعلمات سلسلة الاستعلام. بالتالي يعالج الخادم الطلب ونرى الخرج في سجلات الطرفية للخادم، بما في ذلك قيم سلسلة الاستعلام ومتن الطلب.

[::]:3333: got / request. first(true)=1, second(true)=, body:
This is the body

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "Ctrl+C".

عدّلنا في هذا القسم البرنامج لقراءة وطباعة متن الطلب. تفتح هذه الإمكانية إمكانيات التعامل مع أنواع مختلفة من البيانات، مثل جسون encoding/json، وتتيح إنشاء واجهات برمجة تطبيقات يمكنها التفاعل مع بيانات المستخدم بطريقة مألوفة.

تجدر الملاحظة إلى أنه لا تأتي جميع بيانات المستخدم في شكل واجهات برمجة التطبيقات. تتضمن العديد من مواقع الويب نماذج يملؤها المستخدمون، والتي ترسل البيانات إلى الخادم مثل بيانات نموذج Form. سنعمل على تحسين البرنامج في القسم التالي ليشمل القدرة على قراءة بيانات النموذج ومعالجتها، بالإضافة إلى جسم الطلب وبيانات سلسلة الاستعلام التي كنا نعمل معها سابقًا.

استرجاع بيانات النموذج

لطالما كان إرسال البيانات باستخدام النماذج أو الاستمارات هو الطريقة القياسية للمستخدمين لإرسال البيانات إلى خادم HTTP والتفاعل مع مواقع الويب، وعلى الرغم من انخفاض شعبية النماذج بمرور الوقت، إلا أنها لا تزال تخدم أغراضًا مختلفة لتقديم البيانات. توفر قيمة http.Request* في http.HandlerFunc طريقةً للوصول إلى هذه البيانات، بطريقة مشابهة للطريقة التي توفر بها الوصول إلى سلسلة الاستعلام ومتن الطلب. سنعدّل في هذا القسم الدالة getHello لتلقي اسم مستخدم من نموذج والرد بتحية شخصية.

لنفتح ملف "main.go" ونعدّل getHello لاستخدام التابع PostFormValue من http.Request*:

...

func getHello(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    fmt.Printf("%s: got /hello request\n", ctx.Value(keyServerAddr))

    myName := r.PostFormValue("myName")
    if myName == "" {
        myName = "HTTP"
    }
    io.WriteString(w, fmt.Sprintf("Hello, %s!\n", myName))
}

...

الآن في دالة getHello المحدَّثة، تجري قراءة قيم النموذج المرسلة إلى دالة المعالجة والبحث عن قيمة تسمى myName. إذا لم يُعثر على القيمة أو كانت سلسلة فارغة، تُضبط القيمة الافتراضية HTTP إلى المتغير myName لمنع عرض اسم فارغ على الصفحة. نعدّل أيضًا الخرج المرسل إلى المستخدم لكي يعرض الاسم الذي قدمه أو HTTP إذا لم يُقدّم أي اسم.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

نُشغّل الآن أوامر curl (في الطرفية الثانية)، لتقديم طلب POST مع خيار X POST-، وبدلًا من استخدام الخيار b-، نستخدم الخيار 'F 'myName=Sammy لتضمين بيانات النموذج مع حقل myName والقيمة Sammy:

curl -X POST -F 'myName=Sammy' 'http://localhost:3333/hello'

سيكون الخرج:

Hello, Sammy!

يُستخدم التابع r.PostFormValue في getHello لاسترداد قيمة حقل النموذج myName. يبحث هذا التابع تحديدًا عن القيم المنشورة (البيانات المرسلة من العميل إلى الخادم) في متن الطلب. يمكن أيضًا استخدام التابع r.FormValue، والذي يتضمن كلًا من متن النموذج وأي قيم أخرى في سلسلة الاستعلام. إذا استخدمنا ("r.FormValue("myName وأزلنا الخيار F-، فيمكن تضمين myName = Sammy في سلسلة الاستعلام لرؤية القيمة Sammy.

يوصى عمومًا بأن نكون أكثر صرامة وأن نستخدم الدالة r.PostFormValue إذا كنا نريد تحديدًا استرداد القيم من متن النموذج، إذ تتجنب هذه الدالة التعارضات أو الأخطاء المحتملة التي قد تنشأ عن خلط قيم النموذج من مصادر مختلفة. إذًا، تعد الدالة r.PostFormValue خيارًا أكثر أمانًا عند التعامل مع بيانات النموذج، لكن إذا كنا نحتاج إلى المرونة في وضع البيانات في كل من متن النموذج وسلسلة الاستعلام، فربما نضطر إلى الدالة الأخرى.

عند النظر إلى سجلات الخادم، سنرى أن طلب hello/ قد جرى تسجيله بطريقة مشابهة للطلبات السابقة:

[::]:3333: got /hello request

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "CONTROL+C".

عدّلنا في هذا القسم البرنامج لقراءة اسم من بيانات النموذج المنشورة على الصفحة ثم إعادة هذا الاسم إلى المستخدم.

يمكن أن تسوء بعض الأشياء في هذه المرحلة من البرنامج، لا سيما عند التعامل مع أحد الطلبات، ولن يجري إعلام المستخدمين. لنعدّل في القسم التالي دوال المعالجة لإرجاع رموز حالة HTTP والترويسات headers.

الرد باستجابة تتضمن الترويسات ورمز الحالة

هناك بعض الميزات المستخدمة خلف الكواليس ضمن بروتوكول HTTP لتسهيل الاتصال الفعّال بين المتصفحات والخوادم. إحدى هذه الميزات هي "رموز الحالة"، والتي تعمل مثل وسيلة للخادم لتوضّح للعميل ما إذا كان الطلب ناجحًا أو واجه أي مشكلات في أي من الطرفين.

آلية اتصال أخرى تستخدمها خوادم وعملاء HTTP هي استخدام "حقول الترويسة header fields"، التي تتكون من أزواج ذات قيمة مفتاح يجري تبادلها بين العميل والخادم لنقل المعلومات عن أنفسهم. يمتلك بروتوكول HTTP عدة ترويسات معرّفة مسبقًا، مثل ترويسة Accept، التي يستخدمها العميل لإعلام الخادم بنوع البيانات التي يمكنه التعامل معها. يمكن أيضًا تعريف ترويسات خاصة باستخدام البادئة x- متبوعة بالاسم المطلوب.

سنعمل في هذا القسم على تحسين البرنامج بجعل حقل النموذج myName في دالة المعالجة getHello حقلًا إلزاميًا. بالتالي، إذا لم تُعطى قيمة للحقل myName، فسيستجيب الخادم للعميل برمز الحالة "Bad Request طلب غير صالح" وتضمين الترويسة x-missing-field في الاستجابة، والتي تُعلم العميل بالحقل المفقود من الطلب.

لنفتح ملف "main.go" ونعدّل الدالة getHello وفقًا لما ذُكر:

...

func getHello(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    fmt.Printf("%s: got /hello request\n", ctx.Value(keyServerAddr))

    myName := r.PostFormValue("myName")
    if myName == "" {
        w.Header().Set("x-missing-field", "myName")
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    io.WriteString(w, fmt.Sprintf("Hello, %s!\n", myName))
}

…

سابقًا: إذا كان حقل myName فارغًا، كان يُسند إليه قيمة افتراضية، أما الآن ضمن الدالة getHello المُحدَّثة، نُرسل رسالة خطأ إلى العميل. يُستخدم بدايةً التابع w.Header().Set لضبط الترويسة x-missing-field بقيمة myName في ترويسة الاستجابة، ثم التابع w.WriteHeader لكتابة ترويسات الاستجابة ورمز الحالة "طلب غير صالح" إلى العميل. أخيرًا تُستخدم تعليمة return لضمان إنهاء الدالة وعدم إرسال استجابة إضافية.

من الضروري التأكد من ضبط الترويسات وإرسال رمز الحالة بالترتيب الصحيح، إذ يجب إرسال جميع الترويسات في بروتوكول HTTP قبل الجسم، مما يعني أنه يجب إجراء أي تعديلات على ()w.Header قبل استدعاء w.WriteHeader. عند استدعاء w.WriteHeader يُرسل رمز الحالة والترويسات، ويمكن كتابة المتن بعد ذلك حصرًا. يجب اتباع هذا الأمر لضمان حسن سير استجابة HTTP.

لنُشغّل ملف البرنامج "main.go" بعد حفظه من خلال الأمر go run:

$ go run main.go

نُشغّل الآن الأمر curl -X POST (في الطرفية الثانية) مع المسار hello/ وبدون تضمين F- لإرسال بيانات النموذج. نحتاج أيضًا إلى تضمين الخيار v- لإخبار curl بإظهار الخرج المطوّل حتى نتمكن من رؤية جميع الترويسات والخرج للطلب:

curl -v -X POST 'http://localhost:3333/hello'

سنرى هذه المرة الكثير من المعلومات بسبب استخدامنا الخيار v-:

*   Trying ::1:3333...
* Connected to localhost (::1) port 3333 (#0)
> POST /hello HTTP/1.1
> Host: localhost:3333
> User-Agent: curl/7.77.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 400 Bad Request
< X-Missing-Field: myName
< Date: Wed, 02 Mar 2022 03:51:54 GMT
< Content-Length: 0
< 
* Connection #0 to host localhost left intact

تشير الأسطر الأولى إلى أن curl تحاول إنشاء اتصال بالخادم عند منفذ المضيف المحلي 3333. الأسطر المسبوقة بالرمز < تمثل الطلب المُرسل بواسطة curl، إذ يُرسل طلب POST إلى العنوان أو المسار hello/ باستخدام بروتوكول HTTP 1.1. يتضمن الطلب ترويسات مثل User-Agent و Accept و Host. والجدير بالذكر أن الطلب لا يتضمن متنًا، كما هو موضح في السطر الفارغ.

تظهر استجابة الخادم بالسابقة > بعد إرسال الطلب. يشير السطر الأول إلى أن الخادم قد استجاب برمز حالة "طلب غير صالح" (المعروفة برمز الحالة 400)، كما تُضمّن الترويسة X-Missing-Field التي جرى ضبطها في ترويسة استجابة الخادم، مع تحديد أن الحقل المفقود هو myName. ينتهي الرد بدون أي محتوى في المتن، وهذا ما يتضح من طول المحتوى 0.

إذا نظرنا مرةً أخرى إلى خرج الخادم، فسنرى طلب hello/ للخادم الذي جرت معالجته في الخرج:

[::]:3333: got /hello request

سيستمر البرنامج بالعمل، لذا يجب علينا إيقافه يدويًا من خلال الضغط على المفتاحين "CONTROL+C".

عدّلنا في هذا القسم خادم HTTP ليشمل التحقق من صحة إرسال الطلب hello/. إذا لم يُقدّم اسم في في الطلب، تُضبط ترويسة باستخدام التابع w.Header(). Set للإشارة إلى الحقل المفقود. يُستخدم التابع w.WriteHeader بعد ذلك، لكتابة الترويسات إلى العميل، جنبًا إلى جنب مع رمز الحالة التي تشير إلى "طلب غير صالح". إذًا يُخبر الخادم العميل بوجود مشكلة في الطلب من خلال ضبط الترويسة ورمز الحالة. يسمح هذا الأسلوب بمعالجة الأخطاء بطريقة صحيحة ويوفر ملاحظات للعميل فيما يتعلق بحقل النموذج المفقود.

الخاتمة

تعلمنا كيفية إنشاء خادم HTTP في لغة جو باستخدام حزمة net/http، وطوّرنا الخادم باستخدام مجمّع مخصص للخادم واستخدام نسخhttp.Server متعددة. اسكتشفنا أيضًا طرقًا مختلفة للتعامل مع مُدخلات المستخدم، مثل قيم سلسلة الاستعلام ومتن الطلب وبيانات النموذج. تحققنا أيضًا من صحة الطلب من خلال إعادة ترويسات HTTP مخصصة ورموز حالة إلى العميل.

تتمثل إحدى نقاط القوة في نظام بروتوكول HTTP في توافقه مع العديد من الأطر التي تتكامل بسلاسة مع حزمة net/http. توضح مشاريع مثل github.com/go-chi/chi ذلك من خلال توسيع وظائف خادم http القياسي من خلال تحقيق الواجهة http.Handler. يتيح ذلك للمطورين الاستفادة من البرامج الوسيطة والأدوات الأخرى دون الحاجة لإعادة كتابة المنطق الخاص الخادم، وهذا يسمح بالتركيز على إنشاء برمجيات وسيطة middleware وأدوات أخرى لتحسين الأداء بدلًا من التعامل مع الوظائف الأساسية فقط.

توفر حزمة net/http المزيد من الإمكانات التي لم نتناولها في هذا المقال، مثل العمل مع ملفات تعريف الارتباط وخدمة حركة مرور HTTPS.

ترجمة -وبتصرف- للمقال How To Make an HTTP Server in Go لصاحبه Kristin Davidson.

اقرأ أيضًا

• المقال السابق كيفية استخدام صيغة جسون JSON في لغة جو Go.
• مدخل إلى خادم الويبن.
• مدخل إلى HTTP: شرح التخاطب بين العميل والخادم.
• رموز الحالة status codes.

إحدى الخصائص المهمة في البرامج الحديثة هو إمكانية التواصل مع البرامج الأخرى، سواءٌ كان برنامج جو يتحقق ما إذا كان لدى المستخدم حق الوصول إلى برنامج آخر، أو برنامج جافا سكريبت JavaScript يحصل على قائمة بالطلبات السابقة لعرضها على موقع ويب، أو برنامج رست Rust يقرأ نتائج اختبار من ملف، فهناك حاجة إلى طريقة نزوّد البرامج من خلالها بالبيانات. لدى أغلب لغات البرمجة طريقة خاصة في تخزين البيانات داخليًّا، والتي لا تفهمها اللغات البرمجية الأخرى. للسماح لهذه اللغات بالتفاعل مع بعضها، يجب تحويل البيانات إلى تنسيق أو صيغة مشتركة يمكنهم فهمها جميعًا. إحدى هذه الصيغ هي صيغة جسون JSON، إنها وسيلة شائعة لنقل البيانات عبر الإنترنت وكذلك بين البرامج في نفس النظام. تمتلك لغة جو والعديد من لغات البرمجة الأخرى طريقة لتحويل البيانات من وإلى صيغة جسون في مكتباتها القياسية.

سنُنشئ في هذا المقال برنامجًا يستخدم حزمة encoding/json لتحويل صيغة البيانات من النوع map إلى بيانات جسون، ثم من النوع struct إلى جسون، كما سنتعلم كيفية إجراء تحويل عكسي.

المتطلبات

• إصدار مُثبّت من جو 1.16 أو أعلى، ويمكنك الاستعانة بمقال تثبيت لغة جو Go وإعداد بيئة برمجة محلية على أبونتو Ubuntu لإعداده.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على نظام ماك macOS.
• تثبيت لغة جو وإعداد بيئة برمجة محلية على ويندوز.
• (اختياري) معرفة بكيفية التعامل مع التاريخ والوقت في لغة جو. يمكنك الاطلاع على مقالة استخدام التاريخ والوقت في لغة جو Go.
• معرفة مسبقة بصيغةجسون.
• معرفة مسبقة بكيفية التعامل مع وسوم البنية Struct tags لتخصيص حقول البنية. يمكنك الاطلاع على مقال استخدام وسوم البنية Struct Tags في لغة جو.

استخدام الروابط Maps لتوليد بيانات بصيغة JSON

توفر حزمة encoding/json بعض الدوال لتحويل البيانات من وإلى جسون JSON. الدالة الأولى هي json.Marshal. التنظيم Marshaling أو المعروف أيضًا باسم السلسلة Serialization، هو عملية تحويل بيانات البرنامج من الذاكرة إلى تنسيق يمكن نقله أو حفظه في مكان آخر، وهذا ما تفعله الدالة json.Marshal في لغة جو، إذ تحول بيانات البرنامج قيد التشغيل (الموجود في الذاكرة) إلى بيانات جسون. تقبل هذه الدالة أي قيمة من النوع واجهة {}interface لتنظيمها بصيغة جسون، لذلك يُسمح بتمرير أي قيمة مثل معامل، لتُعيد الدالة البيانات ممثلة بصيغة جسون في النتيجة.

سننشئ في هذا القسم برنامجًا يستخدم دالة json.Marshal لإنشاء ملف جسون يحتوي أنواعًا مختلفة من البيانات من قيم map، ثم سنطبع هذه القيم على شاشة الخرج. تُمثّل بيانات جسون غالبًا على شكل كائن مفاتيحه من سلاسل نصيّة وقيمه من أنواع مختلفة، وهذا يُشبه آلية تمثيل البيانات في روابط جو، لذا فإن الطريقة الأفضل لإنشاء بيانات جسون في لغة جو هي وضع البيانات ضمن رابطة map مع مفاتيح من النوع string وقيم من النوع {}interface. تٌفسّر مفاتيح map مباشرةً على أنها مفاتيح جسون، ويمكن أن تكون قيم النوع interface أي نوع بيانات في لغة جو، مثل int، أو string، أو حتى {}map[string]interface

لبدء استخدام الحزمة encoding/json، وكما هو معتاد، سنحتاج لبدء إنشاء برامجنا إلى إنشاء مجلد للعمل ووضع الملفات فيه، ويمكن وضع المجلد في أي مكان على الحاسب، إذ يكون للعديد من المبرمجين عادةً مجلدٌ يضعون داخله كافة مشاريعهم. سنستخدم في هذا المقال مجلدًا باسم "projects"، لذا فلننشئ هذا المجلد وننتقل إليه:

$ mkdir projects
$ cd projects

الآن، من داخل هذا المجلد، سنشغّل الأمر mkdir لإنشاء مجلد "jsondata" ثم سنستخدم cd للانتقال إليه:

$ mkdir jsondata
$ cd jsondata

يمكننا الآن فتح ملف "main.go" باستخدام محرر نانو nano أو أي محرر آخر تريده:

$ nano main.go

نضيف داخل ملف "main.go" دالة main لتشغيل البرنامج، ثم نضيف قيمة {}map[string]interface مع مفاتيح وقيم من أنواع مختلفة، ثم نستخدم الدالة json.Marshal لتحويل بيانات map إلى بيانات جسون:

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    data := map[string]interface{}{
        "intValue":    1234,
        "boolValue":   true,
        "stringValue": "hello!",
        "objectValue": map[string]interface{}{
            "arrayValue": []int{1, 2, 3, 4},
        },
    }

    jsonData, err := json.Marshal(data)
    if err != nil {
        fmt.Printf("could not marshal json: %s\n", err)
        return
    }

    fmt.Printf("json data: %s\n", jsonData)
}

نلاحظ في المتغير data أن كل قيمة لديها مفتاح string، لكن قيم هذه المفاتيح تختلف، فأحدها int وأحدها bool والأخرى هي رابط {}map[string]interface مع قيم int بداخلها. عند تمرير المتغير data إلى json.Marshal، ستنظر الدالة إلى جميع القيم التي يتضمنها الرابط وتحدد نوعها وكيفية تمثيلها في جسون، وإذا حدثت مشكلة في تفسير بيانات الرابط، ستُعيد خطأ يصف المشكلة. إذا نجحت العملية، سيتضمّن المتغير jsonData بيانات من النوع byte[] تُمثّل البيانات التي جرى تنظيمها إلى صيغة جسون. بما أن byte[] يمكن تحويلها إلى قيمة string باستخدام (myString := string(jsonData أو العنصر النائب s% ضمن تنسيق سلسلة، يمكننا طباعة بيانات جسون على شاشة الخرج باستخدام دالة الطباعة fmt.Printf.

بعد حفظ وإغلاق الملف، لنُشغّل ملف البرنامج "main.go" من خلال الأمر go run:

$ go run main.go

سيكون الخرج على النحو التالي:

json data: {"boolValue":true,"intValue":1234,"objectValue":{"arrayValue":[1,2,3,4]},"stringValue":"hello!"}

نلاحظ من الخرج أن قيمة جسون هي كائن مُمثّل بأقواس معقوصة curly braces {} تحيط به، وأن جميع قيم المتغير data موجودة ضمن هذين القوسين. نلاحظ أيضًا أن رابط المفتاح objectValue الذي هو {}map[string]interface قد جرى تفسيره إلى كائن جسون آخر مُمثّل بأقواس معقوصة {} تحيط به أيضًا، ويتضمن أيضًا المفتاح arrayValue بداخله مع مصفوفة القيم المقابلة [1،2،3،4].

ترميز البيانات الزمنية في جسون

لا تقتصر قدرات الحزمة encoding/json على إمكانية تمثيل البيانات من النوع string و int، إذ يمكنها التعامل مع أنواع أعقد مثل البيانات الزمنية من النوع time.Time من الحزمة time.

لنفتح ملف البرنامج "main.go" مرةً أخرى ونضيف قيمة من النوع time.Time باستخدام الدالة time.Date:

package main

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

func main() {
    data := map[string]interface{}{
        "intValue":    1234,
        "boolValue":   true,
        "stringValue": "hello!",
        "dateValue":   time.Date(2022, 3, 2, 9, 10, 0, 0, time.UTC),
        "objectValue": map[string]interface{}{
            "arrayValue": []int{1, 2, 3, 4},
        },
    }

    ...
}

يؤدي هذا التعديل إلى ضبط التاريخ على March 2, 2022 والوقت على ‎9:10:00 AM في المنطقة الزمنية UTC وربطهم بالمفتاح dateValue. لنُشغّل ملف البرنامج "main.go" من خلال الأمر go run:

$ go run main.go

سيعطي الخرج التالي:

json data: {"boolValue":true,"dateValue":"2022-03-02T09:10:00Z","intValue":1234,"objectValue":{"arrayValue":[1,2,3,4]},"stringValue":"hello!"}

نلاحظ هذه المرة في الخرج الحقل dateValue ضمن بيانات جسون، وأن الوقت مُنسّقٌ وفقًا لتنسيق RFC 3339، وهو تنسيق شائع يُستخدم لنقل التواريخ والأوقات على أنها قيم string.

ترميز قيم Null في جسون

قد نحتاج إلى التعامل مع قيم null، وتحويلها إلى صيغة جسون أيضًا. يمكن لحزمة encoding/json تولي هذه المهمة أيضًا، إذ يمكننا التعامل مع قيم nil (تُقابل قيم null) مثل أي قيمة من نوع آخر ضمن الرابط.

لنفتح ملف "main.go" ولنضع قيمتي null ضمن الرابط:

...

func main() {
    data := map[string]interface{}{
        "intValue":    1234,
        "boolValue":   true,
        "stringValue": "hello!",
                "dateValue":   time.Date(2022, 3, 2, 9, 10, 0, 0, time.UTC),
        "objectValue": map[string]interface{}{
            "arrayValue": []int{1, 2, 3, 4},
        },
        "nullStringValue": nil,
        "nullIntValue":    nil,
    }

    ...
}

وضعنا في الشيفرة أعلاه قيمتي null مع مفتاحين مختلفين، هما nullStringValue و nullIntValue على التوالي، وعلى الرغم من أن أسماء المفاتيح تُشير إلى قيم string و int، لكن هي ليست كذلك (مجرد أسماء). طبعًا كل القيم ضمن الرابط مُشتقة من النوع {}interface والقيمة nil هي قيمة مُحتملة لهذا النوع وبالتالي تُفسّر على أنها null فقط، وهذا كل شيء. لنُشغّل ملف البرنامج "main.go" من خلال الأمر go run:

$ go run main.go

سيكون الخرج كما يلي:

json data: {"boolValue":true,"dateValue":"2022-03-02T09:10:00Z","intValue":1234,"nullIntValue":null,"nullStringValue":null,"objectValue":{"arrayValue":[1,2,3,4]},"stringValue":"hello!"}

نلاحظ في الخرج أن الحقلين nullIntValue و nullStringValue مُضمنان مع قيمة null لكل منهما، بالتالي تمكنا من استخدام {}map[string]interface مع قيم null دون أية مشاكل.

أنشأنا في هذا القسم برنامجًا يمكنه تحويل قيم بيانات من النوع {}map[string]interface إلى بيانات جسون. أضفنا بعد ذلك حقلًا يستخدم بيانات زمنية من النوع time.Time ضمن الرابط، وأخيرًا أضفنا حقلين يستخدمان القيمة null.

بالرغم من مرونة استخدام {}map[string]interface لتحويل البيانات إلى بيانات جسون، إلا أنه قد يكون عُرضةً لحدوث أخطاء غير مقصودة، ولا سيما إذا كنا بحاجة إلى إرسال نفس البيانات إلى عدة أماكن. إذا أرسلنا نُسخًا من هذه البيانات إلى أكثر من مكان ضمن الشيفرة، فربما نُغيّر عن طريق الخطأ اسم حقل أو نضع قيمة غير صحيحة ضمن حقل. في هكذا حالات ربما يكون من المفيد استخدام النوع struct لتمثيل البيانات التي نُريد تحويلها إلى جسون.

استخدام البنى Structs لتوليد بيانات بصيغة جسون

تُعَدّ جو لغةً ثابتة الأنواع statically-typed language مثل لغة C وجافا Java و ++C، وهذا يعني أن كل تعليمة في البرنامج تُفحَص في وقت التصريف. تتمثل فائدة ذلك في السماح للمُصرّف باستنتاج نوع المتغيرات والتحقق منها وفرض التناسق بين قيم المتغيرات. تستفيد الحزمة encoding/json من ذلك من خلال تعريف بنية struct تُمثّل بيانات جسون. يمكننا التحكم في كيفية تفسير البيانات التي تتضمنها البنية باستخدام وسوم البنية Struct tags. سنعدّل البرنامج السابق خلال هذا القسم، لاستخدام بنية بدلًا من رابط، لتوليد بيانات جسون.

عند استخدام struct لتعريف بيانات جسون، يجب علينا تصدير أسماء الحقول (وليس اسم النوع struct نفسه) التي نريد تحويلها إلى جسون، وذلك fأن نبدأ أسماء الحقول بحرف كبير (أي بدلًا من كتابة intValue نكتب IntValue) وإلا لن تكون الحزمة encoding/json قادرةً على الوصول إلى هذه الحقول لتحويلها إلى جسون.

الآن بالنسبة لأسماء الحقول، إذا لم نستخدم وسوم البنية للتحكم في تسمية هذه الحقول، ستُفسّر كما هي مباشرةً ضمن البنية. قد يكون استخدام الأسماء الافتراضية هو ما نريده في بيانات جسون، وذلك وفقًا للطريقة التي نرغب بها بتنسيق بياناتنا، وبذلك لن نحتاج في هذه الحالة إلى أية وسوم. يستخدم العديد من المبرمجين تنسيقات أسماء، مثل intValue، أو int_value مع حقول البيانات، وسنحتاج في هذه الحالة إلى وسوم البنية للتحكم في كيفية تفسير هذه الأسماء.

سيكون لدينا في المثال التالي بنية struct مع حقل وحيد اسمه IntValue وسنحول هذه البنية إلى صيغة جسون:

type myInt struct {
    IntValue int
}

data := &myInt{IntValue: 1234}

إذا حوّلنا المتغير data إلى صيغة جسون باستخدام الدالة json.Marshal، سنرى الخرج التالي:

{"IntValue":1234}

لكن لو كنا نريد أن يكون اسم الحقل في ملف جسون هو intValue بدلًا من IntValue، سنحتاج إلى إخبار encoding/json بذلك. بما أن json.Marshal لا تعرف ماذا نتوقع أن يكون اسم بيانات جسون، سنحتاج إلى إخبارها من خلال إضافة وسم البنية json بعد اسم الحقل مباشرةً مع إرفاقه بالاسم الذي نريد أن يظهر به في صيغة جسون. إذًا، من خلال إضافة هذا الوسم إلى الحقل IntValue مع الاسم الذي نريد يظهر به intValue، ستستخدم الدالة json.Marshal الاسم الذي نريده اسمًا للحقل ضمن صيغة جسون:

type myInt struct {
    IntValue int `json:"intValue"`
}

data := &myInt{IntValue: 1234}

إذا حوّلنا المتغير data إلى صيغة جسون باستخدام الدالة json.Marshal، سنرى الخرج التالي، وكما نلاحظ فإنه يستخدم اسم الحقل الذي نريده:

{"intValue":1234}

سنعدل البرنامج الآن لتعريف نوع بيانات struct يُمكن تحويله إلى بيانات جسون. سنضيف بنيةً باسم myJSON لتمثيل البيانات بطريقة يمكن تحويلها إلى جسون ونضيف البنية myObject التي ستكون قيمة للحقل ObjectValue ضمن البنية myJSON. سنضيف أيضًا وسمًا لكل اسم حقل ضمن البنية myJSON لتحديد الاسم الذي نريد أن يظهر به الحقل ضمن بيانات جسون. يجب أيضًا أن نحدّث الإسناد الخاص بالمتغير dataبحيث نسند له بنية myJSON مع التصريح عنه بنفس الطريقة التي نتعامل مع بنى جو الأخرى.

...

type myJSON struct {
    IntValue        int       `json:"intValue"`
    BoolValue       bool      `json:"boolValue"`
    StringValue     string    `json:"stringValue"`
    DateValue       time.Time `json:"dateValue"`
    ObjectValue     *myObject `json:"objectValue"`
    NullStringValue *string   `json:"nullStringValue"`
    NullIntValue    *int      `json:"nullIntValue"`
}

type myObject struct {
    ArrayValue []int `json:"arrayValue"`
}

func main() {
    otherInt := 4321
    data := &myJSON{
        IntValue:    1234,
        BoolValue:   true,
        StringValue: "hello!",
        DateValue:   time.Date(2022, 3, 2, 9, 10, 0, 0, time.UTC),
        ObjectValue: &myObject{
            ArrayValue: []int{1, 2, 3, 4},
        },
        NullStringValue: nil,
        NullIntValue:    &otherInt,
    }

    ...
}

تُشبه معظم التغييرات في الشيفرة أعلاه ما فعلناه في المثال السابق مع الحقل IntValue، إلا أن هناك بعض الأشياء تستحق الإشارة إليها. أحد هذه الأشياء هو الحقل ObjectValue الذي يستخدم قيمةً مرجعية myObject* لإخبار دالة json.Marshal -التي تؤدي عملية التنظيم- إلى وجود قيمة مرجعية من النوع myObject أو قيمة nil. بهذه الطريقة نكون قد عرّفنا كائن جسون بأكثر من طبقة، وفي حال كانت هذه الطريقة مطلوبة، سيكون لدينا بنيةً أخرى من نوع struct داخل النوع myObject، وهكذا، وبالتالي نلاحظ أنه بإمكاننا تعريف كائنات جسون أعقد وأعقد باستخدام أنواع struct وفقًا لحاجتنا.

واحد من الأشياء الأخرى التي تستحق الذكر هي الحقلين NullStringValue و NullIntValue، وعلى عكس StringValue و IntValue؛ أنواع هذه القيم هي أنواع مرجعية int* و string*، وقيمها الافتراضية هي قيم صفريّة أي nil وهذا يُقابل القيمة 0 لنوع البيانات int والسلسلة الفارغة '' لنوع البيانات string. يمكننا من الكلام السابق أن نستنتج أنه في حال أردنا التعبير عن قيمة من نوع ما تحتمل أن تكون nil، فيجب أن نجعلها قيمةً مرجعية. مثلًا لو كنا نريد أن نعبر عن قيمة حقل تُمثّل إجابة مُستخدم عن سؤال ما، فهنا قد يُجيب المُستخدم عن السؤال أو قد لا يُجيب (نضع niil).

نُعدّل قيمة الحقل NullIntValue بضبطه على القيمة 4321 لنُظهر كيف يمكن إسناد قيمة لنوع مرجعي مثل int*. تجدر الإشارة إلى أنه في لغة جو، يمكننا إنشاء مراجع لأنواع البيانات الأولية primitive types فقط، مثل int و string باستخدام المتغيرات. إذًا، لإسناد قيمة إلى الحقل NullIntValue، نُسند أولًا قيمةً إلى متغير آخر otherInt، ثم نحصل على مرجع منه otherInt& (بدلًا من كتابة 4321& مباشرةً).

لنُشغّل ملف البرنامج "main.go" من خلال الأمر go run:

$ go run main.go

سيكون الخرج على النحو التالي:

json data: {"intValue":1234,"boolValue":true,"stringValue":"hello!","dateValue":"2022-03-02T09:10:00Z","objectValue":{"arrayValue":[1,2,3,4]},"nullStringValue":null,"nullIntValue":4321}

نلاحظ أن هذا الناتج هو نفسه عندما استخدمنا {}map[string]interface، باستثناء أن قيمة nullIntValue هذه المرة هي 4321 لأن هذه هي قيمة otherInt.

يستغرق الأمر في البداية بعض الوقت لتعريف البنية struct وإعداد حقولها، ولكن يمكننا بعد ذلك استخدامها مرارًا وتكرارًا في الشيفرة، وستكون النتيجة هي نفسها بغض النظر عن مكان استخدامها، كما يمكننا تعديلها من مكان واحد بدلًا من تعديلها في كل مكان تتواجد نسخة منها فيه كما في حالة الروابط map.

تتيح لنا الدالة json.Marshal إمكانية تحديد الحقول التي نُريد تضمينها في جسون، في حال كانت قيمة تلك الحقول صفريّة (أي Null وهذا يُكافئ 0 في حالة int و false في حالة bool والسلسلة الفارغة في حالة string ..إلخ). قد يكون لدينا أحيانًا كائن جسون كبير أو حقول اختيارية لا نريد تضمينها دائمًا في بيانات جسون، لذا يكون تجاهل هذه الحقول مفيدًا. يكون التحكم في تجاهل هذه الحقول -عندما تكون قيمها صفريّة أو غير صفريّة- باستخدام الخيار omitempty ضمن وسم بنية json.

لنُحدّث البرنامج السابق لإضافة الخيار omitempty إلى حقل NullStringValue وإضافة حقل جديد يسمى EmptyString مع نفس الخيار:

...

type myJSON struct {
    ...

    NullStringValue *string   `json:"nullStringValue,omitempty"`
    NullIntValue    *int      `json:"nullIntValue"`
    EmptyString     string    `json:"emptyString,omitempty"`
}

...

بعد تحويل البنية myJSON إلى بيانات جسون، سنلاحظ أن الحقل EmptyString والحقل NullStringValue غير موجودان في بيانات جسون، لأن قيمهما صفريّة.

لنُشغّل ملف البرنامج "main.go" من خلال الأمر go run:

$ go run main.go

سيكون الخرج على النحو التالي:

json data: {"intValue":1234,"boolValue":true,"stringValue":"hello!","dateValue":"2022-03-02T09:10:00Z","objectValue":{"arrayValue":[1,2,3,4]},"nullIntValue":4321}

نلاحظ أن الحقل nullStringValue لم يعد موجودًا في الخرج، لأنه يُعد حقلًا بقيمة nil، بالتالي فإن الخيار omitempty استبعده من الخرج. نفس الأمر بالنسبة للحقل emptyString، لأن قيمته صفريّة (القيمة الصفريّة تُكافئ nil كما سبق وذكرنا).

استخدمنا في هذا القسم أسلوب البُنى struct بدلًا من الروابط، لتمثيل كائن جسون في برنامجنا، ثم حولناها إلى بيانات جسون باستخدام الدالة json.Marshal. تعلمنا أيضًا كيفية تجاهل القيم الصفريّة من بيانات جسون.

هذه البيانات (بعد تحويلها لصيغة جسون) قد تُرسل إلى برامج أخرى، وبالتالي إذا كان البرنامج الآخر مكتوب بلغة جو، يجب أن نعرف كيف يمكننا قراءة هذا النوع من البيانات. يمكنك أن تتخيل الأمر على أنه برنامجي جو A و B أحدهما مُخدم والآخر عميل. يُرسل A طلبًا إلى B، فيعالجه ويرسله بصيغة جسون إلى A، ثم يقرأ A هذه البيانات. لأجل ذلك توفر الحزمة encoding/json طريقةً لفك ترميز بيانات جسون وتحويلها إلى أنواع جو المقابلة (مجرد عملية عكسية). سنتعلم في القسم التالي كيفية قراءة بيانات جسون وتحويلها إلى روابط.

تحليل بيانات جسون باستخدام الروابط

بطريقة مشابهة لما فعلناه عندما استخدمنا {}map[string]interface مثل طريقة مرنة لتوليد بيانات جسون، يمكننا استخدامها أيضًا مثل طريقة مرنة لقراءة بيانات جسون. تعمل الدالة json.Unmarshal بطريقة معاكسة للدالة json.Marshal، إذ تأخذ بيانات جسون وتحولها إلى بيانات جو، وتأخذ أيضًا متغيرًا لوضع البيانات التي جرى فك تنظيمها فيه، وتعيد إما خطأ error في حال فشل عملية التحليل أو nil في حال نجحت.

سنعدّل برنامجنا في هذا القسم، بحيث نستخدم الدالة json.Unmarshal لقراءة بيانات جسون من سلسلة وتخزينها في متغير من النوع map، وطباعة الخرج على الشاشة. لنعدّل البرنامج إذًا، بحيث نفك تنظيم البيانات باستخدام الدالة السابقة ونحولها إلى رابط {}map[string]interface. لنبدأ باستبدال المتغير data الأصلي بمتغير jsonData يحتوي على سلسلة جسون، ثم نُصرّح عن متغير data جديد على أنه {}map[string]interfac لتلقي بيانات جسون، ثم نستخدم الدالة json.Unmarshal مع هذه المتغيرات للوصول إلى بيانات جسون:

...

func main() {
    jsonData := `
        {
            "intValue":1234,
            "boolValue":true,
            "stringValue":"hello!",
            "dateValue":"2022-03-02T09:10:00Z",
            "objectValue":{
                "arrayValue":[1,2,3,4]
            },
            "nullStringValue":null,
            "nullIntValue":null
        }
    `

    var data map[string]interface{}
    err := json.Unmarshal([]byte(jsonData), &data)
    if err != nil {
        fmt.Printf("could not unmarshal json: %s\n", err)
        return
    }

    fmt.Printf("json map: %v\n", data)
}