Documentation
¶
Overview ¶
Package handler provides a base HTTP handler for Gin with binding, validation, error mapping, and pagination helpers.
Role in architecture:
- Adapter: translates HTTP (Gin context) into use-case inputs and maps use-case/domain errors to HTTP responses.
Responsibilities:
- Bind request body, query, and URI parameters by content-type and method.
- Map domain errors (ErrNotFound, ErrUnauthorized) and optional notFoundMessages to standardized JSON responses (response package).
- Normalize pagination parameters and build pagination responses.
- Extract user ID and roles from context set by auth middleware.
This package must NOT:
- Contain business logic; only request/response mapping and validation response formatting.
- Depend on concrete repositories or use cases; it receives errors and data from callers.
Index ¶
- Variables
- type BaseHandler
- func (c *BaseHandler) BuildPaginationResponse(data []interface{}, pageNumber, pageSize int, total int64) response.SimplePaginationResponse
- func (c *BaseHandler) CheckUserHasRole(userRoles []string, requiredRoles []string) bool
- func (c *BaseHandler) GetCurrentUserID(ctx *gin.Context) (string, bool)
- func (c *BaseHandler) GetIDFromParam(ctx *gin.Context, paramName string, serviceCode string) (string, bool)
- func (c *BaseHandler) GetIDFromRequestOrParam(ctx *gin.Context, reqID string, paramName string, serviceCode string) (string, bool)
- func (c *BaseHandler) GetTraceID(ctx *gin.Context) string
- func (c *BaseHandler) HandleServiceError(ctx *gin.Context, serviceCode string, err error, notFoundMessages ...string) bool
- func (c *BaseHandler) HandleValidationError(ctx *gin.Context, serviceCode string, err error)
- func (c *BaseHandler) NormalizePagination(pageNumber, pageSize int) (int, int)
- func (c *BaseHandler) ValidateReqParams(ctx *gin.Context, requestParams interface{}) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = domain.ErrNotFound )
ErrNotFound and ErrUnauthorized re-export domain sentinel errors for backward compatibility. Prefer domain.ErrNotFound and domain.ErrUnauthorized in use cases; handlers may use either with errors.Is.
Functions ¶
This section is empty.
Types ¶
type BaseHandler ¶ added in v0.3.0
type BaseHandler struct {
}
BaseHandler provides shared methods for binding, validation, error handling, and pagination. Embed or use as a struct; no fields required.
func (*BaseHandler) BuildPaginationResponse ¶ added in v0.3.0
func (c *BaseHandler) BuildPaginationResponse(data []interface{}, pageNumber, pageSize int, total int64) response.SimplePaginationResponse
BuildPaginationResponse builds a SimplePaginationResponse from data and pagination state. hasNext is derived from (pageNumber * pageSize) < total; hasPrev is pageNumber > 1.
func (*BaseHandler) CheckUserHasRole ¶ added in v0.3.0
func (c *BaseHandler) CheckUserHasRole(userRoles []string, requiredRoles []string) bool
CheckUserHasRole returns true if any element of userRoles equals any element of requiredRoles.
func (*BaseHandler) GetCurrentUserID ¶ added in v0.3.0
func (c *BaseHandler) GetCurrentUserID(ctx *gin.Context) (string, bool)
GetCurrentUserID returns the "user_id" value from the Gin context (set by auth middleware). Second return is false if missing or not a string.
func (*BaseHandler) GetIDFromParam ¶ added in v0.3.0
func (c *BaseHandler) GetIDFromParam(ctx *gin.Context, paramName string, serviceCode string) (string, bool)
GetIDFromParam returns the URL parameter value for paramName. If empty, writes a 422 validation response and returns ("", false); otherwise returns (id, true).
func (*BaseHandler) GetIDFromRequestOrParam ¶ added in v0.3.0
func (c *BaseHandler) GetIDFromRequestOrParam(ctx *gin.Context, reqID string, paramName string, serviceCode string) (string, bool)
GetIDFromRequestOrParam returns reqID if non-empty; otherwise returns the result of GetIDFromParam.
func (*BaseHandler) GetTraceID ¶ added in v0.3.8
func (c *BaseHandler) GetTraceID(ctx *gin.Context) string
GetTraceID returns the trace ID from the request context (set by RequestID or TraceMiddleware). Empty if not set.
func (*BaseHandler) HandleServiceError ¶ added in v0.3.0
func (c *BaseHandler) HandleServiceError(ctx *gin.Context, serviceCode string, err error, notFoundMessages ...string) bool
HandleServiceError maps err to an HTTP response and writes it. Returns true if a response was written. Checks errors.Is(ErrNotFound) -> 404, errors.Is(ErrUnauthorized) -> 401, then notFoundMessages exact match -> 404, then legacy strings "current password is incorrect" / "Unauthorized" -> 401; otherwise 500.
func (*BaseHandler) HandleValidationError ¶ added in v0.3.0
func (c *BaseHandler) HandleValidationError(ctx *gin.Context, serviceCode string, err error)
HandleValidationError writes a 422 response with Laravel-style field errors using response.ValidationError.
func (*BaseHandler) NormalizePagination ¶ added in v0.3.0
func (c *BaseHandler) NormalizePagination(pageNumber, pageSize int) (int, int)
NormalizePagination clamps pageNumber and pageSize to response.DefaultPageNumber, response.DefaultPageSize, and response.MaxPageSize. Returns the normalized (pageNumber, pageSize).
func (*BaseHandler) ValidateReqParams ¶ added in v0.3.0
func (c *BaseHandler) ValidateReqParams(ctx *gin.Context, requestParams interface{}) error
ValidateReqParams binds the request into requestParams based on Content-Type and method. For application/json uses ShouldBindJSON; for application/xml uses ShouldBindXML; for empty Content-Type binds query and URI params. Returns the first binding error if any.
Source Files