API Reference
3 minute read
Core Functions
New
func New(opts ...Option) (*App, error)
Creates a new App instance with the given options. Returns an error if configuration is invalid.
Parameters:
opts- Configuration options
Returns:
*App- The app instanceerror- Configuration validation errors
Example:
a, err := app.New(
app.WithServiceName("my-api"),
app.WithServiceVersion("v1.0.0"),
)
if err != nil {
log.Fatal(err)
}
MustNew
func MustNew(opts ...Option) *App
Creates a new App instance or panics on error. Use for initialization in main() functions.
Parameters:
opts- Configuration options
Returns:
*App- The app instance
Panics: If configuration is invalid
Example:
a := app.MustNew(
app.WithServiceName("my-api"),
)
App Methods
HTTP Method Shortcuts
func (a *App) GET(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) POST(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) PUT(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) DELETE(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) PATCH(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) HEAD(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) OPTIONS(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
func (a *App) Any(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
Register routes for HTTP methods.
Middleware
func (a *App) Use(middleware ...HandlerFunc)
Adds middleware to the app. Middleware executes for all routes registered after Use().
Route Groups
func (a *App) Group(prefix string, middleware ...HandlerFunc) *Group
func (a *App) Version(version string) *VersionGroup
Create route groups and version groups.
Static Files
func (a *App) Static(prefix, root string)
func (a *App) File(path, filepath string)
func (a *App) StaticFS(prefix string, fs http.FileSystem)
func (a *App) NoRoute(handler HandlerFunc)
Serve static files and set custom 404 handler.
Server Management
func (a *App) Start(ctx context.Context, addr string) error
func (a *App) StartTLS(ctx context.Context, addr, certFile, keyFile string) error
func (a *App) StartMTLS(ctx context.Context, addr string, cert tls.Certificate, opts ...MTLSOption) error
Start HTTP, HTTPS, or mTLS servers with graceful shutdown.
Lifecycle Hooks
func (a *App) OnStart(fn func(context.Context) error)
func (a *App) OnReady(fn func())
func (a *App) OnShutdown(fn func(context.Context))
func (a *App) OnStop(fn func())
func (a *App) OnRoute(fn func(*route.Route))
Register lifecycle hooks. See Lifecycle Hooks for details.
Accessors
func (a *App) Router() *router.Router
func (a *App) Metrics() *metrics.Recorder
func (a *App) Tracing() *tracing.Tracer
func (a *App) Readiness() *ReadinessManager
func (a *App) ServiceName() string
func (a *App) ServiceVersion() string
func (a *App) Environment() string
Access underlying components and configuration.
Route Management
func (a *App) Route(name string) (*route.Route, bool)
func (a *App) Routes() []*route.Route
func (a *App) URLFor(routeName string, params map[string]string, query map[string][]string) (string, error)
func (a *App) MustURLFor(routeName string, params map[string]string, query map[string][]string) string
Route lookup and URL generation. Router must be frozen (after Start()).
Metrics
func (a *App) GetMetricsHandler() (http.Handler, error)
func (a *App) GetMetricsServerAddress() string
Access metrics handler and server address.
Logging
func (a *App) BaseLogger() *slog.Logger
Returns the application’s base logger. Never returns nil.
Testing
func (a *App) Test(req *http.Request, opts ...TestOption) (*http.Response, error)
func (a *App) TestJSON(method, path string, body any, opts ...TestOption) (*http.Response, error)
Test routes without starting a server.
Helper Functions
ExpectJSON
func ExpectJSON(t testingT, resp *http.Response, statusCode int, out any)
Test helper that asserts response status and decodes JSON.
Generic Binding
func BindAndValidateInto[T any](c *Context, opts ...validation.Option) (T, error)
func MustBindAndValidateInto[T any](c *Context, opts ...validation.Option) (T, bool)
Type-safe binding with generics.
Types
HandlerFunc
type HandlerFunc func(*Context)
Handler function that receives an app Context.
TestOption
type TestOption func(*testConfig)
func WithTimeout(d time.Duration) TestOption
func WithContext(ctx context.Context) TestOption
Options for testing.
Next Steps
- Options - Configuration options reference
- Context API - Context methods reference
- Lifecycle Hooks - Hook APIs reference
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.