gogen

If this project is useful to you, please consider supporting development via GitHub Sponsors.

gogen is a production-oriented collection of modular, reusable Go packages for building services and infrastructure code.

It solves a common problem in backend teams: repeatedly re-implementing the same foundational components (configuration loading, retries, health checks, logging, metrics, AWS integration, validation, caching, and more) across multiple repositories.

Instead of assembling and maintaining ad-hoc helpers per project, you can adopt tested packages with consistent patterns.

Source documentation: pkg.go.dev/github.com/tecnickcom/gogen

Table of Contents

1. Why gogen
2. Feature Highlights
3. Benefits Summary
4. Package Catalog
5. Developers Quick Start
6. Running All Tests
7. How To Create a New Web Service
8. Contributing

Why gogen

gogen is a good fit for Go teams that want:

• A consistent utility layer across services
• Reusable packages rather than project-specific scripts
• A modular import model without framework lock-in
• A practical example service to accelerate onboarding
• A Makefile-driven workflow for test/build/scaffolding

It also includes a generator path:

make project CONFIG=project.cfg

This scaffolds a new web service from the provided configuration.

Feature Highlights

• Broad package coverage for day-to-day service needs
  Why it matters: reduce dependency sprawl and avoid rewriting boilerplate utilities.

• Production-focused building blocks (HTTP, retries, observability, data stores, AWS)
  Why it matters: ship services faster with less glue code.

• Consistent conventions across packages
  Why it matters: easier code reviews, simpler maintenance, and predictable APIs.

• Testing-first repository culture
  Why it matters: safer refactoring and more reliable behavior over time.

• Built-in project scaffolding and runnable example service
  Why it matters: faster project bootstrap and clearer implementation reference.

Benefits Summary

• Faster development cycles for new services
• Less duplicated utility code across repositories
• Better consistency in operational concerns (logging, metrics, health, tracing)
• Cleaner architecture through package-level composition
• Easier onboarding for engineers joining an existing Go platform

Package Catalog

gogen offers a comprehensive set of well-tested packages.

• awsopt - Utilities for configuring common AWS options with the aws-sdk-go-v2 library. aws, configuration
• awssecretcache - Client for retrieving and caching secrets from AWS Secrets Manager. aws, secrets, caching
• bootstrap - Helpers for application bootstrap and initialization. bootstrap, initialization
• config - Utilities for configuration loading and management. configuration
• countrycode - Functions for country code lookup and validation. geolocation, validation
• countryphone - Phone number parsing and country association. phone, geolocation, parsing
• decint - Helpers for parsing and formatting decimal integers. numeric, formatting, parsing
• devlake - Client for the DevLake Webhook API. webhook, api client
• dnscache - DNS resolution with caching support. dns, caching, networking
• encode - Utilities for data encoding and serialization. encoding, serialization
• encrypt - Helpers for encryption and decryption. encryption, security
• enumbitmap - Encode and decode slices of enumeration strings as integer bitmap values. enum, bitmap, encoding
• enumcache - Caching for enumeration values with bitmap support. enum, caching
• enumdb - Helpers for storing and retrieving enumeration sets in databases. enum, database
• errutil - Error utility functions, including error tracing. error handling, utilities
• filter - Generic rule-based filtering for struct slices. filtering, collections
• healthcheck - Health check endpoints and logic. health, monitoring
• httpclient - HTTP client with enhanced features. http, client
• httpretrier - HTTP request retry logic. http, retry
• httpreverseproxy - HTTP reverse proxy implementation. http, reverse proxy
• httpserver - HTTP server setup and management. http, server
• httputil - HTTP utility functions. http, utilities
• jsendx - Helpers for JSend-compliant responses. http, response formatting
• ipify - IP address lookup using the ipify service. ip lookup, networking, external service
• jirasrv - Client for Jira server APIs. api client, integration
• jwt - JSON Web Token creation and validation. jwt, authentication, security
• kafka - Kafka producer and consumer utilities. kafka, messaging
• kafkacgo - Kafka integration using CGO bindings. kafka, messaging, cgo
• logsrv - Default slog logger with zerolog handler. logging, slog, zerolog
• logutil - General log utilities for log/slog integration. logging, utilities
• maputil - Helpers for Go map manipulation. map utilities, collections
• metrics - Metrics collection and reporting. metrics, monitoring
• opentel - OpenTelemetry metrics exporter (includes tracing). opentelemetry, metrics, tracing
• prometheus - Prometheus metrics exporter. prometheus, metrics
• statsd - StatsD metrics exporter. statsd, metrics
• mysqllock - Distributed locking using MySQL. mysql, locking, distributed
• numtrie - Trie data structure for numeric keys with partial matching. data structure, trie
• paging - Helpers for data pagination. pagination, utilities
• passwordhash - Password hashing and verification. password hashing, security
• passwordpwned - Password breach checking via HaveIBeenPwned. password breach, security
• periodic - Periodic task scheduling. scheduling, tasks
• phonekeypad - Phone keypad mapping utilities. phone, mapping, utilities
• profiling - Application profiling tools. profiling, performance
• random - Utilities for random data generation, including UUID. random, utilities
• redact - Data redaction helpers. redaction, privacy
• redis - Redis client and utilities. redis, database, caching
• retrier - Retry logic for operations. retry, utilities
• s3 - Helpers for AWS S3 integration. aws, s3
• sfcache - Simple in-memory, thread-safe, fixed-size, single-flight cache for expensive lookups. caching, thread-safe, single-flight
• slack - Client for sending messages via the Slack API Webhook. slack, webhook, messaging
• sleuth - Client for the Sleuth.io API. api client, integration
• sliceutil - Utilities for slice manipulation. slice utilities, collections
• sqlconn - Helpers for SQL database connections. sql, database
• sqltransaction - SQL transaction management. sql, transactions
• sqlutil - SQL utility functions. sql, utilities
• sqlxtransaction - Helpers for SQLX transactions. sqlx, transactions
• sqs - Utilities for AWS SQS (Simple Queue Service) integration. aws, sqs, messaging
• stringkey - Create unique hash keys from multiple strings. string keys, hashing
• stringmetric - String similarity and distance metrics. text similarity, metrics
• strsplit - Utilities to split strings and Unicode text. string utilities, text
• testutil - Utilities for testing. testing, utilities
• threadsafe - Thread-safe data structures. thread-safe, concurrency
• tsmap - Thread-safe map implementation. thread-safe, map
• tsslice - Thread-safe slice implementation. thread-safe, slice
• timeutil - Time and date utilities. time, date utilities
• traceid - Trace ID generation and management. tracing, ids
• typeutil - Type conversion and utility functions. type conversion, utilities
• uhex - Utilities for uppercase hexadecimal encoding and decoding. hex, encoding, utilities
• validator - Data validation utilities. validation, utilities
• valkey - Wrapper client for interacting with valkey.io, an open-source in-memory data store. data store, client

Developers Quick Start

Requirements:

• Go (latest stable; repository is configured for Go 1.26)
• Python 3 (required for additional tests)

Clone and validate the repository:

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

The Makefile provides a Linux-friendly workflow for build/test operations. Generated artifacts and reports are written to target/.

To run the same process in Docker:

make dbuild

This uses resources/docker/Dockerfile.dev.

List all available commands:

make help

Running All Tests

Before committing, run:

make x

Or run tests/build inside Docker:

make dbuild

How To Create a New Web Service

The directory examples/service contains a sample web service built with gogen.

To scaffold a new project:

Clone the gogen repository

$ git clone https://github.com/tecnickcom/gogen.git

Cloning into 'gogen'...

Move to the cloned project directory

$ cd gogen/

List available Make targets

$ make

# gogen Makefile.
# GOPATH=/home/demo/GO
# The following commands are available:
#
#   make x              : Test and build everything from scratch
#   make clean          : Remove any build artifact
#   make coverage       : Generate the coverage report
#   make dbuild         : Build everything inside a Docker container
#   make deps           : Get dependencies
#   make dockerdev      : Build a base development Docker image
#   make ensuretarget   : Create the target directories if missing
#   make example        : Build and test the service example
#   make format         : Format the source code
#   make generate       : Generate Go code automatically
#   make linter         : Check code against multiple linters
#   make mod            : Download dependencies
#   make project        : Generate a new project from the example using the data set via CONFIG=project.cfg
#   make qa             : Run all tests and static analysis tools
#   make tag            : Tag the Git repository
#   make test           : Run unit tests
#   make gotools        : Get the go tools
#   make updateall      : Update everything
#   make updatego       : Update Go version
#   make updatelint     : Update golangci-lint version
#   make updatemod      : Update dependencies
#   make version        : Update this library version in the examples
#   make versionup      : Increase the patch number in the VERSION file
#
# To run the full test and build flow from scratch, use:
#     make x

Run the full test and build pipeline

$ make x

# DEVMODE=LOCAL make version format clean mod deps generate qa example

# 1. make version       : Update this library version in the examples
# 2. make format        : Format the source code
# 3. make clean         : Remove any build artifact
# 4. make mod           : Download dependencies
# 5. make deps          : Get dependencies
# 6. make generate      : Generate Go code automatically (test mocks)
# 7. make qa            : Run all tests and static analysis tools
    # 7.1. make linter      : Check the code with multiple linters (golangci/golangci-lint)
    # 7.2. make test        : Run unit tests (go test)
    # 7.3. make coverage    : Generate the coverage report (/target/report/coverage.html)
# 8. make example       : Build and test the service example
    # 8.1. make clean       : Remove any build artifact
    # 8.2. make mod         : Download dependencies
    # 8.3. make deps        : Get dependencies
    # 8.4. make gendoc      : Generate static documentation from /doc/src (gomplate)
    # 8.5. make generate    : Generate Go code automatically (test mocks)
    # 8.6. make qa          : Run all tests and static analysis tools
        # 8.6.1. make linter    : Check the code with multiple linters (golangci/golangci-lint)
        # 8.6.2. make confcheck : Check the configuration files (jv)
        # 8.6.3. make test      : Run unit tests (go test)
        # 8.6.4. make coverage  : Generate the coverage report (target/report/coverage.html)
    # 8.7. make build       : Compile the application (go build > target/usr/bin/gogenexample)

Create a new project from the examples/service template

Customize the project configuration file

$ cp project.cfg myproject.cfg

$ nano myproject.cfg

Generate the project

$ make project CONFIG=myproject.cfg

# Project created at target/github.com/test/dummy

Move the project to a new location

$ mv target/github.com/test/dummy ~/GO/src/myproject/

Run the full test suite on the new project

$ cd ~/GO/src/myproject/

$ make x

# DEVMODE=LOCAL make format clean mod deps gendoc generate qa build docker dockertest

#  1. make format      : Format the source code
#  2. make clean       : Remove any build artifact
#  3. make mod         : Download dependencies
#  4. make deps        : Get dependencies
#  5. make gendoc      : Generate static documentation from /doc/src (gomplate)
#  6. make generate    : Generate Go code automatically (test mocks)
#  7. make qa          : Run all tests and static analysis tools
    #  7.1. make linter    : Check the code with multiple linters (golangci/golangci-lint)
    #  7.2. make confcheck : Check the configuration files (jv)
    #  7.3. make test      : Run unit tests (go test)
    #  7.4. make coverage  : Generate the coverage report (target/report/coverage.html)
#  8. make build       : Compile the application (go build > target/usr/bin/gogenexample)
#  9. make docker      : Build a scratch Docker container to run this service
# 10. make dockertest  : Test the newly built Docker container in an ephemeral Docker Compose environment
    # 10.1. DEPLOY_ENV=int make openapitest apitest
        # 10.1.1. make openapitest : Test the OpenAPI specification with randomly generated Schemathesis tests
        # 10.1.2. make apitest     : Execute API tests with venom

Contributing

Contributions are welcome. Please review CONTRIBUTING.md before opening a pull request.