Golang Microservice Template with Gin

A production-ready microservice template built with Golang and Gin framework, converted from a FastAPI template. This template implements clean architecture principles, comprehensive security features, and modern Go best practices.

🚀 Features

Core Features

• Clean Architecture: Separation of concerns with clear layers (handlers → services → repositories → models)
• RESTful API: Built with Gin framework for high performance
• PostgreSQL Database: GORM ORM with connection pooling and migrations
• Redis Caching: Distributed caching with connection pooling
• JWT Authentication: Secure authentication with device tracking and multi-device support
• Structured Logging: Zap logger with context propagation and log rotation

Security Features

• Rate Limiting: Configurable per-minute and per-hour limits
• Attack Detection: SQL injection, XSS, and path traversal detection
• IP Filtering: IP whitelist/blacklist with automatic blocking
• User Agent Filtering: Bot and suspicious client detection
• Password Hashing: Bcrypt with configurable cost
• Device Fingerprinting: Unique device identification and tracking

Developer Experience

• Environment-based Configuration: Viper for flexible config management
• Dependency Injection: Constructor-based DI for testability
• Generic Base Repository: Type-safe CRUD operations with Go generics
• Comprehensive Error Handling: Custom error types with HTTP status codes
• Docker Support: Multi-stage builds and docker-compose setup
• Makefile: Common development tasks automated

📁 Project Structure

golang-microservice-template/
├── cmd/
│   └── server/
│       └── main.go                    # Application entry point
├── internal/                          # Private application code
│   ├── api/
│   │   ├── handlers/                  # HTTP handlers (controllers)
│   │   ├── middleware/                # HTTP middleware
│   │   ├── routes/                    # Route definitions
│   │   └── dto/                       # Data Transfer Objects
│   ├── domain/                        # Business logic layer
│   │   ├── models/                    # Domain models (DB entities)
│   │   ├── repository/                # Repository interfaces
│   │   └── services/                  # Business logic services
│   ├── infrastructure/                # External dependencies
│   │   ├── database/                  # PostgreSQL connection
│   │   ├── cache/                     # Redis client
│   │   └── persistence/               # Repository implementations
│   ├── pkg/                           # Internal utilities
│   │   ├── config/                    # Configuration management
│   │   ├── logger/                    # Logging setup
│   │   ├── security/                  # Security utilities
│   │   ├── errors/                    # Custom error types
│   │   └── validator/                 # Custom validators
│   └── app/
│       └── app.go                     # Application initialization
├── pkg/                               # Public packages (reusable)
├── configs/                           # Configuration files
├── migrations/                        # Database migrations
├── docker/                            # Docker files
├── scripts/                           # Build/deployment scripts
├── go.mod
├── go.sum
├── Makefile
└── README.md

🏗️ Architecture

Clean Architecture Layers

┌─────────────────────────────────────────┐
│           API Layer (Handlers)          │
│  - HTTP request/response handling       │
│  - Input validation                     │
│  - Response formatting                  │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│        Service Layer (Business Logic)   │
│  - Business rules                       │
│  - Orchestration                        │
│  - Transaction management               │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│      Repository Layer (Data Access)     │
│  - Database operations                  │
│  - Query building                       │
│  - Data mapping                         │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Domain Layer (Models)           │
│  - Entity definitions                   │
│  - Business entities                    │
│  - Domain logic                         │
└─────────────────────────────────────────┘

Dependency Flow

• Handlers depend on Services
• Services depend on Repository Interfaces
• Repository Implementations depend on Models
• Models have no dependencies (pure domain)

🛠️ Technology Stack

Component	Technology
Web Framework	Gin
ORM	GORM
Database	PostgreSQL
Cache	Redis
Configuration	Viper
Logging	Zap
JWT	golang-jwt
Validation	validator
Password Hashing	bcrypt

🚦 Getting Started

Prerequisites

• Go 1.21 or higher
• PostgreSQL 14+
• Redis 6+
• Docker & Docker Compose (optional)

Installation

1. Clone the repository

   git clone <repository-url>
   cd golang-microservice-template

2. Install dependencies

   go mod download

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run database migrations

   make migrate-up

5. Run the application

   make run

The server will start on http://localhost:8000

Using Docker

# Build and run all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

� API Documentation

This project uses Swagger/OpenAPI for API documentation. Once the server is running, you can access the interactive API documentation at:

• Swagger UI: http://localhost:8000/api/swagger/index.html
• API JSON: http://localhost:8000/api/swagger/doc.json

Features

• Interactive API Testing: Try out endpoints directly from the browser
• Request/Response Examples: See sample data for all endpoints
• Authentication: Test protected endpoints with JWT tokens
• Schema Validation: View detailed request/response schemas

Generating Documentation

To regenerate the Swagger documentation after making changes:

# Install swag CLI (if not already installed)
go install github.com/swaggo/swag/cmd/swag@latest

# Generate documentation
swag init -g cmd/server/main.go -o docs

�📝 Configuration

Configuration is managed through environment variables and YAML files. The application supports multiple environments (development, staging, production).

Environment Variables

Key environment variables:

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=microservice_db
DB_USER=postgres
DB_PASSWORD=postgres

# JWT
JWT_SECRET_KEY=your-secret-key
JWT_ACCESS_TOKEN_EXPIRATION_MINUTES=60
JWT_REFRESH_TOKEN_EXPIRATION_DAYS=30

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

See .env.example for all available options.

🔒 Security Features

Authentication & Authorization

• JWT-based authentication with access and refresh tokens
• Device tracking with unique device fingerprinting
• Multi-device support with configurable limits
• Token blacklisting for logout functionality
• Role-based access control (RBAC)

Security Middleware

1. Rate Limiter: Prevents abuse with configurable limits
2. Attack Detector: Detects SQL injection, XSS, path traversal
3. IP Filter: Whitelist/blacklist with automatic blocking
4. User Agent Filter: Blocks suspicious bots and clients

Password Security

• Bcrypt hashing with configurable cost (default: 12)
• Password strength validation
• Salt generation for additional security

📊 API Endpoints

Authentication

POST   /api/auth/register          # Register new user
POST   /api/auth/login             # Login user
POST   /api/auth/refresh-token     # Refresh access token
POST   /api/auth/logout            # Logout current device
POST   /api/auth/logout-all        # Logout all devices
GET    /api/auth/devices           # Get user devices
GET    /api/auth/devices/:id       # Get device details

Users

GET    /api/users                  # Get all users (admin)
GET    /api/users/:id              # Get user by ID
PUT    /api/users/:id              # Update user
DELETE /api/users/:id              # Delete user

Health

GET    /api/health                 # Health check
GET    /api/health/db              # Database health
GET    /api/health/redis           # Redis health

🧪 Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific package tests
go test ./internal/pkg/security/...

🔧 Development

Makefile Commands

make build          # Build the application
make run            # Run the application
make test           # Run tests
make test-coverage  # Run tests with coverage
make lint           # Run linter
make fmt            # Format code
make clean          # Clean build artifacts
make docker-build   # Build Docker image
make docker-run     # Run in Docker
make migrate-up     # Run database migrations
make migrate-down   # Rollback migrations

🐳 Docker

Multi-stage Dockerfile

The included Dockerfile uses multi-stage builds for optimal image size:

1. Builder stage: Compiles the Go application
2. Final stage: Minimal runtime image with just the binary

Docker Compose

Includes services for:

• Application server
• PostgreSQL database
• Redis cache
• Database admin (Adminer)

📈 Performance

Optimizations

• Connection pooling for database and Redis
• Prepared statements for database queries
• Goroutines for async operations (background tasks)
• Context propagation for request cancellation
• Efficient JSON serialization with Gin
• Log rotation to prevent disk space issues

Benchmarks

(Add your benchmark results here)

🔄 Migration from FastAPI

This template is a direct conversion from a FastAPI microservice. Key mappings:

FastAPI	Golang/Gin
Pydantic models	Structs with validation tags
Dependency injection	Constructor injection
async/await	Goroutines + channels
SQLAlchemy async	GORM with context
Alembic migrations	golang-migrate or GORM AutoMigrate
FastAPI middleware	Gin middleware
Loguru	Zap
Python decorators	Function wrappers

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Converted from FastAPI microservice template
• Inspired by clean architecture principles
• Built with modern Go best practices

📞 Support

For issues and questions:

• Open an issue on GitHub
• Contact: your-email@example.com

---

Built with ❤️ using Golang and Gin