Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-backend-go-chi-gorm

tpl-backend-go-chi-gorm

Verified

Template do pack (backend/04-go-chi-gorm.md). Orienta o agente em APIs, servicos e arquitetura backend alinhado a esse contexto.

PROJECT: Go REST API (Chi + GORM)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: backend/04-go-chi-gorm.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

TechnologyVersionPurpose
Go1.22+Language + runtime
Chiv5HTTP router + middleware
GORMv2ORM + migrations
PostgreSQL16Primary database
pgx/v55.xPostgreSQL driver
golang-jwt/jwtv5JWT tokens
bcryptstdlibPassword hashing
testifyv1.9+Assertions + mocking
slogstdlib (1.21+)Structured logging
golangci-lint1.58+Linting suite
godotenv1.5+.env loader for dev

PROJECT STRUCTURE

cmd/
└── api/
    └── main.go           # Entry point: setup + server.ListenAndServe
internal/
├── config/
│   └── config.go         # Config struct + Load() from env
├── server/
│   └── server.go         # Chi router setup, middleware chain, routes
├── handlers/
│   └── users/
│       ├── handler.go    # HTTP handler methods (thin, calls service)
│       └── handler_test.go
├── services/
│   └── users/
│       ├── service.go    # Business logic interface + implementation
│       └── service_test.go
├── repositories/
│   └── users/
│       ├── repository.go # GORM queries implementing interface
│       └── repository_test.go
├── models/
│   └── user.go           # GORM model structs
├── middleware/
│   ├── auth.go           # JWT verification middleware
│   ├── logger.go         # Request logging middleware
│   └── recover.go        # Panic recovery middleware
├── dto/
│   └── users/
│       ├── request.go    # Input structs with validate tags
│       └── response.go   # Output structs (no sensitive fields)
└── database/
    └── database.go       # GORM db connection + AutoMigrate
go.mod
go.sum
.golangci.yml
Makefile

ARCHITECTURE RULES

  • Handler → Service → Repository — never skip levels
  • Define interfaces in the consumer package (service defines its repo interface)
  • Handlers receive *Handler with service interface injected via constructor
  • Services receive Repository interface — not the concrete struct
  • No global state — pass dependencies explicitly (no db package-level variable)
  • All exported functions have godoc comments (// FunctionName does X)
  • JSON tags on all struct fields — never rely on Go's default capitalization
  • Time fields: always time.Time with json:"created_at" (UTC, no timezone stored)

GO-SPECIFIC RULES

Error Handling Pattern

Rule: Never ignore errors. Wrap with context. Return early on error.

// Good — wrap errors with context
func (s *UserService) GetByID(ctx context.Context, id string) (*models.User, error) {
    user, err := s.repo.FindByID(ctx, id)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, ErrUserNotFound // sentinel error
        }
        return nil, fmt.Errorf("UserService.GetByID: %w", err)
    }
    return user, nil
}

// Handler (convert service errors to HTTP responses)
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    user, err := h.svc.GetByID(r.Context(), id)
    if err != nil {
        if errors.Is(err, service.ErrUserNotFound) {
            respondError(w, http.StatusNotFound, "user not found")
            return
        }
        slog.ErrorContext(r.Context(), "failed to get user", "error", err, "id", id)
        respondError(w, http.StatusInternalServerError, "internal error")
        return
    }
    respondJSON(w, http.StatusOK, toUserResponse(user))
}

Interface Pattern

// internal/repositories/users/repository.go
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*models.User, error)
    FindByEmail(ctx context.Context, email string) (*models.User, error)
    Create(ctx context.Context, user *models.User) error
    Update(ctx context.Context, user *models.User) error
    Delete(ctx context.Context, id string) error
}

Goroutine Safety Rules

  • Never share mutable state between goroutines without a mutex or channel
  • Use context.Context for cancellation — always accept ctx context.Context as first param
  • Goroutines spawned in handlers must be tracked (use errgroup.Group or waitgroup)
  • Database operations: GORM's *gorm.DB is safe for concurrent use (connection pool)
  • Never close over loop variables in goroutines — capture explicitly

Chi Middleware Pattern

// internal/server/server.go
func NewRouter(cfg *config.Config, userHandler *userhandler.Handler) *chi.Mux {
    r := chi.NewRouter()

    // Global middlewares (order matters)
    r.Use(middleware.RequestID)
    r.Use(middleware.RealIP)
    r.Use(loggerMiddleware.New(slog.Default()))
    r.Use(recoverMiddleware.New())
    r.Use(chimiddleware.Timeout(30 * time.Second))

    r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    r.Route("/api/v1", func(r chi.Router) {
        r.Post("/auth/login", userHandler.Login)
        r.Post("/auth/register", userHandler.Register)

        r.Group(func(r chi.Router) {
            r.Use(authmiddleware.Authenticate(cfg.JWTSecret))
            r.Get("/users/me", userHandler.Me)
            r.Patch("/users/me", userHandler.UpdateMe)
        })
    })

    return r
}

JWT Auth Middleware

// internal/middleware/auth.go
func Authenticate(secret string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            header := r.Header.Get("Authorization")
            if !strings.HasPrefix(header, "Bearer ") {
                http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
                return
            }
            tokenStr := header[7:]
            token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
                if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
                    return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
                }
                return []byte(secret), nil
            })
            if err != nil || !token.Valid {
                http.Error(w, `{"error":"invalid or expired token"}`, http.StatusUnauthorized)
                return
            }
            claims := token.Claims.(jwt.MapClaims)
            ctx := context.WithValue(r.Context(), ctxKeyUserID, claims["sub"])
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

GORM Hooks

// internal/models/user.go
func (u *User) BeforeCreate(tx *gorm.DB) error {
    u.ID = uuid.New().String()
    hashed, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
    if err != nil {
        return fmt.Errorf("failed to hash password: %w", err)
    }
    u.Password = string(hashed)
    return nil
}

ROUTING TABLE

TriggerMethodRouteMiddlewareHandler
RegisterPOST/api/v1/auth/register—UserHandler.Register
LoginPOST/api/v1/auth/login—UserHandler.Login
Refresh tokenPOST/api/v1/auth/refresh—UserHandler.Refresh
Get my profileGET/api/v1/users/meAuthenticateUserHandler.Me
Update profilePATCH/api/v1/users/meAuthenticateUserHandler.UpdateMe
List usersGET/api/v1/usersAuthenticate, RequireAdminUserHandler.List
Get userGET/api/v1/users/{id}Authenticate, RequireAdminUserHandler.Get
Delete userDELETE/api/v1/users/{id}Authenticate, RequireAdminUserHandler.Delete
Health checkGET/health—inline

QUALITY GATES

Before opening a PR, verify ALL of the following:

  • golangci-lint run ./... passes with zero warnings
  • go test ./... -race -count=1 passes — no race conditions
  • go vet ./... clean
  • Coverage: go test ./... -coverprofile=cover.out ≥ 75%
  • go build ./cmd/api/... compiles without warnings
  • No interface{} — use any (Go 1.18+) or specific types
  • All context parameters are first argument: func F(ctx context.Context, ...)
  • No log.Fatal outside of main.go
  • Database errors wrapped with context: fmt.Errorf("repo.FindByID: %w", err)
  • Struct fields have json tags — no default field name exposure

FORBIDDEN

  • NEVER use panic() for error handling — only for truly unrecoverable init failures
  • NEVER use package-level db variables — inject via constructor
  • NEVER use interface{} as a shortcut — define real types
  • NEVER ignore returned errors: _, _ = someFunc() is forbidden
  • NEVER use time.Sleep inside request handlers — use context deadlines
  • NEVER log secrets, tokens, or passwords even in debug logs
  • NEVER use http.DefaultClient for external requests (no timeout) — configure a client
  • NEVER store pointers to loop variables in goroutines — capture by value
  • NEVER use os.Exit outside main.go
  • NEVER skip -race flag in CI test runs
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall