README
¶
goboot
An annotation-driven, compile-time application framework for Go.
goboot gives you a Spring Boot–style developer experience while keeping everything Go loves: explicit dependencies, static typing, fast startup, and readable code. You annotate ordinary Go types and methods; a CLI compiler reads the annotations, builds a typed application model and dependency graph, validates it, and generates ordinary, readable Go — with no runtime reflection for dependency injection and no classpath scanning.
// @Service(name="userService", implements="UserUseCase")
type UserService struct {
repo domain.UserRepository
}
func NewUserService(repo domain.UserRepository) *UserService { return &UserService{repo: repo} }
// @Transactional
// @Traced(name="users.create")
func (s *UserService) CreateUser(ctx context.Context, cmd CreateUserCommand) (*domain.User, error) {
// ...
}
go run github.com/zombocoder/goboot/cmd/goboot generate ./...
You get generated wiring that constructs your components in dependency order, registers HTTP routes, applies transactions/tracing/metrics through generated proxies, loads typed configuration, runs lifecycle hooks and scheduled tasks, and starts a server — all as plain Go you can read and debug.
Why compile-time?
The single architectural principle: annotations describe intent; the compiler validates that intent into a semantic model; generators turn the model into plain Go. Dependency resolution, component discovery, and wiring all happen at generation time. The generated program does not scan packages or discover components at startup, and interface/dependency compatibility is checked with go/types — never strings.
Features
- Dependency injection — constructor injection, interface resolution,
@Primary,@Nutprovider functions, deterministic construction order, cycle detection. - HTTP controllers —
@RestController/@GetMapping/@PostMappinggenerate handler proxies (bind → validate → authorize → invoke → write) with centralized RFC 7807 error handling. - Configuration — typed
@ConfigurationPropertiesbound from YAML and environment with defaults. - Lifecycle —
@PostConstruct/@PreDestroywith ordered startup, rollback, and graceful shutdown. - Service proxies (interception) —
@Transactional,@Traced,@Timedwrap methods through generated interface proxies. - Repositories — generate implementations from
@Query/@Execinterfaces with named SQL parameters; driver-agnostic via a pluggable dialect. - Conditions & profiles —
@Profile,@ConditionalOnProperty,@ConditionalOnNut,@ConditionalOnMissingNut. - Scheduling —
@Scheduledbackground tasks. - Plugin system — external packages register annotations, analyzers, generators, and database dialects at compile time.
Install
go install github.com/zombocoder/goboot/cmd/goboot@latest
Or pin it via go:generate in your project (recommended for reproducible builds):
//go:generate go run github.com/zombocoder/goboot/cmd/goboot generate ./...
CLI
goboot init # scaffold goboot.yaml
goboot generate ./... # generate wiring into the output package
goboot validate ./... # analyze and report diagnostics, no files written
goboot graph ./... --format mermaid
goboot clean # remove generated files
goboot doctor # environment checks
goboot version
Useful flags on generate/validate: -profile prod,staging, -property cache.enabled=true, -dialect postgres|question, -strict, -tags.
Extending with plugins
goboot is extended at compile time through the plugin package — no dynamic loading. A plugin implements plugin.Plugin plus any of AnnotationProvider, Analyzer, Generator, or DialectProvider (a database driver). See plugin/exampleplugin for a worked example.
Status
goboot is under active development. The core framework — DI, HTTP, configuration, lifecycle, interception, repositories, conditions/profiles, scheduling, a CLI, and a plugin system — is implemented and tested. See implementation-plan.md for the full technical specification and roadmap.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct. Security issues: see SECURITY.md.
License
Licensed under the Apache License, Version 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
databasesql
Package databasesql adapts Go's standard database/sql to goboot's driver-neutral db abstraction (§6.6, §27).
|
Package databasesql adapts Go's standard database/sql to goboot's driver-neutral db abstraction (§6.6, §27). |
|
oidc
module
|
|
|
pgx
module
|
|
|
redis
module
|
|
|
Package cli implements the annotation-driven compiler CLI (§43): it loads Go packages, parses annotations, validates the application, and generates type-safe wiring through the standard go/generate workflow (§44, §59).
|
Package cli implements the annotation-driven compiler CLI (§43): it loads Go packages, parses annotations, validates the application, and generates type-safe wiring through the standard go/generate workflow (§44, §59). |
|
cmd
|
|
|
goboot
command
Command goboot is the annotation-driven compiler CLI (§43).
|
Command goboot is the annotation-driven compiler CLI (§43). |
|
Package compiler loads Go packages, associates annotation comments with the declarations they document, resolves type information, and validates the result against the annotation registry.
|
Package compiler loads Go packages, associates annotation comments with the declarations they document, resolves type information, and validates the result against the annotation registry. |
|
generator
|
|
|
di
Package di generates the dependency-injection wiring for an application: a single Go source file that constructs every singleton component in dependency order and returns them (§32).
|
Package di generates the dependency-injection wiring for an application: a single Go source file that constructs every singleton component in dependency order and returns them (§32). |
|
Package graph builds and analyzes the component dependency graph (§15).
|
Package graph builds and analyzes the component dependency graph (§15). |
|
internal
|
|
|
Package model defines the intermediate application model produced by semantic analysis and consumed by the code generators (specification §38).
|
Package model defines the intermediate application model produced by semantic analysis and consumed by the code generators (specification §38). |
|
Package plugin defines goboot's compile-time extension model (§46).
|
Package plugin defines goboot's compile-time extension model (§46). |
|
exampleplugin
Package exampleplugin is a reference goboot plugin demonstrating every extension point (§46): it registers an annotation, contributes semantic analysis, generates an artifact, and provides a SQL dialect (as a database driver would).
|
Package exampleplugin is a reference goboot plugin demonstrating every extension point (§46): it registers an annotation, contributes semantic analysis, generates an artifact, and provides a SQL dialect (as a database driver would). |
|
plugins
|
|
|
metrics
module
|
|
|
openapi
module
|
|
|
validate
module
|
|
|
Package runtime provides the minimal reusable abstractions that goboot's generated HTTP code depends on: request binding, validation, response writing, centralized error handling, and the RFC 7807-inspired problem model (§22, §23).
|
Package runtime provides the minimal reusable abstractions that goboot's generated HTTP code depends on: request binding, validation, response writing, centralized error handling, and the RFC 7807-inspired problem model (§22, §23). |
|
config
Package config loads typed configuration properties from layered sources — defaults, YAML files, and environment variables — following the precedence of §28.2.
|
Package config loads typed configuration properties from layered sources — defaults, YAML files, and environment variables — following the precedence of §28.2. |
|
db
Package db defines the driver-neutral database abstractions that generated repositories depend on (§27).
|
Package db defines the driver-neutral database abstractions that generated repositories depend on (§27). |
|
Package sqlgen compiles named-parameter SQL into driver-specific positional SQL (§27.4).
|
Package sqlgen compiles named-parameter SQL into driver-specific positional SQL (§27.4). |