Go http.ServeMux版本化API路径返回404问题排查与解决

问题原因 #

当访问/api/v1/users/login时，主mux匹配到/api/v1/users/前缀后，通过http.StripPrefix("/api/v1/users/", ...)移除前缀，剩余请求路径为login（无开头的/）。但用户子mux中注册的路由均以/开头（如/login），而http.ServeMux仅匹配以/开头的路径，因此login无法匹配/login，最终返回404。

疑问解答 #

1. 为何/api/v1/users/login返回404？

核心原因是路径匹配不兼容：StripPrefix后得到的无开头/的路径，与子mux中带开头/的路由规则不匹配，ServeMux找不到对应处理器，返回404。

2. 能否使用http.NewServeMux()实现此类路由？

完全可以。http.NewServeMux()支持嵌套挂载子mux，只要配置逻辑正确，就能实现版本化+模块化的路由结构。

3. 如何正确配置路由？

提供两种简洁的修正方案，任选其一即可：

方案一：调整主路由挂载逻辑（推荐）

修改主路由的注册路径，确保StripPrefix后生成带开头/的路径：

import "strings"

func SetupRoutes(cfg *handler.Config, version string) http.Handler {
    mux := http.NewServeMux()
    apiPath := "/api/v" + version + "/"

    versionedRoutes := map[string]http.Handler{
        "users":    SetupUserRoutes(cfg), // 移除路径末尾的/
        "workouts": SetupWorkoutRoutes(cfg),
        "sessions": SetupSessionRoutes(cfg),
        "admin":    SetupAdminRoutes(cfg),
    }

    for path, handler := range versionedRoutes {
        basePath := apiPath + path
        // 注册匹配所有以basePath/开头的请求
        mux.Handle(basePath+"/", http.StripPrefix(basePath, handler))
    }

    fmt.Printf("%+v\n", mux)
    return mux
}

此时访问/api/v1/users/login，StripPrefix会移除/api/v1/users，剩余路径为/login，可直接匹配子mux中的/login路由。

方案二：调整子路由路径格式

修改用户子路由的路径，移除开头的/，使其适配StripPrefix后的路径格式：

func SetupUserRoutes(cfg *handler.Config) http.Handler {
    mux := http.NewServeMux()

    userRoutes := map[string]http.HandlerFunc{
        "register": cfg.RegisterUser,
        "login":    cfg.LoginUser,
        "logout":   cfg.LogoutUser,
        "edit":     cfg.EditUser,
        "revoke":   cfg.PostRevoke,
        "refresh":  cfg.PostRefresh,
        "":         cfg.ViewUser, // 匹配/users/根路径
    }

    for path, handler := range userRoutes {
        mux.HandleFunc(path, handler)
    }

    return mux
}

这种方式下，StripPrefix后的login路径可直接匹配子mux中的login路由。

内容的提问来源于stack exchange，提问作者Cheezecake