go-api-starter

Production-ready Go API template — clean architecture, WebSocket support, structured logging, graceful shutdown.

Built from patterns proven in production fintech systems (trading engines, real-time data pipelines).

Features

• 🏗️ Clean architecture — domain, service, handler separation
• 🔌 WebSocket support — real-time bidirectional communication
• 📊 Structured logging — JSON logs with correlation IDs
• 🛡️ Graceful shutdown — handles SIGTERM, drains connections
• 🐳 Docker ready — multi-stage build, ~15MB image
• ⚡ Middleware chain — CORS, rate limiting, request ID, recovery
• 📡 Health checks — /healthz and /readyz endpoints
• 🧪 Testable — interfaces for all dependencies

Quick Start

# Clone and run
git clone https://github.com/dioncx/go-api-starter.git
cd go-api-starter
go run ./cmd/api

# Or with Docker
docker build -t go-api-starter .
docker run -p 8080:8080 go-api-starter

Project Structure

go-api-starter/
├── cmd/api/           # Entry point
│   └── main.go
├── internal/
│   ├── handler/       # HTTP handlers
│   ├── middleware/     # CORS, auth, rate limit, recovery
│   ├── model/         # Domain models
│   ├── service/       # Business logic
│   └── ws/            # WebSocket hub + client
├── Dockerfile         # Multi-stage build
├── go.mod
└── README.md

API Endpoints

Method	Path	Description
GET	/healthz	Health check
GET	/readyz	Readiness check
GET	/api/v1/items	List items
POST	/api/v1/items	Create item
GET	/api/v1/items/:id	Get item
WS	/ws	WebSocket connection

WebSocket

const ws = new WebSocket('ws://localhost:8080/ws');
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.send(JSON.stringify({type: "subscribe", channel: "updates"}));

Configuration

Environment variables:

Variable	Default	Description
PORT	8080	Server port
LOG_LEVEL	info	Log level (debug/info/warn/error)
SHUTDOWN_TIMEOUT	10s	Graceful shutdown timeout

License

MIT