📦 Packages and Modules in Go

// math/operations.go
package math

import (
    "fmt"
    "errors"
    "sync"
)

// Exported constant - starts with capital letter
const Pi = 3.14159265359

// Exported type
type Calculator struct {
    Precision int      // Exported field
    mutex     sync.Mutex // Unexported field
}

// Exported function
func Add(a, b float64) float64 {
    return a + b
}

// Unexported helper function
func validate(x float64) error {
    if x < 0 {
        return errors.New("negative value not allowed")
    }
    return nil
}

// init() runs automatically when package is imported
func init() {
    fmt.Println("Math package initialized")
    // Setup code, register handlers, etc.
}

// go.mod
module github.com/username/myproject

go 1.21

require (
    github.com/gorilla/mux v1.8.0
    github.com/stretchr/testify v1.8.4
    github.com/redis/go-redis/v9 v9.0.5
)

require (
    // Indirect dependencies
    github.com/davecgh/go-spew v1.1.1 // indirect
    github.com/pmezard/go-difflib v1.0.0 // indirect
)

// Replace directive for local development
replace github.com/mycompany/shared => ../shared

// Exclude specific versions
exclude github.com/broken/package v1.0.0

// Retract versions with issues
retract (
    v1.0.0 // Published accidentally
    v1.0.1 // Contains critical bug
)

// internal/auth/auth.go
// Can only be imported by packages in the same module
package auth

import (
    "crypto/rand"
    "encoding/base64"
    "time"
)

type TokenManager struct {
    secret []byte
    expiry time.Duration
}

func NewTokenManager(secret string) *TokenManager {
    return &TokenManager{
        secret: []byte(secret),
        expiry: 24 * time.Hour,
    }
}

func (tm *TokenManager) GenerateToken() (string, error) {
    b := make([]byte, 32)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return base64.URLEncoding.EncodeToString(b), nil
}

// main.go can import this
import "myproject/internal/auth"

// External packages cannot import internal/
// This will fail: import "github.com/user/project/internal/auth"

// Working with major versions
import (
    "github.com/user/pkg"       // v0 or v1
    pkgv2 "github.com/user/pkg/v2" // v2+
)

// Build constraints for conditional compilation
//go:build integration
// +build integration

package tests

// Module-aware tools
// Install tools as dependencies
//go:generate go run github.com/tool/cmd@v1.0.0

// tools.go pattern for development tools
//go:build tools
package tools

import (
    _ "github.com/golangci/golangci-lint/cmd/golangci-lint"
    _ "golang.org/x/tools/cmd/goimports"
)

// Package mathutil provides utility functions for mathematical operations
// that are not available in the standard library.
//
// Basic Usage
//
// The package offers various mathematical utilities:
//
//	result := mathutil.Factorial(5)
//	fmt.Println(result) // Output: 120
//
// For more complex operations, use the Calculator type:
//
//	calc := mathutil.NewCalculator()
//	calc.SetPrecision(10)
//	result := calc.SquareRoot(2)
package mathutil

import "errors"

// ErrNegativeInput is returned when a function receives
// a negative input where only non-negative values are valid.
var ErrNegativeInput = errors.New("negative input not allowed")

// Factorial calculates the factorial of n.
// It returns an error if n is negative.
//
// Example:
//
//	fact, err := Factorial(5)
//	if err != nil {
//	    log.Fatal(err)
//	}
//	fmt.Println(fact) // Output: 120
func Factorial(n int) (int, error) {
    if n < 0 {
        return 0, ErrNegativeInput
    }
    if n == 0 || n == 1 {
        return 1, nil
    }
    
    result := 1
    for i := 2; i <= n; i++ {
        result *= i
    }
    return result, nil
}

// Deprecated: Use Factorial instead.
// This function will be removed in v2.0.0.
func OldFactorial(n int) int {
    // Legacy implementation
    return 0
}