handlers

Handlers Package Documentation

The handlers package provides reusable request-processing components for common backend workflows such as:

• querying databases
• executing DML operations
• external API calls
• pagination
• recovery handling
• request consumption pipelines

The package is designed around composable handler logic that can be integrated with the broader requestCore ecosystem.

---

Overview

The handlers package acts as an orchestration layer between:

• request context handling
• query execution
• request lifecycle management
• response generation
• external service communication

It provides reusable building blocks to reduce repetitive endpoint and service logic.

---

Package Structure

handlers/
├── baseHandler.go
├── callApi.go
├── consumeHandler.go
├── dmlHandler.go
├── ormQueryHandler.go
├── pagination.go
├── queryHandler.go
├── recovery.go
└── *_test.go

---

Core Concepts

The handlers package follows several architectural principles:

• reusable request-processing pipelines
• separation of query/DML concerns
• framework-independent business flow handling
• composable handler utilities
• centralized error and recovery behavior
• testing-friendly abstractions

---

Handlers

Base Handler

File:

handlers/baseHandler.go

The base handler provides common functionality shared across specialized handlers.

Typical responsibilities may include:

• request initialization
• context preparation
• validation flow integration
• shared response handling
• standardized execution behavior
• common logging/tracing hooks

This acts as the foundation for other handler implementations.

---

Query Handler

File:

handlers/queryHandler.go

The query handler is responsible for read-oriented operations.

Typical use cases:

• SELECT queries
• fetching paginated data
• filtering/search operations
• response mapping
• query execution orchestration

This handler integrates with the query layer provided by:

libQuery

and may use ORM or direct query execution depending on the implementation.

---

ORM Query Handler

File:

handlers/ormQueryHandler.go

The ORM query handler provides query execution behavior specifically tailored for ORM-backed flows.

Typical responsibilities:

• ORM query execution
• model-based retrieval
• entity mapping
• ORM abstraction integration
• repository-style operations

This handler is useful when the application prefers ORM-based data access instead of raw SQL execution.

---

DML Handler

File:

handlers/dmlHandler.go

The DML handler manages write-oriented database operations.

Typical operations include:

• INSERT
• UPDATE
• DELETE
• transactional workflows
• persistence orchestration

This handler centralizes mutation logic and promotes consistency across write operations.

---

Call API Handler

File:

handlers/callApi.go

The API call handler manages outbound HTTP/API interactions.

Typical responsibilities:

• calling external services
• handling authentication flows
• request serialization
• response parsing
• retry/error handling integration
• multi-service orchestration

This handler works alongside:

libCallApi

to standardize external communication behavior.

---

Consume Handler

File:

handlers/consumeHandler.go

The consume handler is intended for request or event consumption workflows.

Possible use cases:

• async processing
• event/message consumption
• queue-driven workflows
• background task handling
• request replay flows

This handler helps encapsulate consumption-oriented execution patterns.

---

Pagination Utilities

File:

handlers/pagination.go

Pagination utilities provide reusable pagination behavior for query endpoints.

Typical capabilities:

• page-based pagination
• offset/limit handling
• response metadata generation
• pagination validation
• standardized paging responses

Useful for:

• REST APIs
• admin panels
• search endpoints
• reporting APIs

---

Recovery Handler

File:

handlers/recovery.go

Recovery utilities provide panic/error recovery behavior for safer request execution.

Typical responsibilities:

• panic recovery
• structured error conversion
• centralized failure handling
• logging unexpected failures
• preventing application crashes from request-level errors

This improves resiliency and operational stability.

---

Architectural Role

The handlers package sits between:

Transport Layer
    ↓
Context Initialization
    ↓
Handlers
    ↓
Query / Request / Response Layers
    ↓
Database / External Services

This creates a reusable execution pipeline that keeps endpoint logic thin and consistent.

---

Integration with requestCore

Handlers integrate closely with:

Package	Purpose
libContext	unified request context
libQuery	DB/query execution
libRequest	request lifecycle
response	standardized responses
libCallApi	external API communication
libTracing	observability/tracing
libLogger	structured logging

---

Typical Request Flow

A typical flow using handlers may look like:

Incoming Request
    ↓
Framework Adapter (Gin/Fiber/nethttp)
    ↓
libContext Initialization
    ↓
Handler Execution
    ↓
Query/DML/API Logic
    ↓
Response Generation

---

Observability

Handlers are designed to work with the repository’s observability stack:

• OpenTelemetry tracing
• structured logging
• request-scoped metadata
• framework-aware context propagation

This allows consistent visibility across request pipelines.

---

Testing

The handlers package includes test coverage through files such as:

baseHanlder_test.go
callApi_test.go
consumeHandler_test.go
dmlHandler_test.go
queryHandler_test.go

This indicates handlers are designed for isolated testing and reusable execution flows.

---

Recommended Usage Patterns

Keep handlers orchestration-focused

Handlers should primarily:

• coordinate flows
• validate execution paths
• call lower-level services
• standardize responses

Avoid embedding heavy business logic directly in handlers.

---

Use specialized handlers

Prefer:

• QueryHandler for reads
• DMLHandler for writes
• CallApiHandler for external communication

instead of combining unrelated concerns.

---

Keep business logic independent

Business logic should remain in:

• services
• domain modules
• repositories

while handlers remain execution coordinators.

---

Suggested Future Enhancements

Potential improvements for the handlers package:

• middleware chaining support
• generic handler pipelines
• transactional scopes
• retry policies
• circuit breaker integration
• async workflow helpers
• event-driven handler abstractions
• CQRS-oriented handler separation

---

Summary

The handlers package provides reusable orchestration components for:

• query execution
• DML operations
• external API communication
• pagination
• recovery
• request consumption flows

It serves as a reusable execution layer that helps standardize backend request processing while remaining framework-independent and observability-friendly.