Golang Web Modules

Common solution collection for quickly setting up Golang web applications. This library provides a modular plugin architecture with factory functions and config-driven initialization for common web application components.

📚 Documentation

Full API Documentation on pkg.go.dev →

🚀 Quick Start

Installation

go get github.com/poly-workshop/go-webmods

Basic Usage

package main

import (
    "log/slog"
    "github.com/poly-workshop/go-webmods/app"
    gormclient "github.com/poly-workshop/go-webmods/gormclient"
)

func main() {
    // Initialize application with configuration
    app.SetCMDName("myapp")
    app.Init(".")  // Loads config from ./configs/

    // Initialize database
    db := gormclient.NewDB(gormclient.Config{
        Driver:   "postgres",
        Host:     "localhost",
        Port:     5432,
        Username: "user",
        Password: "password",
        DbName:   "mydb",
        SSLMode:  "disable",
    })

    slog.Info("Application started successfully")
    _ = db
}

📦 Packages

app

Core application utilities including:

• Layered configuration management (Viper)
• Structured logging with context propagation (slog)
• Application initialization helpers

gormclient

Database client factory supporting:

• PostgreSQL
• MySQL
• SQLite
• Connection pooling configuration

mongoclient

MongoDB client factory using the v2 driver:

• MongoDB Atlas support
• Connection pooling and timeouts
• Ping verification on startup

redisclient

Redis client with:

• Single-node and cluster mode support
• Two-level caching (local + distributed)
• Automatic cache invalidation via pub/sub

kafkaclient

Kafka client helpers with:

• Reader factory (consumer group or partition)
• Writer factory with configurable batching and acknowledgements

objectstorage

Unified object storage interface supporting:

• Local filesystem
• MinIO / S3-compatible storage
• Volcengine TOS

grpcutils

gRPC server interceptors for:

• Structured logging
• Request ID generation and propagation
• Context-aware tracing

smtpmailer

SMTP email client with:

• TLS support
• HTML and plain text emails
• Multiple recipients support

🏗️ Architecture Patterns

Factory Pattern

Every component uses a Config struct and factory function:

component := package.NewComponent(package.Config{...})

Provider Pattern

Multi-backend support with unified interfaces:

storage, err := objectstorage.NewObjectStorage(objectstorage.Config{
    ProviderType: objectstorage.ProviderLocal,
    ProviderConfig: objectstorage.ProviderConfig{
        BasePath: "/data",
    },
})

Context-Aware Logging

Structured logging with automatic context propagation:

ctx = app.WithLogAttrs(ctx, slog.String("user_id", "123"))
slog.InfoContext(ctx, "User logged in") // Includes user_id automatically

⚙️ Configuration

Configuration uses Viper with layered loading:

1. configs/default.yaml - Base configuration
2. configs/{MODE}.yaml - Environment-specific overrides
3. Environment variables - Final overrides (using __ separator)

Example configs/default.yaml:

log:
  level: info
  format: tint

database:
  driver: postgres
  host: localhost
  port: 5432
  username: user
  password: pass
  name: mydb
  sslmode: disable

Set environment mode:

export MODE=production  # Loads configs/production.yaml

Override with environment variables:

export LOG__LEVEL=debug
export DATABASE__HOST=prod-db

📖 Examples

See the examples in pkg.go.dev for detailed usage examples of each package.

🧪 Development

Run Tests

go test ./...

Format Code

make fmt

Lint Code

make lint

📄 License

This repo is granted under the MIT License. Feel free to use it in your projects.