Migrate from ServeMux
Keep standard handlers. Select path policies to match your existing service.
Replace the constructor
Keep Handle, HandleFunc, and standard handlers. Change the mux constructor:
- mux := http.NewServeMux()
+ mux := rest.NewMux()
mux.HandleFunc("GET /users/{id}", getUser)Continue using r.PathValue, existing middleware, and http.Server configuration.
Choose your path policies
Mino's three path policies default to off. Enable the behavior your service relies on:
| Existing behavior | Mino option |
|---|---|
| Clean repeated slashes and dot segments, then redirect | rest.WithCleanPathRedirect() |
Match escaped path segments, allowing %2F inside parameters | rest.WithEscapedPathMatching() |
Redirect /docs to a registered /docs/ route | rest.WithTrailingSlashRedirect() |
| Set the automatic redirect status | rest.WithRedirectStatus(code) |
For the path behavior of the Go 1.25 service in this example:
mux := rest.NewMux(
rest.WithCleanPathRedirect(),
rest.WithEscapedPathMatching(),
rest.WithTrailingSlashRedirect(),
rest.WithRedirectStatus(http.StatusMovedPermanently),
)Automatic redirects default to 307; one setting applies to both path cleaning and trailing slashes. Go 1.26 changed standard-library trailing-slash redirects to 307. Choose policies using your service's Go version and HTTP tests.
Run the same service
Follow checkout setup, then run one command at a time from examples/:
go run ./migrate -stdlib
go run ./migrate
go run ./migrate -clean-path -escaped-path -trailing-slash -redirect-status=301These select the standard library, Mino defaults, and path policies matching this example. Use -addr=:8081 to change the listen address.
| Request | Mino defaults | Configured Mino |
|---|---|---|
/users/42 | 200, body 42 | 200, body 42 |
/users//42 | 404 | 301 → /users/42 |
/files/a%2Fb | 404 | 200, body a/b |
/docs | 404 | 301 → /docs/ |
Inspect responses without following redirects:
curl -i http://localhost:8080/users//42
curl -i http://localhost:8080/files/a%2Fb
curl -i http://localhost:8080/docsAdapt registration helpers
If a helper accepts a concrete *http.ServeMux, use a local interface containing the methods it needs:
type routeMux interface {
http.Handler
Handle(string, http.Handler)
HandleFunc(string, func(http.ResponseWriter, *http.Request))
}Move global http.Handle / http.HandleFunc registrations onto the new mux instance, then pass it to the server. See the complete migration example.
This guide targets modern ServeMux patterns. Legacy httpmuxgo121=1 behavior and every Go-version-specific edge case are outside this compatibility scope. Keep running your existing HTTP tests during migration.