Documentation
¶
Overview ¶
Package httpx provides gin-kit httpx implementation support.
Index ¶
- Constants
- func BindJSON[T any](c *gin.Context, validators ...*validation.Validator) (T, bool)
- func BindQuery[T any](c *gin.Context, validators ...*validation.Validator) (T, bool)
- func BindURI[T any](c *gin.Context, validators ...*validation.Validator) (T, bool)
- func Created(c *gin.Context, data any)
- func Fail(c *gin.Context, err *Error)
- func Handle(c *gin.Context, mapper Mapper, err error)
- func List(c *gin.Context, data, meta any)
- func Logger(c *gin.Context) *slog.Logger
- func NoContent(c *gin.Context)
- func OK(c *gin.Context, data any)
- type Envelope
- type Error
- type ErrorBody
- type ErrorEnvelope
- type Mapper
Constants ¶
const LoggerKey = "logger"
LoggerKey is the gin context key under which the runtime stores the request-scoped logger.
const RequestIDKey = "request_id"
RequestIDKey is the Gin context key for the request identifier.
const ValidatorKey = "validator"
ValidatorKey is the gin context key under which the runtime stores the application validator, so binders resolve app-registered rules and messages without every call site passing the validator explicitly.
Variables ¶
This section is empty.
Functions ¶
func BindJSON ¶
BindJSON decodes one JSON value, rejects unknown fields and trailing JSON, validates it, and writes a stable error response when it fails.
func BindQuery ¶
BindQuery binds query parameters through `form` struct tags, validates the result, and writes a stable error response when it fails. Parameter values are never echoed back to the client.
func BindURI ¶
BindURI binds path parameters through `uri` struct tags, validates the result, and writes a stable error response when it fails. Give URI fields matching `json` or `form` tags so validation errors use readable names.
Types ¶
type Envelope ¶
type Envelope struct {
// Data is the response payload.
Data any `json:"data"`
// Meta contains optional pagination or response metadata.
Meta any `json:"meta,omitempty"`
}
Envelope is the canonical successful JSON response shape.
type Error ¶
type Error struct {
// Status is the HTTP status code written to the response.
Status int
// Code is the stable application error code.
Code string
// Message is safe to serialize to clients.
Message string
// Details carries optional safe structured data.
Details any
// Cause retains the original internal error for logging and errors.Is checks.
Cause error
}
Error is a public HTTP error. Cause is retained for logging and never serialized.
func DefaultMapper ¶
DefaultMapper preserves public and validation errors; every other error becomes a generic internal_error without exposing its cause.
func ValidationError ¶
func ValidationError(failures *validation.Errors) *Error
ValidationError converts structured validation failures into the canonical 422 validation_failed response.
type ErrorBody ¶
type ErrorBody struct {
// Code is the stable, machine-readable error code.
Code string `json:"code"`
// Message is the safe human-readable error message.
Message string `json:"message"`
// Details optionally carries safe structured error details.
Details any `json:"details,omitempty"`
// RequestID correlates the response with structured server logs.
RequestID string `json:"request_id,omitempty"`
}
ErrorBody contains the serializable portion of one failed response.
type ErrorEnvelope ¶
type ErrorEnvelope struct {
// Error contains the safe public error details.
Error ErrorBody `json:"error"`
}
ErrorEnvelope is the canonical failed JSON response shape.
Source Files