Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-architect

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/golden-main-small-project.md

View on GitHub
# Golden main.go — Small Project Template

Single-domain app (e.g. a users API). All wiring in one place, no feature module splitting.

---

## Complete main.go

```go
package main

import (
	"context"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/jmoiron/sqlx"
	_ "github.com/lib/pq"

	"myapp/internal/config"
	"myapp/internal/handler"
	"myapp/internal/repository"
	"myapp/internal/service"
	"myapp/pkg/middleware"
)

func main() {
	// 1. Logger — initialized first so everything else can log
	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelInfo,
	}))

	// 2. Config
	cfg, err := config.Load()
	if err != nil {
		logger.Error("failed to load config", "error", err)
		os.Exit(1)
	}

	// 3. Database — repositories depend on it
	db, err := sqlx.Connect("postgres", cfg.DatabaseURL)
	if err != nil {
		logger.Error("failed to connect to database", "error", err)
		os.Exit(1)
	}
	db.SetMaxOpenConns(cfg.DBMaxOpenConns)
	db.SetMaxIdleConns(cfg.DBMaxIdleConns)
	db.SetConnMaxLifetime(cfg.DBConnMaxLifetime)
	defer db.Close()

	// 4. Wire dependencies — manual DI: repo → service → handler
	userRepo := repository.NewUserRepository(db)
	userSvc := service.NewUserService(userRepo, logger)
	userHandler := handler.NewUserHandler(userSvc, logger)
	healthHandler := handler.NewHealthHandler(db, logger)

	// 5. Router — gin.New() never gin.Default()
	if cfg.GinMode == "release" {
		gin.SetMode(gin.ReleaseMode)
	}
	r := gin.New()
	r.Use(gin.Recovery())
	r.Use(middleware.RequestID())
	r.Use(middleware.Logger(logger))
	r.Use(middleware.CORS(cfg.AllowedOrigins))

	// 6. Routes
	r.GET("/health", healthHandler.Check)
	api := r.Group("/api/v1")
	api.GET("/users/:id", userHandler.GetByID)
	api.POST("/users", userHandler.Create)
	api.PUT("/users/:id", userHandler.Update)
	api.DELETE("/users/:id", userHandler.Delete)

	// 7. HTTP server with explicit timeouts
	srv := &http.Server{
		Addr:         ":" + cfg.Port,
		Handler:      r,
		ReadTimeout:  cfg.ReadTimeout,
		WriteTimeout: cfg.WriteTimeout,
		IdleTimeout:  cfg.IdleTimeout,
	}

	go func() {
		logger.Info("server starting", "port", cfg.Port, "mode", cfg.GinMode)
		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			logger.Error("server error", "error", err)
			os.Exit(1)
		}
	}()

	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit
	logger.Info("shutdown signal received")

	ctx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
	defer cancel()
	if err := srv.Shutdown(ctx); err != nil {
		logger.Error("server forced shutdown", "error", err)
		os.Exit(1)
	}
	logger.Info("server stopped")
}
```

---

## Config Struct

`internal/config/config.go`:

```go
type Config struct {
	Port              string
	GinMode           string
	DatabaseURL       string
	DBMaxOpenConns    int
	DBMaxIdleConns    int
	DBConnMaxLifetime time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
	ShutdownTimeout   time.Duration
	AllowedOrigins    []string
}

func Load() (*Config, error) {
	return &Config{
		Port:              getEnv("PORT", "8080"),
		GinMode:           getEnv("GIN_MODE", "debug"),
		DatabaseURL:       mustEnv("DATABASE_URL"),
		DBMaxOpenConns:    getEnvInt("DB_MAX_OPEN_CONNS", 25),
		DBMaxIdleConns:    getEnvInt("DB_MAX_IDLE_CONNS", 5),
		DBConnMaxLifetime: getEnvDuration("DB_CONN_MAX_LIFETIME", 5*time.Minute),
		ReadTimeout:       getEnvDuration("READ_TIMEOUT", 10*time.Second),
		WriteTimeout:      getEnvDuration("WRITE_TIMEOUT", 10*time.Second),
		IdleTimeout:       getEnvDuration("IDLE_TIMEOUT", 60*time.Second),
		ShutdownTimeout:   getEnvDuration("SHUTDOWN_TIMEOUT", 30*time.Second),
	}, nil
}
```

**Conventions enforced:** `gin.New()` (not `gin.Default()`), `log/slog` JSON handler, `ShouldBind*` in handlers, `c.Request.Context()` propagated, explicit `http.Server` timeouts, pool configured before first query. See also: `golden-main-medium-project.md`.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall