وصلنا في قصة الشركة الناشئة التي تبيع القهوة والتمر والهيل إلى اللحظة التي كان كل ما سبق يمهد لها: خدمة الطلبات نفسها. والمطلوب منها بسيط في وصفه وصعب في تفاصيله: قائمة المنتجات، وإنشاء طلب يحجز المخزون ويحسب الإجمالي مع ضريبة القيمة المضافة VAT بالهللة، وعرض الطلب برقمه. والتفاصيل هي التي تفرق بين خدمة تعمل في العرض التجريبي وخدمة تعمل يوم التخفيض: ماذا يحدث إذا طلب عشرون عميلاً آخر عشر قطع في نفس الثانية؟ وماذا يرى العميل إذا أرسل الكمية نصاً بدل رقم؟ وكيف تختبر كل ذلك على قاعدة بيانات حقيقية وليس على نسخة مزيفة؟ وكم ذاكرة تحتاج الخدمة، وكم طلباً في الثانية تتحمل في Container بمعالجين؟
وهذا المقال الرابع في مرحلة لغة Go للمطورين، وفيه نبني نفس الخدمة التي يبنيها كل مسار لغة في هذا القسم بنفس المواصفات بالضبط، حتى تقارن بين اللغات على أرض واحدة: نفس جداول PostgreSQL 17، ونفس قواعد الضريبة والأخطاء، ونفس الاختبارات، ونفس طريقة القياس. وفي Go نبنيها بالطريقة الأكثر شيوعاً في مجتمع اللغة: المكتبة القياسية net/http دون إطار عمل Framework، ومكتبة pgx لقاعدة البيانات، وهي المكتبة الخارجية الوحيدة في المشروع. وإذا كنت تريد الصورة العامة لتصميم واجهات REST قبل الكود، فقد شرحناها في مقال تصميم واجهات API.
وسوف نناقش في هذا المقال ما يلي:
- المواصفات المشتركة: الجداول والطرق والردود، ولماذا لا نحتاج إطار عمل في Go.
- شكل المشروع: الحزم
moneyوstoreوapiوcmd/orders، ودور كل منها. - طبقة البيانات بـ pgx: مجمع الاتصالات، والمعاملة الواحدة التي تقفل الأسطر وتفحص وتنقص وتدخل.
- طبقة HTTP: الموجه الجديد في Go 1.22، والتحقق، وتحويل الأخطاء إلى 400 و404 و409، والحماية من الـ panic.
- الإعداد والإيقاف الهادئ Graceful Shutdown ومهلات السيرفر.
- الاختبارات: اختبار وحدة للضريبة، واختبار HTTP بنسخة مزيفة، واختبار تكامل على PostgreSQL حقيقي، واختبار العشرين طلباً المتزامنة، ثم ماذا يحدث إذا حذفنا
FOR UPDATE. - الـ Dockerfile على مرحلتين، والقياس: حجم الـ Image، وزمن البدء، والذاكرة، و
wrk، مع ما لا تقوله الأرقام.
المواصفات المشتركة Specification: نفس الخدمة في كل لغة
المخطط Schema التالي هو نفسه في كل مقالات «خدمة حقيقية» في هذا المسار، وهو في الملف initdb/01-schema.sql الذي ينفذه Container قاعدة البيانات عند أول تشغيل:
-- Shared schema of the orders service (identical in every language of the track)
CREATE TABLE IF NOT EXISTS products (
id serial PRIMARY KEY,
name_ar text NOT NULL,
price_halalas int NOT NULL CHECK (price_halalas >= 0),
stock int NOT NULL CHECK (stock >= 0)
);
CREATE TABLE IF NOT EXISTS orders (
id serial PRIMARY KEY,
created_at timestamptz DEFAULT now(),
total_halalas int NOT NULL
);
CREATE TABLE IF NOT EXISTS order_items (
order_id int NOT NULL REFERENCES orders(id),
product_id int NOT NULL REFERENCES products(id),
qty int NOT NULL CHECK (qty > 0),
price_halalas int NOT NULL
);
INSERT INTO products (name_ar, price_halalas, stock) VALUES
('قهوة عربية مختصة 250 غرام', 4500, 100),
('تمر سكري 1 كيلو', 3800, 100),
('هيل حب 100 غرام', 990, 10);ولاحظ ثلاثة قرارات في هذا المخطط: كل المبالغ بالهللة كأرقام صحيحة، لأن الأرقام العشرية لا تصلح للمال كما شرحنا في مقال الأرقام العشرية Floating Point. والقيد CHECK (stock >= 0) على المخزون، وهو خط الدفاع الأخير الذي سوف نرى قيمته بأعيننا في قسم الاختبارات. وسعر الوحدة يحفظ في order_items وقت الطلب، لأن سعر المنتج قد يتغير غداً، والفاتورة يجب أن تبقى كما كانت.
والطرق ثلاث: GET /products يرجع المنتجات، وPOST /orders يستقبل {"items":[{"product_id":3,"qty":3}]} وينشئ الطلب في معاملة واحدة تقفل الأسطر وتفحص المخزون وتنقصه وتدخل الطلب، مع ضريبة 15% على المجموع بالهللة تقرب نصفها إلى الأعلى، وGET /orders/{id} يرجع الطلب بأسطره. والأخطاء محددة: 400 للمدخلات الخاطئة، و409 للمخزون الذي لا يكفي، و404 للطلب غير الموجود.
وقد يتساءل البعض: لماذا لا نستخدم إطار عمل مثل Gin أو Echo أو Fiber، وهي مشهورة جداً؟ والإجابة أن هذه الأطر جاءت في وقت كان فيه الموجه في المكتبة القياسية لا يفهم طريقة HTTP ولا معاملات المسار، فكان كل مشروع يحتاج مكتبة توجيه. ومنذ Go 1.22 صار الموجه http.ServeMux يقبل أنماطاً مثل POST /orders وGET /orders/{id}، ويرجع 405 وحده للطريقة غير المسموحة، كما تشرح تدوينة تحسينات التوجيه، فلم يعد للإطار في خدمة مثل خدمتنا إلا فائدة صغيرة، مقابل اعتماد إضافي وواجهة خاصة به تختلف عن http.Handler التي تعرفها كل مكتبات Go. ولكن لا بأس بإطار عمل في فريق تعود عليه، فهذه ليست قاعدة، وإنما أسلوب المكتبة القياسية هو ما سوف تجده في أغلب الكود الذي تقرؤه.
شكل المشروع Project Layout: أربع حزم
الصورة التالية تبين طريق الطلب من العميل إلى قاعدة البيانات، والحزمة المسؤولة عن كل خطوة:

وهذا التقسيم بالضبط ما شرحناه في المقال الأول عن المجلد internal وفي المقال الثاني عن الواجهات التي يعرفها المستهلك: الحزمة money لا تعتمد على شيء، والحزمة store تعتمد على money وpgx، والحزمة api تعرف واجهة صغيرة لما تحتاجه من store، والبرنامج في cmd/orders هو الوحيد الذي يعرف كل شيء ويربطه ببعضه. والكود كاملاً في مجلد lab، وسوف نعرض هنا الأجزاء المهمة.
دالة الضريبة VAT: أصغر حزمة وأهمها
// Package money keeps every amount in integer halalas (1 SAR = 100 halalas).
package money
// VATPercent is the Saudi VAT rate.
const VATPercent = 15
// VAT returns 15% of subtotal in halalas, rounded half up.
// 2970 * 15 = 44550; (44550 + 50) / 100 = 446.
func VAT(subtotal int64) int64 {
return (subtotal*VATPercent + 50) / 100
}
// Totals is subtotal, VAT and total of one order.
type Totals struct {
Subtotal int64 `json:"subtotal_halalas"`
VAT int64 `json:"vat_halalas"`
Total int64 `json:"total_halalas"`
}
// Line is one priced line: unit price in halalas and quantity.
type Line struct {
PriceHalalas int64
Qty int64
}
// Compute adds the lines, then the VAT on the subtotal (not per line).
func Compute(lines []Line) Totals {
var t Totals
for _, l := range lines {
t.Subtotal += l.PriceHalalas * l.Qty
}
t.VAT = VAT(t.Subtotal)
t.Total = t.Subtotal + t.VAT
return t
}الضريبة على المجموع وليس على كل سطر، لأن تقريب كل سطر ثم الجمع قد يختلف بهللة عن تقريب المجموع، والمعادلة (subtotal*15 + 50) / 100 تقرب النصف إلى الأعلى بأرقام صحيحة فقط، فمجموع 2,970 هللة ضريبته 44,550 مقسومة على 100، أي 445.5، فتصبح 446. واخترنا int64 بدل int لأن الحقول في PostgreSQL من نوع int بـ 32 بت، وضرب سعر في كمية في 15 قد يتجاوز هذا الحد في طلب كبير قبل القسمة، والوسوم `json:"subtotal_halalas"` تحدد أسماء الحقول في الرد.
طبقة البيانات Data Layer بمكتبة pgx
في Go طريقتان للحديث مع PostgreSQL: الواجهة القياسية database/sql مع أي مشغل Driver، ويشرحها الدرس الرسمي للوصول إلى قواعد البيانات، أو مكتبة pgx مباشرة بواجهتها الخاصة. واخترنا الثانية لأنها الأكثر استخداماً مع PostgreSQL تحديداً، وتعطيك أنواع PostgreSQL كما هي، مثل المصفوفات التي نحتاجها في ANY($1)، والدفعات Batches التي ترسل عدة أوامر دفعة واحدة على الشبكة، ومجمع اتصالات pgxpool مصمم لها. وأول الملف الأنواع والأخطاء:
var (
ErrNotFound = errors.New("not found")
ErrUnknownProduct = errors.New("unknown product")
)
// StockError reports the first product that does not have enough stock.
type StockError struct {
ProductID int64
Want int64
Have int64
}
func (e *StockError) Error() string {
return fmt.Sprintf("product %d: requested %d, in stock %d", e.ProductID, e.Want, e.Have)
}
type Product struct {
ID int64 `json:"id"`
NameAr string `json:"name_ar"`
PriceHalalas int64 `json:"price_halalas"`
Stock int64 `json:"stock"`
}
type Item struct {
ProductID int64 `json:"product_id"`
NameAr string `json:"name_ar,omitempty"`
Qty int64 `json:"qty"`
PriceHalalas int64 `json:"price_halalas"`
}
type Order struct {
ID int64 `json:"id"`
CreatedAt time.Time `json:"created_at"`
TotalHalalas int64 `json:"total_halalas"`
Items []Item `json:"items"`
}
type Store struct{ pool *pgxpool.Pool }
func New(pool *pgxpool.Pool) *Store { return &Store{pool: pool} }
func (s *Store) Products(ctx context.Context) ([]Product, error) {
rows, err := s.pool.Query(ctx, `SELECT id, name_ar, price_halalas, stock FROM products ORDER BY id`)
if err != nil {
return nil, fmt.Errorf("list products: %w", err)
}
return pgx.CollectRows(rows, pgx.RowToStructByPos[Product])
}ولاحظ هنا ما تعلمناه في المقال الثاني: خطآن ثابتان للحالات التي لا تحتاج تفاصيل، ونوع خطأ *StockError يحمل الأرقام التي تحتاجها طبقة HTTP لتبني رد 409 مفيداً. والدالة pgx.CollectRows مع RowToStructByPos تحول الأسطر إلى شريحة من الـ struct بالترتيب، وهي دالة عامة Generic تعمل مع أي نوع، وتغلق الأسطر وحدها حتى عند الخطأ، وهذا مهم، لأن نسيان rows.Close() في الواجهة القديمة يحجز اتصالاً من المجمع إلى الأبد.
مجمع الاتصالات Connection Pool: كم اتصالاً تحتاج؟
كل اتصال بـ PostgreSQL عملية Process كاملة على سيرفر قاعدة البيانات تستهلك ذاكرة، والحد الافتراضي max_connections فيه 100 اتصال، لذلك لا تفتح الخدمة اتصالاً لكل طلب، وإنما تحتفظ بمجمع من الاتصالات المفتوحة وتعيره للطلبات واحداً واحداً. والسؤال الذي يسأله كل فريق: كم اتصالاً يجب أن يكون في المجمع؟ والجواب الذي يفاجئ الناس أن العدد الصغير أفضل غالباً، لأن قاعدة البيانات لا تنفذ في نفس اللحظة أكثر مما عندها من أنوية، والاتصالات الزائدة تتنافس على نفس الأنوية والأقراص والأقفال، فيبطئ كل استعلام بدل أن يزيد العدد المنجز. ولذلك وضعنا MaxConns = 10، وهذا يعني أن الطلب الحادي عشر الذي يحتاج قاعدة البيانات ينتظر عند المجمع في ذاكرة الخدمة، وهو انتظار رخيص، بدل أن ينتظر داخل PostgreSQL وهو انتظار مكلف. والحساب الذي يجب أن تقوم به قبل النشر بسيط: عدد نسخ الخدمة مضروباً في MaxConns، مضافاً إليه اتصالات أدوات الإدارة والنسخ الاحتياطي، يجب أن يبقى أقل من حد قاعدة البيانات بهامش واضح، فثلاث نسخ بعشرين اتصالاً لكل منها مع عشرة للإدارة هي 70 من 100، وعندما تحتاج نسخاً أكثر يأتي دور PgBouncer الذي شرحناه في مقال PostgreSQL لكل شيء. وسوف ترى في قسم القياس أثر هذا الحد: خمسون اتصالاً من wrk على عشرة اتصالات في المجمع، فأغلب الطلبات تنتظر دورها.
ولاحظ أيضاً أن كل دالة في store تأخذ ctx كأول معامل وتمرره إلى pgx، فإذا أغلق العميل الاتصال، أو انتهت مهلة الكتابة في السيرفر، ألغى السياق الاستعلام الجاري وأعاد الاتصال إلى المجمع، وإذا كان داخل معاملة ألغيت المعاملة كلها. وهذا ما تعلمناه في مقال التزامن عن context، وهنا تراه في مكانه الطبيعي: الطلب الذي لم يعد أحد ينتظر نتيجته لا يجب أن يبقى ممسكاً بقفل على سطر الهيل.
المعاملة Transaction: قفل ثم فحص ثم تنقيص
وهذه أهم دالة في الخدمة كلها:
// CreateOrder runs in ONE transaction: lock the product rows, check stock,
// decrement it, insert the order and its items. qty maps product id -> quantity.
func (s *Store) CreateOrder(ctx context.Context, qty map[int64]int64) (Order, money.Totals, error) {
ids := make([]int64, 0, len(qty))
for id := range qty {
ids = append(ids, id)
}
slices.Sort(ids) // always lock in the same order: no deadlock between two orders
tx, err := s.pool.Begin(ctx)
if err != nil {
return Order{}, money.Totals{}, fmt.Errorf("begin: %w", err)
}
defer tx.Rollback(ctx) // no-op after Commit
rows, err := tx.Query(ctx,
`SELECT id, name_ar, price_halalas, stock FROM products WHERE id = ANY($1) ORDER BY id FOR UPDATE`, ids)
if err != nil {
return Order{}, money.Totals{}, fmt.Errorf("lock products: %w", err)
}
products, err := pgx.CollectRows(rows, pgx.RowToStructByPos[Product])
if err != nil {
return Order{}, money.Totals{}, fmt.Errorf("read products: %w", err)
}
if len(products) != len(ids) {
return Order{}, money.Totals{}, ErrUnknownProduct
}
lines := make([]money.Line, 0, len(products))
items := make([]Item, 0, len(products))
for _, p := range products {
want := qty[p.ID]
if p.Stock < want {
return Order{}, money.Totals{}, &StockError{ProductID: p.ID, Want: want, Have: p.Stock}
}
lines = append(lines, money.Line{PriceHalalas: p.PriceHalalas, Qty: want})
items = append(items, Item{ProductID: p.ID, NameAr: p.NameAr, Qty: want, PriceHalalas: p.PriceHalalas})
}
totals := money.Compute(lines)
var o Order
err = tx.QueryRow(ctx, `INSERT INTO orders (total_halalas) VALUES ($1) RETURNING id, created_at`, totals.Total).
Scan(&o.ID, &o.CreatedAt)
if err != nil {
return Order{}, money.Totals{}, fmt.Errorf("insert order: %w", err)
}
batch := &pgx.Batch{}
for _, it := range items {
batch.Queue(`UPDATE products SET stock = stock - $1 WHERE id = $2`, it.Qty, it.ProductID)
batch.Queue(`INSERT INTO order_items (order_id, product_id, qty, price_halalas) VALUES ($1, $2, $3, $4)`,
o.ID, it.ProductID, it.Qty, it.PriceHalalas)
}
if err := tx.SendBatch(ctx, batch).Close(); err != nil {
return Order{}, money.Totals{}, fmt.Errorf("write items: %w", err)
}
if err := tx.Commit(ctx); err != nil {
return Order{}, money.Totals{}, fmt.Errorf("commit: %w", err)
}
o.TotalHalalas = totals.Total
o.Items = items
return o, totals, nil
}
في الكود أعلاه لاحظ التالي:
slices.Sort(ids)قبل أي شيء، وORDER BY idفي الاستعلام، والسبب درس الجمود من المقال الثالث: طلبان فيهما القهوة والهيل بترتيب مختلف قد يقفل كل منهما سطراً وينتظر الآخر، والترتيب الثابت يمنع ذلك. وPostgreSQL يكتشف الجمود ويلغي إحدى المعاملتين، كما شرحنا في مقال الأقفال والجمود في قواعد البيانات، ولكن العميل سوف يرى خطأً لا ذنب له فيه.defer tx.Rollback(ctx)مباشرة بعدBegin، وهو نمط Go المعروف: في كل طريق خروج بخطأ تلغى المعاملة وحدها، وبعدCommitالناجح يصبحRollbackبلا أثر. فلا تحتاج أن تكتب الإلغاء في كلreturn، ولا تخاف أن تنساه في طريق جديد تضيفه بعد سنة.FOR UPDATEيقفل أسطر المنتجات المطلوبة حتى نهاية المعاملة، فكل طلب آخر على نفس المنتج ينتظر عند هذا الاستعلام، ثم يقرأ المخزون بعد أن تغير. والتفاصيل في توثيق FOR UPDATE في PostgreSQL 17 وفي الأقفال الصريحة Explicit Locking.- السعر يقرأ من قاعدة البيانات داخل المعاملة، ولا يقبل من العميل أبداً، وإلا فإن أي عميل يعرف كيف يعدل الطلب يستطيع أن يشتري الهيل بهللة.
- الدفعة
pgx.Batchترسل كل أوامر التنقيص والإدخال في ذهاب وعودة واحد على الشبكة Round Trip بدل واحد لكل أمر، وSendBatch(...).Close()يرجع أول خطأ من أي أمر فيها، وهذا السطر هو الذي سوف يظهر في تجربة «ماذا يحدث إذا». - كل خطأ يغلف بسياقه مثل
fmt.Errorf("lock products: %w", err)، فإذا وصل إلى السجل عرفت أي خطوة فشلت.
وقد يتساءل البعض: لماذا لا نكتفي بأمر واحد مثل UPDATE products SET stock = stock - $1 WHERE id = $2 AND stock >= $1 ثم نفحص عدد الأسطر التي تغيرت؟ والإجابة أن هذه طريقة صحيحة تماماً لمنتج واحد، وهي أسرع لأنها لا تحتاج قراءة منفصلة، ولكن مع طلب فيه عدة منتجات تحتاج أن تعرف أي منتج فشل وكم المتوفر منه لتبني رد 409، وتحتاج أن تفشل كل الطلب إذا فشل سطر واحد، وكل ذلك أوضح بالقفل ثم الفحص. والمستوى الافتراضي للعزل في PostgreSQL هو Read Committed، وهو يكفي هنا لأن القفل الصريح هو الذي يحمينا، والفرق بين المستويات في توثيق مستويات العزل.
طبقة HTTP: المعالجات Handlers والتحقق Validation
أول الملف internal/api/api.go الواجهة التي تحتاجها الطبقة، والموجه:
// Store is what the handlers need; *store.Store satisfies it, tests can fake it.
type Store interface {
Products(ctx context.Context) ([]store.Product, error)
CreateOrder(ctx context.Context, qty map[int64]int64) (store.Order, money.Totals, error)
Order(ctx context.Context, id int64) (store.Order, error)
}
type Server struct {
store Store
log *slog.Logger
}
func New(s Store, log *slog.Logger) http.Handler {
srv := &Server{store: s, log: log}
mux := http.NewServeMux()
mux.HandleFunc("GET /products", srv.listProducts)
mux.HandleFunc("POST /orders", srv.createOrder)
mux.HandleFunc("GET /orders/{id}", srv.getOrder)
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusNoContent) })
return srv.recoverer(mux)
}
type orderRequest struct {
Items []struct {
ProductID int64 `json:"product_id"`
Qty int64 `json:"qty"`
} `json:"items"`
}
const maxBody = 64 << 10 // 64 KiB is far more than any real orderالواجهة Store فيها ثلاث دوال فقط، و*store.Store يحققها دون أن يعرف بوجودها، وهذا ما يسمح لاختبار HTTP أن يمرر نسخة مزيفة. والأنماط "POST /orders" و"GET /orders/{id}" هي الموجه الجديد، والقيمة {id} تقرأ بـ r.PathValue("id")، وكل شيء ملفوف بالدالة recoverer التي سوف نراها بعد قليل. ثم معالج إنشاء الطلب:
func (s *Server) createOrder(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, maxBody)
dec := json.NewDecoder(r.Body)
dec.DisallowUnknownFields()
var req orderRequest
if err := dec.Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
return
}
if len(req.Items) == 0 || len(req.Items) > 50 {
writeError(w, http.StatusBadRequest, "items: between 1 and 50 lines")
return
}
qty := make(map[int64]int64, len(req.Items))
for i, it := range req.Items {
if it.ProductID <= 0 || it.Qty <= 0 || it.Qty > 1000 {
writeError(w, http.StatusBadRequest, fmt.Sprintf("items[%d]: product_id > 0 and 1 <= qty <= 1000", i))
return
}
qty[it.ProductID] += it.Qty // the same product twice becomes one line
}
o, totals, err := s.store.CreateOrder(r.Context(), qty)
var se *store.StockError
switch {
case errors.As(err, &se):
writeJSON(w, http.StatusConflict, map[string]any{
"error": "insufficient stock", "product_id": se.ProductID, "requested": se.Want, "in_stock": se.Have})
case errors.Is(err, store.ErrUnknownProduct):
writeError(w, http.StatusBadRequest, "unknown product_id")
case err != nil:
s.fail(w, r, err)
default:
w.Header().Set("Location", "/orders/"+strconv.FormatInt(o.ID, 10))
writeJSON(w, http.StatusCreated, map[string]any{
"id": o.ID, "created_at": o.CreatedAt, "items": o.Items,
"subtotal_halalas": totals.Subtotal, "vat_halalas": totals.VAT, "total_halalas": totals.Total})
}
}في الكود أعلاه لاحظ التالي:
- http.MaxBytesReader يحد حجم الجسم بـ 64 كيلوبايت، والسبب أن فك JSON بلا حد يسمح لأي شخص أن يرسل جسماً بمئات الميجابايتات فيستهلك ذاكرة الخدمة.
- DisallowUnknownFields يرفض الحقل المجهول، فالخطأ الإملائي
itemzيرجع 400 بدل أن يتجاهل الحقل ويرجع «القائمة فارغة»، وهو خطأ أصعب على من يدمج مع الخدمة. - التحقق يحد عدد الأسطر والكمية، ويجمع المنتج المكرر في سطر واحد بالخريطة
qty، لأن طلباً فيه نفس المنتج مرتين سوف يقفل نفس السطر مرتين ويفحص المخزون مرتين بشكل خاطئ. - الـ
switchبعد الاستدعاء يحول كل شكل خطأ إلى رده:errors.Asلنوع المخزون فيرجع 409 مع الأرقام، وerrors.Isللمنتج المجهول فيرجع 400، وأي خطأ آخر يذهب إلىfailالتي تكتب الخطأ الحقيقي في السجل وترجع للعميل «internal error» فقط، لأن رسالة قاعدة البيانات قد تكشف أسماء جداول وقيوداً لا يحتاج العميل أن يعرفها. - الرد 201 يحمل الترويسة
Locationبعنوان الطلب الجديد، كما تتوقع مكتبات HTTP.
وفي آخر الملف الحماية من الـ panic، وهي نفس الفكرة التي جربناها في المقال الثاني:
// recoverer turns a panic in one handler into a 500 instead of a dead process.
func (s *Server) recoverer(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
defer func() {
if v := recover(); v != nil {
if v == http.ErrAbortHandler {
panic(v)
}
s.log.Error("panic", "path", r.URL.Path, "value", fmt.Sprint(v))
writeError(w, http.StatusInternalServerError, "internal error")
}
s.log.Debug("request", "method", r.Method, "path", r.URL.Path, "took", time.Since(start))
}()
next.ServeHTTP(w, r)
})
}والسيرفر في net/http يلتقط الـ panic في المعالج وحده أصلاً، ولكنه يغلق الاتصال دون رد ويكتب المكدس في السجل القياسي، أما هذه الطبقة فترجع 500 مفهوماً وتكتب الخطأ في سجل JSON مع بقية السجلات. والقيمة http.ErrAbortHandler استثناء مقصود، لأن المكتبة نفسها تستخدمها لتقطع الرد عمداً، فنعيد رميها.
الإعداد Configuration والإيقاف الهادئ Graceful Shutdown
// processStart is set when the binary starts, so the log can say how long startup took.
var processStart = time.Now()
func main() {
log := slog.New(slog.NewJSONHandler(os.Stdout, nil))
if err := run(log); err != nil {
log.Error("exit", "err", err)
os.Exit(1)
}
}
func run(log *slog.Logger) error {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
cfg, err := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))
if err != nil {
return err
}
cfg.MaxConns = 10
pool, err := pgxpool.NewWithConfig(ctx, cfg)
if err != nil {
return err
}
defer pool.Close()
pingCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
if err := pool.Ping(pingCtx); err != nil {
return err
}
addr := ":" + envOr("PORT", "8080")
srv := &http.Server{
Addr: addr,
Handler: api.New(store.New(pool), log),
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
IdleTimeout: 60 * time.Second,
}
errc := make(chan error, 1)
go func() { errc <- srv.ListenAndServe() }()
log.Info("listening", "addr", addr, "max_conns", cfg.MaxConns, "startup", time.Since(processStart).String())
select {
case err := <-errc:
return err
case <-ctx.Done():
}
log.Info("shutting down")
shutCtx, cancel2 := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel2()
if err := srv.Shutdown(shutCtx); err != nil && !errors.Is(err, http.ErrServerClosed) {
return err
}
return nil
}
func envOr(k, def string) string {
if v := os.Getenv(k); v != "" {
return v
}
return def
}في الكود أعلاه لاحظ التالي:
- الدالة
mainلا تفعل شيئاً سوى أن تستدعيrunوتخرج برمز 1 إذا رجع خطأ، وهذا نمط شائع يجعل كلdeferداخلrunيعمل قبل الخروج، لأنos.Exitلا ينفذ الأوامر المؤجلة. - signal.NotifyContext يعطي سياقاً يلغى عند SIGTERM، وهي الإشارة التي يرسلها
docker stopوKubernetes قبل إيقاف الـ Container، فيتوقف السيرفر عن قبول اتصالات جديدة بـShutdown، وينتظر الطلبات الجارية حتى عشر ثوان، ثم يغلق المجمع. وفي تجربتنا ظهر السطرshutting downفي السجل بعدdocker stop، ثم خرج البرنامج قبل أن تنتهي مهلة Docker. - المهلات الأربع في http.Server: القيمة الافتراضية لكل منها صفر، أي بلا حد، وهذا يعني أن عميلاً بطيئاً يرسل الترويسات حرفاً كل دقيقة يحجز اتصالاً إلى الأبد. لذلك
ReadHeaderTimeoutعلى الأقل يجب أن يكون في كل سيرفر يخدم الإنترنت، وأداةgo vetلا تنبهك إلى ذلك. cfg.MaxConns = 10: حد اتصالات المجمع، والطلب الحادي عشر الذي يحتاج قاعدة البيانات ينتظر اتصالاً فارغاً. وهذا الحد يجب أن يحسب مع عدد نسخ الخدمة وحد PostgreSQL نفسه، كما شرحنا في مقال PostgreSQL لكل شيء.- السجل بـ log/slog بصيغة JSON، وهي المكتبة القياسية للسجلات المنظمة منذ Go 1.21، والسطر الأول يسجل زمن البدء من لحظة تحميل البرنامج، وسوف نحتاجه في القياس.
الاختبارات Tests: ثلاث طبقات
شرحنا أنواع الاختبارات ومتى تستخدم كلاً منها في مقال أنواع الاختبارات، وفي هذه الخدمة ثلاث طبقات، لكل منها ما تحميه.
اختبار الوحدة Unit Test للضريبة
package money
import "testing"
func TestCompute(t *testing.T) {
tests := []struct {
name string
lines []Line
want Totals
}{
// 9.90 SAR x 3 = 29.70, VAT 4.455 -> 4.46, total 34.16
{"cardamom x3 rounds half up", []Line{{990, 3}}, Totals{2970, 446, 3416}},
{"coffee + 2 dates", []Line{{4500, 1}, {3800, 2}}, Totals{12100, 1815, 13915}},
{"exact half halala rounds up", []Line{{10, 1}}, Totals{10, 2, 12}}, // 1.5 -> 2
{"below half rounds down", []Line{{3, 1}}, Totals{3, 0, 3}}, // 0.45 -> 0
{"empty order", nil, Totals{}},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
if got := Compute(tc.lines); got != tc.want {
t.Errorf("Compute(%v) = %+v, want %+v", tc.lines, got, tc.want)
}
})
}
}والحالة الأولى هي الحالة المطلوبة في المواصفات: 9.90 ريال × 3 = 29.70، والضريبة 4.455 تصبح 4.46، والإجمالي 34.16. وأضفنا حالتين على حد التقريب، 10 هللات ضريبتها 1.5 فتصبح 2، و3 هللات ضريبتها 0.45 فتصبح صفراً، لأن الأخطاء في التقريب تختبئ عند النصف بالضبط.
اختبار HTTP بنسخة مزيفة Fake
الملف internal/api/api_test.go يعرف نوعاً fakeStore بثلاث دوال، ويرسل اثني عشر طلباً عبر httptest دون شبكة ولا قاعدة بيانات، ويتحقق من رمز الرد ومن جزء من الجسم في كل حالة: 201 مع ضريبة 446، و409 مع المخزون، و400 للمنتج المجهول والقائمة الفارغة والكمية صفر والكمية نصاً والحقل المجهول، و404 و405. وهذا الاختبار يعمل في أقل من 0.1 ثانية، ويحمي عقد الواجهة Contract الذي يعتمد عليه تطبيق المتجر.
اختبار التكامل Integration على PostgreSQL حقيقي
النسخة المزيفة لا تقول شيئاً عن SQL ولا عن الأقفال، لذلك اختبارات الحزمة store تعمل على PostgreSQL 17 حقيقي في Container، وكل اختبار يعيد الجداول إلى البذرة نفسها قبل أن يبدأ:
// newTestStore connects to the real Postgres given in TEST_DATABASE_URL and
// resets the tables to the seed of schema.sql. Tests skip without it.
func newTestStore(t *testing.T) (*Store, *pgxpool.Pool) {
t.Helper()
url := os.Getenv("TEST_DATABASE_URL")
if url == "" {
t.Skip("TEST_DATABASE_URL not set: integration test skipped")
}
ctx := context.Background()
pool, err := pgxpool.New(ctx, url)
if err != nil {
t.Fatal(err)
}
t.Cleanup(pool.Close)
_, err = pool.Exec(ctx, `
TRUNCATE order_items, orders, products RESTART IDENTITY;
INSERT INTO products (name_ar, price_halalas, stock) VALUES
('قهوة عربية مختصة 250 غرام', 4500, 100),
('تمر سكري 1 كيلو', 3800, 100),
('هيل حب 100 غرام', 990, 10);`)
if err != nil {
t.Fatal(err)
}
return New(pool), pool
}واخترنا أن يقرأ الاختبار عنوان القاعدة من المتغير TEST_DATABASE_URL، وأن يتخطى نفسه إذا لم يجده، فيعمل go test ./... على جهاز أي مطور دون Docker، ويعمل الاختبار الكامل في CI حيث تشغل قاعدة البيانات خدمة جانبية. والبديل الشائع مكتبة Testcontainers for Go التي تشغل الـ Container من داخل الاختبار نفسه، وهي مريحة، ولكنها تحتاج أن يصل الاختبار إلى Docker، وهذا يعقد التشغيل داخل Container كما فعلنا. ثم اختبار العشرين طلباً:
// 20 parallel orders for one unit of a product with stock 10: exactly 10 succeed.
func TestConcurrentOrdersNeverOversell(t *testing.T) {
s, pool := newTestStore(t)
ctx := context.Background()
var ok, conflict, other atomic.Int64
var wg sync.WaitGroup
start := make(chan struct{})
for i := 0; i < 20; i++ {
wg.Go(func() {
<-start // release all 20 at the same moment
_, _, err := s.CreateOrder(ctx, map[int64]int64{3: 1})
var se *StockError
switch {
case err == nil:
ok.Add(1)
case errors.As(err, &se):
conflict.Add(1)
default:
other.Add(1)
t.Error(err)
}
})
}
close(start)
wg.Wait()
var stock, items int
pool.QueryRow(ctx, `SELECT stock FROM products WHERE id = 3`).Scan(&stock)
pool.QueryRow(ctx, `SELECT coalesce(sum(qty),0) FROM order_items WHERE product_id = 3`).Scan(&items)
t.Logf("succeeded=%d conflicts=%d other=%d stock=%d sold=%d", ok.Load(), conflict.Load(), other.Load(), stock, items)
if ok.Load() != 10 || conflict.Load() != 10 || stock != 0 || items != 10 {
t.Fatal("oversold or undersold")
}
}والقناة start تمسك العشرين Goroutine حتى تجهز كلها، ثم يطلقها close(start) في نفس اللحظة، وإلا لبدأت الأولى وانتهت قبل أن تنشأ الأخيرة ولم يحدث أي تنافس. ثم شغلنا الاختبارات كلها، والتكامل مع كاشف السباقات:
docker run -d --name slj-go-db --network slj-go-net -e POSTGRES_USER=app -e POSTGRES_PASSWORD=app \
-e POSTGRES_DB=orders -v "$PWD/initdb:/docker-entrypoint-initdb.d:ro" postgres:17-alpine
TEST_DATABASE_URL="postgres://app:app@slj-go-db:5432/orders_test" go test -race -count=1 -v ./internal/store/والمخرج سوف يكون كما يلي:
=== RUN TestCompute
=== RUN TestCompute/cardamom_x3_rounds_half_up
=== RUN TestCompute/coffee_+_2_dates
=== RUN TestCompute/exact_half_halala_rounds_up
=== RUN TestCompute/below_half_rounds_down
=== RUN TestCompute/empty_order
--- PASS: TestCompute (0.00s)
--- PASS: TestCompute/cardamom_x3_rounds_half_up (0.00s)
--- PASS: TestCompute/coffee_+_2_dates (0.00s)
--- PASS: TestCompute/exact_half_halala_rounds_up (0.00s)
--- PASS: TestCompute/below_half_rounds_down (0.00s)
--- PASS: TestCompute/empty_order (0.00s)
PASS
ok example.com/orders/internal/money 0.453s
ok example.com/orders/internal/api 0.086s
=== RUN TestCreateAndGetOrder
--- PASS: TestCreateAndGetOrder (0.33s)
=== RUN TestInsufficientStockChangesNothing
--- PASS: TestInsufficientStockChangesNothing (0.11s)
=== RUN TestUnknownProduct
--- PASS: TestUnknownProduct (0.14s)
=== RUN TestConcurrentOrdersNeverOversell
store_test.go:116: succeeded=10 conflicts=10 other=0 stock=0 sold=10
--- PASS: TestConcurrentOrdersNeverOversell (0.53s)
PASS
ok example.com/orders/internal/store 2.220sفي المخرج أعلاه لاحظ التالي:
- اختبار الوحدة Unit Test مر بحالاته الخمس، وعلامة الجمع في اسم الحالة الثانية بقيت كما هي في اسم الاختبار الفرعي.
TestInsufficientStockChangesNothingيطلب قهوة متوفرة مع هيل لا يكفي، ويتحقق من أن مخزون القهوة بقي 100 وأن جدول الطلبات فارغ، أي أن الطلب فشل كله، وهذا ما تضمنه المعاملة.- السطر المهم:
succeeded=10 conflicts=10 other=0 stock=0 sold=10، عشرة طلبات نجحت، وعشرة رجعتStockErrorالذي يصبح 409، والمخزون صفر، ومجموع الكميات المباعة عشرة بالضبط، والكاشف-raceلم يجد شيئاً في كود الاختبار نفسه.
تشغيل الاختبارات في خط CI Pipeline
ما فعلناه بالأوامر اليدوية يتحول في خط CI إلى ثلاث خطوات: خدمة جانبية من postgres:17-alpine بنفس ملفات initdb، ثم go vet ./... مع فاحص مثل staticcheck، ثم go test -race -count=1 ./... مع المتغير TEST_DATABASE_URL. والخيار -count=1 مهم هنا، لأن go test يحفظ نتائج الاختبارات الناجحة في الـ Cache ولا يعيد تشغيلها إذا لم يتغير الكود، وهذا ممتاز لاختبارات الوحدة، ولكنه خاطئ لاختبار يعتمد على قاعدة بيانات خارجية قد تكون تغيرت. وتذكر أن اختبار التزامن نجح في كل تشغيلاتنا، ولكن نجاح اختبار تزامن مرة واحدة لا يثبت شيئاً، لذلك شغله في CI بالخيار -count=20 مرة في الليل على الأقل، فإذا فشل مرة واحدة من عشرين فعندك سباق حقيقي ينتظر يوم التخفيض. وقد شرحنا تنظيم هذه الخطوات وسرعتها ومشكلة الاختبارات المتقلبة في قسم ضمان الجودة من خارطة الطريق Roadmap.
ماذا يحدث إذا حذفنا FOR UPDATE؟
الآن نحذف الكلمتين FOR UPDATE من الاستعلام في نسخة مؤقتة من الكود، ونعيد اختبار العشرين طلباً ثلاث مرات:
82: `SELECT id, name_ar, price_halalas, stock FROM products WHERE id = ANY($1) ORDER BY id`, ids)
store_test.go:116: succeeded=10 conflicts=3 other=7 stock=0 sold=10
store_test.go:118: oversold or undersold
--- FAIL: TestConcurrentOrdersNeverOversell (0.83s)
store_test.go:116: succeeded=10 conflicts=3 other=7 stock=0 sold=10
store_test.go:118: oversold or undersold
--- FAIL: TestConcurrentOrdersNeverOversell (0.86s)
store_test.go:116: succeeded=10 conflicts=3 other=7 stock=0 sold=10
store_test.go:118: oversold or undersold
--- FAIL: TestConcurrentOrdersNeverOversell (1.55s)ومخرج تشغيل واحد كاملاً:
=== RUN TestConcurrentOrdersNeverOversell
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:107: write items: ERROR: new row for relation "products" violates check constraint "products_stock_check" (SQLSTATE 23514)
store_test.go:116: succeeded=10 conflicts=3 other=7 stock=0 sold=10
store_test.go:118: oversold or undersold
--- FAIL: TestConcurrentOrdersNeverOversell (0.35s)
FAIL
FAIL example.com/orders/internal/store 0.416s
FAILوالنتيجة أكثر إثارة مما توقعنا. كنا ننتظر أن يبيع المتجر أكثر من عشر قطع كما حدث في تجربة الذاكرة في المقال الثالث، ولكن المخزون بقي صفراً والمبيع عشراً بالضبط، والاختبار فشل لسبب آخر: ثلاثة طلبات فقط أخذت 409، وسبعة أخذت خطأً من قاعدة البيانات violates check constraint "products_stock_check". وما حدث أن الطلبات العشرين قرأت المخزون كلها تقريباً قبل أن ينقصه أحد، فرأى أغلبها أن المخزون يكفي، ثم وصلت إلى أمر UPDATE، وهنا يقفل PostgreSQL السطر لأنه يكتب فيه، فانتظرت الطلبات بعضها، وكل واحد منها نفذ stock = stock - 1 على القيمة الحالية، حتى وصل المخزون إلى صفر، وعندها رفض القيد CHECK (stock >= 0) كل تنقيص بعده، فانتهت المعاملة بخطأ وألغيت كلها.

والدرس هنا مزدوج. الأول أن القيد في قاعدة البيانات أنقذ المتجر من البيع الزائد حتى مع كود خاطئ، وهذا سبب أن تضع القيود في المخطط ولا تكتفي بالفحص في الكود، فهي خط الدفاع الذي لا يتجاوزه أي خطأ في أي لغة. والثاني أن هذا الإنقاذ له ثمن: سبعة عملاء رأوا خطأ 500 «internal error» بدل رسالة «الكمية غير متوفرة»، وتطبيق المتجر سوف يعرض لهم «حدث خطأ، حاول لاحقاً»، فيحاولون مرة ثانية ويفشلون مرة ثانية، وفريق المراقبة يرى ارتفاعاً في أخطاء 500 في يوم التخفيض، وهو بالضبط اليوم الذي لا تريد فيه إنذارات كاذبة. فالقفل لم يكن لحماية البيانات وحدها، وإنما ليجعل كل طلب يرى الحقيقة قبل أن يقرر.
وقد يتساءل البعض: إذا كان القيد قد حمى البيانات، فلماذا لا نكتفي به، ونحول خطأه إلى 409؟ وهذا ممكن فعلاً، فمكتبة pgx ترجع الخطأ من النوع *pgconn.PgError، وفيه الحقل Code برمز SQLSTATE، والرمز 23514 يعني مخالفة قيد CHECK، فتستطيع أن تفحصه بـ errors.As وترجع 409. ولكن انظر إلى ما تخسره: الرد لن يعرف كم المتوفر من المخزون لأن المعاملة لم تقرأه بعد آخر تغيير، ومعاملات كثيرة سوف تبدأ وتكتب ثم تلغى، وهذا عمل ضائع على قاعدة البيانات في أكثر لحظاتها ضغطاً، وأي تعديل لاحق في الكود يقرأ المخزون ليقرر شيئاً آخر، مثل خصم على آخر قطعة، سوف يقرأ قيمة قديمة. لذلك اجعل القيد شبكة أمان تلتقط ما فات الكود، واجعل القفل هو الطريق الطبيعي، وتحويل الرمز 23514 إلى 409 إضافة جيدة كخط ثان، وليس بديلاً.
التشغيل والطلبات Requests كما يراها العميل
شغلنا الخدمة على قاعدة البيانات الجديدة، وأرسلنا طلباً لكل حالة بالأمر curl:
$ http://127.0.0.1:19550/products
[{"id":1,"name_ar":"قهوة عربية مختصة 250 غرام","price_halalas":4500,"stock":100},{"id":2,"name_ar":"تمر سكري 1 كيلو","price_halalas":3800,"stock":100},{"id":3,"name_ar":"هيل حب 100 غرام","price_halalas":990,"stock":10}]
-> HTTP 200
$ -X POST http://127.0.0.1:19550/orders -H Content-Type: application/json -d {"items":[{"product_id":3,"qty":3}]}
{"created_at":"2026-10-31T08:38:43.956671Z","id":1,"items":[{"product_id":3,"name_ar":"هيل حب 100 غرام","qty":3,"price_halalas":990}],"subtotal_halalas":2970,"total_halalas":3416,"vat_halalas":446}
-> HTTP 201
$ http://127.0.0.1:19550/orders/1
{"id":1,"created_at":"2026-10-31T08:38:43.956671Z","total_halalas":3416,"items":[{"product_id":3,"name_ar":"هيل حب 100 غرام","qty":3,"price_halalas":990}]}
-> HTTP 200
$ -X POST http://127.0.0.1:19550/orders -d {"items":[{"product_id":3,"qty":8}]}
{"error":"insufficient stock","in_stock":7,"product_id":3,"requested":8}
-> HTTP 409
$ -X POST http://127.0.0.1:19550/orders -d {"items":[{"product_id":3,"qty":"2"}]}
{"error":"invalid JSON: json: cannot unmarshal string into Go struct field orderRequest.items.0.qty of type int64"}
-> HTTP 400
$ -X POST http://127.0.0.1:19550/orders -d {"items":[{"product_id":99,"qty":1}]}
{"error":"unknown product_id"}
-> HTTP 400
$ http://127.0.0.1:19550/orders/999
{"error":"order not found"}
-> HTTP 404كل رد كما في المواصفات: الطلب الأول 201 بمجموع 2,970 وضريبة 446 وإجمالي 3,416 هللة، ثم طلب ثمان قطع والمتبقي سبع فرجع 409 ومعه "in_stock":7، فيستطيع التطبيق أن يقول للعميل «المتوفر 7». والكمية نصاً رجعت 400 مع رسالة مكتبة JSON، وفيها المسار الكامل للحقل items.0.qty، وهذا مفيد للمطور الذي يدمج مع الخدمة، ولكنه يكشف اسم النوع الداخلي orderRequest، فإذا كان هذا يزعجك فاكتب رسالتك بنفسك بدل أن تمرر رسالة المكتبة. ولاحظ أن تاريخ الإنشاء بتوقيت UTC، وهذا ما تريده في التخزين، والتحويل إلى توقيت السعودية مهمة الواجهة.
وهناك تفصيل صغير في المخرج يسأل عنه كل من يقرأ ردود Go لأول مرة: رد إنشاء الطلب جاءت حقوله بترتيب أبجدي، created_at ثم id ثم items ثم subtotal_halalas، بينما رد GET /orders/1 جاءت حقوله بترتيب الـ struct، id ثم created_at. والسبب أننا بنينا الرد الأول من خريطة map[string]any، ومكتبة encoding/json ترتب مفاتيح الخريطة أبجدياً حتى يكون المخرج ثابتاً بين التشغيلات، أما الـ struct فيخرج بترتيب حقوله. ولا يجب أن يعتمد أي عميل على ترتيب الحقول في JSON، ولكن إذا أردت ترتيباً ثابتاً وواضحاً في التوثيق فعرف struct للرد بدل الخريطة، وهذا أيضاً يجعل المترجم يفحص أسماء الحقول بدل أن تكتبها نصاً في كل مكان.
الـ Dockerfile على مرحلتين Multi-stage Build
# syntax=docker/dockerfile:1
# Stage 1: build a static binary with the full Go toolchain.
FROM golang:1.27.3-trixie AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/orders ./cmd/orders
# Stage 2: only the binary, CA certificates and a non-root user.
FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /out/orders /orders
EXPOSE 8080
USER nonroot:nonroot
ENTRYPOINT ["/orders"]في الإعداد أعلاه لاحظ التالي:
- المرحلة الأولى فيها المترجم كاملاً، والثانية فيها الملف التنفيذي فقط، وهذا ما يشرحه توثيق البناء متعدد المراحل.
- نسخ
go.modوgo.sumثمgo mod downloadقبل نسخ الكود، حتى تبقى طبقة المكتبات في الـ Cache ما دامت المكتبات لم تتغير. - السطر
--mount=type=cacheهو الحل لمشكلة رأيناها في مقال اختيار اللغة، حيث أعاد كل بناء ترجمة المكتبة القياسية كلها، والتفاصيل في توثيق تحسين الـ Cache. CGO_ENABLED=0يضمن ملفاً ثابتاً لا يحتاجlibc، و-trimpathيحذف مسارات جهاز البناء من الملف، و-s -wيحذف رموز التصحيح.- الصورة النهائية distroless/static من Google، وفيها شهادات CA وملفات المنطقة الزمنية ومستخدم
nonroot، ولا يوجد فيها shell، فالمخترق الذي يجد ثغرة في الخدمة لا يجد أدوات يعمل بها. وثمن ذلك أنك لا تستطيع أن تدخل الـ Container بـshلتصحح شيئاً، والبديلdocker debugأو Container جانبي.

والبناء الأول أخذ 87 ثانية، منها 49.1 ثانية لخطوة الترجمة و10 ثوان لتنزيل المكتبات، لأن الـ Cache Mount كان فارغاً، والحجم النهائي للـ Image كما يقرؤه docker image inspect هو 22.0 ميجابايت، و5.02 ميجابايت مضغوطة في السجل.
القياس Measurement: معالجان و512 ميجابايت
القياس بنفس السكربت المشترك لكل لغات المسار، وهو في lab/measure.sh: حجم الـ Image، ثم الزمن من docker run إلى أول رد 200 على GET /products، ثم الذاكرة بعد خمس ثوان من الانتظار، ثم تشغيلان للأداة wrk بخيطين وخمسين اتصالاً لمدة 15 ثانية من Container آخر على نفس الشبكة، ثم الذاكرة بعد الضغط، والخدمة محدودة بـ --cpus=2 --memory=512m. وشغلنا السكربت كاملاً مرتين:
NET=slj-go-net bash measure.sh slj-go-orders:1 8080 19550 slj-go- \
-e DATABASE_URL=postgres://app:app@slj-go-db:5432/ordersوالمجموعة الأولى:
== image size
22.0 MB
== cold start (docker run -> first HTTP 200 on GET /products)
8863 ms
== idle memory after 5 s
5.012MiB / 512MiB
== wrk run 1
Running 15s test @ http://slj-go-svc:8080/products
2 threads and 50 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 14.65ms 16.25ms 584.96ms 88.07%
Req/Sec 2.11k 637.89 4.41k 66.78%
62946 requests in 15.05s, 22.93MB read
Requests/sec: 4181.17
Transfer/sec: 1.52MB
== wrk run 2
Running 15s test @ http://slj-go-svc:8080/products
2 threads and 50 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 14.72ms 12.20ms 130.78ms 78.29%
Req/Sec 1.92k 570.01 3.86k 70.49%
57290 requests in 15.13s, 20.87MB read
Requests/sec: 3786.26
Transfer/sec: 1.38MB
== memory after load
11.75MiB / 512MiBوالمجموعة الثانية:
== image size
22.0 MB
== cold start (docker run -> first HTTP 200 on GET /products)
10669 ms
== idle memory after 5 s
6.859MiB / 512MiB
== wrk run 1
Running 15s test @ http://slj-go-svc:8080/products
2 threads and 50 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 16.31ms 14.39ms 285.27ms 88.55%
Req/Sec 1.69k 521.71 3.37k 68.73%
50209 requests in 15.06s, 18.24MB read
Socket errors: connect 0, read 0, write 0, timeout 3
Requests/sec: 3334.52
Transfer/sec: 1.21MB
== wrk run 2
Running 15s test @ http://slj-go-svc:8080/products
2 threads and 50 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 21.42ms 16.42ms 184.54ms 76.16%
Req/Sec 1.28k 537.08 3.43k 68.17%
37961 requests in 15.05s, 13.79MB read
Requests/sec: 2521.77
Transfer/sec: 0.92MB
== memory after load
14.22MiB / 512MiB
ولنقرأ الأرقام بصدق:
- الطلبات في الثانية: 4,181 و3,786 في المجموعة الأولى، و3,335 و2,522 في الثانية، بنفس الكود ونفس الـ Image. والفرق كله من الجهاز، فقد كان Docker Desktop يشغل أعمالاً أخرى، والمجموعة الثانية جاءت في أكثر الدقائق انشغالاً. لذلك لا تأخذ رقماً واحداً، وإنما المدى، وقارن اللغات بالترتيب والنسب على نفس الجهاز في نفس اليوم.
- متوسط زمن الطلب بين 14.7 و21.4 مللي ثانية مع خمسين اتصالاً، وكل طلب يقرأ من PostgreSQL عبر مجمع من عشرة اتصالات، فأربعون اتصالاً تنتظر دورها عند المجمع في كل لحظة. ولاحظ السطر
timeout 3في المجموعة الثانية، وهي ثلاثة طلبات تجاوزت مهلة wrk الافتراضية وهي ثانيتان. - الذاكرة: 5.0 و6.9 ميجابايت والخدمة تنتظر، و11.8 و14.2 بعد خمسين اتصالاً متزامناً، وهذا من أصغر الأرقام التي تراها لخدمة HTTP مع مجمع قاعدة بيانات، وهو سبب أن Go شائعة في الخدمات التي تعمل منها مئات النسخ.
- الحجم 22.0 ميجابايت للـ Image كلها.
- زمن البدء: 8.9 ثم 10.7 ثانية من
docker runإلى أول 200، وهذا الرقم لا يقيس Go، وقد فصلناه بسكربتcold-breakdown.shإلى أجزائه: الأمرdocker run -dنفسه أخذ بين 6.5 و35 ثانية حتى رجع، والعملية داخل الـ Container سجلت أنها كانت جاهزة للاستماع بعد49.39157msمن تحميلها، ومنها الاتصال بقاعدة البيانات والتحقق منه. فإذا قارنت زمن البدء بين اللغات في هذا المسار فقارن السطر الذي تسجله العملية نفسها، لأن زمن Docker Desktop على جهاز مشغول يغطي على كل شيء.
run 1: docker run returned after 15094 ms, first 200 after 15394 ms; container StartedAt 2026-10-31T08:34:48.483013648Z, app listening 2026-10-31T08:34:52.18822345Z
run 2: docker run returned after 35488 ms, first 200 after 36359 ms; container StartedAt 2026-10-31T08:36:43.274371259Z, app listening 2026-10-31T08:36:46.575211134Z
run 3: docker run returned after 14341 ms, first 200 after 18357 ms; container StartedAt 2026-10-31T08:37:15.28178458Z, app listening 2026-10-31T08:37:18.495087237Z
{"time":"2026-10-31T08:37:18.495087237Z","level":"INFO","msg":"listening","addr":":8080","max_conns":10,"startup":"49.39157ms"}
{"time":"2026-10-31T08:37:39.806352712Z","level":"INFO","msg":"shutting down"}وقد يتساءل من قرأ مقال اختيار اللغة: هناك أعطت خدمة Go بين 10 آلاف و28 ألف طلب في الثانية بنفس الأداة ونفس الحد للمعالج، فلماذا هنا أقل من 4,200؟ والإجابة في الفرق بين الخدمتين، لا في اللغة: تلك الخدمة كانت تحسب السعر في الذاكرة دون أي اتصال خارجي، وهذه ترسل كل طلب إلى PostgreSQL عبر الشبكة وتنتظر الرد، وتحول ثلاثة أسطر إلى JSON فيها نصوص عربية، والمجمع يسمح بعشرة استعلامات فقط في نفس الوقت. فالخدمة هنا تقضي أغلب وقتها في انتظار قاعدة البيانات، وهذا هو الشكل الطبيعي لأغلب الخدمات الحقيقية، ولهذا السبب بالذات يصغر الفرق بين اللغات كثيراً في هذا النوع من القياس مقارنة بطريق حسابي بحت، وهي النقطة التي ذكرناها هناك. فإذا أردت أن تزيد هذا الرقم فابدأ من قاعدة البيانات: فهرس، أو ذاكرة مؤقتة لقائمة المنتجات التي لا تتغير كل ثانية، قبل أن تفكر في تغيير اللغة.
ولكي تقرأ هذه الأرقام في سياقها: المتجر في قصتنا يحتاج في أسوأ يوم بضعة طلبات في الثانية، كما حسبنا في مقال كيف تختار لغة البرمجة، فحتى أقل رقم هنا أكبر من الحاجة بمئات المرات، والحد الحقيقي سوف يكون قاعدة البيانات قبل الخدمة. وإذا أردت أن تقيس الخدمة كما يجب قبل يوم تخفيض حقيقي، فبسيناريو كامل وليس بطريق واحد، فقد شرحنا ذلك في مقال اختبار الضغط Load Testing.
ما الذي ينقص الخدمة قبل الإنتاج؟ Production Readiness
الخدمة كما هي تحقق المواصفات المشتركة، وهي عن قصد صغيرة لتقارن بين اللغات، ولكن قبل أن تضعها أمام عملاء حقيقيين يجب أن تضيف أشياء ليست من اختصاص اللغة، ونذكرها هنا حتى لا يظن القارئ أن ما سبق هو كل شيء:
- ترحيل المخطط Migrations: الملف
01-schema.sqlيعمل مرة واحدة على قاعدة فارغة، أما في الإنتاج فكل تغيير في الجداول يحتاج ملف ترحيل مرقماً يطبق بالترتيب ويسجل ما طبق، وفي Go أدوات شائعة لذلك مثل goose وgolang-migrate، وكلها تعمل كبرنامج منفصل أو كخطوة قبل تشغيل الخدمة، وليس داخلmainفي كل نسخة. - فحص الجاهزية Readiness: الطريق
/healthzعندنا يقول إن العملية تعمل، ولكنه لا يقول إن قاعدة البيانات متاحة، وموزع الطلبات أو Kubernetes يحتاج طريقين منفصلين، واحداً للحياة وآخر للجاهزية، والفرق بينهما شرحناه في مقال تصميم الأنظمة. - المقاييس Metrics والتتبع Tracing: عدد الطلبات وأزمنتها بالنسب المئوية لكل طريق، وانتظار المجمع، وعدد أخطاء 409 مقابل 500، وكلها تضاف بطبقة حول المعالجات مثل طبقة
recoverer، وأشهر الخيارات مكتبة Prometheus الرسمية لـ Go وOpenTelemetry. - المصادقة Authentication وتحديد المعدل Rate Limiting: أي أحد يستطيع اليوم أن ينشئ طلبات، وفي خدمة حقيقية يمر الطلب أولاً على بوابة أو طبقة تتحقق من التوكن وتحد عدد الطلبات لكل عميل.
- منع التكرار Idempotency: العميل الذي ضغط «اشتر» وانقطعت الشبكة قبل الرد سوف يضغط مرة ثانية، والخدمة اليوم تنشئ طلبين، وهذا أول تدريب في آخر المقال.
- الإعداد Configuration: نقرأ متغيرين فقط من البيئة، والخدمة الحقيقية تقرأ أكثر، والقاعدة أن تتحقق من كل الإعدادات عند البدء وتخرج برسالة واضحة إذا نقص شيء، بدل أن تكتشف النقص عند أول طلب.
ولاحظ أن كل هذه الإضافات تأتي في Go كطبقات حول http.Handler أو كبرامج منفصلة، دون أن تغير شيئاً في الحزمتين money وstore، وهذه فائدة التقسيم الذي بدأنا به.
نقاط القوة Strengths ونقاط الضعف Weaknesses لهذه الخدمة في Go
بعد أن بنينا الخدمة وقسناها نستطيع أن نقول بصدق ما الذي أعطته Go وما الذي كلفته، وهذا ما سوف تقارنه بالمقالات المقابلة في اللغات الأخرى.
نقاط القوة: ملف تنفيذي واحد في Image بحجم 22 ميجابايت دون أي بيئة تشغيل، وذاكرة بين 5 و14 ميجابايت تجعل تشغيل عشرات النسخ رخيصاً، وعملية جاهزة في 49 مللي ثانية تجعل التوسع السريع ممكناً، ومكتبة قياسية فيها سيرفر HTTP جاهز للإنتاج بمهلاته وإيقافه الهادئ، واختبارات وكاشف سباقات في الأمر go نفسه، ومكتبة خارجية واحدة فقط، فقائمة الاعتماديات التي تراجعها أمنياً قصيرة جداً.
نقاط الضعف: كتبنا بأيدينا ما يعطيك إياه إطار عمل في لغات أخرى، مثل تحويل الأخطاء إلى ردود، وكتابة JSON، والتحقق من المدخلات حقلاً حقلاً، وهذا كود متكرر يزيد مع كل طريق جديد. ولا يوجد في المكتبة القياسية ORM ولا ترحيل للمخطط، فتختار بين SQL مكتوب يدوياً كما فعلنا، أو مولد كود مثل sqlc، أو ORM مثل GORM، ولكل منها ثمن. والسطر if err != nil ظهر في CreateOrder وحدها ست مرات، وهو ما ناقشناه في المقال الثاني. والخلاصة أن Go تعطيك خدمة صغيرة وسريعة وسهلة التشغيل، مقابل كود أطول قليلاً من إطار عمل كبير، وهذا الثمن يقل كلما كبر الفريق وطال عمر الخدمة، لأن الكود الصريح أسهل في القراءة بعد سنتين.
مشكلات Problems واجهتنا أثناء البناء
- أول تشغيل لـ
go vetبعدgo mod tidyفشل بالرسالة"net/http" imported and not usedفي ملف الاختبار، لأننا استخدمناhttptestفقط. والقاعدة التي رأيناها في المقال الأول تعمل على ملفات الاختبار أيضاً، وحذفنا السطر. - الإصدار الذي ثبته
go getمن pgx هو v5.12.0، وقد صدر في نفس يوم التجربة، فاختبرنا عليه كل شيء من جديد بدل أن نفترض أنه يعمل كالإصدار السابق. وفي مشروع حقيقي لا ترفع مكتبة قاعدة البيانات في نفس يوم صدورها إلا لإصلاح أمني، واترك لها أسبوعاً. - زمن البدء الأول 8.9 ثانية بدا غريباً جداً لملف Go واحد، وبدل أن نكتبه كما هو أضفنا إلى السجل الزمن من تحميل العملية، وفصلنا زمن
docker runعن زمن الرد الأول، فظهر أن العملية تحتاج 49 مللي ثانية والباقي Docker Desktop. وهذا تذكير بأن الرقم الذي لا تفهمه لا تنشره قبل أن تفككه. - قاعدة بيانات الاختبار
orders_testينشئها السكربتinitdb/02-testdb.sh، والصورة الرسمية لـ PostgreSQL تشغل ملفات هذا المجلد بترتيب أسمائها عند أول تشغيل فقط، أي عندما يكون مجلد البيانات فارغاً. فإذا عدلت المخطط بعد أول تشغيل فلن يتغير شيء، واحذف الـ Container ومعه بياناته في التجربة، أو اكتب Migration في المشروع الحقيقي.
أخطاء شائعة Common Mistakes في خدمات Go
- فحص المخزون ثم تنقيصه دون قفل داخل نفس المعاملة: رأينا النتيجة، إما بيع زائد أو أخطاء 500 بحسب القيود.
- أخذ السعر من جسم الطلب بدل قاعدة البيانات.
http.ListenAndServeمباشرة بلاhttp.Serverومهلاته: كل عميل بطيء يحجز اتصالاً بلا حد.- فك JSON بلا
MaxBytesReaderوبلا رفض للحقول المجهولة. - إرجاع رسالة خطأ قاعدة البيانات للعميل كما هي.
- عدم تمرير
r.Context()إلى الاستعلامات Queries: العميل أغلق الاتصال والاستعلام يكمل. - نسيان
defer tx.Rollback(ctx)، أو نسيان إغلاق الأسطر في الواجهة القديمة: اتصالات المجمع تنفد واحداً بعد الآخر حتى تتوقف الخدمة. os.Exitأوlog.Fatalداخل دالة عميقة: لا تعمل الأوامر المؤجلة، ولا يغلق المجمع.- عدم معالجة SIGTERM: كل نشر جديد يقطع الطلبات الجارية في منتصفها.
- اختبارات تعتمد على النسخة المزيفة فقط: لا تختبر SQL ولا الأقفال، والخطأ الحقيقي في هذه الخدمة كان هناك.
قائمة تحقق Checklist قبل نشر الخدمة
| البند | في خدمتنا |
|---|---|
| المبالغ بأرقام صحيحة وتقريب مختبر | money.VAT مع حالات النصف |
| كل كتابة مالية في معاملة واحدة | Begin ثم defer Rollback ثم Commit |
| أقفال بترتيب ثابت | slices.Sort وORDER BY id FOR UPDATE |
| قيود في المخطط | CHECK (stock >= 0) وqty > 0 |
| تحقق من المدخلات وحد للجسم | MaxBytesReader وDisallowUnknownFields |
| أخطاء مفهومة للعميل ومفصلة في السجل | 400 و404 و409، و500 عام مع slog |
| مهلات السيرفر | أربع مهلات في http.Server |
| إيقاف هادئ | signal.NotifyContext ثم Shutdown |
| اختبار تكامل واختبار تزامن | PostgreSQL حقيقي و20 طلباً مع -race |
| Image صغيرة بمستخدم غير root | distroless بحجم 22 ميجابايت |
تدريب عملي
- أضف إلى الطلب مفتاح منع التكرار Idempotency Key في ترويسة، واحفظه في جدول بقيد فريد، حتى لا ينشئ ضغط زر «اشتر» مرتين طلبين، والفكرة في مقال Idempotency.
- غير
MaxConnsإلى 25 وأعد القياس بـwrk، ولاحظ هل يتغير الزمن المتوسط مع خمسين اتصالاً. - جرب الطريقة الأخرى: أمر
UPDATE … WHERE stock >= $1واحد لكل منتج مع فحص عدد الأسطر المتغيرة، وشغل اختبار العشرين طلباً عليها. - أضف
net/http/pprofعلى منفذ داخلي منفصل، وخذ ملف المعالج أثناء تشغيلwrk، وانظر أين يقضي الوقت: في JSON أم في pgx أم في الانتظار.
الخلاصة
وصلنا لنهاية الموضوع، وأهم ما فيه:
- الخدمة كاملة بالمكتبة القياسية
net/httpومكتبة واحدة هي pgx، والموجه منذ Go 1.22 يكفي لطرق مثلGET /orders/{id}دون إطار عمل. - المعاملة الواحدة ترتب المنتجات وتقفلها بـ
FOR UPDATEوتفحص وتنقص وتدخل، وdefer tx.Rollbackيلغيها في كل طريق خطأ. - اختبار العشرين طلباً على PostgreSQL حقيقي أعطى عشرة نجاحات وعشرة ردود 409 والمخزون صفر، وبدون
FOR UPDATEمنع القيد البيع الزائد، ولكن سبعة عملاء رأوا 500 بدل 409. - الحساب 990 × 3 أعطى 2,970 وضريبة 446 وإجمالي 3,416 هللة، كما في المواصفات.
- الـ Image على مرحلتين حجمها 22.0 ميجابايت، والذاكرة بين 5 و7 ميجابايت وهي تنتظر و12 إلى 14 بعد الضغط، و
wrkأعطى بين 2,522 و4,181 طلباً في الثانية على جهاز مشغول، والعملية جاهزة بعد 49 مللي ثانية بينما أخذ Docker Desktop ثوان.
وفي المقال الأخير من مرحلة لغة Go للمطورين نجمع الأخطاء التي يقع فيها القادمون من لغات أخرى، كل منها بتشغيل خاطئ حقيقي وإصلاحه، ثم خطة قراءة من المصادر الرسمية:
دليلGo لمن يعرف البرمجة: الأدوات Toolchain وأول مشروعتثبيت Go 1.27 والفرق في صيغتها عما تعرفه، ثم أدواتها في أمر واحد وشكل المشروع، مع تجربة كاملة تبني حاسبة طلب باختباراتها وفحصها وملف تنفيذي واحد.
دليلالأنواع والواجهات Interfaces والذاكرة والأخطاء في Goلماذا لا ينقص المخزون رغم أن الدالة تعمل، ولماذا لا يساوي الخطأ nil وهو يطبع nil، وكيف تقيس ما يحجزه كودك من الذاكرة وتختار شكل الخطأ في خدمة حقيقية بلغة Go.
دليلالتزامن في Go: الـ Goroutines والقنوات Channels بالأرقاممئة طلب شبكة ومهمة SHA-256 بالتسلسل ثم بالـ Goroutines، بحد للمعالج وبدونه، مع حالة سباق باعت عشرين قطعة من عشر، وجمود وتسرب نكشفهما بأدوات Go 1.27.
دليلأخطاء شائعة وأسلوب Go الصحيح Idiomatic Goثلاثة عشر خطأً يأتي بها المطور من Java وPython وJavaScript إلى Go، لكل منها تشغيل خاطئ حقيقي وإصلاحه، ثم ما يبحث عنه المراجع وخطة قراءة من المصادر الرسمية.
دليلكيف تختار لغة البرمجة Programming Language لمشروعك؟نختار لغة خدمة حقيقية بأسئلة الفريق والتوظيف والمكتبات والرخصة، ثم نكتبها بأربع لغات ونقيس البناء والحجم والذاكرة والطلبات في الثانية بأنفسنا.
دليلالأقفال Locks والجمود Deadlock في قواعد البياناتلماذا يوقف أمر ALTER TABLE صغير كل الاستعلامات خلفه، وكيف تقرأ pg_locks وتتجنب الجمود وظواهر العزل في PostgreSQL.سجل التحديثات
- أكتوبر 2026: كتابة المقال، وبناء الخدمة واختبارها وقياسها بالإصدار Go 1.27.3 وpgx v5.12.0 وPostgreSQL 17.11 داخل Docker Desktop على Windows 11.