golang-type-safety

name	golang-type-safety
description	Prefer typed constants and named types over magic strings/numbers in Go. Use when writing function signatures, struct fields, switch statements, or passing enum-like values. Use when this capability is needed.
metadata	{"author":"codeready-toolchain"}

Go Type Safety

Use typed constants and named types instead of magic strings and numbers. This catches misuse at compile time and makes intent explicit.

Named String Types for Enums

When a value comes from a defined set (e.g. ent-generated enums, config enums), use the named type:

// Bad — magic string, no compile-time checking
publishStageStatus(ctx, pub, sid, stgID, name, idx, "investigation", status)

// Good — typed constant, typos caught at compile time
publishStageStatus(ctx, pub, sid, stgID, name, idx, stage.StageTypeInvestigation, status)

Function Signatures

Accept the named type, not string, when the parameter is always one of a known set:

// Bad — caller can pass any string
func publishStageStatus(ctx context.Context, ..., stageType string, status string)

// Good — compiler enforces valid stage types
func publishStageStatus(ctx context.Context, ..., stageType stage.StageType, status string)

Convert to string at serialization boundaries (JSON payloads, DB queries, log messages):

payload.StageType = string(stageType)

Warning: Direct Casting Does Not Validate

stage.StageType(s) compiles but does not check whether s is a known value. Always use a parse helper at API/deserialize boundaries where the input is untrusted:

// Bad — silently accepts unknown values
stageType := stage.StageType(req.StageType)

// Good — rejects unknown values at the boundary
stageType, err := parseStageType(req.StageType)
if err != nil {
    return nil, err
}

parseStageType Helper

Define this once near the package entry point (e.g., handler or service layer):

// parseStageType converts a raw string from an API payload or query parameter
// into a stage.StageType, returning an error for unknown values.
//
// Allowed values: stage.StageTypeInvestigation, stage.StageTypeSynthesis,
// stage.StageTypeChat, stage.StageTypeExecSummary, stage.StageTypeScoring.
func parseStageType(s string) (stage.StageType, error) {
    switch stage.StageType(s) {
    case stage.StageTypeInvestigation,
        stage.StageTypeSynthesis,
        stage.StageTypeChat,
        stage.StageTypeExecSummary,
        stage.StageTypeScoring:
        return stage.StageType(s), nil
    default:
        return "", fmt.Errorf("unknown stage type %q", s)
    }
}

This is the only place where an unvalidated cast is acceptable — all call sites receive an already-validated stage.StageType.

Struct Fields

Use string for DTOs/payloads that cross API boundaries (JSON serialization). Use the named type for internal structs where type safety helps:

// API payload — string is fine (wire format)
type StageStatusPayload struct {
    StageType string `json:"stage_type"`
}

// Internal struct — use the named type
type stageInput struct {
    stageType stage.StageType
}

Struct Literals

When constructing structs with string fields that accept enum values, use string(constant):

// Bad
req := CreateStageRequest{StageType: "synthesis"}

// Good
req := CreateStageRequest{StageType: string(stage.StageTypeSynthesis)}

When NOT to Use Named Types

• One-off values that aren't from a defined set (free-form names, user input)
• Test data where the literal is the point (e.g. "bogus" for invalid input tests)
• String comparisons in tests asserting wire-format output

---

Source: codeready-toolchain/tarsy — distributed by TomeVault.