> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# خدمة طلبات حقيقية بلغة Go: مكتبة net/http مع PostgreSQL
- URL: https://arabroot.io/articles/خدمة-طلبات-حقيقية-بلغة-go-net-http-مع-postgresql/
- Published: 2026-10-31T07:58:51.000Z
- Updated: 2026-11-19T06:44:14.000Z
- Description: نبني خدمة الطلبات المشتركة في هذا المسار بلغة Go والمكتبة القياسية وpgx، بمعاملة تقفل المخزون واختبارات على PostgreSQL حقيقي وImage بحجم 22 ميجابايت، ثم نقيسها بصدق.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, لغات البرمجة عملياً

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

وهذا المقال الرابع في مرحلة [لغة Go للمطورين](https://arabroot.io/start/#stage-lang-go)، وفيه نبني نفس الخدمة التي يبنيها كل مسار لغة في هذا القسم بنفس المواصفات بالضبط، حتى تقارن بين اللغات على أرض واحدة: نفس جداول PostgreSQL 17، ونفس قواعد الضريبة والأخطاء، ونفس الاختبارات، ونفس طريقة القياس. وفي Go نبنيها بالطريقة الأكثر شيوعاً في مجتمع اللغة: المكتبة القياسية `net/http` دون إطار عمل Framework، ومكتبة [pgx](https://github.com/jackc/pgx?ref=arabroot.io) لقاعدة البيانات، وهي المكتبة الخارجية الوحيدة في المشروع. وإذا كنت تريد الصورة العامة لتصميم واجهات REST قبل الكود، فقد شرحناها في مقال [تصميم واجهات API](https://arabroot.io/articles/%D8%AA%D8%B5%D9%85%D9%8A%D9%85-%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-api-rest-%D9%88-grpc-%D9%88-graphql/).

وسوف نناقش في هذا المقال ما يلي:

- المواصفات المشتركة: الجداول والطرق والردود، ولماذا لا نحتاج إطار عمل في 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 قاعدة البيانات عند أول تشغيل:

```sql
-- 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](https://arabroot.io/articles/%D8%A7%D9%84%D8%A3%D8%B1%D9%82%D8%A7%D9%85-%D8%A7%D9%84%D8%B9%D8%B4%D8%B1%D9%8A%D8%A9-floating-point-%D9%85%D9%86-%D8%A7%D9%84%D8%AF%D8%A7%D8%AE%D9%84/). والقيد `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 وحده للطريقة غير المسموحة، كما تشرح [تدوينة تحسينات التوجيه](https://go.dev/blog/routing-enhancements?ref=arabroot.io)، فلم يعد للإطار في خدمة مثل خدمتنا إلا فائدة صغيرة، مقابل اعتماد إضافي وواجهة خاصة به تختلف عن `http.Handler` التي تعرفها كل مكتبات Go. ولكن لا بأس بإطار عمل في فريق تعود عليه، فهذه ليست قاعدة، وإنما أسلوب المكتبة القياسية هو ما سوف تجده في أغلب الكود الذي تقرؤه.

## شكل المشروع Project Layout: أربع حزم

الصورة التالية تبين طريق الطلب من العميل إلى قاعدة البيانات، والحزمة المسؤولة عن كل خطوة:

![خمس مراحل من العميل إلى الموجه ServeMux في net/http إلى المعالجات في internal/api إلى طبقة البيانات في internal/store إلى PostgreSQL 17، وتحتها ثلاث بطاقات للحزمة internal/money والبرنامج cmd/orders وواجهة Store في api](https://arabroot.io/content/images/2026/11/go-real-service-01-architecture.webp)

كل حزمة لها مسؤولية واحدة، والاعتماد يسير في اتجاه واحد من HTTP إلى قاعدة البيانات

وهذا التقسيم بالضبط ما شرحناه في المقال الأول عن المجلد `internal` وفي المقال الثاني عن الواجهات التي يعرفها المستهلك: الحزمة `money` لا تعتمد على شيء، والحزمة `store` تعتمد على `money` وpgx، والحزمة `api` تعرف واجهة صغيرة لما تحتاجه من `store`، والبرنامج في `cmd/orders` هو الوحيد الذي يعرف كل شيء ويربطه ببعضه. والكود كاملاً في مجلد `lab`، وسوف نعرض هنا الأجزاء المهمة.

## دالة الضريبة VAT: أصغر حزمة وأهمها

```go
// 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، ويشرحها [الدرس الرسمي للوصول إلى قواعد البيانات](https://go.dev/doc/tutorial/database-access?ref=arabroot.io)، أو مكتبة pgx مباشرة بواجهتها الخاصة. واخترنا الثانية لأنها الأكثر استخداماً مع PostgreSQL تحديداً، وتعطيك أنواع PostgreSQL كما هي، مثل المصفوفات التي نحتاجها في `ANY($1)`، والدفعات Batches التي ترسل عدة أوامر دفعة واحدة على الشبكة، ومجمع اتصالات [pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool?ref=arabroot.io) مصمم لها. وأول الملف الأنواع والأخطاء:

```go
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: قفل ثم فحص ثم تنقيص

وهذه أهم دالة في الخدمة كلها:

```go
// 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
}
```

![سبع خطوات مرقمة: ترتيب أرقام المنتجات وبدء المعاملة، ثم قفل الأسطر بـ SELECT FOR UPDATE، ثم 400 للمنتج غير الموجود، ثم 409 للمخزون الذي لا يكفي، ثم حساب الضريبة من أسعار قاعدة البيانات، ثم إدخال الطلب وإنقاص المخزون في دفعة، ثم التأكيد ويرجع 201](https://arabroot.io/content/images/2026/11/go-real-service-02-transaction.webp)

كل ما بين البداية والتأكيد يحدث كوحدة واحدة، والقفل يمنع طلبين من قراءة نفس المخزون

في الكود أعلاه لاحظ التالي:

- `slices.Sort(ids)` قبل أي شيء، و`ORDER BY id` في الاستعلام، والسبب درس الجمود من المقال الثالث: طلبان فيهما القهوة والهيل بترتيب مختلف قد يقفل كل منهما سطراً وينتظر الآخر، والترتيب الثابت يمنع ذلك. وPostgreSQL يكتشف الجمود ويلغي إحدى المعاملتين، كما شرحنا في مقال [الأقفال والجمود في قواعد البيانات](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D9%82%D9%81%D8%A7%D9%84-locks-%D9%88%D8%A7%D9%84%D8%AC%D9%85%D9%88%D8%AF-deadlock-%D9%81%D9%8A-%D9%82%D9%88%D8%A7%D8%B9%D8%AF-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA/)، ولكن العميل سوف يرى خطأً لا ذنب له فيه.
- `defer tx.Rollback(ctx)` مباشرة بعد `Begin`، وهو نمط Go المعروف: في كل طريق خروج بخطأ تلغى المعاملة وحدها، وبعد `Commit` الناجح يصبح `Rollback` بلا أثر. فلا تحتاج أن تكتب الإلغاء في كل `return`، ولا تخاف أن تنساه في طريق جديد تضيفه بعد سنة.
- `FOR UPDATE` يقفل أسطر المنتجات المطلوبة حتى نهاية المعاملة، فكل طلب آخر على نفس المنتج ينتظر عند هذا الاستعلام، ثم يقرأ المخزون بعد أن تغير. والتفاصيل في توثيق [FOR UPDATE في PostgreSQL 17](https://www.postgresql.org/docs/17/sql-select.html?ref=arabroot.io#SQL-FOR-UPDATE-SHARE) وفي [الأقفال الصريحة Explicit Locking](https://www.postgresql.org/docs/17/explicit-locking.html?ref=arabroot.io).
- السعر يقرأ من قاعدة البيانات داخل المعاملة، ولا يقبل من العميل أبداً، وإلا فإن أي عميل يعرف كيف يعدل الطلب يستطيع أن يشتري الهيل بهللة.
- الدفعة `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، وهو يكفي هنا لأن القفل الصريح هو الذي يحمينا، والفرق بين المستويات في [توثيق مستويات العزل](https://www.postgresql.org/docs/17/transaction-iso.html?ref=arabroot.io).

## طبقة HTTP: المعالجات Handlers والتحقق Validation

أول الملف `internal/api/api.go` الواجهة التي تحتاجها الطبقة، والموجه:

```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` التي سوف نراها بعد قليل. ثم معالج إنشاء الطلب:

```go
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](https://pkg.go.dev/net/http?ref=arabroot.io#MaxBytesReader) يحد حجم الجسم بـ 64 كيلوبايت، والسبب أن فك JSON بلا حد يسمح لأي شخص أن يرسل جسماً بمئات الميجابايتات فيستهلك ذاكرة الخدمة.
- [DisallowUnknownFields](https://pkg.go.dev/encoding/json?ref=arabroot.io#Decoder.DisallowUnknownFields) يرفض الحقل المجهول، فالخطأ الإملائي `itemz` يرجع 400 بدل أن يتجاهل الحقل ويرجع «القائمة فارغة»، وهو خطأ أصعب على من يدمج مع الخدمة.
- التحقق يحد عدد الأسطر والكمية، ويجمع المنتج المكرر في سطر واحد بالخريطة `qty`، لأن طلباً فيه نفس المنتج مرتين سوف يقفل نفس السطر مرتين ويفحص المخزون مرتين بشكل خاطئ.
- الـ `switch` بعد الاستدعاء يحول كل شكل خطأ إلى رده: `errors.As` لنوع المخزون فيرجع 409 مع الأرقام، و`errors.Is` للمنتج المجهول فيرجع 400، وأي خطأ آخر يذهب إلى `fail` التي تكتب الخطأ الحقيقي في السجل وترجع للعميل «internal error» فقط، لأن رسالة قاعدة البيانات قد تكشف أسماء جداول وقيوداً لا يحتاج العميل أن يعرفها.
- الرد 201 يحمل الترويسة `Location` بعنوان الطلب الجديد، كما تتوقع مكتبات HTTP.

وفي آخر الملف الحماية من الـ panic، وهي نفس الفكرة التي جربناها في المقال الثاني:

```go
// 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

```go
// 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](https://pkg.go.dev/os/signal?ref=arabroot.io#NotifyContext) يعطي سياقاً يلغى عند SIGTERM، وهي الإشارة التي يرسلها `docker stop` وKubernetes قبل إيقاف الـ Container، فيتوقف السيرفر عن قبول اتصالات جديدة بـ `Shutdown`، وينتظر الطلبات الجارية حتى عشر ثوان، ثم يغلق المجمع. وفي تجربتنا ظهر السطر `shutting down` في السجل بعد `docker stop`، ثم خرج البرنامج قبل أن تنتهي مهلة Docker.
- المهلات الأربع في [http.Server](https://pkg.go.dev/net/http?ref=arabroot.io#Server): القيمة الافتراضية لكل منها صفر، أي بلا حد، وهذا يعني أن عميلاً بطيئاً يرسل الترويسات حرفاً كل دقيقة يحجز اتصالاً إلى الأبد. لذلك `ReadHeaderTimeout` على الأقل يجب أن يكون في كل سيرفر يخدم الإنترنت، وأداة `go vet` لا تنبهك إلى ذلك.
- `cfg.MaxConns = 10`: حد اتصالات المجمع، والطلب الحادي عشر الذي يحتاج قاعدة البيانات ينتظر اتصالاً فارغاً. وهذا الحد يجب أن يحسب مع عدد نسخ الخدمة وحد PostgreSQL نفسه، كما شرحنا في مقال [PostgreSQL لكل شيء](https://arabroot.io/articles/postgresql-%D9%84%D9%83%D9%84-%D8%B4%D9%8A%D8%A1-%D9%85%D8%AA%D9%89-%D8%AA%D9%83%D9%81%D9%8A%D9%83-%D9%82%D8%A7%D8%B9%D8%AF%D8%A9-%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D9%88%D8%A7%D8%AD%D8%AF%D8%A9/).
- السجل بـ [log/slog](https://pkg.go.dev/log/slog?ref=arabroot.io) بصيغة JSON، وهي المكتبة القياسية للسجلات المنظمة منذ Go 1.21، والسطر الأول يسجل زمن البدء من لحظة تحميل البرنامج، وسوف نحتاجه في القياس.

## الاختبارات Tests: ثلاث طبقات

شرحنا أنواع الاختبارات ومتى تستخدم كلاً منها في مقال [أنواع الاختبارات](https://arabroot.io/articles/%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1%D8%A7%D8%AA-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-unit-%D9%88-integration-%D9%88-e2e/)، وفي هذه الخدمة ثلاث طبقات، لكل منها ما تحميه.

### اختبار الوحدة Unit Test للضريبة

```go
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](https://pkg.go.dev/net/http/httptest?ref=arabroot.io) دون شبكة ولا قاعدة بيانات، ويتحقق من رمز الرد ومن جزء من الجسم في كل حالة: 201 مع ضريبة 446، و409 مع المخزون، و400 للمنتج المجهول والقائمة الفارغة والكمية صفر والكمية نصاً والحقل المجهول، و404 و405\. وهذا الاختبار يعمل في أقل من 0.1 ثانية، ويحمي عقد الواجهة Contract الذي يعتمد عليه تطبيق المتجر.

### اختبار التكامل Integration على PostgreSQL حقيقي

النسخة المزيفة لا تقول شيئاً عن SQL ولا عن الأقفال، لذلك اختبارات الحزمة `store` تعمل على PostgreSQL 17 حقيقي في Container، وكل اختبار يعيد الجداول إلى البذرة نفسها قبل أن يبدأ:

```go
// 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](https://testcontainers.com/guides/getting-started-with-testcontainers-for-go/?ref=arabroot.io) التي تشغل الـ Container من داخل الاختبار نفسه، وهي مريحة، ولكنها تحتاج أن يصل الاختبار إلى Docker، وهذا يعقد التشغيل داخل Container كما فعلنا. ثم اختبار العشرين طلباً:

```go
// 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)` في نفس اللحظة، وإلا لبدأت الأولى وانتهت قبل أن تنشأ الأخيرة ولم يحدث أي تنافس. ثم شغلنا الاختبارات كلها، والتكامل مع كاشف السباقات:

```bash
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/
```

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

```text
=== 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` من الاستعلام في نسخة مؤقتة من الكود، ونعيد اختبار العشرين طلباً ثلاث مرات:

```text
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)
```

ومخرج تشغيل واحد كاملاً:

```text
=== 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)` كل تنقيص بعده، فانتهت المعاملة بخطأ وألغيت كلها.

![مقارنة بين عشرين مربعاً لكل حالة: مع FOR UPDATE عشرة بالرد 201 وعشرة بالرد 409 والاختبار ينجح، وبدونها عشرة بالرد 201 وثلاثة بالرد 409 وسبعة بالرد 500 بسبب قيد CHECK على المخزون](https://arabroot.io/content/images/2026/11/go-real-service-03-concurrency-test.webp)

القيد منع البيع الزائد، ولكن القفل هو الذي جعل العميل يرى السبب الصحيح

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

وقد يتساءل البعض: إذا كان القيد قد حمى البيانات، فلماذا لا نكتفي به، ونحول خطأه إلى 409؟ وهذا ممكن فعلاً، فمكتبة pgx ترجع الخطأ من النوع `*pgconn.PgError`، وفيه الحقل `Code` برمز SQLSTATE، والرمز `23514` يعني مخالفة قيد CHECK، فتستطيع أن تفحصه بـ `errors.As` وترجع 409\. ولكن انظر إلى ما تخسره: الرد لن يعرف كم المتوفر من المخزون لأن المعاملة لم تقرأه بعد آخر تغيير، ومعاملات كثيرة سوف تبدأ وتكتب ثم تلغى، وهذا عمل ضائع على قاعدة البيانات في أكثر لحظاتها ضغطاً، وأي تعديل لاحق في الكود يقرأ المخزون ليقرر شيئاً آخر، مثل خصم على آخر قطعة، سوف يقرأ قيمة قديمة. لذلك اجعل القيد شبكة أمان تلتقط ما فات الكود، واجعل القفل هو الطريق الطبيعي، وتحويل الرمز 23514 إلى 409 إضافة جيدة كخط ثان، وليس بديلاً.

## التشغيل والطلبات Requests كما يراها العميل

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

```text
$ 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

```dockerfile
# 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"]
```

في الإعداد أعلاه لاحظ التالي:

- المرحلة الأولى فيها المترجم كاملاً، والثانية فيها الملف التنفيذي فقط، وهذا ما يشرحه توثيق [البناء متعدد المراحل](https://docs.docker.com/build/building/multi-stage/?ref=arabroot.io).
- نسخ `go.mod` و`go.sum` ثم `go mod download` قبل نسخ الكود، حتى تبقى طبقة المكتبات في الـ Cache ما دامت المكتبات لم تتغير.
- السطر `--mount=type=cache` هو الحل لمشكلة رأيناها في مقال اختيار اللغة، حيث أعاد كل بناء ترجمة المكتبة القياسية كلها، والتفاصيل في توثيق [تحسين الـ Cache](https://docs.docker.com/build/cache/optimize/?ref=arabroot.io).
- `CGO_ENABLED=0` يضمن ملفاً ثابتاً لا يحتاج `libc`، و`-trimpath` يحذف مسارات جهاز البناء من الملف، و`-s -w` يحذف رموز التصحيح.
- الصورة النهائية [distroless/static](https://github.com/GoogleContainerTools/distroless?ref=arabroot.io) من Google، وفيها شهادات CA وملفات المنطقة الزمنية ومستخدم `nonroot`، ولا يوجد فيها shell، فالمخترق الذي يجد ثغرة في الخدمة لا يجد أدوات يعمل بها. وثمن ذلك أنك لا تستطيع أن تدخل الـ Container بـ `sh` لتصحح شيئاً، والبديل `docker debug` أو Container جانبي.

![مرحلتان: مرحلة البناء من golang:1.27.3-trixie بحجم 1.31 جيجابايت مع تنزيل المكتبات والترجمة التي أخذت 49.1 ثانية، ومرحلة التشغيل من distroless/static-debian13:nonroot فيها الملف التنفيذي فقط بحجم 22 ميجابايت](https://arabroot.io/content/images/2026/11/go-real-service-04-image.webp)

المترجم يبقى في مرحلة البناء، ولا يصل إلى السيرفر إلا ملف واحد

والبناء الأول أخذ 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](https://github.com/wg/wrk?ref=arabroot.io) بخيطين وخمسين اتصالاً لمدة 15 ثانية من Container آخر على نفس الشبكة، ثم الذاكرة بعد الضغط، والخدمة محدودة بـ `--cpus=2 --memory=512m`. وشغلنا السكربت كاملاً مرتين:

```bash
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
```

والمجموعة الأولى:

```text
== 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
```

والمجموعة الثانية:

```text
== 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
```

![أعمدة لأربعة تشغيلات wrk بين 4181 و2522 طلباً في الثانية، وبجانبها حجم الـ Image 22 ميجابايت، والذاكرة وهي تنتظر 5.0 و6.9 ميجابايت، وبعد الضغط 11.8 و14.2، وبدء العملية 49 مللي ثانية، والزمن من docker run إلى أول 200 بين 8.9 و10.7 ثانية](https://arabroot.io/content/images/2026/11/go-real-service-05-measure.webp)

الأرقام الثابتة هي الحجم والذاكرة، أما الطلبات في الثانية والبدء فتأثرا بانشغال الجهاز

ولنقرأ الأرقام بصدق:

- الطلبات في الثانية: 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 على جهاز مشغول يغطي على كل شيء.

```text
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 فيها نصوص عربية، والمجمع يسمح بعشرة استعلامات فقط في نفس الوقت. فالخدمة هنا تقضي أغلب وقتها في انتظار قاعدة البيانات، وهذا هو الشكل الطبيعي لأغلب الخدمات الحقيقية، ولهذا السبب بالذات يصغر الفرق بين اللغات كثيراً في هذا النوع من القياس مقارنة بطريق حسابي بحت، وهي النقطة التي ذكرناها هناك. فإذا أردت أن تزيد هذا الرقم فابدأ من قاعدة البيانات: فهرس، أو ذاكرة مؤقتة لقائمة المنتجات التي لا تتغير كل ثانية، قبل أن تفكر في تغيير اللغة.

ولكي تقرأ هذه الأرقام في سياقها: المتجر في قصتنا يحتاج في أسوأ يوم بضعة طلبات في الثانية، كما حسبنا في مقال [كيف تختار لغة البرمجة](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%AE%D8%AA%D8%A7%D8%B1-%D9%84%D8%BA%D8%A9-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%84%D9%85%D8%B4%D8%B1%D9%88%D8%B9%D9%83/)، فحتى أقل رقم هنا أكبر من الحاجة بمئات المرات، والحد الحقيقي سوف يكون قاعدة البيانات قبل الخدمة. وإذا أردت أن تقيس الخدمة كما يجب قبل يوم تخفيض حقيقي، فبسيناريو كامل وليس بطريق واحد، فقد شرحنا ذلك في مقال [اختبار الضغط Load Testing](https://arabroot.io/articles/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1-%D8%A7%D9%84%D8%A7%D8%AD%D9%85%D8%A7%D9%84-%D9%88%D8%A7%D9%84%D8%B6%D8%BA%D8%B7-load-%D9%88-stress-testing-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/).

## ما الذي ينقص الخدمة قبل الإنتاج؟ 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](https://arabroot.io/articles/idempotency-%D9%83%D9%8A%D9%81-%D8%AA%D8%AC%D8%B9%D9%84-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D8%A7%D9%85%D9%86%D8%A9-%D8%B9%D9%86%D8%AF-%D8%AA%D9%83%D8%B1%D8%A7%D8%B1%D9%87%D8%A7/).
- غير `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 للمطورين](https://arabroot.io/start/#stage-lang-go) نجمع الأخطاء التي يقع فيها القادمون من لغات أخرى، كل منها بتشغيل خاطئ حقيقي وإصلاحه، ثم خطة قراءة من المصادر الرسمية:

[![](https://arabroot.io/content/images/2026/10/go-for-devs-cover-cover.webp)دليلGo لمن يعرف البرمجة: الأدوات Toolchain وأول مشروعتثبيت Go 1.27 والفرق في صيغتها عما تعرفه، ثم أدواتها في أمر واحد وشكل المشروع، مع تجربة كاملة تبني حاسبة طلب باختباراتها وفحصها وملف تنفيذي واحد.](https://arabroot.io/articles/go-%D9%84%D9%85%D9%86-%D9%8A%D8%B9%D8%B1%D9%81-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A7%D9%84%D8%A7%D8%AF%D9%88%D8%A7%D8%AA-%D9%88%D8%A7%D9%88%D9%84-%D9%85%D8%B4%D8%B1%D9%88%D8%B9/)[![](https://arabroot.io/content/images/2026/10/go-types-memory-cover-cover.webp)دليلالأنواع والواجهات Interfaces والذاكرة والأخطاء في Goلماذا لا ينقص المخزون رغم أن الدالة تعمل، ولماذا لا يساوي الخطأ nil وهو يطبع nil، وكيف تقيس ما يحجزه كودك من الذاكرة وتختار شكل الخطأ في خدمة حقيقية بلغة Go.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D9%88%D8%A7%D9%84%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-interfaces-%D9%88%D8%A7%D9%84%D8%B0%D8%A7%D9%83%D8%B1%D8%A9-%D9%88%D8%A7%D9%84%D8%A7%D8%AE%D8%B7%D8%A7%D8%A1-%D9%81%D9%8A-go/)[![](https://arabroot.io/content/images/2026/10/go-concurrency-cover-cover.webp)دليلالتزامن في Go: الـ Goroutines والقنوات Channels بالأرقاممئة طلب شبكة ومهمة SHA-256 بالتسلسل ثم بالـ Goroutines، بحد للمعالج وبدونه، مع حالة سباق باعت عشرين قطعة من عشر، وجمود وتسرب نكشفهما بأدوات Go 1.27.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B2%D8%A7%D9%85%D9%86-%D9%81%D9%8A-go-goroutines-%D9%88%D8%A7%D9%84%D9%82%D9%86%D9%88%D8%A7%D8%AA-channels/)[![](https://arabroot.io/content/images/2026/10/go-idioms-cover-cover.webp)دليلأخطاء شائعة وأسلوب Go الصحيح Idiomatic Goثلاثة عشر خطأً يأتي بها المطور من Java وPython وJavaScript إلى Go، لكل منها تشغيل خاطئ حقيقي وإصلاحه، ثم ما يبحث عنه المراجع وخطة قراءة من المصادر الرسمية.](https://arabroot.io/articles/%D8%A7%D8%AE%D8%B7%D8%A7%D8%A1-%D8%B4%D8%A7%D8%A6%D8%B9%D8%A9-%D9%88%D8%A7%D8%B3%D9%84%D9%88%D8%A8-go-%D8%A7%D9%84%D8%B5%D8%AD%D9%8A%D8%AD-idiomatic-go/)[![](https://arabroot.io/content/images/2026/11/choose-language-cover-cover.webp)دليلكيف تختار لغة البرمجة Programming Language لمشروعك؟نختار لغة خدمة حقيقية بأسئلة الفريق والتوظيف والمكتبات والرخصة، ثم نكتبها بأربع لغات ونقيس البناء والحجم والذاكرة والطلبات في الثانية بأنفسنا.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%AE%D8%AA%D8%A7%D8%B1-%D9%84%D8%BA%D8%A9-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%84%D9%85%D8%B4%D8%B1%D9%88%D8%B9%D9%83/)[![](https://arabroot.io/content/images/2026/11/db-locking-cover-cover.webp)دليلالأقفال Locks والجمود Deadlock في قواعد البياناتلماذا يوقف أمر ALTER TABLE صغير كل الاستعلامات خلفه، وكيف تقرأ pg\_locks وتتجنب الجمود وظواهر العزل في PostgreSQL.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D9%82%D9%81%D8%A7%D9%84-locks-%D9%88%D8%A7%D9%84%D8%AC%D9%85%D9%88%D8%AF-deadlock-%D9%81%D9%8A-%D9%82%D9%88%D8%A7%D8%B9%D8%AF-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA/)

## سجل التحديثات

- أكتوبر 2026: كتابة المقال، وبناء الخدمة واختبارها وقياسها بالإصدار Go 1.27.3 وpgx v5.12.0 وPostgreSQL 17.11 داخل Docker Desktop على Windows 11.