go-common

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

1. Import the Framework

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

1. 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

Validator

Request validation with custom validation rules and integration with validator/v10.

• Features:
  • Struct validation
  • Custom validation rules
  • Field-level validation
  • Integration with web frameworks
  • Detailed error messages

JWT

JWT token creation and validation with support for multiple signing algorithms.

• Features:
  • HS256 (HMAC) signing
  • RS256 (RSA) signing
  • Custom claims support
  • Token validation and parsing
  • Context-aware operations

Package Index

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License.