Golang Packages and Modules: Organize Code with go.mod

Packages

Every Golang file belongs to a package. A package groups related files in one directory and gives other code a stable import path. Packages are the main unit of organization in Golang projects.

Package names should be short, lowercase, and meaningful. Avoid vague names such as utils or helpers when a specific name such as slug, email, billing, or auth explains the purpose better.

Package Example

package calculator

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

func internalLabel() string {
    return "calculator"
}

Exported Identifiers

Identifiers that start with a capital letter are exported and can be used from other packages. Lowercase identifiers are package-private.

This rule applies to functions, variables, constants, types, struct fields, and methods. A public API should expose only what other packages truly need, while internal helpers should stay lowercase.

Identifier	Exported?	Meaning
Add	Yes	Other packages can call it
internalLabel	No	Only this package can call it
User.Name	Yes	Field appears in other packages and encoders
User.password	No	Field stays internal

Exported Type and Private Field

package users

type User struct {
    ID       int
    Name     string
    password string
}

func NewUser(name, password string) User {
    return User{Name: name, password: password}
}

Imports

Use import to bring another package into the current file. The imported package name is usually the last part of the import path, but packages can choose a different package name internally.

Golang does not allow unused imports. This keeps files clean and prevents stale dependencies from hiding in the code.

Import Packages

package main

import (
    "fmt"
    "strings"

    "example.com/tutorialslogic/golang-demo/internal/slug"
)

func main() {
    title := strings.TrimSpace(" Golang Modules ")
    fmt.Println(slug.Make(title))
}

Modules and go.mod

A module is a versioned collection of packages. The go.mod file declares the module path, Golang version, and dependency requirements.

Create a module with go mod init. The module path is often a repository path, but local learning projects can use a simple example path. Once a module exists, the go command can resolve imports and manage dependencies.

File	Purpose
go.mod	Declares module path, Golang version, and direct dependencies.
go.sum	Stores dependency checksums for reproducible downloads.
Package files	Contain the actual source code inside module directories.

Module Commands

go mod init example.com/tutorialslogic/golang-demo
go mod tidy
go test ./...

Dependency Commands

The go command downloads and manages dependencies. Modern Golang updates go.mod as needed when you import and build packages.

go mod tidy is especially important before committing because it adds missing module requirements and removes unused ones. It also updates go.sum when dependency checksums are needed.

Command	Purpose
go get example.com/pkg	Add, upgrade, or change a dependency
go mod tidy	Clean module requirements
go list -m all	List dependencies
go test ./...	Test all module packages
go mod why example.com/pkg	Explain why a dependency is needed

Project Structure

Small Golang projects can stay simple. Larger services often place command entry points under cmd and private implementation packages under internal.

The internal directory has special meaning. Packages inside it can only be imported by code inside the parent tree, which helps protect implementation details.

Service Layout

golang-demo/
  go.mod
  go.sum
  cmd/
    api/
      main.go
  internal/
    users/
      service.go
      service_test.go
    slug/
      slug.go
  README.md

Package Design Tips

Design packages around responsibility, not around file type. A package named users is usually clearer than separate packages named models, services, and helpers when those files only serve user behavior.

Keep package APIs small. Export constructors, types, and functions that callers need, but keep implementation details private. This makes packages easier to refactor without breaking other code.

Before you move on