golang-rest-api-template

Overview

This is a template for building production-ready and easily extendible REST API using Go. It follows best practices and includes a standardized project structure with all necessary components for building scalable microservices.

Features

• Structured logging
• Middleware support (authentication, etc.)
• Configuration management
• API documentation with Swagger
• Docker support
• CI/CD pipeline with Jenkins
• Database migrations
• End-to-end testing
• Makefile for common operations

The main ones are:

• gorilla/mux for routing
• go-playground/validator for request validation
• go-sql-driver/mysql for MySQL database access
• jmoiron/sqlx for enhanced database access
• Masterminds/squirrel for SQL builder
• golang-migrate/migrate for database migrations
• swaggo/swag for API documentation generation
• strechr/testify for writing easier test assertions
• mockery for generating mock interfaces
• uber/zap for structured logging
• prometheus/client_golang for metrics
• otel for observability
• jaeger for distributed tracing

Project Structure

golang-microservice-template/
│── cmd/
│   ├── server/                # Main entry point for the service
│   │   ├── main.go
│── config/
│   ├── config.go              # Application configuration
│── docs/                      # API documentation
│── internal/
│   ├── handlers/              # HTTP handlers
│   │   ├── server.go          # HTTP server
│   ├── services/              # Business logic
│   ├── repository/            # Data access layer
│── package/                   # Utility packages (database, logging, middleware, etc.)
│   ├── database/
│   │   ├── database.go
│── │   ├──migrations/         # Database migrations
│   ├── logger/
│   │   ├── logger.go
│   ├── middleware/
│   │   ├── basic_auth.go       # Basic authentication middleware
│   │   ├── cors.go             # CORS middleware
│   ├── ├── promotheus.go       # Prometheus metrics
│── test/
│   ├── e2e/                    # End-to-end tests
│── Dockerfile                  # Docker build configuration
│── docker-compose.yml          # Docker Compose setup
│── Makefile                    # Build automation
│── go.mod                      # Go module dependencies
│── go.sum                      # Dependencies lock file
│── README.md                   # Project documentation

Getting Started

Prerequisites

• Go 1.21 or higher
• Docker and Docker Compose
• Make

All Make Commands

To Check All Commands:

make help

Running the Application

1; Clone the repository

git clone https://github.com/MitulShah1/golang-rest-api-template.git

2; Create .env file from .env.example add details

make env

3; Start the application using Docker Compose

make docker_up

Development

Build the application:

make build

Run tests:

make test

Generate API documentation:

make generate_docs

DB Migrations

Create Migration:

make create_migration

Run Migrations:

make migration_up

Down Migrations:

make migration_down

Configuration

Configuration is managed through .env. Environment variables can override these settings.

API Documentation

API documentation is generated using Swagger. The documentation is available at http://localhost:8080/swagger/index.html.

Prometheus Metrics

Prometheus metrics are exposed at http://localhost:8080/metrics.

Testing

• Unit tests are alongside the code
• Integration tests are in the test/ directory
• Run all tests with make test

Deployment

The project includes:

• Dockerfile for containerization
• docker-compose.yml for local development
• Jenkinsfile for CI/CD pipeline

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

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