reqx

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package reqx 为基于 net/http 的 JSON API 提供输入侧能力。

它只覆盖 request 边界：

  • 单字段 path/query helper：Path、Query
  • DTO binder：BindQuery、BindBody
  • 请求级显式规则：InvalidRequest
  • request-side field error 公开模型：FieldError、FieldErrorCode、FieldErrorIn、Code*、In*

reqx 是请求输入侧的较低层原生面。 对多数 handler 调用方，优先直接使用根包 hah；reqx 主要服务于：

  • 拆分 request-side 组件
  • 直接依赖输入层公开契约
  • 需要显式引用 request-side FieldError / Code* / In* 的场景

Path / Query 是请求侧主路径。它们暴露两个 source root：

  • PathParam
  • QueryParam

root 之后的公开 builder family 收敛为：

  • StringParam
  • ValueParam[T]
  • OrderedParam[T]
  • TimeParam
  • MultiParam[T]

这组 builder family 已视为核心公开面，应保持收敛，不轻易继续扩展新的 family、 source root 或隐式 binding 模式。

具体行为以 docs 设计文档为准：

  • docs/path-design.md
  • docs/query-design.md
  • docs/binding-query-design.md
  • docs/binding-body-design.md
  • docs/public-api-scope.md

Index

Constants

View Source 
const (
	CodeInvalidJSON          = "invalid_json"
	CodeUnsupportedMediaType = "unsupported_media_type"
	CodeRequestTooLarge      = "request_too_large"
)
View Source 
const (
	CodeInvalid  = errx.CodeInvalid
	CodeRequired = errx.CodeRequired
	CodeUnknown  = errx.CodeUnknown
	CodeType     = errx.CodeType
	CodeMultiple = errx.CodeMultiple
)
View Source 
const (
	InBody   = errx.InBody
	InQuery  = errx.InQuery
	InPath   = errx.InPath
	InHeader = errx.InHeader
)

Variables

This section is empty.

Functions

func BindBody added in v0.2.0 

func BindBody(r *http.Request, target any) error

零字节 body 直接 no-op；非空 body 则按 JSON object 输入模型处理， 全部成功后再一次性提交到零值临时对象对应的 target。

func BindQuery added in v0.5.0 

func BindQuery(r *http.Request, target any) error

BindQuery 只从 query 参数绑定数据。

func InvalidRequest added in v0.1.1 

func InvalidRequest(fieldErrors ...FieldError) error

InvalidRequest 生成统一的 invalid_request 错误包络。

Types

type FieldError added in v0.8.5 

type FieldError = errx.FieldError

FieldError 描述单个公开字段错误。

type FieldErrorCode added in v0.8.5 

type FieldErrorCode = errx.FieldErrorCode

FieldErrorCode 描述公开字段错误码。

type FieldErrorIn added in v0.8.5 

type FieldErrorIn = errx.FieldErrorIn

FieldErrorIn 描述公开字段错误来源。

type MultiParam added in v0.6.0 

type MultiParam[T any] struct {
	// contains filtered or unexported fields
}

MultiParam 读取并校验多值参数。

func (*MultiParam[T]) Check added in v0.6.0 

func (p *MultiParam[T]) Check(check func([]T) error) *MultiParam[T]

func (*MultiParam[T]) Default added in v0.6.0 

func (p *MultiParam[T]) Default(value []T) *MultiParam[T]

func (*MultiParam[T]) Get added in v0.6.0 

func (p *MultiParam[T]) Get() ([]T, error)

func (*MultiParam[T]) Required added in v0.6.0 

func (p *MultiParam[T]) Required() *MultiParam[T]

type OrderedParam added in v0.6.0 

type OrderedParam[T cmp.Ordered] struct {
	// contains filtered or unexported fields
}

OrderedParam 读取并校验可比较范围的单值参数。

func (*OrderedParam[T]) Check added in v0.6.0 

func (p *OrderedParam[T]) Check(check func(T) error) *OrderedParam[T]

func (*OrderedParam[T]) Default added in v0.6.0 

func (p *OrderedParam[T]) Default(value T) *OrderedParam[T]

func (*OrderedParam[T]) Get added in v0.6.0 

func (p *OrderedParam[T]) Get() (T, error)

func (*OrderedParam[T]) Max added in v0.6.0 

func (p *OrderedParam[T]) Max(value T) *OrderedParam[T]

func (*OrderedParam[T]) Min added in v0.6.0 

func (p *OrderedParam[T]) Min(value T) *OrderedParam[T]

func (*OrderedParam[T]) Required added in v0.6.0 

func (p *OrderedParam[T]) Required() *OrderedParam[T]

type PathParam added in v0.4.0 

type PathParam struct {
	// contains filtered or unexported fields
}

PathParam 表示一个待解析的 path 单参数。

func Path added in v0.4.1 

func Path(r *http.Request, name string) *PathParam

Path 创建 path 单参数读取与校验 builder。

func (*PathParam) Int added in v0.4.2 

func (p *PathParam) Int() *OrderedParam[int]

Int 读取 int 参数。

func (*PathParam) Int64 added in v0.4.2 

func (p *PathParam) Int64() *OrderedParam[int64]

Int64 读取 int64 参数。

func (*PathParam) String added in v0.4.2 

func (p *PathParam) String() *StringParam

String 读取 string 参数。

func (*PathParam) UUID added in v0.4.2 

func (p *PathParam) UUID() *ValueParam[uuid.UUID]

UUID 读取 uuid.UUID 参数。

func (*PathParam) Uint added in v0.4.2 

func (p *PathParam) Uint() *OrderedParam[uint]

Uint 读取 uint 参数。

func (*PathParam) Uint64 added in v0.4.2 

func (p *PathParam) Uint64() *OrderedParam[uint64]

Uint64 读取 uint64 参数。

type QueryParam added in v0.4.0 

type QueryParam struct {
	// contains filtered or unexported fields
}

QueryParam 表示一个待解析的 query 单参数。

func Query added in v0.4.1 

func Query(r *http.Request, name string) *QueryParam

Query 创建 query 单参数读取与校验 builder。

func (*QueryParam) Bool added in v0.4.2 

func (p *QueryParam) Bool() *ValueParam[bool]

Bool 读取 bool 参数。

func (*QueryParam) Duration added in v0.4.2 

func (p *QueryParam) Duration() *OrderedParam[time.Duration]

Duration 读取 time.Duration 参数。

func (*QueryParam) Float64 added in v0.4.2 

func (p *QueryParam) Float64() *OrderedParam[float64]

Float64 读取 float64 参数。

func (*QueryParam) Int added in v0.4.2 

func (p *QueryParam) Int() *OrderedParam[int]

Int 读取 int 参数。

func (*QueryParam) Int64 added in v0.4.2 

func (p *QueryParam) Int64() *OrderedParam[int64]

Int64 读取 int64 参数。

func (*QueryParam) String added in v0.4.2 

func (p *QueryParam) String() *StringParam

String 读取 string 参数。

func (*QueryParam) Time added in v0.4.2 

func (p *QueryParam) Time() *TimeParam

Time 按严格 RFC3339 读取 time.Time 参数。

func (*QueryParam) UUID added in v0.4.2 

func (p *QueryParam) UUID() *ValueParam[uuid.UUID]

UUID 读取 uuid.UUID 参数。

func (*QueryParam) Uint added in v0.4.2 

func (p *QueryParam) Uint() *OrderedParam[uint]

Uint 读取 uint 参数。

func (*QueryParam) Uint64 added in v0.4.2 

func (p *QueryParam) Uint64() *OrderedParam[uint64]

Uint64 读取 uint64 参数。

func (*QueryParam) UnixTime added in v0.4.2 

func (p *QueryParam) UnixTime() *TimeParam

UnixTime 按恰好 10 个十进制数字的秒级 Unix 时间戳读取 time.Time 参数。

func (*QueryParam) Values added in v0.4.2 

func (p *QueryParam) Values() *MultiParam[string]

Values 读取 query 参数的全部解析后值。

type StringParam added in v0.4.1 

type StringParam struct {
	// contains filtered or unexported fields
}

StringParam 读取并校验 string 参数。

func (*StringParam) Check added in v0.4.1 

func (p *StringParam) Check(check func(string) error) *StringParam

func (*StringParam) Default added in v0.4.1 

func (p *StringParam) Default(value string) *StringParam

func (*StringParam) Get added in v0.4.1 

func (p *StringParam) Get() (string, error)

func (*StringParam) Match added in v0.4.1 

func (p *StringParam) Match(pattern *regexp.Regexp) *StringParam

func (*StringParam) MaxLen added in v0.4.1 

func (p *StringParam) MaxLen(n int) *StringParam

func (*StringParam) MinLen added in v0.4.1 

func (p *StringParam) MinLen(n int) *StringParam

func (*StringParam) OneOf added in v0.4.1 

func (p *StringParam) OneOf(values ...string) *StringParam

func (*StringParam) Required added in v0.4.1 

func (p *StringParam) Required() *StringParam

type TimeParam added in v0.4.1 

type TimeParam struct {
	// contains filtered or unexported fields
}

TimeParam 读取并校验 time.Time 参数。

func (*TimeParam) After added in v0.4.1 

func (p *TimeParam) After(value time.Time) *TimeParam

func (*TimeParam) Before added in v0.4.1 

func (p *TimeParam) Before(value time.Time) *TimeParam

func (*TimeParam) Check added in v0.4.1 

func (p *TimeParam) Check(check func(time.Time) error) *TimeParam

func (*TimeParam) Default added in v0.4.1 

func (p *TimeParam) Default(value time.Time) *TimeParam

func (*TimeParam) Get added in v0.4.1 

func (p *TimeParam) Get() (time.Time, error)

func (*TimeParam) Required added in v0.4.1 

func (p *TimeParam) Required() *TimeParam

type ValueParam added in v0.6.0 

type ValueParam[T any] struct {
	// contains filtered or unexported fields
}

ValueParam 读取并校验通用单值参数。

func (*ValueParam[T]) Check added in v0.6.0 

func (p *ValueParam[T]) Check(check func(T) error) *ValueParam[T]

func (*ValueParam[T]) Default added in v0.6.0 

func (p *ValueParam[T]) Default(value T) *ValueParam[T]

func (*ValueParam[T]) Get added in v0.6.0 

func (p *ValueParam[T]) Get() (T, error)

func (*ValueParam[T]) Required added in v0.6.0 

func (p *ValueParam[T]) Required() *ValueParam[T]

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.