跳转到正文
Mino

httpx · 请求与响应

绑定请求、验证输入、返回 JSON 与处理 HTTP 错误。

Read in English ↗

配合任意标准 HTTP handler 使用。本例直接接入 http.ServeMux。

绑定、验证与响应

main.go
package main

import (
	"log"
	"net/http"

	"github.com/hainuoli/mino/rest/httpx"
)

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 main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", getUser)
	log.Fatal(http.ListenAndServe(":8080", mux))
}

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,
	})
}

完整示例 · cd examples && go run ./packages/httpx

curl 'http://localhost:8080/users/42?verbose=true'
{"id":42,"verbose":true}

Parse 在绑定后调用目标的 Validate() error。本例中,非正数 ID 返回 400。

选择输入来源

Parse 按 JSON → form → query → header → path 绑定,最后验证。存在的后续输入覆盖之前的值;缺失输入保留默认值。

来源tag 示例单独解析
JSONjson:"name"ParseJSON
表单form:"name"ParseForm
Queryquery:"page"ParseQuery
Headerheader:"X-Request-ID"ParseHeader
路径path:"id"ParsePath

单独解析不会执行验证。非结构体目标(如 map、切片)仅接收 JSON。专属于其他来源的字段应加 json:"-",避免被 JSON 绑定。

解析 JSON 与限制体积

func createUser(w http.ResponseWriter, r *http.Request) {
	var in struct {
		Name string `json:"name"`
	}
	if err := httpx.ParseJSON(r, &in, httpx.WithMaxJSONBody(1<<20)); err != nil {
		httpx.Err(w, r, err)
		return
	}
	httpx.JSON(w, http.StatusCreated, in)
}

本例将上限设为 1 MiB。默认上限为 8 MiB,选项仅作用于本次调用。Parse 根据 application/json 或 +json 选择 JSON;ParseJSON 不检查 Content-Type。

允许空 body,解析不关闭 body;失败时目标可能已被部分填充。表单沿用 net/http 的解析和限制;multipart 数据需先单独解析。

返回响应

调用响应
Ok(w)200,无正文
OkJSON(w, value)200,JSON
JSON(w, status, value)指定状态码的 JSON
OkJSONCtx(ctx, w, value)200,关联上下文记录失败日志
JSONCtx(ctx, w, status, value)指定状态码,关联上下文记录失败日志

JSON 输出不添加业务信封。编码失败返回固定的 JSON 500,写入失败通过 log/slog 记录;204、205、304 不写正文。

返回 HTTP 错误

httpx.Err(w, r, httpx.Errorf(http.StatusNotFound, "user %d not found", id))
错误默认响应
普通绑定或验证错误400
可识别的请求体超限413
context.Canceled499,无正文
Errorf / StatusCoder对应的 400–599 状态码
其他错误500,隐藏内部细节

Err 在提交响应前调用,传入有效请求;nil 错误不作处理。4xx 消息应适合直接公开,5xx 默认显示 internal error。包装后的状态错误仍可识别。

自定义错误映射

var ErrUserNotFound = errors.New("user not found")

func configureErrors() {
	httpx.SetErrorHandler(func(r *http.Request, err error) (int, any) {
		if errors.Is(err, ErrUserNotFound) {
			return http.StatusNotFound, map[string]string{
				"message": "user not found",
			}
		}
		return httpx.DefaultErrorHandler(r, err)
	})
}

在启动阶段设置,作用于进程内所有 Err 调用。映射器须支持并发调用;返回 nil body 时仅写状态码。SetErrorHandler(nil) 恢复默认映射。

API · 包与默认行为

本页目录