Runnable, zero-setup programs that show gostructor from a first Configure
call up to a full production configuration. Every example writes any files it
needs to a temp dir and cleans up after itself, so you can just run it:
go run ./examples/<name>
Start at the top and work down — each one introduces a little more.
| Example | What it shows | Modules needed |
|---|---|---|
basic |
The minimum: a cfg base name (env) with a gos:"default:..." fallback. |
core only |
priority |
The headline feature — the same struct resolving differently per environment, purely from the WithSources order. |
core only |
filesources |
The two core file sources (json + ini) combined with env and defaults in one source-order chain. | core only |
types |
The breadth of supported field types from a JSON source: durations, slices/arrays, time.Time/net.IP, named types, pointers, maps, and slices/maps of structs. |
core only |
hooks |
WithHook for validation (reject out-of-range values) and transformation (normalise strings), on the typed value. |
core only |
errors |
A tour of the typed error taxonomy — trigger each failure and classify it with errors.Is/errors.As. |
core only |
observability |
ConfigureWithReport: the focused resolution trace (primary source, overrides & secrets), Provenance(), and gos:"secret" masking. |
core only |
webservice |
The big one. A full microservice config (~30 fields, nested sub-structs) assembled from a JSON base + env overrides + defaults, with masked secrets and a focused trace. | core only |
multisource |
A field with several sources including a real YAML file, plus a validation hook. Priority is the source order. | gostructor/yaml |
These show gostructor.Watch — the struct re-fills when the backing source
changes. All but hotreload-file bring their backend up with docker-compose
and seed it, so each is fully reproducible; see the example’s own README for the
exact commands.
| Example | What it shows | Backend |
|---|---|---|
hotreload-file |
Watch + fsnotify file source: edit a JSON file, the struct reloads. Transactional last-known-good via WithValidate. |
none (local file) |
git |
Config from a git repo, ref = version; drift polling and runtime SetVersion; snapshot fallback. |
git daemon (compose) |
consul |
Consul KV prefix, live via blocking queries. | hashicorp/consul (compose) |
etcd |
etcd key prefix, live via the native watch API. | etcd (compose) |
springcloud |
Spring Cloud Config Server over HTTP, live via polling. | spring-cloud-config-server (compose) |
vault |
Vault secrets with live rotation (polling); secret masking. | hashicorp/vault (compose) |
basic — get the shape of Configure and the two tags.priority — the one feature that sets gostructor apart from a plain
unmarshaller: source-order priority, chosen at the call site.filesources / types — real sources and the full type range.hooks / errors — validation, transformation, and failure modes.observability — see why each field got the value it did.webservice — everything at once, at production scale.multisource — bringing in an external source module (YAML).Most core examples live in the root module and need no extra setup.
multisource and every live-config example are their own modules (they pull in
an external source module) with replace directives pointing back at the repo,
so run each from its own directory: cd examples/<name> && go run ..