DEV Community: Kittipat.po

Building Powerful CLI Tools in Go with Cobra 🐍

Kittipat.po — Fri, 03 Apr 2026 14:16:22 +0000

Introduction

If you've ever used kubectl, hugo, gh (GitHub CLI), or helm, you've already used a CLI built with Cobra. It's the standard library for building command-line interfaces in Go — and for good reason.

In this blog, we'll walk through everything you need to know about Cobra 🐍 — from installing it and creating your first command, all the way to subcommands, flags, argument validation and lifecycle hooks. Plenty of examples along the way.

Installation & Project Setup 🛠️

Step 1: Install Cobra

# Add cobra to your Go module
go get github.com/spf13/cobra@latest

Step 2: (Optional) Install cobra-cli generator
The cobra-cli tool generates command boilerplate so you don't have to write it from scratch every time

go install github.com/spf13/cobra-cli@latest

Step 3: Recommended project structure
Keep your CLI commands organized — one file per command inside cmd/:

myapp/
├── main.go         ← tiny entry point
├── cmd/
│   ├── root.go     ← rootCmd lives here
│   ├── serve.go    ← "serve" subcommand
│   └── version.go  ← "version" subcommand
└── go.mod

Your First Command 🚀

main.go — keep it as thin as possible
The entry point does one thing: call cmd.Execute().

package main

import "myapp/cmd"

func main() {
    cmd.Execute()
}

cmd/root.go — define the root command

package cmd

import (
    "fmt"
    "os"
    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "A brief description of myapp",
    Long: `myapp is a demo CLI built with Cobra.
It shows how to structure a Go CLI application.`,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Welcome to myapp! Run --help for usage.")
    },
}

func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Let's run it:

~ go run . --help
myapp is a demo CLI built with Cobra.
It shows how to structure a Go CLI application.
Usage:
  myapp [flags]
  myapp [command]
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  user        A brief description of your command
Flags:
  -h, --help   help for myapp
Use "myapp [command] --help" for more information about a command.

You already get a fully formatted --help page for free. ✅

Subcommands 🌲

Subcommands are just more cobra.Command values, attached to a parent with AddCommand(). This is how you build git-style CLIs like myapp server start.

Example: nested subcommands — myapp server start / stop

package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var serverCmd = &cobra.Command{
    Use:   "server",
    Short: "Manage the server",
}

var serverStartCmd = &cobra.Command{
    Use:   "start",
    Short: "Start the server",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("🚀 Server starting...")
    },
}

var serverStopCmd = &cobra.Command{
    Use:   "stop",
    Short: "Stop the server",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("🛑 Server stopped.")
    },
}

func init() {
    serverCmd.AddCommand(serverStartCmd, serverStopCmd)
    rootCmd.AddCommand(serverCmd)
}

~ go run . server
Manage the server

Usage:
  myapp server [command]

Available Commands:
  start       Start the server
  stop        Stop the server

Flags:
  -h, --help   help for server

Use "myapp server [command] --help" for more information about a command.

~ go run . server start
🚀 Server starting...

~ go run . server stop 
🛑 Server stopped.

Flags 🚩

Cobra supports two kinds of flags: local (only on that command) and persistent (inherited by all subcommands).

But before we get there, you'll notice Cobra has four naming patterns for every flag type. People often get confused by this, so let's clear it up first.

The 4 naming patterns

Take String as an example — the same pattern applies to every type (Int, Bool, Duration, etc.):

Method	Returns	Shorthand	Who holds the value
`String(name, value, usage)`	`*string`	❌	Cobra owns the pointer
`StringP(name, short, value, usage)`	`*string`	✅	Cobra owns the pointer
`StringVar(p, name, value, usage)`	nothing	❌	You own the pointer
`StringVarP(p, name, short, value, usage)`	nothing	✅	You own the pointer

The naming rules are simple:

P suffix → adds a single-character shorthand (e.g. -n alongside --name)
Var suffix → you pass in your own variable; Cobra writes into it

`String` and `StringP` — Cobra gives you the pointer

var serveCmd = &cobra.Command{
    Use: "serve",
    Run: func(cmd *cobra.Command, args []string) {
        // retrieve via .GetString()
        host, _ := cmd.Flags().GetString("host")
        fmt.Println("host:", host)
    },
}

func init() {
    // String — no shorthand
    serveCmd.Flags().String("host", "localhost", "Host to bind")

    // StringP — adds -H as shorthand
    serveCmd.Flags().StringP("host", "H", "localhost", "Host to bind")
}

~ go run . serve
host: localhost

~ go run . serve --host 127.0.0.1
host: 127.0.0.1

You don't have a variable to read directly — you have to call cmd.Flags().GetString("name") inside Run. Fine for simple scripts, but it gets noisy fast.

`StringVar` and `StringVarP` — you own the variable

var host string // declare at package level

var serveCmd = &cobra.Command{
    Use: "serve",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("host:", host) // just use it directly ✅
    },
}

func init() {
    // StringVar — no shorthand
    serveCmd.Flags().StringVar(&host, "host", "localhost", "Host to bind")

    // StringVarP — adds -H as shorthand
    serveCmd.Flags().StringVarP(&host, "host", "H", "localhost", "Host to bind")
}

You pass a pointer to your own variable. Cobra fills it in before Run is called. No GetString needed.

💡 In practice, always use Var / VarP. Declaring your flags as package-level variables is cleaner, easier to test, and works well with Viper bindings.

When to add `P` (shorthand)

Add a shorthand when the flag is frequently typed. Common conventions:

cmd.Flags().StringVarP(&output, "output", "o", "", "Output file")
cmd.Flags().StringVarP(&config, "config", "c", "", "Config file")
cmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
cmd.Flags().IntVarP(&port, "port", "p", 8080, "Port to listen on")

Local vs Persistent flags

Local — only visible on the command they're defined on:

func init() {
    // --port is only available on serveCmd
    serveCmd.Flags().IntVarP(&port, "port", "p", 8080, "Port to listen on")
}

Persistent — inherited by the command and all its subcommands:

func init() {
    // --verbose works on rootCmd AND every subcommand
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
}

A common pattern is to put global flags like --config, --verbose, and --env as persistent on rootCmd, and command-specific flags like --port or --output as local on their own command.

Check if a flag was explicitly set

Sometimes you need to know whether the user actually passed a flag, or if you're just seeing the default value:

RunE: func(cmd *cobra.Command, args []string) error {
    if cmd.Flags().Changed("port") {
        fmt.Println("user explicitly set --port to", port)
    } else {
        fmt.Println("using default port:", port)
    }
    return nil
},

This is especially useful when you want environment variables or a config file to take precedence over the default, but not over an explicit flag.

Arguments & Validation 🔒

Set the Args field on a command to validate positional arguments before Run is called.

MinimumNArgs

var greetCmd = &cobra.Command{
    Use:   "greet [names...]",
    Short: "Greet one or more people",
    Args:  cobra.MinimumNArgs(1), // at least one name required
    Run: func(cmd *cobra.Command, args []string) {
        for _, name := range args {
            fmt.Printf("Hello, %s!\n", name)
        }
    },
}

~ go run . greet Dev.to Reader
Hello, Dev.to!
Hello, Reader!

OnlyValidArgs

var greetCmd = &cobra.Command{
    Use:       "greet [names...]",
    Short:     "Greet one or more people",
    ValidArgs: []string{"Dev.to"},
    Args:      cobra.OnlyValidArgs,
    Run: func(cmd *cobra.Command, args []string) {
        for _, name := range args {
            fmt.Printf("Hello, %s!\n", name)
        }
    },
}

~ go run . greet Dev.to Reader
Error: invalid argument "Reader" for "myapp greet"
Usage:
  myapp greet [names...] [flags]

Flags:
  -h, --help   help for greet

invalid argument "Reader" for "myapp greet"
exit status 1

Validator	Meaning
`ArbitraryArgs`	Any number of arguments (default)
`MinimumNArgs(n)`	At least n arguments
`MaximumNArgs(n)`	At most n arguments
`ExactArgs(n)`	Exactly n arguments
`RangeArgs(min, max)`	Between min and max
`OnlyValidArgs`	Only values listed in `ValidArgs`

Lifecycle Hooks ⚙️

Cobra executes hooks in a well-defined order around your main Run function. This is useful for things like loading config, validating auth, or sending notifications.

var deployCmd = &cobra.Command{
    Use: "deploy",

    // 1. Runs before PreRun of this AND all children
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("[1] PersistentPreRun — loading config...")
    },
    // 2. Runs just before Run (not inherited)
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("[2] PreRun — validating credentials...")
    },
    // 3. The main logic
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("[3] Run — deploying...")
    },
    // 4. Runs after Run (not inherited)
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("[4] PostRun — sending notification...")
    },
    // 5. Runs after PostRun for this AND all children
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("[5] PersistentPostRun — cleanup done.")
    },
}

~ go run . deploy
[1] PersistentPreRun — loading config...
[2] PreRun — validating credentials...
[3] Run — deploying...
[4] PostRun — sending notification...
[5] PersistentPostRun — cleanup done.

💡 Tip
Use the E-suffix variants (PersistentPreRunE, RunE, etc.) when a hook can fail — they return an error and stop execution if it's non-nil.

Error Handling 🛡️

Use RunE to return errors

var fetchCmd = &cobra.Command{
    Use:  "fetch [url]",
    Args: cobra.ExactArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        resp, err := http.Get(args[0])
        if err != nil {
            return fmt.Errorf("fetch failed: %w", err)
        }
        defer resp.Body.Close()
        fmt.Printf("Status: %s\n", resp.Status)
        return nil
    },
}

~ go run . fetch a
Error: fetch failed: Get "a": unsupported protocol scheme ""
Usage:
  myapp fetch [url] [flags]

Flags:
  -h, --help   help for fetch

fetch failed: Get "a": unsupported protocol scheme ""
exit status 1

Optionally suppress Cobra's duplicate "Error: ..." print

var rootCmd = &cobra.Command{
    Use: "myapp",

    SilenceErrors: true, // quiet errors down stream
    SilenceUsage:  true, // silence usage when an error occurs

    Short: "A brief description of myapp",
    Long: `myapp is a demo CLI built with Cobra.
It shows how to structure a Go CLI application.`,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Welcome to myapp! Run --help for usage.")
    },
}

~ go run . fetch a    
fetch failed: Get "a": unsupported protocol scheme ""
exit status 1

📝 Conclusion

Cobra is the gold standard for building CLI tools in Go. It takes care of all the boring stuff — help pages, flag parsing, shell completion — so you can focus on what your tool actually does.

Here's what we covered:

✅ Installing Cobra and setting up a project
✅ Creating root and subcommands
✅ Flags
✅ Argument validation
✅ Lifecycle hooks
✅ Error handling with RunE

The next step? Try pairing Cobra with Viper for configuration management — they're built to work together. Happy coding! 🥂

Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

Structured Logging in Go: Context-Aware, JSON-Ready, and Production-Proven

Kittipat.po — Mon, 15 Sep 2025 07:46:26 +0000

Every developer has been there:

You’re on-call, an alert fires at 2 AM, and you’re staring at a wall of logs that look like this:

The Evolution of Logging 🧭

Logging in software has evolved a lot — but not every project has kept up:

1. Print Statements (the Stone Age): Just fmt.Println(“something happened”). Quick and dirty, but useless at scale.
2. Plain Logs with Timestamps (basic survival): Go’s log.Println gives you a timestamp, but everything else is left to you. Debugging across services? Forget it.
3. Leveled Logging (finding your voice): Tools like INFO, WARN, and ERROR levels made logs less noisy. You could finally filter out debug spam in production. But still no structure.
4. Structured Logging (the turning point): Instead of dumping plain text, logs became key–value pairs in JSON. Now you can query logs like data:
{ “severity”: “error”, “user_id”: 12345, “message”: “login failed” }
5. Context-Aware & Observability-Ready (where we are now): Modern systems aren’t just about logs — they’re about traces, spans, request IDs, and correlating everything in your observability stack. If your logger doesn’t integrate with context.Context, you’re already missing half the picture.

The Problem With Go’s Default Logging

Go’s built-in log package is fine for “hello world” projects, but once you’re in microservices land:

It doesn’t support structured fields.
It doesn’t know about context.Context.
It won’t give you trace IDs, caller info, or stack traces.

That gap inspired me to build something better. 🚀

Introducing the Logger Package 🎉

That’s where my Logger package comes in.

It’s a structured, context-aware logging solution for Go, built on top of Logrus, designed for production environments.

Think of it as logging upgraded for the cloud-native era:

JSON logs out of the box.
Automatic context propagation (trace_id, span_id).
Caller + stack trace included when you need it.
Customizable formatters and outputs.
Clean API that feels natural in Go.

How It Works ⚙️

The Logger package is designed to feel simple but powerful. Here’s how you can bring it into your project.

1. Install

go get github.com/kittipat1413/go-common/framework/logger

2. Create a Logger
You can start with the default production-ready logger:

log := logger.NewDefaultLogger()
log.Info(context.Background(), "Application started", nil)

Or configure it yourself using the Config struct:

logConfig := logger.Config{
    Level: logger.INFO,
    Formatter: &logger.StructuredJSONFormatter{
        TimestampFormat: time.RFC3339,
        // PrettyPrint
        // - true  = pretty-printed JSON (indented, easier for humans to read)
        // - false = compact JSON (single line, no indentation)
        PrettyPrint:     false,
    },
    Environment: "production",
    ServiceName: "order-service",
}

log, _ := logger.NewLogger(logConfig)

3. Structured JSON Formatter
By default, logs are emitted in structured JSON:

4. Customize Keys and Metadata
Don’t like the default field names in your logs?

You can redefine field names using a FieldKeyFormatter:

formatter := &logger.StructuredJSONFormatter{
    TimestampFormat: time.RFC3339,
    FieldKeyFormatter: func(key string) string {
        switch key {
        case logger.DefaultEnvironmentKey:
            return "env"
        case logger.DefaultServiceNameKey:
            return "service"
        default:
            return key
        }
    },
}

Now your logs use env and service instead of the defaults.

5. Context-Aware Logging
Pass in a context.Context with tracing info, and the logger automatically enriches logs with trace_id and span_id.

ctx, span := tracer.Start(context.Background(), "checkout")
defer span.End()

log.Info(ctx, "Processing checkout request", logger.Fields{
    "user_id": 42,
})

Log output:

6. Error Logging with Stack Traces
When logging errors, the logger automatically includes stack traces for quick debugging:

err := errors.New("database connection failed")
log.Error(ctx, "Failed to query user", err, logger.Fields{
    "query": "SELECT * FROM users",
})

Log output:

Final Thoughts ✨

This logger has already helped me a lot in my own projects — from cleaning up noisy logs to making debugging at 2 AM way less painful. That’s why I decided to share it with the community.

If you give it a try and it makes your life easier too, that’s a win.

And if you have suggestions, ideas, or improvements, I’d love to hear them. Open an issue or drop a comment — feedback is always welcome.

👉 Explore the examples.
👉 Or check out the documentation on pkg.go.dev.

Prevent Race Conditions in Go Microservices with Distributed Locks

Kittipat.po — Tue, 17 Jun 2025 10:30:16 +0000

Introduction

In distributed systems, coordinating access to shared resources—such as rows in a database, files, or operations like seat reservation or payment processing—can be challenging when multiple services are involved. This is where distributed locks come in.

In this post, we’ll cover:

What distributed locks are
Why and when you need them
Common pitfalls
A practical example in Go using Redsync
How to use the lockmanager from the go-common library to simplify implementation

What is a Distributed Lock?

A distributed lock ensures that multiple nodes in a system do not simultaneously perform conflicting operations on shared resources. It’s the distributed equivalent of a mutex, but across processes and machines.

Common Use Cases

Preventing double booking in a ticketing system
Ensuring only one worker processes a message from a queue
Serializing access to a critical section of code across pods or services

Redsync: Redis-based Locking 🔒

Redsync is a Go implementation of the Redlock algorithm, using Redis as the coordination backend. It’s simple, reliable, and battle-tested in production.

🔧 Example: Using Redsync

package main

import (
    goredislib "github.com/redis/go-redis/v9"
    "github.com/go-redsync/redsync/v4"
    "github.com/go-redsync/redsync/v4/redis/goredis/v9"
)

func main() {
    // Create a pool with go-redis (or redigo) which is the pool redisync will
    // use while communicating with Redis. This can also be any pool that
    // implements the `redis.Pool` interface.
    client := goredislib.NewClient(&goredislib.Options{
        Addr: "localhost:6379",
    })
    pool := goredis.NewPool(client) // or, pool := redigo.NewPool(...)

    // Create an instance of redisync to be used to obtain a mutual exclusion
    // lock.
    rs := redsync.New(pool)

    // Obtain a new mutex by using the same name for all instances wanting the
    // same lock.
    mutexname := "my-global-mutex"
    mutex := rs.NewMutex(mutexname)

    // Obtain a lock for our given mutex. After this is successful, no one else
    // can obtain the same lock (the same mutex name) until we unlock it.
    if err := mutex.Lock(); err != nil {
        panic(err)
    }

    // Do your work that requires the lock.

    // Release the lock so other processes or threads can obtain a lock.
    if ok, err := mutex.Unlock(); !ok || err != nil {
        panic("unlock failed")
    }
}

🤝 Simplifying with go-common `LockManager`

While Redsync is powerful, you often end up repeating boilerplate logic: setting up Redis clients, creating mutexes with consistent options, generating unique tokens and managing error types.

To simplify this, the lockmanager package from the go-common library provides a clean abstraction over Redsync with:

✅ A standard LockManager interface
⚙️ Pluggable token generator and retry logic
🧪 Easy mocking for unit testing

💡 Example: Using go-common LockManager

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/go-redsync/redsync/v4"
    "github.com/redis/go-redis/v9"

    redsyncLocker "github.com/kittipat1413/go-common/framework/lockmanager/redsync"
)

func main() {
    // Initialize Redis client
    client := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })
    defer client.Close()

    // Create LockManager with optional token generator and redsync config
    locker := redsyncLocker.NewRedsyncLockManager(
        client,
        redsyncLocker.WithTokenGenerator(func(key string) string {
            return "token-for:" + key
        }),
        redsyncLocker.WithRedsyncOptions(
            redsync.WithTries(3),
            redsync.WithRetryDelay(100*time.Millisecond),
        ),
    )

    ctx := context.Background()
    lockKey := "demo-lock-key"
    ttl := 2 * time.Second

    // Acquire lock
    token, err := locker.Acquire(ctx, lockKey, ttl)
    if err != nil {
        log.Fatalf("❌ Failed to acquire lock: %v", err)
    }
    fmt.Printf("✅ Lock acquired with token: %s\n", token)

    // Attempt to acquire the same lock again with a different token
    _, err = locker.Acquire(ctx, lockKey, ttl, "another-token")
    if err != nil {
        fmt.Printf("⛔ Re-acquire failed as expected: %v\n", err)
    }

    // Release lock
    if err := locker.Release(ctx, lockKey, token); err != nil {
        log.Fatalf("❌ Failed to release lock: %v", err)
    }
    fmt.Println("🔓 Lock released successfully")

    // Attempt releasing again (should be a no-op or handled gracefully)
    if err := locker.Release(ctx, lockKey, token); err != nil {
        fmt.Printf("🔁 Second release failed gracefully: %v\n", err)
    } else {
        fmt.Println("⚠️ Released again without error (already expired)")
    }
}

Pitfalls to Avoid ⚠️

While distributed locks can be powerful, they come with caveats:

Short TTLs may expire before the critical section is done, leading to unintended parallel execution.
Long TTLs may block progress if a node crashes without releasing the lock.
Don’t use locks as permanent ownership — they’re for coordination, not persistent state.
Always wrap lock usage with context timeouts or deadlines to avoid deadlocks.

🧠 Pro Tip: Design your system to recover gracefully even if the lock fails or expires unexpectedly.

Conclusion 🎯

Distributed locks are a foundational building block in microservices and distributed architectures. Whether you’re managing ticket availability, serializing task execution, or controlling access to shared state, having a reliable and testable lock mechanism makes a huge difference.

Structuring a Go Project with Clean Architecture — A Practical Example

Kittipat.po — Sun, 25 May 2025 15:53:50 +0000

🧠 Applying Clean Architecture in Go — A Real-World Project Walkthrough

Clean Architecture is a popular approach for building scalable and maintainable backend systems. However, applying it effectively — especially in real-world projects — can feel overwhelming without concrete examples.

In this post, I’d like to share how I’ve applied Clean Architecture principles in a simple Go project called 🎟️ Ticket Reservation System. It’s a small concert ticket booking service, and while not exhaustive, it demonstrates one possible way to organize code using Clean Architecture. The project includes features like domain-driven modeling, repository interfaces, CLI tooling, Swagger documentation, and modular routing.

If you’re looking for a starting point to apply Clean Architecture in your own Go projects, this layout might offer a useful reference.

🧭 Why Clean Architecture?

Clean architecture promotes separation of concerns, testability, and clear boundaries between core business logic and external dependencies like databases, HTTP frameworks, or third-party APIs.

This means:

Business logic doesn’t depend on frameworks.
Infrastructure can change without rewriting your use cases.
Handlers, services, and domain models remain isolated and testable.

🧱 Folder Structure Breakdown

Here’s the high-level layout of the ticket-reservation project:

ticket-reservation/
├── cmd/                          # Application entry points and CLI commands
│   ├── root.go                   # Root command for the CLI
│   ├── serve_cmd.go              # Command to start the server
│   ├── migrate_cmd.go            # Command to run database migrations
│   ├── new_migration_cmd.go      # Command to create new migration files
│   ├── print_config_cmd.go       # Command to print the current configuration
│   └── generate_sql_builder.go   # Command to generate SQL builder files
│   └── ...                       # Other commands
├── db/                           # Database-related files
│   └── migrations/               # Database migration files
├── docs/                         # Documentation files
│   ├── swagger.yaml              # API documentation in Swagger format
│   └── ...                       # Other design and architecture documents
├── internal/                     # Internal application code
│   ├── api/                      # Delivery layer
│   │   └── http/                 # HTTP API components
│   │       ├── handler/          # HTTP handlers by domain
│   │       │   ├── healthcheck/  # Health check handlers
│   │       │   └── ...           # Other domain handlers
│   │       ├── middleware/       # HTTP middleware
│   │       └── route/            # HTTP route definitions
│   ├── config/                   # Application configuration
│   ├── domain/                   # Domain layer
│   │   ├── cache/                # Cache-related interfaces
│   │   ├── entity/               # Domain models (e.g., Concert, Reservation)
│   │   ├── errs/                 # Domain-specific errors
│   │   └── repository/           # Repository interfaces
│   ├── infra/                    # Infrastructure layer
│   │   ├── db/                   # Database implementations
│   │   │   ├── connection.go     # Database connection setup
│   │   │   ├── sql_execer.go     # SQL execution interface
│   │   │   ├── transactor.go     # Transaction management
│   │   │   ├── mocks/            # Mock implementations
│   │   │   ├── model_gen/        # Generated models from DB schema
│   │   │   └── repository/       # Repository implementations
│   │   │       ├── healthcheck/  # Health check repository
│   │   │       └── ...           # Other repositories
│   │   └── redis/                # Redis implementations
│   │       ├── client.go         # Redis client interface
│   │       ├── connection.go     # Redis connection setup
│   │       ├── mocks/            # Mock implementations
│   │       └── repository/       # Repository implementations
│   │           ├── seat/         # Seat locking and cache implementations
│   │           └── ...           # Other repositories
│   ├── server/                   # Server setup and initialization
│   │   ├── dependency.go         # Dependency injection
│   │   ├── middleware.go         # Server middleware
│   │   └── server.go             # HTTP server setup
│   ├── usecase/                  # Application business logic
│   │   ├── healthcheck/          # Health check use case
│   │   └── ...                   # Other use cases
│   └── util/                     # Utility functions
│       ├── httpresponse/         # HTTP response helpers
│       └── ...                   # Other utility functions
├── pkg/                          # Shared helper packages
├── docker-compose.yaml           # Docker Compose for local development
├── Dockerfile                    # Docker build definition
├── env.yaml                      # Environment variables configuration
├── go.mod                        # Go module definition
├── go.sum                        # Go module dependencies
├── main.go                       # Main application entry point
├── Makefile                      # Makefile for common tasks
└── README.md                     # Project documentation

Let’s walk through some highlights 👇

🧩 Clean Architecture in Action

1. Delivery Layer — internal/api/http/
This layer exposes the API using the Gin framework. It includes:

handler/: request parsing, validation, response formatting
middleware/: application-level HTTP middleware such as authentication
route/: HTTP route setup using injected dependencies

2. Usecase Layer — internal/usecase/
This layer contains pure application logic. It defines input/output structs and orchestrates repository calls or business rules. It does not depend on Gin, SQL, or any infra packages.

3. Domain Layer — internal/domain/
This is the heart of the application. It defines:

entity/: domain models like Concert, Reservation
repository/: abstract interfaces for data access
mocks/: auto-generated mocks for unit tests

No dependencies, no framework imports — just business terms and contracts.

4. Infrastructure Layer — internal/infra/
This layer implements database logic using go-jet and sqlx. It satisfies the interfaces defined in the domain layer.

🛠️ Built-in CLI Tools

This project comes with a built-in CLI (powered by Cobra) for common dev tasks. Run go run main.go --help to explore all commands.

Key commands:

serve: Start the HTTP server
migrate: Run database migrations
new-migration: Generate new migration files
print-config: Print current effective config
generate-db: Generate SQL builder and model files using go-jet

🔄 Project Status

This project is still a work-in-progress, and not all features are complete. However, it already provides a useful reference for:

Structuring Go services with Clean Architecture
Organizing code for testability and scalability
Using tools like Cobra, Swagger, Jet, and MockGen effectively

If you’re starting a backend service in Go and want a clean, extensible foundation — feel free to fork or study this project. Feedback and contributions are welcome!
👉 GitHub Repo — ticket-reservation

Coding Tips #1: Name Your Maps Like You Care About Your Future Self

Kittipat.po — Mon, 07 Apr 2025 05:38:45 +0000

Let’s say you’re reading some Go code and stumble upon this:

for _, transaction := range transactions {
    customer := customerMap[transaction.Ref]
    sendReportEmail(customer.Email)
}

At first glance, it works. But if you’re the poor soul maintaining this code, questions start flooding in:

What is customerMap actually mapping?
What is transaction.Ref referring to? Is it a Customer ID? A Card ID? A National ID?
What does that string key even represent?

You’re stuck. You can’t proceed confidently until you understand what customerMap is mapping from and to.

So, what’s your next move?
If you’re lucky 🍀, you find this somewhere earlier in the code:

customerMap := groupCustomerByCustomerId(customers)

Ah! Now it clicks. customerMap maps from CustomerID to Customer. So transaction.Ref must be the Customer ID. You make a mental note and continue reading.

But if you’re not lucky? 😩 You find this instead:

customerMap := buildMapFromCustomers(customers)

Now you have to dive into that function just to figure out one simple thing: what’s the key?

Remember, all you wanted was to tweak the logic slightly. But now you’re deep in unrelated code, just trying to answer a basic question: what does this map do?

🧠 So What’s the Fix?

Name your maps clearly and semantically.
Instead of this:

customerMap := groupCustomerByCustomerId(customers)

Use this:

customerIdToCustomer := groupCustomerByCustomerId(customers)

Now the loop reads beautifully:

for _, transaction := range transactions {
    customer := customerIdToCustomer[transaction.Ref]
    sendReportEmail(customer.Email)
}

Even without looking elsewhere in the code, you immediately know:

The key is a CustomerID
The value is a Customer
transaction.Ref is likely a Customer ID

And just like that, you can keep reading without breaking your flow. ✅

🔁 In General: Use `keyToValue` Naming for Maps

When naming maps, this format is gold:

keyToValue := make(map[KeyType]ValueType)

Examples:

userIdToEmail
orderIdToStatus
productCodeToPrice

Understanding Request ID: Why It's Essential for Modern APIs

Kittipat.po — Mon, 24 Feb 2025 15:59:56 +0000

Introduction

When working with distributed systems, logging, and debugging APIs, one common pattern you’ll see is the use of a Request ID. Many services, frameworks, and cloud providers implement this concept. But why is it so widely adopted, and how can you use it effectively in your own applications? Let’s dive in.

What is a Request ID?

A Request ID is a unique identifier assigned to an API request, usually in the form of a UUID (Universally Unique Identifier) or another unique string. This ID follows the request as it moves through different services, making it easier to trace its journey across the system.

Example:

When a client sends a request to an API, the server may generate a Request ID, such as:

X-Request-ID: 8f74a1b3-9e22-4c10-92a5-8b6ec5f79e1d

This ID is then passed along to downstream services, included in logs, and returned in responses, allowing for full traceability of a request’s lifecycle.

Why Implement Request IDs?

1. Improved Debugging & Tracing: Without a Request ID, debugging issues in a distributed system can be like searching for a needle in a haystack. By including a Request ID in logs, you can correlate logs across multiple services and pinpoint where failures occurred.
2. Easier Customer Support: When users report issues, having a Request ID makes it significantly easier to look up their specific request in logs and investigate what went wrong.
3. Correlation in Microservices: If your system consists of multiple services communicating via APIs, passing a Request ID ensures all services handling the same request can log and track it consistently.
4. Security & Auditability: For compliance-heavy applications, Request IDs help track how data moves through a system, providing a way to audit access and activity.

How to Implement Request ID

1. Generating a Request ID
Most implementations generate a UUID for the Request ID if the client hasn’t provided one. In Go, you can generate a UUID using:

import (
    "github.com/google/uuid"
)

func GenerateRequestID() string {
    return uuid.New().String()
}

2. Passing Request ID in Headers
A common convention is to use the X-Request-ID header. The flow typically looks like this:

The client sends a request (optionally including X-Request-ID).
If the header is missing, the server generates a new Request ID.
The Request ID is included in all downstream requests.
The response includes the Request ID, so the client can log it.

3. Middleware for Automatic Handling
Example Middleware Implementation:

package middleware

import (
    "context"
    "github.com/gin-gonic/gin"
    "github.com/rs/xid"
)

var requestIDContextKey struct{}

// GetRequestIDFromContext retrieves the request ID from the context.
func GetRequestIDFromContext(ctx context.Context) (string, bool) {
    requestID, ok := ctx.Value(requestIDContextKey).(string)
    return requestID, ok
}

const DefaultRequestIDHeader = "X-Request-ID"

// RequestID returns a Gin middleware that injects a unique request ID into each request context.
func RequestID() gin.HandlerFunc {
    return func(c *gin.Context) {
        requestID := c.GetHeader(DefaultRequestIDHeader)
        if requestID == "" {
            requestID = xid.New().String()
        }
        c.Writer.Header().Set(DefaultRequestIDHeader, requestID)
        ctx := context.WithValue(c.Request.Context(), requestIDContextKey, requestID)
        c.Request = c.Request.WithContext(ctx)
        c.Next()
    }
}

4. Logging the Request ID
In your logging system, make sure every log entry includes the Request ID:

log.WithField("request_id", reqID).Info("Processing request")

Using `go-common` for Request ID Handling

If you’re using Go with Gin, you can utilize my go-common library, which already provides a configurable middleware for managing Request IDs. This middleware ensures that each request has a unique identifier, manages propagation, and injects it into the request context. With go-common, you can easily customize the request ID header name and ID generation strategy, making it a flexible solution for various applications.

Example Usage:

router.Use(
    middleware.RequestID(
        middleware.WithRequestIDHeader("X-Custom-Request-ID"), // Use a custom header name.
        middleware.WithRequestIDGenerator(func() string {     // Use a custom generator function.
            return "custom-" + xid.New().String()
        }),
    ),
)

You can find a complete working example here

The middleware performs the following tasks:

Extracts the request ID from the incoming request headers using the specified header name (default: X-Request-ID).
Validates the request ID to ensure it is not empty and does not exceed 64 characters. If invalid or missing, it generates a new request ID using the provided or default generator function.
Sets the request ID in the response headers so that the client knows which request ID was assigned.
Stores the request ID in the request context, making it accessible to downstream middlewares and handlers.

Conclusion 🥂

Request IDs are a simple but powerful tool for improving observability, debugging, and monitoring in distributed systems. Whether you’re working on a monolithic application or microservices architecture, implementing Request IDs can significantly enhance your ability to trace and diagnose issues.

☕ Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

Understanding the Decorator Pattern in Go

Kittipat.po — Mon, 10 Feb 2025 09:56:30 +0000

Decorator Pattern

The Decorator Pattern is a structural design pattern that allows behavior to be dynamically added to objects without modifying their code.

Imagine ordering a cup of coffee at a café: you start with a basic coffee, but you can customize it by adding milk, sugar, or caramel. Each of these additions enhances the coffee without altering its fundamental nature.

Similarly, in software development, the Decorator Pattern allows us to extend the functionality of an object dynamically while keeping its core structure unchanged.

The Decorator Pattern in Action

Let’s illustrate the Decorator Pattern with a simple example before diving into a real-world use case.

Basic Example: Decorating a Notifier
Suppose we have a simple notifier that sends messages:

// Notifier interface
type Notifier interface {
    Send(message string)
}

// Concrete Notifier implementation
type EmailNotifier struct{}

func (e *EmailNotifier) Send(message string) {
    fmt.Println("Sending Email:", message)
}

Now, let's say we want to add SMS notifications without modifying EmailNotifier. We can use the Decorator Pattern:

// SMS Decorator
type SMSNotifier struct {
    WrappedNotifier Notifier
}

func (s *SMSNotifier) Send(message string) {
    s.WrappedNotifier.Send(message) // Call original notifier
    fmt.Println("Sending SMS:", message)
}

With this setup, we can now layer multiple notification methods dynamically:

func main() {
    email := &EmailNotifier{}
    sms := &SMSNotifier{WrappedNotifier: email}

    sms.Send("Hello, World!")
}

Real-World Use Case: Go's `http.RoundTripper`

A great real-world example of the Decorator Pattern in Go is the http.RoundTripper interface used in the http.Client. The RoundTripper interface allows developers to wrap the default HTTP transport with additional behavior, such as logging, authentication, retries, or request modifications. This follows the Decorator Pattern since it enables dynamically extending the HTTP client's functionality without altering the core implementation.

How does `RoundTripper` work?

By default, Go’s http.Client uses http.DefaultTransport (which implements http.RoundTripper) to send HTTP requests. When we set a custom Transport in http.Client, the Do method of http.Client internally calls Transport.RoundTrip, allowing us to modify the request or response within our custom decorator.

How RoundTrip Works: The RoundTrip method is responsible for executing a single HTTP request and returning the response. It is called internally by http.Client.Do(req). If we replace the Transport field in http.Client, every request will pass through our custom RoundTripper, enabling us to modify requests before they are sent and responses before they are returned.

For example, middleware in HTTP clients, such as logging or retry mechanisms, can be implemented by wrapping http.RoundTripper:

// Logging HTTP Client Decorator
type LoggingTransport struct {
    Wrapped http.RoundTripper
}

func (l *LoggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    fmt.Println("Request URL:", req.URL)
    return l.Wrapped.RoundTrip(req)
}

Now, we can use this decorator with an http.Client:

client := &http.Client{
    Transport: &LoggingTransport{
        Wrapped: http.DefaultTransport,
    },
}

This way, we dynamically extend the client's behavior without modifying its core logic, demonstrating the Decorator Pattern in practice.

Combining Multiple `RoundTripper` Decorators

One of the key advantages of the Decorator Pattern is that we can chain multiple Transport decorators together. If we need additional behavior, such as retry logic, we can wrap LoggingTransport inside another transport:

type RetryTransport struct {
    Wrapped http.RoundTripper
    MaxRetries int
}

func (r *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    var resp *http.Response
    var err error
    for i := 0; i < r.MaxRetries; i++ {
        resp, err = r.Wrapped.RoundTrip(req)
        if err == nil {
            return resp, nil
        }
        fmt.Println("Retrying request...", i+1)
    }
    return nil, err
}

Now, we can use both LoggingTransport and RetryTransport together:

client := &http.Client{
    Transport: &RetryTransport{
        Wrapped: &LoggingTransport{
            Wrapped: http.DefaultTransport,
        },
        MaxRetries: 3,
    },
}

In this case:

The request first goes through RetryTransport, which retries the request if needed.
Then, it passes through LoggingTransport, which logs the request details.
Finally, it reaches http.DefaultTransport, which actually sends the request.

Advantages of the Decorator Pattern

Open-Closed Principle: The Decorator Pattern allows us to extend behavior without modifying existing code, adhering to the Open-Closed Principle.
Flexible and Reusable: Decorators can be combined in different ways to achieve various functionalities, making the system highly modular.
Dynamically Add Features: New behaviors can be added at runtime without altering the core object.

Conclusion 🍻

The Decorator Pattern is a powerful tool for extending an object’s functionality without modifying its code. It enables flexible and modular designs, making it an excellent choice for applications that require dynamic behavior enhancements. By understanding and applying the Decorator Pattern, developers can create more maintainable and scalable Go applications, ensuring they can evolve smoothly as new requirements arise.

☕ Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

JWT Tokens in Golang: A Developer’s Guide to Secure APIs

Kittipat.po — Tue, 14 Jan 2025 10:50:10 +0000

Introduction

In modern web development, secure and scalable authentication is essential. JSON Web Tokens (JWT) have become a standard approach to achieving this. In this blog, we’ll explore what JWT is, how it works, and how to implement it in Golang.

What is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe way of representing claims to be securely transferred between two parties. It is commonly used to authenticate and authorize users in APIs and distributed systems.

Structure of a JWT

A JWT consists of three parts separated by dots (.):

Header.Payload.Signature

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.reGQzG3OKdoIMWLDKOZ4TICJit3EW69cQE72E2CfzRE

Each part is:
1.Header: Specifies the token type (JWT) and signing algorithm (HS256).

{
  "alg": "HS256",
  "typ": "JWT"
}

2.Payload: Contains claims (user data like id, role, or name).

{
    "sub": "1234567890",
    "name": "John Doe",
    "admin": true,
    "iat": 1516239022
}

3.Signature: Ensures the token’s integrity using a cryptographic signing process. Let’s explore this in detail.

The signature is created by:

Concatenating the Encoded Header and Payload:
  base64UrlEncode(header) + "." + base64UrlEncode(payload)
Signing the Result:

A cryptographic signing algorithm (e.g., HMACSHA256, RS256) is used with a secret or private key.

Appending the Signature: The final JWT becomes
  header.payload.signature

How JWT Works

The client sends login credentials to the server.
If valid, the server generates a JWT and returns it to the client.
The client stores the JWT (e.g., in localStorage or cookies).
For every request, the client includes the JWT in the Authorization header: Authorization: Bearer <token>
The server validates the JWT on each request.
- Recalculating the signature using the received header and payload.
  - In symmetric encryption (e.g. HS256), the same secret key is used for both encryption (or signing) and decryption (or verification).
  - In asymmetric encryption (e.g. RS256), a pair of keys is used: a private key and a public key. The private key is used for signing and the public key is used for verification. This means that anyone who has the public key can verify signatures, but they cannot create valid signatures without the private key.
- Comparing the recalculated signature with the received signature.

Implementing JWT in Golang

Golang developers can leverage the excellent golang-jwt/jwt library for handling JWTs. This library provides robust features for creating, signing, and validating JWTs. You can find it here.

However, managing JWTs often requires repetitive tasks like configuring signing methods, parsing tokens, and validating claims. To simplify this, I’ve written a custom package that wraps the golang-jwt functionality. You can check out my package here.

Below is an example of how to use my custom JWT package.

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/golang-jwt/jwt/v5"
    jwtutil "github.com/kittipat1413/go-common/util/jwt"
)

type MyCustomClaims struct {
    jwt.RegisteredClaims
    UserID string `json:"uid"`
}

func main() {
    ctx := context.Background()
    signingKey := []byte("super-secret-key")
    manager, err := jwtutil.NewJWTManager(jwtutil.HS256, signingKey)
    if err != nil {
        log.Fatalf("Failed to create JWTManager: %v", err)
    }

    // Prepare custom claims
    claims := &MyCustomClaims{
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(15 * time.Minute)),
            Issuer:    "example-HS256",
            Subject:   "example-subject",
        },
        UserID: "abc123",
    }

    // Create the token
    tokenStringHS256, err := manager.CreateToken(ctx, claims)
    if err != nil {
        log.Fatalf("Failed to create token: %v", err)
    }
    fmt.Println("Generated Token:", tokenStringHS256)

    // Validate the token
    parsedClaims := &MyCustomClaims{}
    err = manager.ParseAndValidateToken(ctx, tokenStringHS256, parsedClaims)
    if err != nil {
        log.Fatalf("Failed to validate token: %v", err)
    }

    fmt.Printf("Token is valid! UserID: %s, Issuer: %s\n", parsedClaims.UserID, parsedClaims.Issuer)
}

You can explore the full implementation and documentation of my package on GitHub: here.

Best Practices for JWT

Use HTTPS: Always transmit tokens over secure channels.
Set Expiration Times: Include a reasonable exp to limit token misuse.
Secure the Secret Key: Store keys securely using environment variables or secret managers.
Avoid Sensitive Data in Payload: Only include non-critical information.
Use Refresh Tokens: Pair JWT with refresh tokens to securely extend sessions.

Conclusion 🥂

JWT is a powerful tool for secure, stateless authentication. The signature ensures token integrity and authenticity, making JWT ideal for APIs and distributed systems. With libraries like jwt-go, you can easily implement JWT in your Golang projects.

☕ Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

Understanding Digital Signatures: The Key to Secure Communications

Kittipat.po — Fri, 27 Dec 2024 11:20:19 +0000

Introduction

In today’s interconnected world, digital communication forms the backbone of personal, professional, and commercial interactions. However, as our reliance on digital systems grows, so does the need for robust mechanisms to ensure trust, authenticity, and data integrity. This is where digital signatures come into play. Acting as the modern-day equivalent of a handwritten signature, they provide a secure way to authenticate the origin of data and guarantee its integrity. In this blog, we’ll explore what digital signatures are, how they work, and why they’re a vital component of secure communications.

What is a Digital Signature?

A digital signature is a cryptographic technique that ensures data integrity and authenticity. It acts as a virtual fingerprint for electronic documents or messages, certifying that they originated from a specific sender and have not been altered during transmission.

Here’s how digital signatures work in a nutshell:

Key Pair Generation: The sender generates a public-private key pair. The private key remains confidential, while the public key is shared.
Signing the Data: Before signing, the sender first creates a unique hash (a fixed-size string) of the data using a cryptographic hash function like SHA-256. This hash represents the data in a condensed, irreversible form. The private key is then used to encrypt this hash, creating the digital signature.
Verification: Upon receiving the data and the digital signature, the recipient uses the sender’s public key to decrypt the signature and retrieve the hash. The recipient then calculates their own hash of the received data using the same hash function. If the decrypted hash matches the calculated hash, the signature is valid.

Why Use Digital Signatures?

Digital signatures offer multiple benefits, making them a vital component of secure communications:

Data Integrity: Digital signatures ensure that the data has not been altered during transmission. Even a tiny change in the original data will result in a completely different hash, making any tampering immediately detectable.
Authentication: Digital signatures confirm the identity of the sender by tying the signature to their unique private key. Only the sender with access to this private key could have created the signature.
Non-repudiation: Digital signatures provide proof that the sender signed the document or message. Since the private key is unique and confidential, the sender cannot later deny having signed it.

Digital Signatures in Practice

Let’s explore a practical implementation of digital signatures in Go to understand their inner workings.

package main

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
)

func generateKeyPair() (*rsa.PrivateKey, *rsa.PublicKey) {
    privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
    if err != nil {
        panic(err)
    }
    return privateKey, &privateKey.PublicKey
}

func signData(privateKey *rsa.PrivateKey, data []byte) string {
    hashed := sha256.Sum256(data)
    signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, hashed[:])
    if err != nil {
        panic(err)
    }
    return base64.StdEncoding.EncodeToString(signature)
}

func verifySignature(publicKey *rsa.PublicKey, data []byte, signature string) bool {
    hashed := sha256.Sum256(data)
    decodedSig, err := base64.StdEncoding.DecodeString(signature)
    if err != nil {
        panic(err)
    }
    err = rsa.VerifyPKCS1v15(publicKey, crypto.SHA256, hashed[:], decodedSig)
    return err == nil
}

func main() {
    privateKey, publicKey := generateKeyPair()
    fmt.Println("Keys generated successfully.")

    message := []byte("Secure this message")
    signature := signData(privateKey, message)

    isValid := verifySignature(publicKey, message, signature)
    if isValid {
        fmt.Println("Signature is valid.")
    } else {
        fmt.Println("Signature is invalid.")
    }
}

Using Digital Signatures in REST APIs

In the context of REST APIs, digital signatures play a vital role in securing communication between clients and servers. To implement digital signatures effectively, they are often added as custom headers in the HTTP request and response. A typical implementation might include headers such as:

X-Signature: Contains the Base64-encoded digital signature of the payload, generated using the sender’s private key.
X-Public-Key-ID: Identifies the public key used to verify the signature. This could be a unique key identifier or reference that allows the receiver to fetch the correct public key from a key registry.
X-Timestamp: Ensures the signature’s validity for a specific time window, helping to mitigate replay attacks.

For example, when sending an API request, the client signs the payload and includes these headers to ensure the server can authenticate the request and verify its integrity. Similarly, servers can sign responses to assure clients that the data is untampered and legitimate. Naming headers descriptively, like X-Signature and X-Public-Key-ID, ensures clarity and consistency in implementation across APIs.

Incorporating digital signatures into REST APIs enhances security by preventing tampering, authenticating request origins, and ensuring trust in sensitive operations such as financial transactions or identity verification.

Conclusion 🥂

Digital signatures are a linchpin of modern cryptography, enabling secure and trustworthy digital communications. By implementing digital signatures in your applications, you can ensure that data integrity, authenticity, and non-repudiation are maintained.

☕ Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

Configuration Management in Go with Viper

Kittipat.po — Mon, 16 Dec 2024 16:07:46 +0000

A Guide to Configuration Management in Go with Viper

Kittipat.po ・ Dec 3

#go #webdev #backend #programming

A Guide to Configuration Management in Go with Viper

Kittipat.po — Tue, 03 Dec 2024 09:27:23 +0000

Introduction

Managing configurations efficiently is a cornerstone of building scalable and maintainable software. In Go, the Viper package 🐍 stands out as a robust solution for managing application configurations. With support for multiple file formats, environment variables, and seamless unmarshaling to structs, Viper simplifies configuration management for modern applications.

In this blog, we’ll walk through how to use Viper to load and manage configurations from different sources, map them to Go structs, and integrate environment variables dynamically.

👩‍💻 Setting Up Viper:

Let’s dive into the practical implementation of Viper in a Go application. For this guide, we’ll use a simple application configuration example with a YAML file and environment variables.

Step 1: Install the Viper Package

Start by installing Viper in your project:

go get github.com/spf13/viper

Step 2: Create a Configuration File

Create a config.yaml file in your project’s root directory. This file will define the default configuration for your application:

app:
  name: "MyApp"
  port: 8080
namespace: "myapp"
owner: "John Doe"

🔨 Implementing Viper in Go

Here’s how you can use Viper in your application. Below is the example code from main.go:

package main

import (
    "fmt"
    "log"
    "strings"

    "github.com/spf13/viper"
)

type AppConfig struct {
    App struct {
        Name string `mapstructure:"name"`
        Port int    `mapstructure:"port"`
    } `mapstructure:"app"`
    NS    string `mapstructure:"namespace"`
    Owner string `mapstructure:"owner"`
}

func main() {
    // Set up viper to read the config.yaml file
    viper.SetConfigName("config") // Config file name without extension
    viper.SetConfigType("yaml")   // Config file type
    viper.AddConfigPath(".")      // Look for the config file in the current directory


    /*
        AutomaticEnv will check for an environment variable any time a viper.Get request is made.
        It will apply the following rules.
            It will check for an environment variable with a name matching the key uppercased and prefixed with the EnvPrefix if set.
    */
    viper.AutomaticEnv()
    viper.SetEnvPrefix("env")                              // will be uppercased automatically
    viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_")) // this is useful e.g. want to use . in Get() calls, but environmental variables to use _ delimiters (e.g. app.port -> APP_PORT)

    // Read the config file
    err := viper.ReadInConfig()
    if err != nil {
        log.Fatalf("Error reading config file, %s", err)
    }

    // Set up environment variable mappings if necessary
    /*
        BindEnv takes one or more parameters. The first parameter is the key name, the rest are the name of the environment variables to bind to this key.
        If more than one are provided, they will take precedence in the specified order. The name of the environment variable is case sensitive.
        If the ENV variable name is not provided, then Viper will automatically assume that the ENV variable matches the following format: prefix + "_" + the key name in ALL CAPS.
        When you explicitly provide the ENV variable name (the second parameter), it does not automatically add the prefix.
            For example if the second parameter is "id", Viper will look for the ENV variable "ID".
    */
    viper.BindEnv("app.name", "APP_NAME") // Bind the app.name key to the APP_NAME environment variable

    // Get the values, using env variables if present
    appName := viper.GetString("app.name")
    namespace := viper.GetString("namespace") // AutomaticEnv will look for an environment variable called `ENV_NAMESPACE` ( prefix + "_" + key in ALL CAPS)
    appPort := viper.GetInt("app.port")       // AutomaticEnv will look for an environment variable called `ENV_APP_PORT` ( prefix + "_" + key in ALL CAPS with _ delimiters)

    // Output the configuration values
    fmt.Printf("App Name: %s\n", appName)
    fmt.Printf("Namespace: %s\n", namespace)
    fmt.Printf("App Port: %d\n", appPort)

    // Create an instance of AppConfig
    var config AppConfig
    // Unmarshal the config file into the AppConfig struct
    err = viper.Unmarshal(&config)
    if err != nil {
        log.Fatalf("Unable to decode into struct, %v", err)
    }

    // Output the configuration values
    fmt.Printf("Config: %v\n", config)
}

Using Environment Variables 🌐

To integrate environment variables dynamically, create a .env file with the following content:

export APP_NAME="MyCustomApp"
export ENV_NAMESPACE="go-viper"
export ENV_APP_PORT=9090

Run the command to load the environment variables:

source .env

In the code, Viper’s AutomaticEnv and SetEnvKeyReplacer methods allow you to map nested configuration keys like app.port to environment variables such as APP_PORT. Here’s how it works:

Prefix with SetEnvPrefix: The line viper.SetEnvPrefix("env") ensures that all environment variable lookups are prefixed with ENV_. For example:
- app.port becomes ENV_APP_PORT
- namespace becomes ENV_NAMESPACE
Key Replacements with SetEnvKeyReplacer: The SetEnvKeyReplacer(strings.NewReplacer(".", "_")) replaces . with _ in the key names, so nested keys like app.port can map directly to environment variables.

By combining these two methods, you can seamlessly override specific configuration values using environment variables.

🚀 Running the Example

Run the application using:

go run main.go

Expected Output:

App Name: MyCustomApp
Namespace: go-viper
App Port: 9090
Config: {{MyCustomApp 9090} go-viper John Doe}

Best Practices 🌟

Use Environment Variables for Sensitive Data:Avoid storing secrets in config files. Use environment variables or secret management tools.
Set Default Values: Use viper.SetDefault("key", value) to ensure your application has sensible defaults.
Validate Configuration: After loading configurations, validate them to prevent runtime errors.
Keep Configuration Organized: Group related configurations together and use nested structs for clarity.

🔧 Using Viper with `go-common` Config Package

While Viper is a powerful tool for configuration management, in production-grade systems, it’s often beneficial to abstract and standardize how configuration is loaded, validated, and injected across services. That’s exactly what the go-common library provides via its config package.

Built on top of Viper, the config package simplifies and unifies your configuration loading process with:

Required or optional YAML file loading
Fallback default injection
Context-aware config propagation

Example: Using go-common Config in Your App

package main

import (
    "fmt"

    "github.com/kittipat1413/go-common/framework/config"
)

func main() {
    cfg := config.MustConfig(
        config.WithRequiredConfigPath("env.yaml"),
        config.WithDefaults(map[string]any{
            "SERVICE_NAME": "my-service",
            "SERVICE_PORT": ":8080",
            "ENV":          "development",
        }),
    )

    fmt.Println("=== Service Config ===")
    fmt.Println("Service Name:", cfg.GetString("SERVICE_NAME"))
    fmt.Println("Port:", cfg.GetString("SERVICE_PORT"))
    fmt.Println("Environment:", cfg.GetString("ENV"))
}

Then in your env.yaml file, you can override any field:

SERVICE_NAME: "user-api"
SERVICE_PORT: ":9090"
ENV: "staging"

🧪 Example in Practice
This approach is already used in real-world-style projects like my 🎟️ ticket-reservation system, which demonstrates how the go-common library can be used to manage configurations consistently across services.

📝 Conclusion

By leveraging Viper, you can simplify configuration management in your Go applications. Its flexibility to integrate multiple sources, dynamic environment variable support, and unmarshaling to structs make it an indispensable tool for developers.

Start using Viper in your next project and experience hassle-free configuration management. Happy coding! 🥂

Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

Checking if a Type Satisfies an Interface in Go

Kittipat.po — Thu, 31 Oct 2024 04:34:08 +0000

In Go, developers often use interface to define expected behavior, making code flexible and robust. But how do you ensure a type truly implements an interface, especially in a large codebase? Go provides a simple and effective way to verify this at compile time, preventing the risk of runtime errors and making your code more reliable and readable.

You might have seen syntax like

var _ InterfaceName = TypeName{} 
// or 
var _ InterfaceName = (*TypeName)(nil)

in Go code. This article will walk you through what these lines do and why they’re essential.

How to Check Interface Satisfaction in Go

In Go, to check if a type (e.g., a struct) implements an interface, you can add a compile-time assertion. This assertion tells the Go compiler, “Make sure this type implements this interface—now, not at runtime.”

There are two ways to do this:

var _ InterfaceName = TypeName{}

or, if the interface requires pointer receivers:

var _ InterfaceName = (*TypeName)(nil)

If TypeName does not fully implement InterfaceName (i.e., if it’s missing required methods), the Go compiler will raise an error immediately. This simple check ensures your types comply with the interface they’re expected to fulfill, long before you run your code.

When to Use Value or Pointer Receivers

The choice between TypeName{} and (*TypeName)(nil) depends on how your type’s methods are defined:

Value Receivers: If TypeName implements interface methods with value receivers (e.g., func (t TypeName) Method()), you can use either TypeName{} or (*TypeName)(nil) in your assertion. Both options will work since Go can convert values to pointers where needed.
Pointer Receivers: If TypeName implements any methods with pointer receivers (e.g., func (t *TypeName) Method()), you must use (*TypeName)(nil). This ensures that a pointer to the type satisfies the interface, as only a pointer will be able to call the method.

Benefits of Compile-Time Interface Satisfaction Checks

Using compile-time checks provides several advantages:

Compile-Time Safety: This method catches potential issues early by ensuring that types meet all the requirements of the interface, helping you avoid nasty surprises at runtime.
Clear Documentation: These assertions serve as documentation, showing explicitly that a type is expected to implement a specific interface. Anyone reading your code will immediately see that this type is intended to satisfy the interface, making the code more readable and maintainable.
Flexible Code Refactoring: With this assurance in place, you can confidently refactor code or change interface methods, knowing that the compiler will alert you if any type falls out of compliance.

Example in Practice

Let’s look at an example to make it concrete. Suppose we have a simple interface Shape and a struct Circle:

type Shape interface {
    Area() float64
}

type Circle struct {
    Radius float64
}

func (c Circle) Area() float64 {
    return 3.14 * c.Radius * c.Radius
}

To verify that Circle implements Shape, we can add a compile-time assertion:

var _ Shape = Circle{}

or, if Circle’s methods required pointer receivers:

var _ Shape = (*Circle)(nil)

📝 Conclusion

Using compile-time assertions to check if a type satisfies an interface is a best practice in Go. It not only guarantees that types meet their interface contracts, reducing the risk of runtime errors, but also improves code readability and maintainability. This approach is especially beneficial in larger or polymorphic codebases where interfaces are central to the design.

☕ Support My Work ☕

If you enjoy my work, consider buying me a coffee! Your support helps me keep creating valuable content and sharing knowledge. ☕

DEV Community: Kittipat.po

Building Powerful CLI Tools in Go with Cobra 🐍

Introduction

Installation & Project Setup 🛠️

Your First Command 🚀

Subcommands 🌲

Flags 🚩

The 4 naming patterns

String and StringP — Cobra gives you the pointer

StringVar and StringVarP — you own the variable

When to add P (shorthand)

Local vs Persistent flags

Check if a flag was explicitly set

Arguments & Validation 🔒

Lifecycle Hooks ⚙️

Error Handling 🛡️

📝 Conclusion

Support My Work ☕

Structured Logging in Go: Context-Aware, JSON-Ready, and Production-Proven

Every developer has been there:

The Evolution of Logging 🧭

The Problem With Go’s Default Logging

Introducing the Logger Package 🎉

How It Works ⚙️

Final Thoughts ✨

Prevent Race Conditions in Go Microservices with Distributed Locks

Introduction

What is a Distributed Lock?

Redsync: Redis-based Locking 🔒

🤝 Simplifying with go-common LockManager

Pitfalls to Avoid ⚠️

Conclusion 🎯

Structuring a Go Project with Clean Architecture — A Practical Example

🧠 Applying Clean Architecture in Go — A Real-World Project Walkthrough

🧭 Why Clean Architecture?

🧱 Folder Structure Breakdown

🧩 Clean Architecture in Action

🛠️ Built-in CLI Tools

🔄 Project Status

Coding Tips #1: Name Your Maps Like You Care About Your Future Self

🧠 So What’s the Fix?

🔁 In General: Use keyToValue Naming for Maps

Understanding Request ID: Why It's Essential for Modern APIs

Introduction

What is a Request ID?

Example:

Why Implement Request IDs?

How to Implement Request ID

Using go-common for Request ID Handling

Conclusion 🥂

☕ Support My Work ☕

Understanding the Decorator Pattern in Go

Decorator Pattern

The Decorator Pattern in Action

Real-World Use Case: Go's http.RoundTripper

How does RoundTripper work?

Combining Multiple RoundTripper Decorators

Advantages of the Decorator Pattern

Conclusion 🍻

☕ Support My Work ☕

JWT Tokens in Golang: A Developer’s Guide to Secure APIs

Introduction

What is a JWT?

Structure of a JWT

How JWT Works

Implementing JWT in Golang

Best Practices for JWT

Conclusion 🥂

☕ Support My Work ☕

Understanding Digital Signatures: The Key to Secure Communications

Introduction

What is a Digital Signature?

Why Use Digital Signatures?

Digital Signatures in Practice

Using Digital Signatures in REST APIs

Conclusion 🥂

☕ Support My Work ☕

Configuration Management in Go with Viper

A Guide to Configuration Management in Go with Viper

Kittipat.po ・ Dec 3

`String` and `StringP` — Cobra gives you the pointer

`StringVar` and `StringVarP` — you own the variable

When to add `P` (shorthand)

🤝 Simplifying with go-common `LockManager`

🔁 In General: Use `keyToValue` Naming for Maps

Using `go-common` for Request ID Handling

Real-World Use Case: Go's `http.RoundTripper`

How does `RoundTripper` work?

Combining Multiple `RoundTripper` Decorators

🔧 Using Viper with `go-common` Config Package