my-module/              ← جذر الوحدة، يحتوي go.mod
├── go.mod
├── main.go             ← package main
├── mathutil/           ← حزمة فرعية mathutil
│   └── calc.go         ← package mathutil
└── internal/           ← حزمة داخلية
    └── secret.go       ← package internal

package main // حزمة الدخول للبرامج التنفيذية

package mathutil // حزمة الأدوات

# نفّذ في جذر المشروع
go mod init my-module

# يُنشئ ملف go.mod:
# module my-module
#
# go 1.24

# إضافة التبعيات المفقودة، إزالة غير المستخدمة
go mod tidy

import "fmt"                    // المكتبة القياسية
import "github.com/gin-gonic/gin" // حزمة طرف ثالث

// استيرادات مجمعة (موصى بها)
import (
    "fmt"
    "log"
    "os"
)

package mathutil

var Pi = 3.14159      // يبدأ بحرف كبير → مُصدَّر، مرئي خارجيًا
var version = "1.0"   // يبدأ بحرف صغير → غير مُصدَّر، خاص بالحزمة فقط

func Add(a, b int) int { // حرف كبير → مُصدَّر
    return a + b
}

func subtract(a, b int) int { // حرف صغير → غير مُصدَّر
    return a - b
}

myapp/
├── internal/
│   └── auth/        ← فقط myapp/ و أدلة الفرعية يمكنها الاستيراد
│       └── auth.go
└── cmd/
    └── server/
        └── main.go ← ✅ يمكنها استيراد myapp/internal/auth

# تحميل الحزمة وتحديث go.mod / go.sum
go get github.com/gin-gonic/gin

# تحديد إصدار
go get github.com/gin-gonic/gin@v1.9.1

# إزالة التبعيات غير المستخدمة
go mod tidy

greet-app/
├── go.mod
├── main.go
└── greeting/
    └── greet.go

package greeting

import "fmt"

// Hello يُرجع تحية (حرف كبير، مُصدَّر)
func Hello(name string) string {
    return fmt.Sprintf("Hello, %s! Welcome to Go programming.", name)
}

// farewell يُرجع رسالة وداع (حرف صغير، غير مُصدَّر)
func farewell(name string) string {
    return fmt.Sprintf("Goodbye, %s!", name)
}

// Goodbye هو غلاف مُصدَّر لـ farewell (حرف كبير، مُصدَّر)
func Goodbye(name string) string {
    return farewell(name)
}

package main

import (
    "fmt"
    "greet-app/greeting" // استيراد حزمة فرعية محلية
)

func main() {
    // استخدام الدوال المُصدَّرة
    fmt.Println(greeting.Hello("Alice"))
    fmt.Println(greeting.Goodbye("Alice"))

    // ❌ الكود التالي سيُسبب خطأ: farewell غير مُصدَّر
    // fmt.Println(greeting.farewell("Alice"))
}

go run main.go

Hello, Alice! Welcome to Go programming.
Goodbye, Alice!

mkdir http-demo && cd http-demo
go mod init http-demo
go get github.com/gin-gonic/gin

package main

import (
    "net/http"

    "github.com/gin-gonic/gin" // إطار ويب من طرف ثالث
)

// User يُعرّف تراكيب مستخدم
type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    r := gin.Default() // إنشاء محرك افتراضي

    // طلب GET: إرجاع رسالة ترحيب
    r.GET("/", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Welcome to the Go package management tutorial!",
        })
    })

    // طلب GET: إرجاع معلومات المستخدم
    r.GET("/user", func(c *gin.Context) {
        user := User{
            Name:  "Alice",
            Email: "alice@example.com",
        }
        c.JSON(http.StatusOK, user)
    })

    // بدء الخادم، الاستماع على المنفذ 8080
    r.Run(":8080")
}

go run main.go
# بعد بدء الخادم، زر http://localhost:8080

bank-system/
├── go.mod
├── main.go
├── account/
│   └── account.go       ← حزمة الحساب (عامة)
├── internal/
│   └── validator/
│       └── validator.go ← حزمة المدقق (داخلية فقط)
└── transaction/
    └── transaction.go   ← حزمة المعاملات (عامة)

module bank-system

go 1.24

package validator

import "errors"

// ValidateAmount يُحقّق من مبلغ المعاملة (حزمة داخلية فقط)
func ValidateAmount(amount float64) error {
    if amount <= 0 {
        return errors.New("amount must be greater than zero")
    }
    if amount > 1000000 {
        return errors.New("single transaction cannot exceed 1 million")
    }
    return nil
}

// ValidateAccountID يُحقّق من معرّف الحساب
func ValidateAccountID(id string) error {
    if len(id) < 6 {
        return errors.New("account ID must be at least 6 characters")
    }
    return nil
}

package account

import (
    "fmt"
    "bank-system/internal/validator" // استيراد الحزمة الداخلية
)

// Account تراكيب
type Account struct {
    ID      string
    Name    string
    Balance float64
}

// NewAccount يُنشئ حسابًا جديدًا
func NewAccount(id, name string, balance float64) (*Account, error) {
    // استخدام دالة التحقق من الحزمة الداخلية
    if err := validator.ValidateAccountID(id); err != nil {
        return nil, fmt.Errorf("account creation failed: %w", err)
    }
    if balance < 0 {
        return nil, fmt.Errorf("initial balance cannot be negative")
    }
    return &Account{
        ID:      id,
        Name:    name,
        Balance: balance,
    }, nil
}

// Deposit يودع أموالًا
func (a *Account) Deposit(amount float64) error {
    // استخدام دالة التحقق من الحزمة الداخلية
    if err := validator.ValidateAmount(amount); err != nil {
        return fmt.Errorf("deposit failed: %w", err)
    }
    a.Balance += amount
    return nil
}

// GetBalance يحصل على الرصيد
func (a *Account) GetBalance() float64 {
    return a.Balance
}

package transaction

import (
    "fmt"
    "bank-system/account"
    "bank-system/internal/validator" // يمكنها أيضًا استيراد الحزمة الداخلية
)

// Transfer دالة التحويل
func Transfer(from, to *account.Account, amount float64) error {
    // استخدام الحزمة الداخلية للتحقق من المبلغ
    if err := validator.ValidateAmount(amount); err != nil {
        return fmt.Errorf("transfer failed: %w", err)
    }

    if from.GetBalance() < amount {
        return fmt.Errorf("transfer failed: insufficient balance (current: %.2f)", from.GetBalance())
    }

    // تنفيذ التحويل
    if err := from.Deposit(-amount); err != nil {
        return fmt.Errorf("deduction failed: %w", err)
    }
    if err := to.Deposit(amount); err != nil {
        // تراجع
        from.Deposit(amount)
        return fmt.Errorf("credit failed: %w", err)
    }

    return nil
}

package main

import (
    "fmt"
    "bank-system/account"
    "bank-system/transaction"
    // ❌ الاستيراد التالي سيفشل: الحزمة الداخلية لا يمكن استيرادها خارجيًا
    // "bank-system/internal/validator"
)

func main() {
    // إنشاء حسابين
    acc1, err := account.NewAccount("ACC001", "Alice", 10000)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    acc2, err := account.NewAccount("ACC002", "Bob", 5000)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Printf("Before transfer - Alice: %.2f, Bob: %.2f\n", acc1.GetBalance(), acc2.GetBalance())

    // تنفيذ التحويل
    err = transaction.Transfer(acc1, acc2, 3000)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Printf("After transfer - Alice: %.2f, Bob: %.2f\n", acc1.GetBalance(), acc2.GetBalance())

    // اختبار مبلغ غير صالح
    err = acc1.Deposit(-100)
    if err != nil {
        fmt.Println("Expected error:", err)
    }
}

go run main.go

Before transfer - Alice: 10000.00, Bob: 5000.00
After transfer - Alice: 7000.00, Bob: 8000.00
Expected error: deposit failed: amount must be greater than zero

my-app/
├── go.mod
├── main.go
└── logger/
    └── logger.go

package logger

import (
    "fmt"
    "os"
    "time"
)

// Level مستوى السجل
type Level int

const (
    LevelDebug Level = iota // 0
    LevelInfo               // 1
    LevelWarn               // 2
    LevelError              // 3
)

// Logger تراكيب
type Logger struct {
    prefix string
    level  Level
}

// New يُنشئ كائن مسجل
func New(prefix string, level Level) *Logger {
    return &Logger{
        prefix: prefix,
        level:  level,
    }
}

// log أسلوب داخلي لإخراج السجلات
func (l *Logger) log(level Level, tag, msg string) {
    if level < l.level {
        return
    }
    timestamp := time.Now().Format("2006-01-02 15:04:05")
    line := fmt.Sprintf("[%s] [%s] [%s] %s\n", timestamp, tag, l.prefix, msg)
    os.Stdout.WriteString(line)
}

// Debug سجل تصحيح
func (l *Logger) Debug(msg string) {
    l.log(LevelDebug, "DEBUG", msg)
}

// Info سجل معلومات
func (l *Logger) Info(msg string) {
    l.log(LevelInfo, "INFO", msg)
}

// Warn سجل تحذير
func (l *Logger) Warn(msg string) {
    l.log(LevelWarn, "WARN", msg)
}

// Error سجل خطأ
func (l *Logger) Error(msg string) {
    l.log(LevelError, "ERROR", msg)
}

package main

import (
    "my-app/logger"
)

func main() {
    log := logger.New("APP", logger.LevelInfo)

    log.Debug("This won't show because level is below Info")
    log.Info("Application started")
    log.Warn("Disk space low")
    log.Error("Database connection failed")
}

[2026-06-26 10:30:00] [INFO] [APP] Application started
[2026-06-26 10:30:00] [WARN] [APP] Disk space low
[2026-06-26 10:30:00] [ERROR] [APP] Database connection failed

web-service/
├── go.mod
├── go.sum
├── main.go
├── config/
│   └── config.go        ← إدارة الإعدادات
├── internal/
│   ├── model/
│   │   └── user.go      ← نموذج البيانات
│   ├── repository/
│   │   └── user_repo.go ← طبقة الوصول للبيانات
│   └── service/
│       └── user_service.go ← طبقة منطق الأعمال
└── handler/
    └── user_handler.go  ← طبقة معالج HTTP

package config

// Config إعدادات التطبيق
type Config struct {
    Port     string
    DBHost   string
    DBPort   int
    LogLevel string
}

// Load يُحمّل الإعدادات (مثال مبسط)
func Load() *Config {
    return &Config{
        Port:     "8080",
        DBHost:   "localhost",
        DBPort:   5432,
        LogLevel: "info",
    }
}

package model

// User نموذج
type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

package repository

import (
    "fmt"
    "web-service/internal/model"
)

// UserRepository مستودع بيانات المستخدمين
type UserRepository struct {
    users  map[int]*model.User
    nextID int
}

// NewUserRepository يُنشئ كائن مستودع
func NewUserRepository() *UserRepository {
    return &UserRepository{
        users:  make(map[int]*model.User),
        nextID: 1,
    }
}

// Create يُنشئ مستخدمًا
func (r *UserRepository) Create(name, email string) *model.User {
    user := &model.User{
        ID:    r.nextID,
        Name:  name,
        Email: email,
    }
    r.users[r.nextID] = user
    r.nextID++
    return user
}

// FindByID يبحث عن مستخدم بالمعرّف
func (r *UserRepository) FindByID(id int) (*model.User, bool) {
    user, ok := r.users[id]
    return user, ok
}

// FindAll يجد جميع المستخدمين
func (r *UserRepository) FindAll() []*model.User {
    result := make([]*model.User, 0, len(r.users))
    for _, u := range r.users {
        result = append(result, u)
    }
    return result
}

// String يُرجع ملخص المستودع
func (r *UserRepository) String() string {
    return fmt.Sprintf("UserRepository{%d users total}", len(r.users))
}

package main

import (
    "fmt"
    "web-service/config"
    "web-service/internal/repository"
)

func main() {
    // تحميل الإعدادات
    cfg := config.Load()
    fmt.Println("Port:", cfg.Port)

    // استخدام المستودع
    repo := repository.NewUserRepository()
    repo.Create("Alice", "alice@example.com")
    repo.Create("Bob", "bob@example.com")

    fmt.Println(repo)

    // العثور على جميع المستخدمين
    for _, u := range repo.FindAll() {
        fmt.Printf("  ID=%d, Name=%s, Email=%s\n", u.ID, u.Name, u.Email)
    }
}

Port: 8080
UserRepository{2 users total}
  ID=1, Name=Alice, Email=alice@example.com
  ID=2, Name=Bob, Email=bob@example.com

// myutil/calc.go
package calculator // اسم الحزمة لا يطابق اسم الدليل

// الاستيراد يستخدم المسار، لكن الاستخدام يستخدم اسم الحزمة
import "my-module/myutil" // المسار
calculator.Add(1, 2)      // استخدام اسم الحزمة

# ✅ مُوصى به: سهل للآخرين للإشارة
go mod init github.com/yourname/yourproject

# ⚠️ مقبول أيضًا: مشاريع محلية
go mod init myproject

# ❌ تجنب: أحرف خاصة أو مسافات
go mod init "my project"

# go.mod — يُعلن التبعيات والإصدارات
# go.sum — يتحقق من سلامة التبعيات
# كلاهما ضروري
git add go.mod go.sum

// mathutil/add.go
package mathutil

func Add(a, b int) int { return a + b }

// mathutil/multiply.go — نفس الحزمة، يمكنها استخدام Add مباشرة
package mathutil

func Multiply(a, b int) int {
    result := 0
    for i := 0; i < b; i++ {
        result = Add(result, a) // استدعاء مباشر، لا حاجة لاستيراد
    }
    return result
}