httpx

httpx: Minimalist HTTP Extensions for Go

中文 | English

httpx is a set of HTTP extension tools based on Go 1.18+ generics. It is not a heavy web framework, but a powerful enhancement for the standard library net/http.

It aims to eliminate repetitive JSON decoding, parameter validation, and response encapsulation code in http.Handler through Generics, while maintaining full compatibility with the standard library.

Core Concepts

1. Type Safety: Leveraging generics to transform func(w, r) into strongly typed func(ctx, *Req) (*Res, error).
2. Convention over Configuration: Provides standard JSON response envelopes, error handling, and log formats out of the box.
3. Performance at Scale: Provides a SelfValidatable interface to bypass reflection validation; integrates httpsnoop for zero-overhead metric capture.

Installation

go get github.com/oy3o/httpx

Quick Start

1. Define Request & Response

Use json tags to define the structure and validate tags to define validation rules.

type LoginReq struct {
    Username string `json:"username" validate:"required,min=3"`
    Password string `json:"password" validate:"required"`
}

type LoginRes struct {
    Token string `json:"token"`
    User  string `json:"user_id"`
}

2. Write Business Logic

No need to manipulate http.ResponseWriter and *http.Request. Just focus on inputs and outputs.

func LoginHandler(ctx context.Context, req *LoginReq) (*LoginRes, error) {
    if req.Username == "admin" && req.Password == "123456" {
        return &LoginRes{Token: "abc-123", User: "1"}, nil
    }
    // Return an error, httpx will automatically map it to an HTTP status code
    return nil, &httpx.HttpError{Code: 401, Msg: "Invalid credentials"}
}

3. Register Routes

Use httpx.NewHandler to convert business functions into standard http.Handlers.

func main() {
    mux := http.NewServeMux()

    // Automatic processing: Bind -> Validate -> Logic -> Response
    mux.Handle("POST /login", httpx.NewHandler(LoginHandler))

    // Add middleware: Recovery -> Logger -> CORS -> Handler
    handler := httpx.Chain(mux, 
        httpx.Recovery(nil),
        httpx.Logger(nil),
        httpx.DefaultCORS(),
    )

    http.ListenAndServe(":8080", handler)
}

Example Response:

{
    "code": 0,
    "message": "ok",
    "data": {
        "token": "abc-123",
        "user_id": "1"
    }
}

Core Features

1. Smart Binding

httpx.Bind automatically selects the parsing strategy based on the request headers:

• GET: Parses URL Query parameters.
• Content-Type: application/json: Parses JSON Body.
• Content-Type: multipart/form-data: Parses forms (supports file uploads).

2. Hybrid Validation

To balance development efficiency and runtime performance, httpx supports two validation modes:

• Reflection Mode (Slow Path): Uses struct tags (validate:"required"). Fast development, but incurs reflection overhead.
• Interface Mode (Fast Path): Implements the SelfValidatable interface. Completely reflection-free, suitable for high-traffic endpoints.

// Fast Validation: httpx calls this method first, skipping reflection
func (r *LoginReq) Validate(ctx context.Context) error {
    if len(r.Username) < 3 {
        return errors.New("username too short")
    }
    return nil
}

3. Unified Error Handling

Any return value implementing the error interface will be captured. If the ErrorCoder interface is implemented, the specified HTTP status code is returned.

// Predefined error
return nil, httpx.ErrBadRequest

// Custom status code
return nil, &httpx.HttpError{Code: 429, Msg: "Slow down"}

4. Flexible Response Options

• Standard Mode: Default wrapper in {code, msg, data}.
• No Envelope Mode: Use the httpx.NoEnvelope() option to return data directly (suitable for standard protocols like OAuth).
• Streamable Response: Return values implementing the Streamable interface (e.g., FileResponse) handle file downloads or streaming writes automatically.

Middleware Ecosystem

httpx provides a set of middleware based on standard library interfaces:

Best Practices

It is recommended to use httpx with netx (network layer extensions) and o11y (observability) to build complete Go services:

// server/run.go
func Run() {
    // 1. Network Layer (netx)
    ln := netx.Listen(":8080") 
    
    // 2. Application Layer (httpx)
    h := httpx.NewHandler(MyLogic)
    
    // 3. Start
    http.Serve(ln, h)
}