This repository provides a robust and well-structured template for building microservices with Go, designed for deployment in a Kubernetes environment.
- Production-Ready Structure: A clean and organized project layout (
cmd/,internal/,pkg/) promotes maintainability and scalability. - Configuration Management: Viper handles configuration from files (YAML, JSON, TOML), environment variables, making your service highly configurable.
- Structured Logging: slog provides structured logging with various output formats, and contextual logging.
- Health Checks: Built-in support for Kubernetes liveness, readiness, and startup probes, ensuring smooth deployments and service health.
- HTTP and gRPC Support: Includes examples for both HTTP (using Gorilla Mux) and gRPC servers, allowing you to choose the best communication protocol for your needs. Middleware for CORS, Logging and Panic recovery are included.
- Multi-Platform Docker Builds:
Dockerfileis optimized for multi-stage builds and multi-platform support (linux/amd64, linux/arm64), creating small and efficient container images. - Dependency Management: Uses Go modules for managing dependencies.
- Graceful Shutdown: Implements graceful shutdown of servers, ensuring a smooth exit on termination signals.
- Cobra CLI: Uses Cobra to provide a powerful and easy to use command line interface.
- Makefile: Includes a Makefile with convenient commands for building, linting, testing, and cleaning your project.
- GitHub Actions: CI/CD workflow for building, linting, testing, and building/pushing Docker images.
Here's a quick overview of the main parts of the template:
cmd/service/main.go: The entry point of your service. It uses Cobra for command-line argument parsing and orchestrates the service startup and shutdown.internal/: This directory contains your application's private code.config/: Handles loading and managing configuration using Viper.handlers/: Contains HTTP and gRPC handler functions.health/: Implements Kubernetes health check endpoints.log/: Provides a wrapper aroundslogfor structured logging, configurable output, format, and context.server/: Sets up and manages HTTP and gRPC servers.service/: Contains the core business logic of your service.
96FB
pkg/: This directory is for reusable libraries that you might share across multiple projects. It's empty by default in this template.Dockerfile: Defines how to build a Docker image for your service.go.modandgo.sum: Go module files for managing dependencies.app.yaml: Example YAML configuration file. Viper supports other formats too!.github/workflows/build.yaml: GitHub Actions workflow for CI/CD.Makefile: Defines useful commands for local development.
-
Clone the Repository:
git clone [https://github.com/zaibon/go-template.git](https://github.com/zaibon/go-template.git) cd go-template -
Initialize Your Service:
-
Modify the
go.modfile to reflect your service's module path:go mod edit -module your-service-name
-
Run go mod tidy
go mod tidy
-
-
Configure Your Service:
- Create a configuration file (e.g.,
app.yaml) in the root directory. See theapp.yamlexample for the structure. - Set any necessary environment variables.
- Create a configuration file (e.g.,
-
Implement Your Logic:
- Write your business logic in the
internal/service/service.gofile. - Define your HTTP handlers in
internal/handlers/http.goand gRPC definitions and handlers ininternal/handlers/grpc.go.
- Write your business logic in the
-
Build and Run:
- Use the Makefile:
make build
- Or directly:
go build -o ./bin/your-service ./cmd/service/main.go
- Run the service:
./bin/your-service
- Use the Makefile:
-
Containerize with Docker:
-
Build the Docker image:
docker build -t your-service-image . -
Run the Docker container:
docker run -p 8080:8080 -p 9090:9090 your-service-image
-
-
Deploy to Kubernetes:
- Create Kubernetes deployment and service manifests. (This is beyond the scope of this README, but the template is designed to work well in Kubernetes.)
The service uses Viper for configuration. You can configure it using:
- Configuration files (YAML, JSON, TOML, etc.)
- Environment variables (which override file settings)
See the internal/config/config.go file for how configuration is loaded and structured.
The service uses slog for logging. The logger is configured in cmd/service/main.go using the options pattern defined in internal/log/log.go.
The /healthz endpoint provides a liveness probe, and the /readyz endpoint provides a readiness probe for Kubernetes. You can add your own health check logic in the internal/health package.
The HTTP server uses Gorilla Mux for routing and includes middleware for:
- CORS
- Logging
- Panic recovery
The template includes a basic gRPC server setup. Define your gRPC service definitions in .proto files and generate the Go code using protoc.
The Makefile provides the following commands:
make all: Builds, lints, and tests the service.make build: Builds the service.make lint: Lints the code using golangci-lint.make test: Runs the tests.make clean: Removes build artifacts.
The template includes a GitHub Actions workflow (.github/workflows/build.yaml) that:
- Builds, lints, and tests the service on pushes and pull requests to the
mainanddevelopbranches. - Builds and pushes a Docker image to Docker Hub on pushes to the
mainbranch when the build job is successful.
Contributions are welcome! Feel free to submit issues or pull requests.