README
¶
VEF Framework Go
An opinionated Go framework for enterprise applications, built with Fiber, Uber FX, and Bun.
Unified API resources, generic CRUD, authentication, RBAC, validation, caching, events, storage, MCP, and more.
English | 简体中文 | Quick Start | Documentation | API Reference
VEF Framework Go combines dependency injection, HTTP routing, and data access into a cohesive application framework, with built-in support for API resources, authentication, RBAC, validation, caching, events, storage, MCP, and more.
This README is intentionally brief. Detailed tutorials and reference material are available on the documentation site.
Development status: the project is still pre-1.0. Expect breaking changes while conventions and APIs continue to evolve.
Why VEF
- One resource model for both RPC and REST APIs
- Generic CRUD primitives that reduce repetitive backend code
- Modular composition with Uber FX for clean wiring and extension
- Built-in auth, RBAC, rate limiting, audit, caching, events, storage, MCP, and other infrastructure you would otherwise assemble yourself
Quick Start
Requirements:
- Go 1.26.0 or newer
- A supported database such as PostgreSQL, MySQL, or SQLite
Install:
go get github.com/coldsmirk/vef-framework-go
Create main.go:
package main
import "github.com/coldsmirk/vef-framework-go"
func main() {
vef.Run()
}
Create configs/application.toml:
[vef.app]
name = "my-app"
port = 8080
[vef.data_source]
type = "sqlite"
path = "./my-app.db"
This is the smallest runnable configuration. Sections such as vef.monitor, vef.mcp, and vef.approval are optional.
Run:
go run main.go
VEF loads application.toml from ./configs, ., ../configs, or the path pointed to by VEF_CONFIG_PATH.
Core Concepts
vef.Run(...)starts the framework and wires the default module chain: config, database, ORM, middleware, API, security, event, CQRS, cron, redis, mold, storage, sequence, schema, monitor, MCP, and app.- API endpoints are defined as resources with
api.NewRPCResource(...)orapi.NewRESTResource(...). - Business modules are composed with FX options, for example
vef.ProvideAPIResource(...),vef.ProvideMiddleware(...), andvef.ProvideMCPTools(...). - CRUD-heavy modules can build on the generic helpers in
crud/instead of writing repetitive handlers from scratch.
Typical application layout:
my-app/
├── cmd/
├── configs/
└── internal/
├── auth/
├── sys/
├── <domain>/
└── web/
Documentation
- Documentation site: https://coldsmirk.github.io/vef-framework-go-docs
- API reference: https://pkg.go.dev/github.com/coldsmirk/vef-framework-go
- Repository knowledge map: https://deepwiki.com/coldsmirk/vef-framework-go
- Testing conventions: TESTING.md
If you need step-by-step guides, architectural deep dives, or feature-specific reference, prefer the documentation site rather than expanding this README.
Development
Common verification commands:
go test ./...
go test -race ./...
golangci-lint run
go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...
License
Licensed under the Apache License 2.0.
Documentation
¶
Index ¶
- Variables
- func NamedLogger(name string) logx.Logger
- func ProvideAPIResource(constructor any, paramTags ...string) fx.Option
- func ProvideApprovalLifecycleHook(constructor any, paramTags ...string) fx.Option
- func ProvideCQRSBehavior(constructor any, paramTags ...string) fx.Option
- func ProvideChallengeProvider(constructor any, paramTags ...string) fx.Option
- func ProvideEventConsumeMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideEventErrorSink(constructor any, paramTags ...string) fx.Option
- func ProvideEventMetricsRecorder(constructor any, paramTags ...string) fx.Option
- func ProvideEventPublishMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideEventTransport(constructor any, paramTags ...string) fx.Option
- func ProvideMCPPrompts(constructor any, paramTags ...string) fx.Option
- func ProvideMCPResourceTemplates(constructor any, paramTags ...string) fx.Option
- func ProvideMCPResources(constructor any, paramTags ...string) fx.Option
- func ProvideMCPTools(constructor any, paramTags ...string) fx.Option
- func ProvideMiddleware(constructor any, paramTags ...string) fx.Option
- func ProvideSPAConfig(constructor any, paramTags ...string) fx.Option
- func Run(options ...fx.Option)
- func SupplyBusinessBindingHook(constructor any) fx.Option
- func SupplyFileACL(constructor any) fx.Option
- func SupplyMCPServerInfo(info *mcp.ServerInfo) fx.Option
- func SupplySPAConfigs(config *middleware.SPAConfig, configs ...*middleware.SPAConfig) fx.Option
- func SupplyURLKeyMapper(constructor any) fx.Option
- type Hook
- type HookFunc
- type In
- type Lifecycle
- type Out
Constants ¶
This section is empty.
Variables ¶
Functions ¶
func NamedLogger ¶
NamedLogger creates a named logger instance for the specified component. This is a convenience function that wraps the internal logger factory.
func ProvideAPIResource ¶
ProvideAPIResource provides an API resource to the dependency injection container. The resource will be registered in the "vef:api:resources" group. The constructor must return api.Resource (not a concrete type).
func ProvideApprovalLifecycleHook ¶ added in v0.24.0
ProvideApprovalLifecycleHook registers a synchronous approval.InstanceLifecycleHook into the FX container. Hooks run inside the engine transaction for OnInstanceCreated / OnInstanceCompleted, so returning an error rolls back the surrounding business operation.
The constructor must return approval.InstanceLifecycleHook (not a concrete type). Multiple hooks compose via the `vef:approval:lifecycle_hooks` group.
func ProvideCQRSBehavior ¶
ProvideCQRSBehavior provides a CQRS behavior middleware to the dependency injection container. The constructor must return cqrs.Behavior (not a concrete type).
func ProvideChallengeProvider ¶
ProvideChallengeProvider provides a login challenge provider to the dependency injection container. The provider will be registered in the "vef:security:challenge_providers" group. The constructor must return security.ChallengeProvider (not a concrete type).
func ProvideEventConsumeMiddleware ¶ added in v0.24.0
ProvideEventConsumeMiddleware registers a consume-side event middleware. The constructor must return event/middleware.ConsumeMiddleware.
func ProvideEventErrorSink ¶ added in v0.24.0
ProvideEventErrorSink overrides the framework's default async error sink. The constructor must return event.ErrorSink. Useful when async-publish failures need to flow to a metrics or alerting system rather than just the logger.
func ProvideEventMetricsRecorder ¶ added in v0.24.0
ProvideEventMetricsRecorder overrides the framework's default (expvar-backed) event.MetricsRecorder. The constructor must return event.MetricsRecorder. Use this when forwarding publish/consume observations to Prometheus, OpenTelemetry, or a vendor SDK.
Example:
fx.New(
vef.Module,
vef.ProvideEventMetricsRecorder(newPrometheusRecorder),
)
func ProvideEventPublishMiddleware ¶ added in v0.24.0
ProvideEventPublishMiddleware registers a publish-side event middleware. The constructor must return event/middleware.PublishMiddleware.
func ProvideEventTransport ¶ added in v0.24.0
ProvideEventTransport registers a custom event Transport. The constructor must return event/transport.Transport (or a type that satisfies it).
func ProvideMCPPrompts ¶
ProvideMCPPrompts provides an MCP prompt provider. The constructor must return mcp.PromptProvider (not a concrete type).
func ProvideMCPResourceTemplates ¶
ProvideMCPResourceTemplates provides an MCP resource template provider. The constructor must return mcp.ResourceTemplateProvider (not a concrete type).
func ProvideMCPResources ¶
ProvideMCPResources provides an MCP resource provider. The constructor must return mcp.ResourceProvider (not a concrete type).
func ProvideMCPTools ¶
ProvideMCPTools provides an MCP tool provider. The constructor must return mcp.ToolProvider (not a concrete type).
func ProvideMiddleware ¶
ProvideMiddleware provides a middleware to the dependency injection container. The middleware will be registered in the "vef:app:middlewares" group. The constructor must return app.Middleware (not a concrete type).
func ProvideSPAConfig ¶
ProvideSPAConfig provides a Single Page Application configuration to the dependency injection container. The config will be registered in the "vef:spa" group.
func Run ¶
Run starts the VEF framework with the provided options. It initializes all core modules and runs the application.
func SupplyBusinessBindingHook ¶ added in v0.24.0
SupplyBusinessBindingHook replaces the framework-provided default approval.BusinessBindingHook (no-op create + status write-back) with a host-supplied implementation. Hosts override this when their business row needs to be allocated during start_instance or when the write-back must touch additional columns / cross-service calls.
constructor is an fx-style factory that returns approval.BusinessBindingHook (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example:
fx.New(
vef.Module,
vef.SupplyBusinessBindingHook(newMyHook),
)
func SupplyFileACL ¶ added in v0.23.0
SupplyFileACL replaces the framework-provided default storage.FileACL with a business-specific implementation. The default ACL is pub-only (reads of keys under storage.PublicPrefix are allowed; everything else is denied), so any application that stores private files MUST register its own implementation through this helper.
constructor is an fx-style factory that returns storage.FileACL (or a type implementing it). It may declare any dependencies already registered in the fx graph — typically orm.DB plus any business services that own the reverse index from object key to owning row.
Example:
type myACL struct{ db orm.DB }
func newMyACL(db orm.DB) storage.FileACL {
return &myACL{db: db}
}
fx.New(
vef.Module,
vef.SupplyFileACL(newMyACL),
)
func SupplyMCPServerInfo ¶
func SupplyMCPServerInfo(info *mcp.ServerInfo) fx.Option
SupplyMCPServerInfo supplies MCP server info.
func SupplySPAConfigs ¶
func SupplySPAConfigs(config *middleware.SPAConfig, configs ...*middleware.SPAConfig) fx.Option
SupplySPAConfigs supplies multiple Single Page Application configurations to the dependency injection container. All configs will be registered in the "vef:spa" group.
func SupplyURLKeyMapper ¶ added in v0.23.0
SupplyURLKeyMapper replaces the framework-provided default storage.URLKeyMapper (identity) with a business-specific implementation. The default mapper assumes the frontend embeds bare storage keys verbatim in <img src> /  constructs; applications that embed proxy paths (e.g. "/storage/files/<key>"), CDN URLs, or any other URL convention MUST register their own mapper here so meta: "rich_text" / "markdown" reconciliation can resolve those URLs back to storage keys before consuming claims or scheduling deletions.
constructor is an fx-style factory that returns storage.URLKeyMapper (or a type implementing it). It may declare any dependencies already registered in the fx graph.
Example: stripping the framework's default proxy prefix.
type proxyURLMapper struct{}
func (proxyURLMapper) URLToKey(u string) string {
return strings.TrimPrefix(u, "/storage/files/")
}
func (proxyURLMapper) KeyToURL(k string) string {
return "/storage/files/" + k
}
fx.New(
vef.Module,
vef.SupplyURLKeyMapper(func() storage.URLKeyMapper { return proxyURLMapper{} }),
)
Types ¶
type Hook ¶
func StartStopHook ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
vef-cli
command
|
|
|
Package event defines the framework's event bus contract: the minimal Event interface every domain event satisfies, the Envelope metadata carried alongside payloads, and the Bus surface used by publishers and subscribers.
|
Package event defines the framework's event bus contract: the minimal Event interface every domain event satisfies, the Envelope metadata carried alongside payloads, and the Bus surface used by publishers and subscribers. |
|
inbox
Package inbox declares the idempotency record model and repository contract used by the consume-side Inbox middleware.
|
Package inbox declares the idempotency record model and repository contract used by the consume-side Inbox middleware. |
|
middleware
Package middleware defines the publish-side and consume-side middleware contracts used by the event bus.
|
Package middleware defines the publish-side and consume-side middleware contracts used by the event bus. |
|
transport
Package transport defines the pluggable delivery contract for the event bus.
|
Package transport defines the pluggable delivery contract for the event bus. |
|
transport/memory
Package memory declares the configuration surface for the in-process Transport.
|
Package memory declares the configuration surface for the in-process Transport. |
|
transport/outbox
Package outbox declares the persistent outbox Transport contract: records, status, repository interface, and configuration.
|
Package outbox declares the persistent outbox Transport contract: records, status, repository interface, and configuration. |
|
transport/redisstream
Package redisstream declares the cross-process Transport contract backed by Redis Streams.
|
Package redisstream declares the cross-process Transport contract backed by Redis Streams. |
|
internal
|
|
|
approval/auth
Package auth provides the default identity-resolution wiring for the approval module.
|
Package auth provides the default identity-resolution wiring for the approval module. |
|
approval/binding
Package binding provides the default BusinessBindingHook implementation that wires the approval engine into the host application's business tables declared via Flow.BusinessTable / BusinessPkField / BusinessStatusField.
|
Package binding provides the default BusinessBindingHook implementation that wires the approval engine into the host application's business tables declared via Flow.BusinessTable / BusinessPkField / BusinessStatusField. |
|
approval/shared
Package shared collects cross-cutting types and helpers for the approval module: sentinel errors with stable codes, ID utilities, deadline math, CC user resolution, and small DTOs shared by the command/query/resource boundaries.
|
Package shared collects cross-cutting types and helpers for the approval module: sentinel errors with stable codes, ID utilities, deadline math, CC user resolution, and small DTOs shared by the command/query/resource boundaries. |
|
event
Package event implements the framework's event Bus: routing, transports, middleware composition, and the async fan-in pump.
|
Package event implements the framework's event Bus: routing, transports, middleware composition, and the async fan-in pump. |
|
event/middleware
Package middleware provides the built-in publish-side and consume-side middlewares wired by internal/event.
|
Package middleware provides the built-in publish-side and consume-side middlewares wired by internal/event. |
|
event/transport/memory
Package memory implements the in-process Transport.
|
Package memory implements the in-process Transport. |
|
event/transport/redisstream
Package redisstream implements the cross-process Transport backed by Redis Streams (XADD / XREADGROUP / XACK / XCLAIM).
|
Package redisstream implements the cross-process Transport backed by Redis Streams (XADD / XREADGROUP / XACK / XCLAIM). |
|
event/transport/transporttest
Package transporttest hosts the shared transport contract suite.
|
Package transporttest hosts the shared transport contract suite. |
|
eventtest
Package eventtest provides synchronous in-memory test doubles for the framework's event Bus.
|
Package eventtest provides synchronous in-memory test doubles for the framework's event Bus. |
|
sqlmigration
Package sqlmigration provides the framework-internal DDL migration helper shared by every module that ships its own SQL scripts (approval, storage, event inbox, event outbox).
|
Package sqlmigration provides the framework-internal DDL migration helper shared by every module that ships its own SQL scripts (approval, storage, event inbox, event outbox). |