تصميم الحزم

تصميم الحزم — Package Design

الحزمة (Package) هي وحدة التنظيم الأساسية في Go. كل مجلد = حزمة واحدة. تصميم الحزم بشكل جيد هو ما يفرق بين مشروع Go مبتدئ ومحترف.

التصدير — Exported vs Unexported

في Go، الحرف الأول يُحدد هل الشيء مرئي خارج الحزمة:

main.go

package main

import "fmt"

// مُصدّر — يبدأ بحرف كبير — Exported
type User struct {
    Name  string // مُصدّر — Exported
    Email string // مُصدّر — Exported
    age   int    // خاص — Unexported
}

// مُصدّر — Exported function
func NewUser(name, email string, age int) *User {
    return &User{Name: name, Email: email, age: age}
}

// خاص — Unexported function
func validateEmail(email string) bool {
    for _, ch := range email {
        if ch == '@' {
            return true
        }
    }
    return false
}

// مُصدّر يستدعي خاص — Exported calls unexported
func (u *User) IsValid() bool {
    return u.Name != "" && validateEmail(u.Email)
}

func main() {
    u := NewUser("أحمد", "ahmed@example.com", 28)
    fmt.Printf("الاسم: %s\n", u.Name)   // ✅ مُصدّر
    fmt.Printf("البريد: %s\n", u.Email) // ✅ مُصدّر
    // fmt.Println(u.age)               // ❌ خاص (في حزمة أخرى)
    fmt.Printf("صالح: %v\n", u.IsValid())

    fmt.Println("\n=== قواعد التصدير ===")
    fmt.Println("User     → مُصدّر (حرف كبير)")
    fmt.Println("user     → خاص (حرف صغير)")
    fmt.Println("NewUser  → مُصدّر")
    fmt.Println("validate → خاص")
    fmt.Println("Name     → حقل مُصدّر")
    fmt.Println("age      → حقل خاص")
}

Output:

مجلد internal/ — الحزم الداخلية

internal/ هو مجلد خاص في Go — الحزم داخله لا يمكن استيرادها إلا من الحزم الأم:

myproject/
├── internal/
│   ├── auth/       # فقط myproject يستطيع استيرادها
│   └── database/   # لا يستطيع مشروع آخر استيرادها
├── pkg/
│   └── utils/      # أي مشروع يستطيع استيرادها
└── main.go

هذا يُعطيك ضمان أن الأشياء الداخلية لن يعتمد عليها أحد.

دالة init()

init() تُنفّذ تلقائياً عند استيراد الحزمة — قبل main():

main.go

package main

import "fmt"

// متغيرات على مستوى الحزمة — Package-level variables
var config map[string]string

// init تعمل قبل main — init runs before main
func init() {
    fmt.Println("1️⃣ init: تهيئة الإعدادات")
    config = map[string]string{
        "env":  "production",
        "port": "8080",
    }
}

// يمكن كتابة عدة init — Multiple init functions allowed
func init() {
    fmt.Println("2️⃣ init: تحقق من الإعدادات")
    if config["env"] == "" {
        panic("البيئة غير محددة!")
    }
}

func main() {
    fmt.Println("3️⃣ main: البرنامج بدأ")
    fmt.Printf("البيئة: %s، المنفذ: %s\n", config["env"], config["port"])
}

Output:

متى تستخدم init():

تسجيل مشغّلات قواعد البيانات (database/sql drivers)
تهيئة إعدادات ثابتة
التحقق من متغيرات البيئة

متى لا تستخدمها:

منطق أعمال معقد
عمليات I/O ثقيلة
أي شيء قد يفشل (صعب الاختبار)

أفضل ممارسات تصميم الحزم

main.go

package main

import "fmt"

func main() {
    fmt.Println("=== أفضل ممارسات تصميم الحزم ===\n")

    tips := []struct {
        rule    string
        good    string
        bad     string
    }{
        {
            "اسم الحزمة = مفرد قصير",
            "user, auth, http",
            "users, authentication, httpHandler",
        },
        {
            "لا تكرر اسم الحزمة",
            "user.New() — واضح",
            "user.NewUser() — تكرار",
        },
        {
            "حزمة واحدة = مسؤولية واحدة",
            "auth/ (مصادقة فقط)",
            "utils/ (كل شيء مختلط)",
        },
        {
            "صدّر فقط ما يحتاجه المستخدم",
            "Exported: New(), Get()",
            "كل شيء مُصدّر بلا سبب",
        },
        {
            "تجنّب حزمة utils العامة",
            "strings.Contains()",
            "utils.Contains()",
        },
    }

    for i, t := range tips {
        fmt.Printf("%d. %s\n", i+1, t.rule)
        fmt.Printf("   ✅ %s\n", t.good)
        fmt.Printf("   ❌ %s\n\n", t.bad)
    }
}

Output:

نشر وحدة — Publishing a Module

main.go

package main

import "fmt"

func main() {
    fmt.Println("=== خطوات نشر وحدة Go ===\n")

    steps := []string{
        "أنشئ مستودع على GitHub: github.com/user/mylib",
        "go mod init github.com/user/mylib",
        "اكتب الكود والاختبارات",
        "git tag v1.0.0 && git push origin v1.0.0",
        "الآن أي شخص يستطيع: go get github.com/user/mylib@v1.0.0",
    }

    for i, s := range steps {
        fmt.Printf("  %d. %s\n", i+1, s)
    }

    fmt.Println("\n💡 نصائح:")
    fmt.Println("  - اكتب README.md واضح مع أمثلة")
    fmt.Println("  - أضف LICENSE (MIT أو Apache 2.0)")
    fmt.Println("  - اكتب اختبارات (go test -cover)")
    fmt.Println("  - أضف GoDoc comments لكل شيء مُصدّر")
    fmt.Println("  - pkg.go.dev يُنشئ التوثيق تلقائياً")
}

Output:

توثيق GoDoc

// Package auth provides authentication and authorization utilities.
// It supports JWT tokens and API key authentication.
package auth

// User represents an authenticated user in the system.
// A User is created after successful authentication via Authenticate.
type User struct {
    ID    int
    Name  string
    Email string
}

// Authenticate validates credentials and returns a User.
// It returns ErrInvalidCredentials if the email or password is wrong.
//
// Example:
//
//	user, err := auth.Authenticate("[email protected]", "password")
//	if err != nil {
//	    log.Fatal(err)
//	}
func Authenticate(email, password string) (*User, error) {
    // ...
}

تحدي — Challenge

package main

import "fmt"

type User struct {
    Name  string
    Email string
    age   int // خاص — private
}

// أنشئ دالة NewUser تُرجع *User — اكتب الكود هنا
func NewUser(name, email string, age int) *User {
    return nil
}

// أضف أسلوب IsValid ��تحقق أن Name و Email غير فارغين — اكتب الكود هنا
func (u *User) IsValid() bool {
    return false
}

func main() {
    u := NewUser("أحمد", "ahmed@example.com", 28)
    fmt.Printf("✅ NewUser: %s (%s)\n", u.Name, u.Email)
    fmt.Printf("✅ IsValid: %v\n", u.IsValid())
    fmt.Println("✅ حقل خاص محمي: لا يمكن الوصول لـ age من خارج الحزمة")
}