Skip to Content
Mino

Progressive adoption

From a standalone utility to an HTTP service, reusing your code at every step.

简体中文 ↗

Start with a utility

Import core/jsonx for JSON conveniences, or core/errorx for wrapping and aggregating errors that retain errors.Is / errors.As support. Neither needs a router or a Mino application.

data, err := jsonx.MarshalToString(map[string]string{"hello": "Go"})
if err != nil {
	return err
}
fmt.Println(data) // {"hello":"Go"}

Add binding and validation

httpx works with the standard library router. A handler can bind parameters, validate input, return errors, and write JSON while keeping the standard signature:

type userRequest struct {
	ID      int  `path:"id" json:"-"`
	Verbose bool `query:"verbose" json:"-"`
}

func (in *userRequest) Validate() error {
	if in.ID <= 0 {
		return httpx.Errorf(http.StatusBadRequest, "id must be positive")
	}
	return nil
}

func getUser(w http.ResponseWriter, r *http.Request) {
	var in userRequest
	if err := httpx.Parse(r, &in); err != nil {
		httpx.Err(w, r, err)
		return
	}
	httpx.OkJSONCtx(r.Context(), w, map[string]any{
		"id": in.ID, "verbose": in.Verbose,
	})
}

Register it with net/http:

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", getUser)

GET /users/42?verbose=true returns {"id":42,"verbose":true}. An invalid ID returns 400. Parse binds present values in JSON → form → query → header → path order, then calls Validate() error if implemented. Missing inputs keep defaults; later sources override earlier ones. Use json:"-" for fields reserved for other sources.

JSON bodies default to an 8 MiB limit, adjustable per call with httpx.WithMaxJSONBody. ParseJSON, ParseQuery, ParseHeader, ParsePath, and ParseForm are also available individually.

Add routing and groups

Keep the same getUser handler, and change the registration:

mux := rest.NewMux()
api := mux.Route("/api")
api.Get("/users/{id}", getUser)

Mino exposes parameters through r.PathValue. Its mux is an http.Handler, so http.Server, httptest, and standard middleware work directly. Routing includes method matching, HEAD fallback to GET, 404/405 handling, host-specific routes, route inspection, and optional path/redirect policies.

Compose middleware and existing components

func requestHeader(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("X-Service", "mino")
		next.ServeHTTP(w, r)
	})
}

Apply it with mux.Use(requestHeader), scope it to selected registrations with mux.With(requestHeader).Get(...), or use the immutable chain package on any existing handler:

handler := chain.New(requestHeader).Then(existingHandler)

Mount another router or handler with mux.Mount("/legacy", existingHandler); Mino strips the mount prefix before delegating. Keep your existing components and choose when to adopt more.

See the runnable progressive example: cd examples && go run ./progressive, then request /api/users/42?verbose=true.

Configure routes and middleware before serving. Optional jsonx.SetCodec and httpx.SetErrorHandler configure process-wide defaults at startup, before concurrent use. JSON defaults to encoding/json; error responses hide internal server details, and failure logging uses standard log/slog.

Before running the checked-in example, follow checkout setup. See packages and defaults for limits and configuration.

On this page