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 ProvideCQRSBehavior(constructor any, paramTags ...string) fx.Option
- func ProvideChallengeProvider(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 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 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 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 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: "richtext" / "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{} }),
)
Source Files
Directories