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. Modern Conventions: Uses String Codes (e.g., "OK", "INVALID_ARGUMENT") for business logic, distinct from HTTP Status Codes.
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.

import "github.com/oy3o/httpx"

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 automatically maps HTTP Status to a Business Code.
    // E.g., 401 -> "UNAUTHORIZED"
    // You can also define custom codes: httpx.NewError(401, "LOGIN_FAILED", "...")
    return nil, &HttpError{HttpCode: http.StatusUnauthorized, BizCode: CodeUnauthorized, Msg: "Unauthorized"} // httpx.ErrUnauthorized
}

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), // Uses httpsnoop
        httpx.DefaultCORS(),
    )

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

Example Response:

{
    "code": "OK",
    "message": "success",
    "data": {
        "token": "abc-123",
        "user_id": "1"
    }
}

Error Response:

{
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "data": null
}

Core Features

1. Cooperative Binding

httpx.Bind is smart enough to handle multiple data sources simultaneously.

• Metadata: URL Query parameters are always parsed (if the struct has matching tags).
• Body: Automatically selects JSON or Form binding based on Content-Type.
• Conflict Resolution: If a field exists in both Query and Body, the Body takes precedence.

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. Semantic Error Handling

We separate Transport State (HTTP Status Code) from Business State (String Code).

• If you return httpx.NewError(404, "USER_NOT_FOUND", "..."):
  • HTTP Status: 404
  • JSON Body: {"code": "USER_NOT_FOUND", ...}
• If you return standard errors (e.g., os.ErrNotExist), httpx infers a default code (e.g., "INTERNAL_ERROR").

4. Flexible Response Options

• Standard Mode: Default wrapper in {code: "OK", 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. Filenames in headers are safely escaped.

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) - Limits, KeepAlive, Context
    ln := netx.Listen(":8080") 
    
    // 2. Application Layer (httpx) - Routing, Validation, Logic
    h := httpx.NewHandler(MyLogic)
    
    // 3. Start
    http.Serve(ln, h)
}