gonest

README

Gonest

Simple and elegant Go Web framework inspired by ASP.NET Core and NestJS

English | 中文 | 日本語

---

Core Features

Feature	Description
🏗️ Interface-First Architecture	Interfaces in core/abstract/, implementations in core/, extensions depend on interfaces
🔌 Modular Design	Middleware, protocols, and task scheduling are independent packages - use what you need
⚡ Fine-Grained Interfaces	ContextAbstract = RequestReader + ResponseWriter + ValueStore - compose dependencies at will
📦 Production Ready	Config (Koanf), logging (Zap), authentication, authorization - complete solution

---

Get Started in 5 Minutes

Installation

go get github.com/linuxerlv/gonest

Quick Start

package main

import (
    "github.com/linuxerlv/gonest/core"
    "github.com/linuxerlv/gonest/core/abstract"
    "github.com/linuxerlv/gonest/extensions"
)

func main() {
    // Create WebApplication builder (ASP.NET Core style)
    builder := core.CreateBuilder()

    // Add services to DI container
    builder.Services().AddSingleton(&MyService{})

    // Build application
    app := builder.Build()

    // Use middleware (extension methods)
    extensions.UseRecovery(app, nil)
    extensions.UseCORS(app, nil)

    // Register routes
    app.MapGet("/hello", func(ctx abstract.ContextAbstract) error {
        return ctx.JSON(200, map[string]string{"message": "Hello World"})
    })

    app.Run()
}

Builder Pattern (Recommended with Dependency Injection)

package main

import (
    "github.com/linuxerlv/gonest/core"
    "github.com/linuxerlv/gonest/core/abstract"
    "github.com/linuxerlv/gonest/config"
    "github.com/linuxerlv/gonest/extensions"
)

func main() {
    // Create WebApplication builder (ASP.NET Core style)
    builder := core.CreateBuilder()

    // Configure configuration and environment
    cfg := config.NewKoanfConfig(".")
    builder.UseConfig(cfg)
    builder.Environment().Set("APP_ENV", "production")

    // Register services to DI container
    builder.Services().AddSingleton(&MyService{})
    builder.Services().AddScoped(func(s abstract.ServiceCollectionAbstract) *DbContext {
        return &DbContext{DSN: builder.Environment().Get("DATABASE_URL")}
    })

    // Build application
    app := builder.Build()

    // Get service from DI container
    service := core.GetService[*MyService](app.Services())

    // Use middleware
    extensions.UseRecovery(app, nil)
    extensions.UseCORS(app, &extensions.CORSMiddlewareOptions{
        AllowOrigins: []string{"https://example.com"},
    })

    // Register routes
    app.MapGet("/hello", func(ctx abstract.ContextAbstract) error {
        return ctx.JSON(200, map[string]string{"message": "Hello World"})
    })

    app.Run()
}

Generic Application (Non-Web)

package main

import (
    "github.com/linuxerlv/gonest/core"
    "github.com/linuxerlv/gonest/core/abstract"
)

func main() {
    // Create generic Application builder (for non-web scenarios)
    builder := core.CreateApplicationBuilder()

    // Add services
    builder.Services().AddSingleton(&MyService{})
    builder.Services().AddTransient(func(s abstract.ServiceCollectionAbstract) *Worker {
        return &Worker{}
    })

    // Build application
    app := builder.Build()

    // Get service and run business logic
    service := core.GetService[*MyService](app.Services())
    service.DoWork()
}

---

Project Structure

gonest/
├── core/
│   ├── abstract/              # Interface definitions (fine-grained, composable)
│   │   ├── context.go         # ContextAbstract, RequestReaderAbstract, ResponseWriterAbstract...
│   │   ├── router.go          # RouterAbstract, RouteBuilderAbstract...
│   │   ├── middleware.go      # MiddlewareAbstract...
│   │   ├── di.go              # ServiceCollectionAbstract...
│   │   ├── env.go             # EnvAbstract environment variables interface
│   │   └── ...                # Other interfaces
│   │
│   ├── context.go             # HttpContext implementation
│   ├── router.go              # HttpRouter implementation
│   ├── application.go         # Application implementation
│   ├── builder.go             # WebApplicationBuilder implementation
│   ├── env.go                 # Env environment variables implementation
│   └── ...                    # Other implementations
│
├── config/                    # Configuration module
│   ├── config.go              # Config interface (implements abstract.ConfigAbstract)
│   └── koanf.go               # Koanf implementation
│
├── logger/                    # Logger module
│   ├── logger.go              # Logger interface (implements abstract.LoggerAbstract)
│   └── zap.go                 # Zap implementation
│
├── middleware/                # Middleware extension packages
│   ├── auth/                  # JWT authentication
│   ├── session/               # Session management
│   ├── casbin/                # Casbin permission control
│   ├── cors/                  # CORS
│   ├── recovery/              # Panic recovery
│   ├── ratelimit/             # Rate limiting
│   ├── timeout/               # Timeout control
│   ├── gzip/                  # Gzip compression
│   ├── security/              # Security headers
│   ├── logger/                # Logger middleware
│   └── requestid/             # Request ID
│
├── protocol/                  # Protocol extension packages
│   ├── websocket/             # WebSocket
│   ├── sse/                   # Server-Sent Events
│   ├── http3/                 # HTTP/3
│   └── grpc/                  # gRPC
│
├── task/                      # Task scheduling
│   ├── interface.go           # TaskQueue, CronScheduler interfaces
│   ├── asynq.go               # Asynq implementation (Redis)
│   ├── cron.go                # Cron implementation
│   └── memory.go              # Memory implementation
│
├── ipc/                       # IPC interface (inter-process communication)
│   └── interface.go           # Endpoint, Publisher, Subscriber...
│
└── gonest.go                  # Backward compatible type aliases

---

Interface Design

Fine-Grained Interfaces (core/abstract/)

The framework adopts fine-grained interface design, allowing developers to depend on exactly what they need:

// Request reading interface
type RequestReaderAbstract interface {
    Method() string
    Path() string
    Header(name string) string
}

// Response writing interface
type ResponseWriterAbstract interface {
    Status(code int)
    JSON(code int, v any) error
    String(code int, s string) error
}

// Complete context interface (composed)
type ContextAbstract interface {
    ContextRunnerAbstract
    FullRequestReaderAbstract
    FullResponseWriterAbstract
    ValueStoreAbstract
}

Usage Patterns

// 1. Use complete core package
import "github.com/linuxerlv/gonest/core"
app := core.CreateApplication()

// 2. Use only interface definitions (write extensions)
import "github.com/linuxerlv/gonest/core/abstract"
func MyMiddleware(ctx abstract.ContextAbstract) error { ... }

// 3. Use extension middleware
import "github.com/linuxerlv/gonest/middleware/auth"
app.Use(auth.New(provider, nil))

// 4. Backward compatibility (gonest package type aliases)
import "github.com/linuxerlv/gonest"
app := gonest.NewApplication()

---

API Quick Reference

Application Creation (ASP.NET Core Style)

import "github.com/linuxerlv/gonest/core"

// Web Application (with HTTP server)
builder := core.CreateBuilder()           // Create WebApplication builder
app := builder.Build()                 // Build WebApplication
app.Run()                                 // Start server

// Generic Application (non-web scenarios)
builder := core.CreateApplicationBuilder() // Create Application builder
app := builder.Build()                     // Build Application

// Access services
services := builder.Services()             // Get ServiceCollection
cfg := builder.Configuration()             // Get Configuration
env := builder.Environment()               // Get Environment

Route Registration

import "github.com/linuxerlv/gonest/core/abstract"

// MapXXX methods (ASP.NET Core style)
app.MapGet("/users", func(ctx abstract.ContextAbstract) error {
    return ctx.JSON(200, users)
})

app.MapPost("/users", func(ctx abstract.ContextAbstract) error {
    var user User
    ctx.Bind(&user)
    return ctx.JSON(201, user)
})

app.MapPut("/users/:id", func(ctx abstract.ContextAbstract) error {
    id := ctx.Param("id")
    return ctx.JSON(200, map[string]string{"id": id})
})

app.MapDelete("/users/:id", func(ctx abstract.ContextAbstract) error {
    return ctx.JSON(200, nil)
})

// Route groups
api := app.Group("/api/v1")
api.MapGet("/users", listUsers)

Middleware (Extension Methods)

import "github.com/linuxerlv/gonest/extensions"

// UseXXX extension methods
extensions.UseRecovery(app, nil)
extensions.UseCORS(app, &extensions.CORSMiddlewareOptions{
    AllowOrigins: []string{"https://example.com"},
})
extensions.UseRateLimit(app, &extensions.RateLimitMiddlewareOptions{
    Limit:  100,
    Window: 60, // seconds
})
extensions.UseGzip(app, nil)
extensions.UseSecurityHeaders(app, nil)
extensions.UseRequestID(app, nil)
extensions.UseTimeout(app, &extensions.TimeoutMiddlewareOptions{
    Timeout: 30, // seconds
})

// Or use raw middleware
app.Use(middleware)

Dependency Injection

// Register services
builder.Services().AddSingleton(&MyService{})
builder.Services().AddScoped(func(s abstract.ServiceCollectionAbstract) *DbContext {
    return &DbContext{}
})
builder.Services().AddTransient(func(s abstract.ServiceCollectionAbstract) *CacheService {
    return &CacheService{}
})

// Retrieve services from application
service := core.GetService[*MyService](app.Services())

Environment Variables

// Read environment variables
dbUrl := builder.Environment().Get("DATABASE_URL")
port := builder.Environment().GetOrDefault("PORT", "8080")

// Check existence
if builder.Environment().Has("DEBUG") {
    // ...
}

// Get all
allEnv := builder.Env.All()

Configuration Files

import "github.com/linuxerlv/gonest/config"

// Load JSON configuration file
cfg := config.NewKoanfConfig(".")
cfg.Load(
    config.NewFileProvider("config.json", config.NewJSONParser()),
    config.NewJSONParser(),
)

// Load YAML configuration file
cfg.Load(
    config.NewFileProvider("config.yaml", config.NewYAMLParser()),
    config.NewYAMLParser(),
)

// Read configuration
port := cfg.GetString("server.port")
debug := cfg.GetBool("debug")

// Bind to struct
type ServerConfig struct {
    Port    string `koanf:"port"`
    Timeout int    `koanf:"timeout"`
}
var serverCfg ServerConfig
cfg.Unmarshal("server", &serverCfg)

// Set to builder
builder := core.CreateBuilder()
builder.Config = cfg

---

Documentation Navigation

Document	Audience	Content
Tutorial	🎓 Go Beginners	Progressive learning guide
API Reference	👨‍💻 Application Developers	Complete API documentation
Contributing Guide	🛠️ Framework Contributors	Architecture design, coding standards, testing strategies, extension mechanisms

---

License

MIT License - See LICENSE file

Documentation

Index

• Variables
• type AppBuilder
• type Application
• type ApplicationBuilder
• type CORSMiddlewareOptions
• type Context
• type Controller
• type ExceptionFilter
• type Guard
• type GuardFunc
• type GzipMiddlewareOptions
• type HostApplication
• type HttpContext
• type HttpError
• type HttpRouter
• type Interceptor
• type InterceptorFunc
• type LoggingMiddlewareOptions
• type Middleware
• type MiddlewareFunc
• type Pipe
• type PipeFunc
• type RateLimitMiddlewareOptions
• type RecoveryMiddlewareOptions
• type RequestIDMiddlewareOptions
• type Route
• type RouteBuilder
• type RouteGroup
• type RouteHandler
• type Router
• type SecurityMiddlewareOptions
• type ServiceCollection
• type ServiceDescriptor
• type TimeoutMiddlewareOptions
• type WebApp
• type WebAppBuilder
• type WebApplication
• type WebApplicationBuilder

Variables

var ApplicationCreateBuilder = core.ApplicationCreateBuilder

var BadRequest = abstract.BadRequest

var CreateApplication = core.CreateApplication

var CreateBuilder = core.CreateBuilder

var Forbidden = abstract.Forbidden

var InternalError = abstract.InternalError

var NewApplication = core.NewApplication

var NewApplicationBuilder = core.NewApplicationBuilder

var NewContext = core.NewContext

var NewContextWithParams = core.NewContextWithParams

var NewHostBuilder = core.NewHostBuilder

var NewHttpException = abstract.NewHttpException

var NewRouter = core.NewRouter

var NewServiceCollection = core.NewServiceCollection

var NewWebApplicationBuilder = core.NewWebApplicationBuilder

var NotFound = abstract.NotFound

var Unauthorized = abstract.Unauthorized

var UseCORS = extensions.UseCORS

var UseGzip = extensions.UseGzip

var UseLogging = extensions.UseLogging

var UseRateLimit = extensions.UseRateLimit

var UseRecovery = extensions.UseRecovery

var UseRequestID = extensions.UseRequestID

var UseSecurity = extensions.UseSecurity

var UseTimeout = extensions.UseTimeout

var WebApplicationCreateBuilder = core.WebApplicationCreateBuilder

Types

type AppBuilder

type AppBuilder = core.ApplicationBuilder

type Application

type Application = abstract.Application

type ApplicationBuilder

type ApplicationBuilder = abstract.ApplicationBuilder

type CORSMiddlewareOptions

type CORSMiddlewareOptions = extensions.CORSMiddlewareOptions

type Context

type Context = abstract.Context

type Controller

type Controller = abstract.Controller

type ExceptionFilter

type ExceptionFilter = abstract.ExceptionFilter

type Guard

type Guard = abstract.Guard

type GuardFunc

type GuardFunc = abstract.GuardFunc

type GzipMiddlewareOptions

type GzipMiddlewareOptions = extensions.GzipMiddlewareOptions

type HostApplication

type HostApplication = core.HostApplication

type HttpContext

type HttpContext = core.HttpContext

type HttpError

type HttpError = abstract.HttpError

type HttpRouter

type HttpRouter = core.HttpRouter

type Interceptor

type Interceptor = abstract.Interceptor

type InterceptorFunc

type InterceptorFunc = abstract.InterceptorFunc

type LoggingMiddlewareOptions

type LoggingMiddlewareOptions = extensions.LoggingMiddlewareOptions

type Middleware

type Middleware = abstract.Middleware

type MiddlewareFunc

type MiddlewareFunc = abstract.MiddlewareFunc

type Pipe

type Pipe = abstract.Pipe

type PipeFunc

type PipeFunc = abstract.PipeFunc

type RateLimitMiddlewareOptions

type RateLimitMiddlewareOptions = extensions.RateLimitMiddlewareOptions

type RecoveryMiddlewareOptions

type RecoveryMiddlewareOptions = extensions.RecoveryMiddlewareOptions

type RequestIDMiddlewareOptions

type RequestIDMiddlewareOptions = extensions.RequestIDMiddlewareOptions

type Route

type Route = core.Route

type RouteBuilder

type RouteBuilder = abstract.RouteBuilder

type RouteGroup

type RouteGroup = abstract.RouteGroup

type RouteHandler

type RouteHandler = abstract.RouteHandler

type Router

type Router = abstract.Router

type SecurityMiddlewareOptions

type SecurityMiddlewareOptions = extensions.SecurityMiddlewareOptions

type ServiceCollection

type ServiceCollection = core.ServiceCollection

type ServiceDescriptor

type ServiceDescriptor = core.ServiceDescriptor

type TimeoutMiddlewareOptions

type TimeoutMiddlewareOptions = extensions.TimeoutMiddlewareOptions

type WebApp

type WebApp = core.WebApplication

type WebAppBuilder

type WebAppBuilder = core.WebApplicationBuilder

type WebApplication

type WebApplication = abstract.WebApplication

type WebApplicationBuilder

type WebApplicationBuilder = abstract.WebApplicationBuilder