中文文档: README_CN.md

This library is optimized around low-latency request handling, tight routing, and low-allocation parsing/writing paths.

Current benchmark snapshot on darwin/arm64 (Apple M2):

Notes:

• Memory reports Go benchmark B/op and allocs/op; the snapshot was collected with -benchmem.
• Static JSON responses are down to a single allocation on the request path.
• No-content and manual-write response paths stay at 0 alloc.
• Standard net/http handlers can be mounted with 0 alloc request overhead.
• Ctx.Blob provides an explicit fast path for pre-encoded byte responses.
• Param and catch-all routing become 0 alloc when params are pooled, which is already how Application runs.
• Pre-encoded JSON (json.RawMessage) has a dedicated write fast path.
• TryParseJSONBodyFast is the opt-in fast path for JSON request bodies when unknown-field rejection is not required.
• Client response decoding has an explicit raw-body fast path via *web.RawBody.
• Binary and avro responses have direct fast paths.
• Integer and slice parsing hot paths avoid extra scans and intermediate slices while remaining 0 alloc.

Run the current benchmark suite:

go test -run '^$' -bench 'Benchmark(ServeHTTP|TreeGetValue|TryParse|TryInt|TryUint|TryBool|Post(JSON|Bytes)|DoReqWithClient(Struct|RawBody)|Ctx|ParamsVal|ParseMediaType|AcceptMediaType)' -benchmem ./...

Compare current results against the committed baseline:

./bench/compare.sh

Refresh the committed baseline:

./bench/update_baseline.sh

Generate a Markdown benchmark snapshot ready to paste into the README:

./bench/snapshot.sh

Update the benchmark snapshot blocks in README.md and README_CN.md:

./bench/update_snapshot_readme.sh

Useful overrides:

COUNT=3 ./bench/compare.sh
BENCH_EXPR='BenchmarkServeHTTP(StaticJSON|PathParamJSON)$' ./bench/compare.sh
CURRENT_FILE=./bench/servehttp.txt COUNT=3 ./bench/compare.sh
SHOW_MISSING=1 ./bench/compare.sh
COUNT=3 ./bench/update_baseline.sh
COUNT=3 ./bench/snapshot.sh
COUNT=3 ./bench/update_snapshot_readme.sh

Files:

• baseline: bench/baseline.txt
• compare script: bench/compare.sh
• update script: bench/update_baseline.sh
• snapshot script: bench/snapshot.sh
• README update script: bench/update_snapshot_readme.sh

• Prefer []byte or web.AvroMarshaler for binary/avro responses.
• Prefer c.Blob(...) for pre-encoded byte responses that should write immediately.
• Use HandleHTTP/GetHTTP/PostHTTP when integrating existing net/http handlers.
• Prefer PostBytes/PutBytes/PatchBytes/DoBytes when the request body is already encoded.
• Prefer *WithClient helpers when you need tuned timeouts, connection pooling, or a custom transport.
• Reuse destination slices when calling TryParse(..., &slice) in hot paths.
• Prefer pooled param paths if you benchmark routing in isolation; the framework already does this in normal request handling.
• Treat single benchmark runs as noisy. Use the baseline comparison script for direction, not intuition.

package main

import (
	"log"
	"net/http"

	"pkg.gostartkit.com/web"
)

func main() {
	app := web.New()

	app.Get("/health", func(c *web.Ctx) (any, error) {
		return map[string]string{"status": "ok"}, nil
	})

	log.Fatal(app.ListenAndServe("tcp", ":8080"))
}

This section focuses on the most common way to use the framework. If you only need to get an API online quickly, start here.

Use web.New() for the default setup. If you already know you want middleware or structured errors, pass options at construction time.

app := web.New(
	web.WithMiddleware(
		web.RequestID("", nil),
		web.Recover(nil),
	),
	web.WithErrorHandler(web.JSONErrorHandler(true)),
)

Use the option-based form when you want startup code to stay declarative. Use app.Use(...) when middleware is added later or conditionally.

Handlers use the signature:

func(c *web.Ctx) (any, error)

The simplest handler returns a value and lets the framework encode it.

app.Get("/health", func(c *web.Ctx) (any, error) {
	return map[string]string{"status": "ok"}, nil
})

You can also register other HTTP methods:

app.Post("/users", createUser)
app.Put("/users/:id", updateUser)
app.Delete("/users/:id", deleteUser)
app.Handle("PURGE", "/cache/:key", purgeCache)

If you already have standard net/http handlers, mount them directly:

app.GetHTTP("/metrics", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusNoContent)
}))

Use Param, Query, and Form for string access. Use typed helpers when you want parsing and validation in one step.

app.Get("/users/:id", func(c *web.Ctx) (any, error) {
	id, err := c.ParamUint64("id")
	if err != nil {
		return nil, web.ErrBadRequest
	}

	verbose := c.Query("verbose") == "1"

	return map[string]any{
		"id":      id,
		"verbose": verbose,
	}, nil
})

For form requests:

app.Post("/login", func(c *web.Ctx) (any, error) {
	email := c.Form("email")
	password := c.Form("password")

	if email == "" || password == "" {
		return nil, web.ErrBadRequest
	}

	return map[string]bool{"ok": true}, nil
})

Use TryParseBody when the request Content-Type should control decoding. It supports the built-in JSON, GOB, and XML readers.

type CreateUserRequest struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

app.Post("/users", func(c *web.Ctx) (any, error) {
	var req CreateUserRequest
	if err := c.TryParseBody(&req); err != nil {
		return nil, err
	}

	return map[string]any{
		"name": req.Name,
		"age":  req.Age,
	}, nil
})

Use TryParseJSONBodyFast when you know the body is JSON and want the faster path based on pooled buffers and json.Unmarshal.

app.Post("/events", func(c *web.Ctx) (any, error) {
	var req struct {
		Type string `json:"type"`
	}

	if err := c.TryParseJSONBodyFast(&req); err != nil {
		return nil, err
	}

	return map[string]string{"accepted": req.Type}, nil
})

Choose TryParseBody when strict JSON unknown-field rejection matters. Choose TryParseJSONBodyFast when raw speed matters more.

The default response behavior is intentionally simple:

• return nil, nil writes 204 No Content
• return value, nil writes 200 OK
• c.SetStatus(code) overrides the default success status
• return nil, err writes an error response

Example with explicit success status:

app.Post("/users", func(c *web.Ctx) (any, error) {
	c.SetStatus(http.StatusCreated)
	return map[string]string{"result": "created"}, nil
})

If you want to write the response immediately, use the explicit helpers:

app.Get("/ping", func(c *web.Ctx) (any, error) {
	return nil, c.String(http.StatusOK, "pong")
})

app.Get("/config.json", func(c *web.Ctx) (any, error) {
	return nil, c.JSON(http.StatusOK, map[string]bool{"ok": true})
})

app.Get("/logo", func(c *web.Ctx) (any, error) {
	return nil, c.Blob(http.StatusOK, "image/png", pngBytes)
})

For framework-style handlers, returning values is usually the more idiomatic choice. The immediate helpers are best when you need exact response control.

Use groups to keep prefixes and middleware close to the routes that need them.

api := app.Group("/api", web.Timeout(2*time.Second))
api.Use(web.AccessLog(func(c *web.Ctx, status int, d time.Duration, err error) {
	log.Printf("%s %s -> %d (%s)", c.Method(), c.Path(), status, d)
}))

api.Get("/users/:id", func(c *web.Ctx) (any, error) {
	return map[string]string{
		"id":         c.Param("id"),
		"request_id": c.RequestID(),
	}, nil
})

The middleware order is:

• application middleware
• parent group middleware
• child group middleware
• route middleware

Common built-in middleware you can mix in:

• web.RequestID("", nil) adds a request ID to context and response headers
• web.Recover(nil) converts panics into framework errors
• web.Timeout(2 * time.Second) adds a cooperative deadline
• web.MaxBodyBytes(1 << 20) limits request bodies to 1 MiB
• web.SecurityHeaders() adds a default set of security response headers
• web.CORSMiddleware(...) emits CORS headers for matched routes

You can return the built-in framework errors directly:

app.Get("/private", func(c *web.Ctx) (any, error) {
	if c.BearerToken() == "" {
		return nil, web.ErrUnauthorized
	}
	return map[string]bool{"ok": true}, nil
})

To standardize API error output, install JSONErrorHandler:

app.SetErrorHandler(web.JSONErrorHandler(true))

That produces a body like:

{
  "code": 401,
  "message": "UNAUTHORIZED",
  "request_id": "abc123"
}

For redirects, prefer c.Redirect(...):

app.Get("/old-home", func(c *web.Ctx) (any, error) {
	return nil, c.Redirect(http.StatusMovedPermanently, "/new-home")
})

Use ServeFiles when part of your application should expose files from a directory.

app.ServeFiles("/static/*filepath", http.Dir("./public"))

Requests such as /static/app.css or /static/js/app.js are forwarded to the underlying file system with the /static prefix stripped.

For browser-facing APIs, a common setup looks like this:

app := web.New(
	web.WithCORS(web.NewCORS(web.CORSOptions{
		AllowOrigins:     []string{"https://app.example.com"},
		AllowHeaders:     []string{"Authorization", "Content-Type"},
		AllowCredentials: true,
		MaxAge:           10 * time.Minute,
	})),
)

app.Use(
	web.CORSMiddleware(web.CORSOptions{
		AllowOrigins:     []string{"https://app.example.com"},
		ExposeHeaders:    []string{"X-Request-Id"},
		AllowCredentials: true,
	}),
	web.SecurityHeaders(),
)

Use both pieces together when you want:

• NewCORS(...) to cover the framework's automatic OPTIONS responses
• CORSMiddleware(...) to cover matched GET / POST / PUT / PATCH / DELETE responses

If you only need security headers, web.SecurityHeaders() is the shortest path. Use SecurityHeadersWithOptions(...) when you need custom CSP, HSTS, or related policies.

The package also includes lightweight client helpers.

Simple JSON GET:

var resp struct {
	Name string `json:"name"`
}

if err := web.Get(context.Background(), "https://api.example.com/user/1", "", &resp); err != nil {
	return err
}

JSON POST:

payload := map[string]string{"name": "alice"}

var resp struct {
	ID uint64 `json:"id"`
}

if err := web.Post(context.Background(), "https://api.example.com/users", token, payload, &resp); err != nil {
	return err
}

Pre-encoded request body:

body := []byte(`{"name":"alice"}`)
if err := web.PostBytes(context.Background(), "https://api.example.com/users", token, body, &resp); err != nil {
	return err
}

Retrying requests:

if err := web.TryGet(context.Background(), "https://api.example.com/user/1", token, &resp, 3); err != nil {
	return err
}

Use *WithClient helpers when you need a custom timeout, transport, or connection pool:

client := &http.Client{Timeout: 2 * time.Second}
if err := web.GetWithClient(client, context.Background(), "https://api.example.com/user/1", token, &resp); err != nil {
	return err
}

If you want the raw response bytes instead of JSON decoding:

req, _ := http.NewRequest(http.MethodGet, "https://example.com/data", nil)

var raw web.RawBody
if err := web.DoReqWithClient(http.DefaultClient, req, &raw, nil); err != nil {
	return err
}

• web.New(options ...Option) *Application
• route registration:
  • Get, Post, Put, Patch, Delete, Head, Options, Handle
  • GetHTTP, PostHTTP, PutHTTP, PatchHTTP, DeleteHTTP, HeadHTTP, OptionsHTTP, HandleHTTP
• framework composition:
  • Use, Group, SetErrorHandler, RegisterReader, RegisterWriter
  • options: WithMiddleware, WithErrorHandler, WithNotFound, WithMethodNotAllowed, WithCORS
• server lifecycle:
  • ListenAndServe, ListenAndServeTLS, Shutdown
• helpers:
  • ServeFiles, Redirect, TryParse(...), TryXxx(...), JSONErrorHandler, NewCORS
• context (*Ctx) common methods:
  • request: Method, Path, Query, Param, Body, ContentType, BearerToken, RequestID
  • parse: TryParseBody, TryParseJSONBodyFast, TryParseParam, TryParseQuery, TryParseForm
  • response: SetHeader, SetCookie, AllowCredentials, JSON, String, Blob, NoContent, content negotiation via Accept

• Handler return value controls response:
  • (nil, nil) -> 204 No Content
  • (value, nil) -> 200 OK
  • call c.SetStatus(code) to explicitly override the default success status
  • (_, err) -> status code from framework error type, body contains err.Error()
• Response format is selected by request Accept header:
  • application/json
  • application/x-gob
  • application/xml
  • application/octet-stream
  • application/x-avro

• Static, param, and catch-all segments can coexist at the same tree level.
• Match priority is fixed and does not depend on registration order:
  • static > param > catch-all
• Catch-all routes are still only allowed at the end of the path.
• Invalid wildcard combinations remain rejected at registration time.

This makes common REST route sets work without handler-level catch-all dispatch:

app.Get("/organizations/:id/devices/bulk/disable", bulkDisable)
app.Get("/organizations/:id/devices/provision", provision)
app.Get("/organizations/:id/devices/config/rollout", configRollout)
app.Get("/organizations/:id/devices/:device_id", showDevice)

With the routes above:

• GET /organizations/1/devices/provision matches the static route.
• GET /organizations/1/devices/42 matches the param route.
• Registering :device_id before or after provision produces the same result.

• Middleware and route groups are registration-time features:
  • app.Use(...)
  • app.Group("/api", ...)
  • group-local Use(...)
• Built-in middleware is explicit opt-in:
  • RequestID
  • Recover
  • RecoverWithOptions
  • Timeout
  • AccessLog
  • AccessLogWithOptions
  • MaxBodyBytes
  • SecurityHeaders
  • SecurityHeadersWithOptions
  • CORSMiddleware
• Structured API errors are opt-in via SetErrorHandler(JSONErrorHandler(...))
• Automatic OPTIONS CORS responses are opt-in via SetCORS(NewCORS(...))
• Reader/writer overrides are media-type specific and do not affect the default hot path unless registered
• Construction-time options let setup stay declarative without changing request-time cost.
• Existing net/http handlers can be mounted directly with HandleHTTP/GetHTTP.

app := web.New(
	web.WithMiddleware(web.RequestID("", nil), web.Recover(nil)),
	web.WithErrorHandler(web.JSONErrorHandler(true)),
)

api := app.Group("/api", web.Timeout(2*time.Second))
api.Get("/users/:id", func(c *web.Ctx) (any, error) {
	return map[string]string{
		"id":         c.Param("id"),
		"request_id": c.RequestID(),
	}, nil
})

api.GetHTTP("/metrics", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusNoContent)
}))
api.Get("/avatar/:id", func(c *web.Ctx) (any, error) {
	return nil, c.Blob(http.StatusOK, "image/png", []byte{0x89, 'P', 'N', 'G'})
})

For finer control, use the options-based middleware variants:

app.Use(
	web.RecoverWithOptions(web.RecoverOptions{
		DefaultStatus: http.StatusServiceUnavailable,
		DefaultBody:   "UNAVAILABLE",
	}),
	web.AccessLogWithOptions(web.AccessLogOptions{
		Log: func(c *web.Ctx, entry web.AccessLogEntry) {
			// route-aware access logging hook
		},
	}),
)

• Try* retry semantics updated:
  • retry <= 0 now still performs one request attempt.
  • retry loop stops early for ErrUnauthorized, ErrForbidden, and ErrBadRequest (including wrapped).
• TryDo now supports safe body replay across retries (request body is buffered once and recreated per attempt).
• Raw body helpers added:
  • PostBytes, PutBytes, PatchBytes, DoBytes
  • TryPostBytes, TryPutBytes, TryPatchBytes, TryDoBytes
  • default request headers are Content-Type: application/octet-stream and Accept: application/json
• Explicit client helpers added:
  • DoReqWithClient, DoWithClient, DoBytesWithClient
  • wrapper and retry variants for Get/Post/Put/Patch/Delete
  • use these when transport-level performance tuning matters
• Raw response fast path added:
  • DoReq / DoReqWithClient now recognize *web.RawBody
  • existing JSON destinations like []byte and json.RawMessage keep their original JSON semantics
• Ctx.writeBinary and Ctx.writeAvro are implemented:
  • previous behavior for these media types was ErrNotImplemented.
  • now they support fast-path direct writing (see Binary / Avro response section).
• Redirect usage:
  • returning only ErrMovedPermanently does not set Location.
  • use web.Redirect(url, code) to generate proper redirect response headers.
• Header negotiation improvement:
  • Accept/Content-Type values with parameters (e.g. application/json; charset=utf-8) are now parsed correctly.

Migration tips:

• If you relied on retry=0 to skip outbound call, replace with explicit conditional in caller.
• If your handlers used application/octet-stream or application/x-avro, you can now return []byte, io.Reader, or custom marshaler types directly.
• For redirects, migrate to web.Redirect(...) for predictable behavior.

Ctx.writeBinary and Ctx.writeAvro are optimized for fast paths.

• Binary fast-path input types:
  • []byte
  • string
  • *bytes.Buffer
  • io.Reader
  • encoding.BinaryMarshaler
• Avro fast-path input types:
  • web.AvroMarshaler
  • falls back to binary writer for the same input types above

type Event struct {
	Raw []byte
}

func (e Event) MarshalAvro() ([]byte, error) {
	return e.Raw, nil
}

app.Get("/payload", func(c *web.Ctx) (any, error) {
	// Client sends: Accept: application/x-avro
	return Event{Raw: []byte{0xAA, 0xBB}}, nil
})

Use web.Redirect(url, code) to return redirect responses.

app.Get("/old", func(c *web.Ctx) (any, error) {
	return web.Redirect("/new", http.StatusMovedPermanently)
})

TryGet, TryPost, TryPut, TryPatch, TryDelete, TryDo:

• retry <= 0 still performs at least one request.
• retries stop early for non-retriable errors:
  • ErrUnauthorized
  • ErrForbidden
  • ErrBadRequest (including wrapped)
• TryDo safely retries with request body replay (body is cached once and recreated per attempt).

Use TryParseJSONBodyFast when the request body is JSON and unknown-field rejection is not required.

app.Post("/ingest", func(c *web.Ctx) (any, error) {
	var req struct {
		ID int `json:"id"`
	}

	if err := c.TryParseJSONBodyFast(&req); err != nil {
		return nil, err
	}

	return struct {
		Ok bool `json:"ok"`
	}{Ok: true}, nil
})

Use DoReqWithClient with *web.RawBody when you want the response payload without JSON decoding cost.

req, _ := http.NewRequest(http.MethodGet, "https://example.com/data", nil)

var raw web.RawBody
if err := web.DoReqWithClient(client, req, &raw, nil); err != nil {
	panic(err)
}

• Best performance for param/catch-all routing is achieved when params are pooled (already used in Application).
• For binary/avro responses, prefer returning []byte or implementing web.AvroMarshaler to avoid extra encoding overhead.
• TryParseBody currently supports JSON/GOB/XML only.

Thanks to all open-source projects, I’ve learned a lot from them.

Special thanks to：

• httprouter: A high-performance HTTP router that inspired the routing logic in this project.
• web: A lightweight web framework that provided insights into efficient server design.