Nicola

Posted on Apr 10 • Originally published at tecnick.com

Stop Rewriting Go Service Boilerplate: Ship a Production-Ready API Faster with gogen

#go #opensource #programming #softwareengineering

Every backend team says the same thing when starting a new service:

"This one will be lean."

Then the infrastructure checklist arrives.

Configuration loading. Structured logging. Metrics. Retries. Health checks. Graceful shutdown. Validation. Cache layers. Cloud clients. Test utilities.

None of this is core business logic, but all of it is essential in production.

After seeing this pattern repeat across teams and projects, I consolidated battle-tested building blocks into one open-source project: gogen.

This post focuses on one concrete outcome:

Bootstrap a reliable Go service lifecycle without rewriting the same infrastructure code for every new service.

The Problem: Service Lifecycle Code Is Easy to Get Wrong

Many backend production incidents come not from core algorithms, but from operational failures and missing guardrails:

Services that do not shut down gracefully
Missing logs or inconsistent structure that slow diagnosis
Missing or late metrics that delay detection
Retry and timeout behaviour implemented inconsistently
Utility packages that drift between repositories

In Go, this often turns into custom glue code in every new project.

It works, until the third or fourth service.

Why gogen Exists

gogen is not a monolithic framework.

It is a production-oriented collection of modular Go packages for common backend concerns, plus a working REST API example that demonstrates how to compose them.

The goal is simple:

Reuse stable, tested components
Stay aligned with open standards and common conventions
Keep APIs idiomatic and composable
Reduce dependency sprawl and custom one-off helpers
Ship faster with safer defaults

Project links:

GitHub: https://github.com/tecnickcom/gogen
Package docs: https://pkg.go.dev/github.com/tecnickcom/gogen

What Makes gogen Different

Many libraries solve only one narrow task. gogen is different in practice because it combines three strengths:

1. Breadth Without Framework Lock-In

gogen provides dozens of packages across key backend categories:

Infrastructure and service lifecycle
Observability and operations
Data, storage, and caching
Security, privacy, and validation
Cloud integrations and messaging
Data processing, utilities, and testing

You can adopt one package at a time. No forced architecture. Just composable packages.

2. High Standards and OSS Discipline

Quality and security badges are publicly visible in the repository README.

gogen is actively maintained with a quality-first approach:

Code Quality: High unit test coverage enforced in CI, plus strict linting with golangci-lint
Security: CodeQL analysis and dependency review in CI to catch vulnerabilities early
Transparency: Public coverage, build status, and quality signals visible to all users
Process: Rigorous code review, contribution guidelines, and strong engineering hygiene
Recognition: Open Source Security Foundation (OpenSSF) Best Practices badge achieved

For teams adopting OSS in production, these guarantees matter as much as the features themselves.

3. Production-Ready Example Service

The examples/service project is not toy code. It demonstrates config, logging, metrics, docs, packaging, testing, and deployment-friendly workflows.

You can also scaffold a new service with:

make project CONFIG=project.cfg

cd target/github.com/test/dummy/

This scaffolds a ready-to-use project with runtime wiring, HTTP exposure, operational assets, and generated output clearly separated.

That structure matters because it lets you extend the example without mixing application code, deployment assets, and generated artefacts in the same place.
For a detailed breakdown of the project structure and key files, see examples/service/README.md.

Top Features

Three-server runtime layout via monitoring, private, and public HTTP endpoints. Why it matters: it shows how to isolate operational traffic from internal and external APIs from day one.
Configuration-first bootstrap in internal/cli. Why it matters: startup, logging, metrics, health checks, and graceful shutdown are all wired in one place, which keeps new features easier to add safely.
Operational assets shipped with the codebase in resources. Why it matters: local development, integration tests, packaging, container builds, and service-manager integration stay reproducible.
Generated documentation and artefacts kept separate in doc and target. Why it matters: developers can regenerate docs and build outputs without polluting source packages.

Benefits Summary

Faster onboarding because each concern has an obvious home.
Safer feature work because bootstrap, handlers, and operational assets are separated cleanly.
Better operability because monitoring, packaging, and test resources are part of the project instead of tribal knowledge.
Easier extension because new routes, dependencies, and deployment assets fit into an existing structure instead of forcing a reorganisation later.

From there, you can tailor it to your specific needs.

Honest Challenges from the Journey

Building reusable infrastructure packages is harder than writing project-local helpers.

Main trade-offs I had to handle:

Keeping APIs flexible without becoming generic to the point of ambiguity
Preserving backward compatibility while evolving internals
Balancing "do one thing well" package boundaries with discoverability
Supporting real-world operational needs without turning into a framework

These constraints shaped the package design philosophy: small, focused modules, explicit options, practical defaults.

Solve One Real Problem: Reliable Bootstrap and Graceful Shutdown

Let’s focus on one often-underestimated package: pkg/bootstrap.

It centralises the standard service lifecycle:

Create and propagate context.Context
Initialise logger and metrics
Bind application components
Listen for OS signals (SIGTERM, SIGINT)
Broadcast shutdown events
Wait for dependents with timeout bounds

This removes repetitive startup/shutdown orchestration from every service.

A Basic Integration Example

package main

import (
    "context"
    "log"
    "log/slog"
    "sync"
    "time"

    "github.com/tecnickcom/gogen/pkg/bootstrap"
    "github.com/tecnickcom/gogen/pkg/logutil"
    "github.com/tecnickcom/gogen/pkg/metrics"
)

func bind(ctx context.Context, l *slog.Logger, m metrics.Client) error {
    // register HTTP handlers, DB clients, workers, consumers, etc.
    return nil
}

func main() {
    shutdownWG := &sync.WaitGroup{}
    shutdownCh := make(chan struct{})

    err := bootstrap.Bootstrap(
        bind,
        bootstrap.WithLogConfig(logutil.DefaultConfig()),
        bootstrap.WithShutdownTimeout(30*time.Second),
        bootstrap.WithShutdownWaitGroup(shutdownWG),
        bootstrap.WithShutdownSignalChan(shutdownCh),
    )
    if err != nil {
        log.Fatal(err)
    }
}

The value here is not just "less code." It is predictable behaviour under pressure: controlled shutdown, consistent observability hooks, and fewer edge-case bugs.

For an advanced, runnable implementation, see:

Developer Contribution Quick Start (15 Minutes)

If you want to contribute to gogen, start with this fast onboarding path:

Clone the repository.
Run the full local quality pipeline.
Explore the service example.
Scaffold your own project.

git clone https://github.com/tecnickcom/gogen.git
cd gogen
make x

If you prefer a Docker-based workflow:

make dbuild

After setup, pick one high-value contribution path:

Add focused docs and examples for under-explained packages
Propose performance benchmarks for hot-path utilities
Expand integration examples in examples/service

Review contribution guidelines in the repository before opening a PR.

Final Takeaway

If your team keeps rebuilding the same Go service primitives, you are paying a hidden tax on every project.

gogen helps remove that tax with tested, modular packages and a practical reference service you can actually build from.

If this aligns with your stack:

Explore the repo: https://github.com/tecnickcom/gogen
Read the docs: https://pkg.go.dev/github.com/tecnickcom/gogen
Try the quick start and share feedback
Star the project if it is useful

OSS grows through real-world usage and honest feedback. Contributions are welcome.

Originally published at https://tecnick.com on March 29, 2026.

DEV Community