pn-go-scaffolding

Go backend scaffolding

When to use

• Starting a new Go API project.
• Adding a new handler, route group, or domain package.
• Establishing project structure from scratch.

Project structure

# Standard Go layout
cmd/
  server/
    main.go           # Entry point: init config, DB, router, start server
internal/
  users/
    handler.go        # HTTP handlers for the users domain
    service.go        # Business logic
    repository.go     # DB queries for users
    model.go          # User struct + domain types
  orders/
    handler.go
    service.go
    repository.go
  middleware/
    auth.go
    logger.go
    recover.go
  config/
    config.go         # Typed config from env vars
  db/
    db.go             # DB connection pool setup
  apierr/
    errors.go         # Sentinel errors + HTTP mapping
go.mod
go.sum
.env.example

• cmd/ for binary entry points.
• internal/ for everything that is not a public library. Prevents external packages from importing your internals.
• Never put business logic in main.go.

Gin scaffold

// internal/users/handler.go
package users

import (
	"net/http"
	"strconv"

	"github.com/gin-gonic/gin"
	"yourmodule/internal/apierr"
)

type Handler struct {
	svc *Service
}

func NewHandler(svc *Service) *Handler {
	return &Handler{svc: svc}
}

func (h *Handler) RegisterRoutes(rg *gin.RouterGroup) {
	rg.POST("", h.Create)
	rg.GET("/:id", h.GetByID)
}

func (h *Handler) Create(c *gin.Context) {
	var req CreateUserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": gin.H{"code": "BAD_REQUEST", "message": err.Error()}})
		return
	}
	user, err := h.svc.Create(c.Request.Context(), req)
	if err != nil {
		apierr.Respond(c, err)
		return
	}
	c.JSON(http.StatusCreated, gin.H{"data": user})
}

func (h *Handler) GetByID(c *gin.Context) {
	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": gin.H{"code": "BAD_REQUEST", "message": "Invalid ID"}})
		return
	}
	user, err := h.svc.GetByID(c.Request.Context(), id)
	if err != nil {
		apierr.Respond(c, err)
		return
	}
	c.JSON(http.StatusOK, gin.H{"data": user})
}