محتويات الدورة

Go / المتقدم: السلامة والأداء وتصميم الخدمات / الدرس 18

تصميم الواجهات وعقود النشر

انقل صحة اللغة إلى واجهات ذات إصدار وإعداد وإنهاء متدرج وآثار إصدار قابلة للتكرار.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • تحديد حدود التحقق والخطأ والملكية والتوافق.
  • فحص الإعداد قبل بدء الموارد.
  • تخطيط بناء متكرر وإنهاء محدود دون نشر تلقائي.

الواجهة أكثر من توقيعات مكشوفة

تحدد الواجهة المستقرة المدخل والترتيب ومعنى nil والفراغ والملكية والأخطاء والإلغاء وسلامة التزامن. وثق تعديل الشرائح والاحتفاظ بالمراجع. قد يكسر توقيع ثابت الوعود السلوكية بين الإصدارات.

فضل واجهات صغيرة من مستهلكين فعليين وأنواعا بثوابت قابلة للفرض. اجعل الخيارات صريحة وافحص التعارض. تجنب منشئا يبدأ روتينات بلا حد أو مستمعا دون مقبض إيقاف. ينقل بدء العمل التزام عمر ينبغي كشفه.

رفض الإعداد قبل الآثار الجانبية

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

افصل التمثيل من السياسة: تتعرف strconv.Atoi على العدد وتبلغ مشاكل التحويل، ويفرض الفحص حد الخدمة. قد يأتي الإعداد من الأعلام أو البيئة ويجب أن يلتقي في التحقق نفسه. لا تطبع الأسرار في التشخيص.

go فحص خيار نشر محدود
package main

import (
	"fmt"
	"strconv"
)

func workerLimit(text string) (int, error) {
	value, err := strconv.Atoi(text)
	if err != nil {
		return 0, fmt.Errorf("worker limit: %w", err)
	}
	if value < 1 || value > 16 {
		return 0, fmt.Errorf("worker limit outside 1..16")
	}
	return value, nil
}

func main() {
	workers, err := workerLimit("4")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("workers", workers)
}
الناتج المتوقع
workers 4

تفي الأربعة الاصطناعية بالصياغة وسياسة الواحد حتى الستة عشر.

رفض شكل طلب غير موثق

فك JSON عقد حد لا مدقق أعمال تلقائيا. يرفض المثال الثاني حقولا مجهولة ويشترط غياب قيمة ثانية ثم يفحص كمية غير سالبة. حد الحجم لازم قبل فك جسم غير موثوق؛ والنص الثابت هنا محدود اصطناعي.

رفض المجهول قرار توافق مقصود؛ تسمح واجهات بالتوسع وتطلب أخرى شكلا صارما. قرر ووثق لا تفعل الإعداد عميانا. قد لا تميز القيمة الصفرية حقلا غائبا من صفر صريح فاستخدم مؤشرات أو تمثيلا آخر عند أهمية الوجود.

go حد JSON صارم لسجل واحد
package main

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

type Request struct {
	Quantity int `json:"quantity"`
}

func main() {
	decoder := json.NewDecoder(strings.NewReader(`{"quantity":3}`))
	decoder.DisallowUnknownFields()
	var request Request
	if err := decoder.Decode(&request); err != nil {
		panic(err)
	}
	var extra any
	if err := decoder.Decode(&extra); err != io.EOF {
		panic("trailing JSON value")
	}
	if request.Quantity < 0 {
		panic("negative quantity")
	}
	fmt.Println("quantity", request.Quantity)
}
الناتج المتوقع
quantity 3

يفك حقل معروف ويرفض اللاحق ويقبل فحص المجال ثلاثة.

تسجيل مدخلات أثر الإصدار الفعلية

سجل الأدوات وبيانات الوحدة وGOOS وGOARCH ووسوم البناء وإعداد cgo المهم. ليس ملف Go عالميا لكل نظام ومعمارية وبيئة libc. تعتمد افتراضات الترجمة المتقاطعة والربط الساكن على الاعتمادات والإعداد. افحص الأثر في بيئة ممثلة للهدف.

شغل التنسيق والاختبارات وvet وrace المدعومة وتحليل الثغرات المناسب ضمن إصدار مضبوط. تحتاج تحديثات الأدوات والاعتمادات مراجعة وافهم اختيار الأدوات التلقائي. يشمل التكرار الملفات المولدة والإعداد لا main.go وحدها.

الإنهاء جزء من واجهة الخدمة

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

اكشف إشارات صحة وتشغيل مفيدة دون أسرار أو تشخيص عام عرضا. ميز الجاهزية من مجرد وجود العملية. اختبر فشل البداية والإنهاء أثناء الحجب. النشر فعل مخول منفصل؛ ولا تعني مادة درس أو نجاح بناء إذن نشر.

الأخطاء الشائعة وإصلاحها

يُعد الحقل الغائب صفرا مقدما صراحة.

لماذا يحدث؟
يسجل التمثيل القيمة لا الوجود.
كيف تصلحه؟
استخدم حقلا واعيا بالوجود أو قاعدة صريحة.
كيف تتجنب تكراره؟
اختبر الغياب وnull والصفر وغير الصفر.

يبدأ الخادم قبل اكتشاف خطأ الإعداد.

لماذا يحدث؟
تداخل التحقق والآثار.
كيف تصلحه؟
حلل وافحص قبل الحصول على الموارد.
كيف تتجنب تكراره؟
اختبر رفض البداية دون فتح مستمع.

يعود الإنهاء والعاملون محجوبون.

لماذا يحدث؟
يغيب الإلغاء أو الانتظار للعمل المملوك.
كيف تصلحه؟
حدد توقفا واكتمالا لكل مورد.
كيف تتجنب تكراره؟
اختبر الإنهاء مع صفوف وإرسالات حاجبة.

اختبر فهمك

1. كانت واجهة تعيد نسخة شريحة ثم أعادت مخبأها بالتوقيع نفسه. هل تتوافق بالضرورة؟

اعرض الحل المشروح

لا؛ قد يعتمد المستدعي على تعديل النتيجة أو حفظها مستقلة. يغير الاسم البديل الملكية والتزامن رغم تطابق الأنواع. احفظ النسخ أو انشر منظورا مستعارا ثابتا بانتقال توافق مقصود أو قدم واجهة أخرى توضح الفرق.

2. حدد بداية وإنهاء أمر يملك خادم HTTP ومجموعة عاملين.

اعرض الحل المشروح

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

أهم ما تعلمته

  • يشمل التوافق العام nil والملكية والأخطاء والإلغاء.
  • تحقق قبل الآثار وسجل افتراضات البناء كاملة.
  • يحتاج الأثر القابل للنشر عقد بداية وإنهاء محدودا.

المراجع الرسمية