Type Parameters & Constraint Interfaces

Type parameters are declared in bracket lists, and constraint interfaces define which types may replace them using methods, underlying types (~T), and unions (|).

Summary

Type parameters turn concrete types into compile-time variables for functions and named types.

Constraint interfaces are the guardrails: they list allowed operations and type sets.

The ~ operator matches named types by underlying type; | unions multiple types or underlying types into one constraint.

Named constraint types keep APIs readable when the same bound appears in many signatures.

Recipe

Quick-reference recipe card - copy-paste ready.

// Named constraint - reuse across APIs
type Ordered interface {
    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
    ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
    ~float32 | ~float64 |
    ~string
}
 
func Clamp[T Ordered](v, lo, hi T) T {
    if v < lo {
        return lo
    }
    if v > hi {
        return hi
    }
    return v
}

When to reach for this:

• You need one function body for several concrete types that share operators or methods.
• A named type should participate because its underlying type matches (~byte).
• Multiple unrelated types must be accepted via a union (int | string is invalid for shared ops - design carefully).

Working Example

package main
 
import (
    "fmt"
    "strconv"
)
 
// Method constraint
type Stringable interface {
    String() string
}
 
// Underlying type + union
type Digit interface {
    ~int | ~int8 | ~int16 | ~int32 | ~int64
}
 
type UserID int
 
func (id UserID) String() string {
    return strconv.Itoa(int(id))
}
 
func FormatAll[T Stringable](items []T) string {
    out := ""
    for i, v := range items {
        if i > 0 {
            out += ", "
        }
        out += v.String()
    }
    return out
}
 
func Twice[T Digit](v T) T {
    return v * 2
}
 
func main() {
    ids := []UserID{1, 2, 3}
    fmt.Println(FormatAll(ids))
    fmt.Println(Twice(UserID(5)))
}

What this demonstrates:

• Method constraints enable calls like v.String() inside the generic body.
• ~int lets UserID satisfy Digit without listing every named int type.
• Separate constraints compose different capabilities (Stringable vs Digit).

Deep Dive

How It Works

• Type parameters are declared on functions (func F[T any]()) or types (type Stack[T any] struct{}).
• Each parameter has a constraint interface; default unconstrained use is any.
• The compiler computes the constraint's type set; only types in that set may instantiate the generic.
• The function body may only use operations valid for all types in the set (the core type set rules).

Constraint Forms at a Glance

Type Parameter Lists

Go Notes

// Extract constraints to package-level names for public APIs
type JSONMarshaler interface {
    MarshalJSON() ([]byte, error)
}
 
func Encode[T JSONMarshaler](v T) ([]byte, error) {
    return v.MarshalJSON()
}
 
// Embedding predeclared constraints
type Key interface {
    comparable
    fmt.Stringer
}

• Constraint interfaces cannot embed arbitrary non-interface types except type terms in unions.
• A union may not mix incompatible operations - if one arm lacks <, the body cannot use < on T.
• Use cmp.Ordered and cmp.Or from stdlib instead of copying large union lists.

Gotchas

• Using int instead of ~int - Named types like type Celsius float64 will not match float64 alone. Fix: use ~float64 when named types should qualify.
• Union too wide for one body - int | string cannot use + or shared comparisons beyond == if not comparable together. Fix: narrow the union or split functions.
• Embedding comparable incorrectly - interface { comparable; []byte } is invalid because slices are not comparable. Fix: list only comparable type terms.
• Constraint interface with only methods, no type set - Empty interface method sets behave differently from unions; read spec for comparable core type sets. Fix: test instantiations in compile-time table tests.
• Exporting huge constraint unions - Public APIs become hard to read and stabilize. Fix: unexport constraint, export function with minimal bounds.
• Duplicate type parameters - [T any, T comparable] is invalid. Fix: one name per parameter in the list.

Alternatives

FAQs

Related

• Generics in Go: Constraints Without Templates - conceptual overview
• Generics Basics - first generic snippets
• Type Sets & the comparable Constraint - comparable deep dive
• Generic Algorithms: slices, maps & cmp Packages - cmp.Ordered usage
• When to Avoid Generics in Go APIs - public API guidance

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

49454e4f4d5f434e4f5904434556494d43451f1a1d56181a181c1a1d