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_sources.primary]
type = "sqlite"
path = "./my-app.db"
# Additional named sources are optional; each one is reachable through
# datasource.Registry.Get("<name>"). Example:
# [vef.data_sources.analytics]
# type = "postgres"
# host = "analytics.example.com"
# database = "warehouse"
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, data sources (the registry and primary database connection), 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 ProvideDataSourceProvider(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 ProvideDataSourceProvider ¶ added in v0.27.0
ProvideDataSourceProvider registers a datasource.Provider that the framework consults during boot, after the primary and static (TOML) data sources have been registered. Every spec returned by the provider's Load method is passed to datasource.Registry.Register; a name collision with any existing source (TOML or another provider) fails boot.
Typical use case: a tenant table in the primary database whose rows describe additional data sources. The provider reads the table during Load and returns one datasource.Spec per row. For periodic re-sync of the same table, register a cron job that calls datasource.Registry.Reconcile instead.
constructor is an fx-style factory that returns datasource.Provider (or a type that implements it).
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
|
|
|
internal
|
|
|
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). |