Common Backend Framework

Welcome to the Common Backend Framework repository! This project provides a collection of utilities, libraries, and frameworks designed to standardize and streamline the development of backend API services within our organization.

Gitbook: https://kittipat1413.gitbook.io/go-common
Go Documentation: https://pkg.go.dev/github.com/kittipat1413/go-common
Github Repo: https://github.com/kittipat1413/go-common

Introduction

This repository serves as a central codebase for common functionalities and utilities used across various backend API projects. By consolidating shared code, we aim to:

Promote consistency and code standardization.
Reduce duplication of effort.
Facilitate easier maintenance and updates.
Accelerate development by providing ready-to-use components.

Installation

Include the framework in your project by adding it to your go.mod file:

go get github.com/kittipat1413/go-common

Getting Started

Import the Framework

import (
    "github.com/kittipat1413/go-common/framework/logger"
    "github.com/kittipat1413/go-common/framework/trace"
    // ... other imports
)

Initialize Components Set up the components you need, such as the logger and tracer, in your application's entry point.

func main() {
    // Initialize the logger
    logger := logger.NewDefaultLogger()

    // Initialize the tracer
    endpoint := "localhost:4317"
    tracerProvider, err := trace.InitTracerProvider(ctx, "my-service", &endpoint, trace.ExporterGRPC)
    if err != nil {
      // Handle error
      return
    }
    defer func() {
      if err := tracerProvider.Shutdown(ctx); err != nil {
        // Handle error
      }
    }()

    // ... rest of your application setup
}

Example Project

Looking for a real-world implementation?

Check out the 🎟️ Ticket Reservation System, a clean-architecture-based backend service that demonstrates how to integrate and use the go-common framework across all layers — config, logging, tracing, error handling, HTTP handlers, use cases, and repositories.

Modules and Packages

Cache

Provides a unified caching interface with multiple backend implementations for high-performance data access.

LocalCache - In-memory caching with TTL support and automatic cleanup
Features:
- Generic type-safe interface
- Thread-safe operations
- Configurable TTL and cleanup intervals
- Context-aware operations

Config

Manages application configuration with support for multiple sources and context propagation.

Features:
- Environment variable loading
- YAML/JSON configuration files
- Type-safe configuration access
- Context-based configuration retrieval

Errors

Standardizes error handling and response formatting with categorized error types.

Features:
- Predefined error categories (authentication, bad request, internal server, etc.)
- Consistent error formatting and wrapping
- Error codes and messages
- HTTP status code mapping
- Error response generation for APIs

Lock Manager

Unified distributed locking interface for coordinating access to shared resources.

LocalLock - In-memory locks for single-instance applications
Redsync - Redis-based distributed locks for multi-instance deployments
Features:
- Consistent locking API across implementations
- Configurable lock TTL and retry policies
- Context support with cancellation
- Custom token generation

Logger

Structured, context-aware logging built on logrus for production-ready applications.

Features:
- Configurable log levels (DEBUG, INFO, WARN, ERROR, FATAL)
- Structured JSON logging
- Context propagation for tracing (trace_id, span_id)
- Flexible output destinations
- Custom formatters support
- No-op logger for testing

Middleware

Collection of HTTP middleware for common web application concerns.

Gin Middleware - Ready-to-use middleware for Gin framework
Features:
- Request logging
- Error handling
- Recovery from panics
- Request ID generation

Retry

Flexible retry mechanism with multiple backoff strategies for resilient operations.

Features:
- Exponential backoff
- Linear backoff
- Configurable retry policies
- Context-aware execution
- Custom retry conditions

Server Utils

Server lifecycle utilities for graceful startup and shutdown.

Features:
- Graceful shutdown handling
- Signal handling (SIGTERM, SIGINT)
- Configurable shutdown timeout
- Multiple server support

SFTP

Production-ready SFTP client with connection pooling and advanced file transfer capabilities.

Features:
- Connection pooling with automatic management
- Password and private key authentication
- Upload/Download with progress tracking
- Smart overwrite policies
- Automatic retry with exponential backoff
- Directory operations (create, list, remove)

Trace

Distributed tracing implementation using OpenTelemetry for observability.

Features:
- OpenTelemetry integration
- Span creation and context propagation
- Multiple exporter support (GRPC, HTTP)
- Minimal performance overhead
- Trace function utilities