golang-rest-api-template

module

v1.3.0 Latest Latest Go to latest Published: Aug 8, 2025 License: MIT

README ¶

golang-rest-api-template

🚀 Template Repository

This is a template repository for building REST APIs with Go. Click the "Use this template" button above to create your own repository based on this template.

Overview

This template includes everything you need to build a REST API with Go - logging, middleware, database setup, testing, and deployment configs.

Features

Structured logging
Middleware (auth, CORS, etc.)
Config management
API docs with Swagger
Docker setup
GitHub Actions CI/CD
Database migrations
Tests
Makefile for common tasks

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
Redis for cache

🎯 Quick Start (Using Template)

1. Create Repository from Template

Click the "Use this template" button at the top of this repository, or use GitHub CLI:

gh repo create my-go-api --template MitulShah1/golang-rest-api-template

2. Clone Your New Repository

git clone https://github.com/YOUR_USERNAME/my-go-api.git
cd my-go-api

3. Update Project Details

After creating your repository, update these files:

go.mod - Update module name
README.md - Update project name and description
.github/workflows/go.yml - Update repository references if needed
docker-compose.yml - Update service names if needed

4. Start Development

make help          # See all available commands
make env           # Create .env file
make docker_up     # Start with Docker
make test          # Run tests

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+
Docker and Docker Compose
Make

All Make Commands

To Check All Commands:

make help

Make Help Commands

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
GitHub Actions for CI/CD pipeline

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a new Pull Request

License

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

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
server command
config Package config provides configuration management for the application.	Package config provides configuration management for the application.
docs Package docs Code generated by swaggo/swag.	Package docs Code generated by swaggo/swag.
internal
application Package application provides application lifecycle management.	Package application provides application lifecycle management.
handlers Package handlers provides HTTP server setup and routing functionality.	Package handlers provides HTTP server setup and routing functionality.
handlers/category Package category provides HTTP handlers for category-related operations.	Package category provides HTTP handlers for category-related operations.
handlers/category/model Package model provides data structures for category-related operations.	Package model provides data structures for category-related operations.
handlers/health Package health provides HTTP handlers for health check operations.	Package health provides HTTP handlers for health check operations.
handlers/product Package product provides HTTP handlers for product-related operations.	Package product provides HTTP handlers for product-related operations.
handlers/product/model Package model provides data structures for product-related operations.	Package model provides data structures for product-related operations.
repository Package repository provides data access layer for the application.	Package repository provides data access layer for the application.
repository/model Package model provides data structures for database entities.	Package model provides data structures for database entities.
response Package response provides HTTP response utilities for the application.	Package response provides HTTP response utilities for the application.
services/category Package category provides business logic for category operations.	Package category provides business logic for category operations.
services/category/mocks
services/product Package product provides business logic for product operations.	Package product provides business logic for product operations.
services/product/mocks
package
cache Package cache provides Redis caching functionality for the application.	Package cache provides Redis caching functionality for the application.
database Package database provides database connection and configuration utilities.	Package database provides database connection and configuration utilities.
database/mocks Package mocks provides mock implementations for testing.	Package mocks provides mock implementations for testing.
logger Package logger provides structured logging functionality for the application.	Package logger provides structured logging functionality for the application.
middleware Package middleware provides HTTP middleware components for the application.	Package middleware provides HTTP middleware components for the application.
validation Package validation provides data validation utilities for the application.	Package validation provides data validation utilities for the application.