Go http.Request.ParseForm 怎样区分查询参数与表单参数

在 Go 的 HTTP 处理器里，想同时读取 URL 查询参数和 POST 表单参数，关键不是直接调用 FormValue，而是先理解 Request.ParseForm() 写入的两个集合：r.Form 保存合并后的参数，r.PostForm 只保存 POST、PUT、PATCH 请求体中的表单参数。请求体与查询串出现同名键时，r.Form 中请求体参数优先。

官方文档：https://pkg.go.dev/net/http#Request.ParseForm

需要区分参数来源时显式调用 ParseForm，再分别查看 r.Form 和 r.PostForm；只想取一个值且不关心解析错误时，才考虑 FormValue 或 PostFormValue。

• 查询参数：所有请求都会解析 URL 的 RawQuery，并写入 r.Form。
• 表单请求体：POST、PUT、PATCH 且 Content-Type 为 application/x-www-form-urlencoded 时，内容进入 r.PostForm 和 r.Form。
• 同名键：r.Form 先保留请求体值，再追加查询串值；读取单值时要明确你的业务优先级。

先看清两个参数集合的职责

ParseForm 的结果可以用“来源”和“用途”来记。r.PostForm 是请求体视角，只适合回答“用户在表单体里提交了什么”；r.Form 是合并视角，既包括 URL 查询串，也包括符合条件的表单体。

例如请求为 /search?tag=url&page=2，请求体为 tag=body&name=go。解析后，r.PostForm["tag"] 只有 body，而 r.Form["tag"] 同时包含请求体和查询串的值。不要把 r.Form 误认为“只来自 URL”，也不要从它推断参数的原始来源。

用 ParseForm 显式读取重复键

当一个键可能出现多次时，直接取字符串会丢失信息。url.Values 的值类型是 []string，应先调用 ParseForm，再根据参数来源选集合，并检查错误。

func searchHandler(w http.ResponseWriter, r *http.Request) {
    // 显式解析，保留查询参数与表单体的来源信息。
    if err := r.ParseForm(); err != nil {
        http.Error(w, "表单解析失败", http.StatusBadRequest)
        return
    }

    // PostForm 只看请求体；Form 是合并后的视图，重复键要保留全部值。
    bodyTags := r.PostForm["tag"]
    allTags := r.Form["tag"]
    if len(bodyTags) == 0 && len(allTags) == 0 {
        http.Error(w, "缺少 tag 参数", http.StatusBadRequest)
        return
    }

    // 业务若优先采用请求体，就先读 PostForm，再决定是否回退到查询串。
    chosen := bodyTags
    if len(chosen) == 0 {
        chosen = r.URL.Query()["tag"]
    }
    fmt.Fprintf(w, "body=%v all=%v chosen=%v", bodyTags, allTags, chosen)
}

示例中的 chosen 明确表达了业务策略：只要请求体提供了 tag，就不把查询串的同名值混进最终选择。若业务允许两类来源合并，则可以遍历 r.Form["tag"]，但应在文档中说明顺序。

代码需要导入 fmt、net/http。这里没有把 ParseForm 的错误吞掉，因为非法查询转义、读取请求体失败等问题都可能影响参数可信度。重复键也不要只取 values[0] 后假装它是唯一值。

方法和 Content-Type 会改变读取范围

官方实现只对 POST、PUT、PATCH 尝试读取表单请求体；其他方法的请求体不会因为调用 ParseForm 就自动变成 r.PostForm。同时，Content-Type 不是 application/x-www-form-urlencoded 时，r.PostForm 会被初始化为空集合，正文不会按这种表单格式读取。

这也是“明明传了 body，ParseForm 却读不到”的常见原因。JSON 请求应使用 JSON 解码器，multipart 表单应按文件上传流程调用 ParseMultipartForm 或使用 MultipartReader，不要强行把它们当作 URL 编码表单。

未提前限制请求体时，Go 文档说明表单体读取上限为 10 MB。面向公网的服务应在进入业务解析前根据接口约束使用 http.MaxBytesReader，再调用 ParseForm；这样限制的是请求体资源，而不是靠业务层事后判断字符串长度。

func limitedFormHandler(w http.ResponseWriter, r *http.Request) {
    // 先限制请求体，避免把不受控的大正文交给表单解析。
    r.Body = http.MaxBytesReader(w, r.Body, 1

上限的具体数值应由接口契约决定。若请求是 multipart 文件上传，不能套用这个片段替代文件大小策略；应同时设计文件部件的内存与临时文件边界。

什么时候不用 FormValue

FormValue 会在需要时自动调用表单解析，并忽略解析错误；它适合简单的单值读取，但不适合必须区分来源、检查重复值或记录坏输入的接口。PostFormValue 只看 POST、PUT、PATCH 请求体，查询参数会被忽略，同样会忽略解析错误。

常见问题

GET 请求的查询参数会进入 r.PostForm 吗？

不会。查询串会进入 r.Form；r.PostForm 只面向 POST、PUT、PATCH 的表单请求体。

同名键在 r.Form 里取哪个值？

表单请求体值优先于 URL 查询值。若要表达更明确的业务规则，直接查看 r.PostForm 与 r.URL.Query()，不要只依赖一个字符串读取方法。

ParseForm 可以调用多次吗？

可以。官方文档将它定义为幂等操作；但重复调用不能改变已经确定的来源规则，也不能把 JSON 或 multipart 自动转换成普通表单。

记住一句话：r.PostForm 用来确认请求体，r.Form 用来查看合并结果，r.URL.Query() 用来单独确认查询串。需要可靠排错时，显式解析、检查错误，并保留重复键，而不是让便捷方法替你隐藏边界。