How do you manage internal vs public API boundaries within a Go module?

Question

Accepted Answer

myservice/
├── cmd/
│   └── server/
│       └── main.go
├── internal/          // only importable by myservice module
│   ├── auth/
│   │   └── jwt.go    // internal JWT implementation
│   ├── database/
│   │   └── pool.go   // internal DB pool
│   └── config/
│       └── loader.go // internal config parsing
├── pkg/              // public, importable by other modules
│   └── client/
│       └── client.go // public API client
└── go.mod

// Attempting to import internal from outside the module:
// import "github.com/myorg/myservice/internal/auth"
// Error: use of internal package not allowed

// Exported vs unexported
type UserService struct {}         // exported — public API
type userRepository struct {}      // unexported — implementation detail

func NewUserService(db *sql.DB) *UserService { // exported constructor
    return &UserService{}
} Unexported identifiers are free to change without versioning concerns — keep implementation details unexported Exported identifiers form a contract — once published, changing them requires a major version bump Accept interfaces, return concrete types in public APIs for flexibility Use internal/ for shared code across services in the same module without exposing it publicly Document exported identifiers — godoc generates documentation from exported types and functions

How do you manage internal vs public API boundaries within a Go module?

The internal/ package enforces compile-time import restrictions within a module. Minimizing exported identifiers and using unexported types is Go's primary API boundary mechanism.

Scenario Questions

Follow-up Questions