README
¶
components
This module is a Go component library. Import subpackages directly; the root package has no runtime API.
Package map
| Need | Package | Notes |
|---|---|---|
| Load, merge, watch, and scan configuration | github.com/go-jimu/components/config |
Sources live in config/file, config/env, and config/inmem; higher-level loading lives in config/loader. |
| Register and retrieve codecs | github.com/go-jimu/components/encoding |
Blank import encoding/json, encoding/yaml, encoding/toml, or encoding/proto to register built-in codecs. |
| Model polymorphic states | github.com/go-jimu/components/fsm |
Put behavior on concrete state types; use fsm.Transit after behavior succeeds. |
| Same bounded-context domain events | github.com/go-jimu/components/ddd/event |
New domain event code should use this instead of mediator. |
| Cross-boundary integration messages | github.com/go-jimu/components/ddd/message |
Protobuf-first message DTOs and handler routing; broker runtime belongs to providers. |
| Reliable integration message publishing | github.com/go-jimu/components/ddd/message/outbox |
Transaction-time recording plus relay primitives. |
| Transport-neutral task queue contracts | github.com/go-jimu/components/taskqueue |
Task envelopes, processors, routing, schedules, middleware, and worker interfaces. |
| Notification/specification validation helpers | github.com/go-jimu/components/validation |
Specification combinators and error notification collection. |
log/slog helpers |
github.com/go-jimu/components/sloghelper |
Preferred logging helper package for new code. |
| Legacy logger abstraction | github.com/go-jimu/components/logger |
Deprecated for new code; prefer log/slog and sloghelper. |
| Legacy in-process mediator | github.com/go-jimu/components/mediator |
Compatibility package; prefer ddd/event for new domain event code. |
Domain events
For new domain event code, use github.com/go-jimu/components/ddd/event.
The legacy mediator package remains source-compatible for existing users and
will only receive compatibility fixes. See
docs/mediator-migration.md for the semantic
differences and migration guidance.
Integration messages
Use github.com/go-jimu/components/ddd/message for protobuf integration DTOs
that cross bounded-context or service boundaries.
message.Kind is a semantic message type used for handler routing and payload
resolution. It is not a broker topic, subject, queue, partition, or offset.
Provider packages map Kind, Message.ID, Message.Key, OccurredAt, and
headers into their own broker envelopes and own retry, DLQ, ack, and commit
policy.
message.Handler.Handle errors are message-level failures for one delivered
message. message.Runner.Run errors are runtime-level failures for a provider
loop; context shutdown returns ctx.Err(). Provider packages must document how
message-level failures are retried, routed to DLQ, dropped, or otherwise
recorded without treating every handler error as a runtime failure.
Task queues
Use github.com/go-jimu/components/taskqueue for provider-neutral task queue
contracts, including task envelopes, processors, routing, enqueue policy, and
recurring enqueue definitions. Read taskqueue/README.md
before generating taskqueue consumer code or provider adapters.
Finite state machines
Use github.com/go-jimu/components/fsm for lightweight polymorphic state
objects. Consumers put behavior on concrete states, such as
UnpaidOrderState.Pay and PaidOrderState.Pay; the package owns transition
definitions and target state construction after a behavior succeeds, while the
business object executes its own transition through fsm.Transit.
See fsm/README.md for the expected setup and runtime pattern.
Verification
Run the repository test suite with:
go test ./...
Documentation
¶
Overview ¶
Package components is a collection of small Go component packages.
Import subpackages directly. The root package intentionally has no runtime API; it exists only as the module root for packages such as config, encoding, fsm, ddd/event, ddd/message, taskqueue, validation, logger, and sloghelper.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides source-based configuration loading, merging, placeholder resolution, value lookup, scanning, and watching.
|
Package config provides source-based configuration loading, merging, placeholder resolution, value lookup, scanning, and watching. |
|
env
Package env provides a config.Source backed by environment variables.
|
Package env provides a config.Source backed by environment variables. |
|
file
Package file provides a config.Source backed by files or directories.
|
Package file provides a config.Source backed by files or directories. |
|
inmem
Package inmem provides an in-memory config.Source.
|
Package inmem provides an in-memory config.Source. |
|
loader
Package loader provides an opinionated application configuration loader.
|
Package loader provides an opinionated application configuration loader. |
|
Package ddd contains reusable components named after DDD concepts.
|
Package ddd contains reusable components named after DDD concepts. |
|
event
Package event provides domain event primitives for use inside one bounded context.
|
Package event provides domain event primitives for use inside one bounded context. |
|
message
Package message provides protobuf-first integration message primitives for direct, non-transactional communication across boundaries.
|
Package message provides protobuf-first integration message primitives for direct, non-transactional communication across boundaries. |
|
message/outbox
Package outbox provides transaction-time recording and relay primitives for reliable integration message publishing.
|
Package outbox provides transaction-time recording and relay primitives for reliable integration message publishing. |
|
Package encoding provides a registry for named codecs.
|
Package encoding provides a registry for named codecs. |
|
json
Package json registers the JSON codec with the encoding registry.
|
Package json registers the JSON codec with the encoding registry. |
|
proto
Package proto defines the protobuf codec.
|
Package proto defines the protobuf codec. |
|
toml
Package toml registers the TOML codec with the encoding registry.
|
Package toml registers the TOML codec with the encoding registry. |
|
yaml
Package yaml registers the YAML codec with the encoding registry.
|
Package yaml registers the YAML codec with the encoding registry. |
|
Package fsm provides small finite state machine primitives for polymorphic state objects.
|
Package fsm provides small finite state machine primitives for polymorphic state objects. |
|
Package logger provides the legacy logging abstraction used by older code in this module.
|
Package logger provides the legacy logging abstraction used by older code in this module. |
|
Package mediator provides the legacy in-process mediator.
|
Package mediator provides the legacy in-process mediator. |
|
Package sloghelper provides helpers around the standard library log/slog package.
|
Package sloghelper provides helpers around the standard library log/slog package. |
|
Package taskqueue defines transport-neutral task queue contracts.
|
Package taskqueue defines transport-neutral task queue contracts. |
|
Package validation provides small validation helpers.
|
Package validation provides small validation helpers. |