如何使用 Gorilla Mux 正确解析带查询参数的 REST API 请求

本文详解如何用 gorilla mux 精确匹配并提取 url 路径变量与查询参数（如 `?number=10&target=google.com&message=hello`），解决 `formvalue` 丢失部分参数的问题，推荐使用 `.queries()` 链式方法实现强约束、高可读的路由定义。

Gorilla Mux 默认对查询参数（query string）不做强校验，仅通过 r.FormValue("key") 读取时看似简单，但实际中常因 URL 编码、特殊字符（如 &, /, .）或未调用 r.ParseForm() 导致参数解析失败——这正是你只拿到 number 却丢失 target 和 message 的根本原因。

✅ 正确做法：使用 .Queries() 显式声明并校验查询参数
.Queries() 允许你在路由层面定义查询参数的名称与正则模式，Mux 会自动解析并注入 mux.Vars(r)，确保所有参数安全、统一、类型可控地到达处理器：

import (
    "log"
    "net/http"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    // ✅ 推荐：显式声明路径变量 + 查询参数（支持正则约束）
    r.Methods("GET").
        Path("/api/myapiname/{version}").
        Queries(
            "number", `{number:[0-9]+}`,     // 仅匹配数字
            "target", `{target:[^&]+}`,      // 匹配非 & 字符（安全捕获域名/路径）
            "message", `{message:[^&]+}`,    // 同上，避免截断
        ).
        HandlerFunc(apiHandler)

    http.ListenAndServe(":8000", r)
}

func apiHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r) // ✅ 所有参数（path + query）均在此 map 中

    log.Println("Version:", vars["version"])   // e.g. "v1"
    log.Println("Number: ", vars["number"])    // e.g. "10"
    log.Println("Target: ", vars["target"])    // e.g. "google.com"
    log.Println("Message:", vars["message"])   // e.g. "hello"

    w.
Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"ok"}`))
}

? 关键说明：

• vars["number"] 等价于 vars("number")（注意：原答案中 vars("number") 是错误写法，mux.Vars(r) 返回 map[string]string，应使用方括号索引）；
• 正则 {[^&]+} 表示“匹配一个或多个非 & 字符”，可安全处理含 .、/、- 的值（如 example.co.uk 或 api/v2），避免因 & 提前截断；
• 若某查询参数为可选，可改用 Queries("key", "{key:.*}") 并在 handler 中判空；
• 不需手动调用 r.ParseForm() —— .Queries() 已隐式完成解析与验证；
• 错误请求（如 ?number=abc）将被 Mux 自动拒绝（返回 404），提升 API 健壮性。

⚠️ 注意事项：

• 避免混用 r.FormValue() 和 mux.Vars(r) 解析同一参数，易引发逻辑混乱；
• 若需支持复杂嵌套参数（如 ?filter[name]=john&filter[age]=30），建议保留 r.URL.Query() 手动解析，.Queries() 更适合扁平、结构化、强约束的查询字段；
• 生产环境建议配合中间件记录请求路径与参数，便于审计与调试。

总之，.Queries() 不仅解决了你的参数丢失问题，更将路由契约显式化、可测试化——这是构建可靠 Go Web API 的关键实践。