Domain-Driven Entities in Go
TL;DR — Entity = type with identity that enforces its own invariants. Value object = type without identity, immutable. Use constructors to gate creation. No setters; methods that enforce business rules. Errors live in the domain package. Nothing in domain imports framework code.
After Go DI , the inside of the structs we’re wiring up. Domain modeling is where Clean Architecture earns its keep — business rules live in domain types, not scattered across services and handlers.
Entity vs value object
Two patterns to know.
Entity — type with identity (usually a UUID or DB ID). Two entities can have the same field values and still be distinct. Example: Subscription.
Value object — type without identity. Two value objects with the same fields are equal. Immutable. Example: Money, EmailAddress, BillingPeriod.
Practically:
// Entity
type Subscription struct {
id uuid.UUID // unexported — identity
customerID uuid.UUID
plan Plan // value object
status Status
period BillingPeriod // value object
}
// Value object
type Money struct {
amount int64 // cents
currency string
}
func NewMoney(cents int64, currency string) (Money, error) {
if currency == "" || len(currency) != 3 {
return Money{}, ErrInvalidCurrency
}
return Money{amount: cents, currency: currency}, nil
}
func (m Money) Cents() int64 { return m.amount }
func (m Money) Currency() string { return m.currency }
Value objects are constructed via a function that validates. They have getters but no setters — immutable.
Unexported fields, constructor, accessor
The Go idiom: keep fields unexported, expose accessors:
type Subscription struct {
id uuid.UUID
customerID uuid.UUID
plan Plan
status Status
}
func NewSubscription(customerID uuid.UUID, plan Plan, now time.Time) (*Subscription, error) {
if plan.ID == "" {
return nil, ErrInvalidPlan
}
return &Subscription{
id: uuid.New(),
customerID: customerID,
plan: plan,
status: StatusActive,
}, nil
}
func (s *Subscription) ID() uuid.UUID { return s.id }
func (s *Subscription) CustomerID() uuid.UUID { return s.customerID }
func (s *Subscription) Plan() Plan { return s.plan }
func (s *Subscription) Status() Status { return s.status }
The constructor is the only way to make a valid Subscription. Callers can’t construct an invalid one (no &Subscription{} outside the package).
Adapter layer needs a way to reconstruct entities from DB rows. Two patterns:
Pattern A — second constructor for reconstruction:
// For DB rehydration. Accepts everything.
func RestoreSubscription(id, customerID uuid.UUID, plan Plan, status Status) *Subscription {
return &Subscription{id: id, customerID: customerID, plan: plan, status: status}
}
Restore skips validation because the data is presumed valid (it came from the database). Adapter uses this.
Pattern B — accept exported “raw” struct then convert:
Less common in Go; common in Java/PHP. Skip in Go.
Methods enforce invariants
The reason for unexported fields: state changes go through methods that enforce rules.
func (s *Subscription) Cancel(now time.Time) error {
if s.status == StatusCanceled {
return ErrAlreadyCanceled
}
s.status = StatusCanceled
s.canceledAt = now
return nil
}
func (s *Subscription) Renew(now time.Time, period BillingPeriod) error {
if s.status != StatusActive {
return ErrCannotRenewInactive
}
s.period = period
s.renewsAt = now.Add(period.Duration())
return nil
}
You can’t bypass these by setting fields directly from outside the package. The state machine is enforced by the type.
Domain errors
Define errors as package-level values:
package domain
import "errors"
var (
ErrInvalidPlan = errors.New("invalid plan")
ErrAlreadyCanceled = errors.New("subscription already canceled")
ErrCannotRenewInactive = errors.New("cannot renew inactive subscription")
ErrInvalidCurrency = errors.New("invalid currency")
)
Callers check with errors.Is:
err := sub.Cancel(time.Now())
if errors.Is(err, domain.ErrAlreadyCanceled) {
// handle gracefully — return 409 from HTTP, etc.
}
For errors with structured data (e.g., the invalid value), use typed errors:
type ErrInvalidStatus struct {
Got Status
}
func (e ErrInvalidStatus) Error() string {
return fmt.Sprintf("invalid status: %s", e.Got)
}
Caller does var e domain.ErrInvalidStatus; if errors.As(err, &e) { ... }. Useful when handlers need to surface specific data.
What goes in domain — checklist
Yes:
- Entity types and their methods
- Value objects
- Domain services (pure functions over entities)
- Domain errors
- Domain events (struct definitions only — publishing is adapter concern)
- Pure business logic (proration, tax calculation rules, eligibility checks)
No:
- HTTP types (
*http.Request) - DB types (
pgx.Conn) - Framework imports
- JSON tags (they’re for adapters)
- Logging calls (domain doesn’t know what logger to use)
- Time.Now() called directly (pass
now time.Timeorclock func() time.Time)
A complete domain file
package domain
import (
"errors"
"time"
"github.com/google/uuid"
)
type Status string
const (
StatusActive Status = "active"
StatusPastDue Status = "past_due"
StatusCanceled Status = "canceled"
)
type Plan struct {
ID string
PriceCents int64
Currency string
Interval time.Duration
}
func NewPlan(id string, priceCents int64, currency string, interval time.Duration) (Plan, error) {
if id == "" {
return Plan{}, ErrInvalidPlan
}
if priceCents < 0 {
return Plan{}, ErrNegativePrice
}
return Plan{ID: id, PriceCents: priceCents, Currency: currency, Interval: interval}, nil
}
type Subscription struct {
id, customerID uuid.UUID
plan Plan
status Status
startedAt time.Time
renewsAt time.Time
canceledAt *time.Time
}
func NewSubscription(customerID uuid.UUID, plan Plan, now time.Time) (*Subscription, error) {
if plan.ID == "" {
return nil, ErrInvalidPlan
}
return &Subscription{
id: uuid.New(),
customerID: customerID,
plan: plan,
status: StatusActive,
startedAt: now,
renewsAt: now.Add(plan.Interval),
}, nil
}
func RestoreSubscription(id, customerID uuid.UUID, plan Plan, status Status, startedAt, renewsAt time.Time, canceledAt *time.Time) *Subscription {
return &Subscription{id, customerID, plan, status, startedAt, renewsAt, canceledAt}
}
func (s *Subscription) ID() uuid.UUID { return s.id }
func (s *Subscription) Status() Status { return s.status }
func (s *Subscription) Plan() Plan { return s.plan }
func (s *Subscription) Cancel(now time.Time) error {
if s.status == StatusCanceled {
return ErrAlreadyCanceled
}
s.status = StatusCanceled
s.canceledAt = &now
return nil
}
var (
ErrInvalidPlan = errors.New("invalid plan")
ErrNegativePrice = errors.New("negative price")
ErrAlreadyCanceled = errors.New("already canceled")
)
That’s a complete, testable, framework-free domain file. ~50 lines. Tests run in 0.005 seconds.
Common Pitfalls
Exporting fields for “convenience.” Now callers can set invalid states. Always private; expose methods.
Anemic entities — structs with no methods. That’s just a DTO. Add the rules.
Domain that imports an ORM. db:"customer_id" struct tags = ORM concern. Keep them out.
time.Now() inside the domain. Untestable. Inject as function or clock.
Domain that imports HTTP. Same — domain doesn’t care if it’s served over HTTP.
Returning database row structs from domain methods. Wrong shape leaks. Define your own types.
Wrapping Up
Entities with identity + value objects + invariant-enforcing methods + domain errors. 50-line files; fast tests; framework-independent. Monday: repositories — the port interfaces use cases consume .
