Go API Server

A modern Go REST API server following best practices with clean architecture, comprehensive testing, and Docker support.

Features

• 🚀 RESTful API server using Gin framework
• ✅ Comprehensive unit tests with high coverage
• 🔍 Linting with golangci-lint (Docker support)
• 🐳 Docker support for containerized deployment
• 📦 Modern project structure following Go best practices
• 🔧 Makefile for common development tasks
• ⚡ Graceful shutdown support
• 📝 Clean code architecture

Project Structure

.
├── cmd/
│   └── server/          # Application entry point
├── internal/
│   ├── api/             # API route setup
│   ├── handlers/        # HTTP handlers
│   └── models/          # Data models
├── pkg/                 # Public library code
├── bin/                 # Build artifacts
├── Makefile             # Build automation
├── .golangci.yml        # Linter configuration
├── Dockerfile           # Docker image definition
├── go.mod               # Go module definition
└── README.md            # This file

Prerequisites

• Go 1.23 or later
• Docker (optional, for linting)
• Make (optional, for using Makefile)

Quick Start

Install Dependencies

make install
# or
go mod download

Run the Server

make run
# or
go run cmd/server/main.go

The server will start on http://localhost:8080 by default.

Build the Application

make build
# or
go build -o bin/server ./cmd/server

Run Tests

make test
# or
go test ./...

Run Tests with Coverage

make test-coverage

Run Linter (using Docker)

make lint

Run Linter (locally, requires golangci-lint installed)

make lint-local

API Endpoints

Health Check

GET /health

Returns the health status of the service.

Response:

{
  "status": "ok",
  "service": "go-api-server"
}

Users API

Get All Users

GET /api/v1/users

Get User by ID

GET /api/v1/users/:id

Create User

POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Delete User

DELETE /api/v1/users/:id

Environment Variables

• PORT: Server port (default: 8080)
• ENV: Environment mode (development/production, default: development)

Makefile Commands

Run make help to see all available commands:

• make build - Build the application
• make run - Run the application
• make test - Run tests
• make test-coverage - Run tests with coverage report
• make lint - Run linter using Docker
• make lint-local - Run linter locally
• make fmt - Format code
• make vet - Run go vet
• make install - Install dependencies
• make clean - Clean build artifacts
• make ci - Run CI checks (lint + test)

Docker Setup

This project uses Colima (headless Docker daemon) for Docker support. See SETUP.md for Docker installation instructions.

Build Docker Image

make docker-build
# or
docker build -t go-api-server:latest .

Run Docker Container

make docker-run
# or
docker run -p 8080:8080 go-api-server:latest

Docker Compose

docker-compose up
# or in detached mode
docker-compose up -d

Development

Code Style

• Follow Effective Go guidelines
• Run make fmt before committing
• Ensure make lint passes
• Write tests for new features

Testing

• All tests should be in *_test.go files
• Use the standard testing package
• Use testify for assertions
• Aim for >80% test coverage

License

MIT