Reflection & Code Generation Best Practices

Choose reflection for frameworks, codegen for hot paths.

These rules turn the reflection and codegen articles in this section into reviewable habits for libraries, services, and platform teams.

How to Use This List

• Apply during API design, performance reviews, and dependency upgrades.
• Separate framework init (reflection OK) from per-request work (prefer codegen or hand code).
• Revisit when adding ORMs, JSON APIs, or monorepo-wide API migrations.

A - Choosing Reflection vs Codegen

• Profile before optimizing. Use pprof and benchmarks to prove reflection is a bottleneck, not assumed.
• Use reflection on cold paths (startup binding, CLI parsing, test helpers). Avoid it in inner RPC or DB loops without caching.
• Prefer codegen when types are known at build time and the same encoder or mapper runs thousands of times per second.
• Implement Marshaler/Unmarshaler on proven hot types before adopting a new JSON generator framework.
• Keep DTOs flat when serializers or ORMs reflect over many nested fields.

B - Struct Tags and Metadata

• One tag grammar per key documented in the package README (validate, json, db, custom).
• Use Tag.Lookup when key presence matters; do not rely on Get alone to detect missing keys.
• Run struct tag linters in CI to catch duplicate json names and invalid tag syntax.
• Parse tags once per reflect.Type and cache field plans in sync.Map or package init.
• Do not store secrets in struct tags; tags are compile-time visible metadata, not a vault.

C - go generate and Custom Generators

• Commit generated files with // Code generated ... DO NOT EDIT headers unless all consumers always run generators.
• Fail CI when go generate ./... produces a diff so drift is caught before merge.
• Pin generator tools in tools.go (build tag tools) and install that version in CI.
• Always format.Source generator output so gofmt checks pass.
• Write golden tests for custom generators using small testdata/ inputs.

D - Performance and Operations

• Benchmark with -benchmem when comparing reflective JSON/ORM paths to generated alternatives.
• Watch for reflect.* in CPU profiles under marshal, scan, and validation handlers.
• Pool buffers for encoders on HTTP/gRPC edges even when using codegen.
• Regenerate after Go upgrades alongside go fix and go test ./....
• Document TinyGo/WASM limits where reflection is reduced; prefer codegen on embedded targets.

E - API Migrations with go fix

• Add //go:fix inline on forwarding shims when renaming or moving symbols, with Deprecated: godoc.
• Preview with go fix -diff on large repos before applying sweeping changes.
• Run go fix twice on upgrade branches when release notes recommend synergistic passes.
• Keep shim bodies simple (ideally one call to the new API) so the inliner produces tidy output.
• Test after batch fix; unused locals can appear when multiple fixes interact.

FAQs

Related

• Reflection vs Code Generation in Go - conceptual overview
• Reflection Basics - hands-on primitives
• go generate & stringer - standard codegen workflow
• go:fix inline & API Migration Directives - automated migrations
• ORM & Serializer Reflection Costs - when to optimize

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).