- Book: Hexagonal Architecture in Go
- Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
- My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
- Me: xgabriel.com | GitHub
You're reviewing a pull request. The function signature is this:
func TransferFunds(
from string,
to string,
amount float64,
currency string,
note string,
) error
Five arguments. Four of them are strings. The reviewer reads the diff, nods, hits approve. Two weeks later support gets a ticket: a EUR transfer landed in a USD account at the dollar amount of the original request. Somewhere a float64 was treated as cents. Somewhere from and to got swapped because the caller had them in a different order in a struct.
None of those bugs needed to be possible. They became possible the moment the team decided that "string" was a good enough type for an account ID, a currency code, and a free-form note all at once.
Domain primitives fix this. The thesis is short: every real-world concept gets its own Go type. Not a string with validation. Not an int64 with a comment. A named type, a private field, a constructor that validates, and methods that enforce its invariants. Once a value enters the domain through that constructor, every function downstream gets a compile-time guarantee for free.
The broader principle is simple: every concept is a type, no exceptions.
The Cost of "Just Use a String"
A string for a UserID looks economical. One less file, one less constructor, one less type to import. It is also four hidden costs you pay later:
-
No swap protection.
func DeleteAccount(userID, adminID string)— both are strings, so the compiler cannot stop you from callingDeleteAccount(adminID, userID). The wrong account dies. - Validation duplicated everywhere. Every layer that touches the value re-checks it, or trusts the layer above. One of those layers will eventually skip the check.
-
No domain methods. You cannot put
IsExpired()on astring. You end up with a free-standingIsExpired(token string)that nobody can find. -
Equality is by value, not by meaning. Two
stringtokens are equal if their bytes match. TwoSessionIDtokens should be equal only if they refer to the same session. You might also want canonical formatting (lowercase, trimmed) to be part of equality.
A domain primitive collapses all four problems into one solution: define the type once, validate at the edge, and the compiler protects the rest of the codebase.
The Shape Every Domain Primitive Shares
Five things, every time:
type Email struct {
value string // unexported — forces use of the constructor
}
func NewEmail(raw string) (Email, error) { /* validate */ }
func (e Email) String() string { return e.value }
func (e Email) Equals(other Email) bool { return e.value == other.value }
func (e Email) IsZero() bool { return e.value == "" }
A struct with one unexported field. A constructor that validates and is the only path to a valid value. A String() method for printing. An Equals method so callers do not reach into the field directly. An IsZero because Go's zero value bypasses the constructor and you need a way to detect that at trust boundaries.
That is the entire pattern. Four concepts that show up in almost every backend show why.
UserID: Stop Swapping Identifiers
The first place domain primitives pay off is identifiers. Every system has at least three or four ID types: UserID, OrderID, ProductID, SessionID. Every one of them is "just a string" until something gets swapped.
package domain
import (
"errors"
"github.com/google/uuid"
)
type UserID struct {
value uuid.UUID
}
func NewUserID(raw string) (UserID, error) {
parsed, err := uuid.Parse(raw)
if err != nil {
return UserID{}, errors.New(
"user id: not a valid uuid",
)
}
return UserID{value: parsed}, nil
}
func GenerateUserID() UserID {
return UserID{value: uuid.New()}
}
func (id UserID) String() string {
return id.value.String()
}
func (id UserID) Equals(other UserID) bool {
return id.value == other.value
}
Now define OrderID the same way. Both wrap a UUID. Both have the same shape. They are still incompatible at the type level.
func GetUser(id UserID) (*User, error) { /* ... */ }
func GetOrder(id OrderID) (*Order, error) { /* ... */ }
userID, _ := NewUserID(req.PathValue("id"))
GetOrder(userID) // compile error: cannot use UserID as OrderID
An order ID passed to a user lookup, returning zero rows, the API responding "user not found": that bug cannot exist. The compiler refuses to build the binary.
Email: Validate Once, Trust Forever
Email is the canonical example because everyone has been bitten by it. Some layer accepts an empty string. Another layer accepts a string with no @. A third layer normalises by lowercasing. Three different rules in three different places.
A domain primitive lifts the rule into the type:
package domain
import (
"errors"
"fmt"
"net/mail"
"strings"
)
type Email struct {
value string
}
func NewEmail(raw string) (Email, error) {
raw = strings.TrimSpace(strings.ToLower(raw))
if raw == "" {
return Email{}, errors.New("email: empty")
}
if _, err := mail.ParseAddress(raw); err != nil {
return Email{}, fmt.Errorf(
"email: %q invalid: %w", raw, err,
)
}
return Email{value: raw}, nil
}
func (e Email) String() string { return e.value }
func (e Email) Domain() string {
at := strings.IndexByte(e.value, '@')
return e.value[at+1:]
}
func (e Email) MarshalJSON() ([]byte, error) {
return []byte(`"` + e.value + `"`), nil
}
func (e *Email) UnmarshalJSON(data []byte) error {
raw := strings.Trim(string(data), `"`)
parsed, err := NewEmail(raw)
if err != nil {
return err
}
*e = parsed
return nil
}
JSON unmarshalling is the boundary you have to think about explicitly. A struct with unexported fields cannot be filled by encoding/json directly, so you write UnmarshalJSON once and every API handler that decodes a request body now validates email formatting for free. The same applies to database/sql's Scan — when you read an email from a row, the same constructor runs.
Email.Domain() is a domain method attached where it belongs. Any handler that needs to know the email's domain calls e.Domain(), not strings.Split(emailString, "@")[1] for the fifteenth time.
Money: Kill Currency Mixing at Compile Time
Money is the type that punishes carelessness the hardest. Storing it as float64 loses cents to floating-point rounding. Storing it as int64 loses currency. Storing currency as a string next to the amount lets two amounts in different currencies be added without complaint.
A real Money type carries both pieces and refuses to mix them:
package domain
import (
"errors"
"fmt"
)
type Currency string
const (
USD Currency = "USD"
EUR Currency = "EUR"
GBP Currency = "GBP"
)
func ParseCurrency(raw string) (Currency, error) {
switch Currency(raw) {
case USD, EUR, GBP:
return Currency(raw), nil
default:
return "", fmt.Errorf(
"currency: %q not supported", raw,
)
}
}
type Money struct {
cents int64
currency Currency
}
var ErrCurrencyMismatch = errors.New(
"money: currency mismatch",
)
func NewMoney(cents int64, c Currency) (Money, error) {
if c == "" {
return Money{}, errors.New(
"money: currency required",
)
}
return Money{cents: cents, currency: c}, nil
}
func (m Money) Add(other Money) (Money, error) {
if m.currency != other.currency {
return Money{}, ErrCurrencyMismatch
}
return Money{
cents: m.cents + other.cents,
currency: m.currency,
}, nil
}
func (m Money) IsNegative() bool { return m.cents < 0 }
func (m Money) String() string {
return fmt.Sprintf(
"%d.%02d %s",
m.cents/100,
absInt(m.cents%100),
m.currency,
)
}
func absInt(v int64) int64 {
if v < 0 {
return -v
}
return v
}
a.Add(b) returns an error if currencies do not match. There is no way to write total += amount and silently turn a EUR balance into a corrupted dollar total. Every place that sums money has to handle the mismatch, which is exactly the discomfort that makes the bug visible.
The original TransferFunds signature now reads like this:
func TransferFunds(
from AccountID,
to AccountID,
amount Money,
note string,
) error
Four parameters instead of five. Each one a different type. from and to cannot be swapped with amount. amount cannot be passed in the wrong currency. The string note is still a string because a free-form note has no rules. That is the one case where a primitive type stays a primitive.
PostalCode: Format Encodes Country
Postal codes look like a string with a regex on top. They are not. The format depends on the country, and the country depends on the address it belongs to. A primitive that refuses to exist in the wrong shape is the one that never gets the rule wrong:
package domain
import (
"errors"
"fmt"
"regexp"
"strings"
)
type PostalCode struct {
value string
country Country
}
type Country string
const (
US Country = "US"
DE Country = "DE"
UK Country = "UK"
)
var postalPatterns = map[Country]*regexp.Regexp{
US: regexp.MustCompile(`^\d{5}(-\d{4})?$`),
DE: regexp.MustCompile(`^\d{5}$`),
UK: regexp.MustCompile(
`^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$`,
),
}
func NewPostalCode(
raw string, c Country,
) (PostalCode, error) {
raw = strings.ToUpper(strings.TrimSpace(raw))
pattern, ok := postalPatterns[c]
if !ok {
return PostalCode{}, fmt.Errorf(
"postal: country %q unsupported", c,
)
}
if !pattern.MatchString(raw) {
return PostalCode{}, errors.New(
"postal: format invalid for country",
)
}
return PostalCode{value: raw, country: c}, nil
}
func (p PostalCode) String() string { return p.value }
func (p PostalCode) Country() Country { return p.country }
A PostalCode cannot exist without a country. The validation is country-specific by design. Trying to construct a UK postal code with the US format fails at the boundary, before any address row gets written.
The Frontier: Where to Stop
Domain primitives have a cost. Every type is a file, a constructor, a String(), possibly a MarshalJSON. The cost is real. The question is where the line sits.
The line is invariants. If a value has rules (must be non-empty, must match a format, must come from a fixed set, must be comparable to other values of its kind), wrap it. If it does not, leave it alone. A user's bio is just text; making Bio a type buys nothing. A discount percentage is bounded between 0 and 100; making Percentage a type stops a 150% discount from ever getting persisted.
Three signs you need a domain primitive:
-
You wrote
if x == "" { return errors.New("...") }more than once for the same concept. That validation belongs in a constructor. -
Two values share an underlying type and could be swapped.
userIDandadminIDbothstring.weightandheightbothfloat64. The compiler should have your back. -
You catch yourself reaching for
strings.Splitor a regex on a value across multiple files. That is a method asking to be born on a type.
The point of the pattern is not maximalism. The point is that the type system is the cheapest place to enforce a rule, because it runs at compile time, in every layer, with no test to write and no drift to manage. Every concept that has a rule and cannot defend itself becomes a class of bug you keep meeting in production.
When the function signature has eight string parameters, the system is telling you something. The fix is not better naming. The fix is more types.
If this was useful
Domain primitives are one of the first patterns Hexagonal Architecture in Go covers, because hexagonal layering only works when the domain layer carries its own invariants. Once your UserID, Email, and Money defend themselves, ports and adapters get cleaner — the application service stops re-validating, the database adapter stops returning raw strings, and the HTTP handler shrinks to a parser. The book walks through the whole stack with real Go code.
If you build with Claude Code or other AI coding tools, Hermes IDE is the editor I'm building for that workflow — domain models like the ones above are exactly the kind of thing it helps you scaffold and keep consistent across a service.
Top comments (0)