artubss/SKILLS-CLAUDE-CODE / favorites/tpl-backend-go-chi-gorm
tpl-backend-go-chi-gorm
VerifiedTemplate 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
| Technology | Version | Purpose |
|---|---|---|
| Go | 1.22+ | Language + runtime |
| Chi | v5 | HTTP router + middleware |
| GORM | v2 | ORM + migrations |
| PostgreSQL | 16 | Primary database |
| pgx/v5 | 5.x | PostgreSQL driver |
| golang-jwt/jwt | v5 | JWT tokens |
| bcrypt | stdlib | Password hashing |
| testify | v1.9+ | Assertions + mocking |
| slog | stdlib (1.21+) | Structured logging |
| golangci-lint | 1.58+ | Linting suite |
| godotenv | 1.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
*Handlerwith service interface injected via constructor - Services receive
Repositoryinterface — not the concrete struct - No global state — pass dependencies explicitly (no
dbpackage-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.Timewithjson:"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.Contextfor cancellation — always acceptctx context.Contextas first param - Goroutines spawned in handlers must be tracked (use
errgroup.Groupor waitgroup) - Database operations: GORM's
*gorm.DBis 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
| Trigger | Method | Route | Middleware | Handler |
|---|---|---|---|---|
| Register | POST | /api/v1/auth/register | — | UserHandler.Register |
| Login | POST | /api/v1/auth/login | — | UserHandler.Login |
| Refresh token | POST | /api/v1/auth/refresh | — | UserHandler.Refresh |
| Get my profile | GET | /api/v1/users/me | Authenticate | UserHandler.Me |
| Update profile | PATCH | /api/v1/users/me | Authenticate | UserHandler.UpdateMe |
| List users | GET | /api/v1/users | Authenticate, RequireAdmin | UserHandler.List |
| Get user | GET | /api/v1/users/{id} | Authenticate, RequireAdmin | UserHandler.Get |
| Delete user | DELETE | /api/v1/users/{id} | Authenticate, RequireAdmin | UserHandler.Delete |
| Health check | GET | /health | — | inline |
QUALITY GATES
Before opening a PR, verify ALL of the following:
-
golangci-lint run ./...passes with zero warnings -
go test ./... -race -count=1passes — no race conditions -
go vet ./...clean - Coverage:
go test ./... -coverprofile=cover.out≥ 75% -
go build ./cmd/api/...compiles without warnings - No
interface{}— useany(Go 1.18+) or specific types - All context parameters are first argument:
func F(ctx context.Context, ...) - No
log.Fataloutside ofmain.go - Database errors wrapped with context:
fmt.Errorf("repo.FindByID: %w", err) - Struct fields have
jsontags — no default field name exposure
FORBIDDEN
- NEVER use
panic()for error handling — only for truly unrecoverable init failures - NEVER use package-level
dbvariables — inject via constructor - NEVER use
interface{}as a shortcut — define real types - NEVER ignore returned errors:
_, _ = someFunc()is forbidden - NEVER use
time.Sleepinside request handlers — use context deadlines - NEVER log secrets, tokens, or passwords even in debug logs
- NEVER use
http.DefaultClientfor external requests (no timeout) — configure a client - NEVER store pointers to loop variables in goroutines — capture by value
- NEVER use
os.Exitoutsidemain.go - NEVER skip
-raceflag in CI test runs
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |