Articles/Claude Code

⟐ Claude Code/2026-04-08Advanced

Claude Code × Go: Production-Grade REST API Development — Gin, GORM, Docker & GitHub Actions

Build production-grade Go REST APIs with Claude Code. Covers Gin, GORM, PostgreSQL, Docker multi-stage builds, JWT auth, and GitHub Actions CI/CD.

Go² Golang² REST API² Gin² GORM² Docker⁵ GitHub Actions¹² Backend⁴ Production²³

✦ Premium Article

Why Go × Claude Code?

Go (Golang), created by Google, is a compiled, statically-typed language that has become the go-to choice for microservices and REST API backends. Its simple syntax, fast compilation, and excellent concurrency support have made it one of the most popular backend languages among developers worldwide.

The combination of Go and Claude Code is particularly powerful for three reasons.

First, code generation accuracy. Go's strict type system means Claude Code generates code that compiles correctly on the first try far more often than with dynamically-typed languages. The simplicity of Go's type inference keeps generated code clean and predictable.

Second, standard library richness. Go includes networking, HTTP, JSON, and cryptography in its standard library. Claude Code can implement features without reaching for external dependencies, keeping generated code lean and maintainable.

Third, performance and portability. Go compiles to a single binary, making Docker images dramatically smaller than Node.js or Python equivalents. This simplicity makes CI/CD automation with Claude Code especially effective.

By the end of this guide, you will have a fully operational system with:

A high-performance REST API built with the Gin framework
Type-safe data access with GORM and PostgreSQL
JWT-based authentication and authorization
Docker multi-stage builds producing images under 15MB
GitHub Actions CI/CD pipeline with automated testing
Structured logging and health check endpoints

Prerequisites and Environment Setup

Required Environment

To follow this guide, you will need:

Claude Code (latest version) installed and working
Go 1.22 or later (go version to verify)
Docker Desktop
PostgreSQL (local or via Docker)
Git

Download Go from the official download page.

Verify your setup in Claude Code's terminal:

go version
# go version go1.22.4 darwin/arm64
 
docker --version
# Docker version 26.1.0
 
git --version
# git version 2.44.0

Setting Up CLAUDE.md

The single most impactful thing you can do before writing a line of code is configure CLAUDE.md to give Claude Code your project context. This dramatically improves generated code quality.

# Project: Go REST API
 
## Tech Stack
- Go 1.22+ / Gin v1.10 / GORM v2 / PostgreSQL 16
 
## Architecture
- Clean Architecture (Handler → Service → Repository)
- Dependency Injection pattern
 
## Code Conventions
- Package names: lowercase only
- Always wrap errors: fmt.Errorf("%w", err)
- Logging: log/slog (standard library)
- Testing: testify
 
## Prohibitions
- No global variables
- No panic() — always return errors
- No init() functions (except DI)

With this context, Claude Code will generate code that is consistent with your project's architecture from the very first prompt.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Master the full Claude Code workflow for Go project design — from Clean Architecture scaffolding to production-ready code generation

✦Understand type-safe API design patterns using Gin router and GORM with PostgreSQL for real-world backend services

✦Implement a complete deployment pipeline: Docker multi-stage builds (under 15MB images), GitHub Actions CI/CD with coverage reporting

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Project Structure Design

Clean Architecture in Go

Prompt Claude Code to scaffold the project structure:

Following the conventions in CLAUDE.md, design a project structure
for a user management API using Clean Architecture.
Create the directory layout and go.mod file.

The generated structure will look like this:

go-api/
├── cmd/
│   └── api/
│       └── main.go          ← Entry point
├── internal/
│   ├── domain/
│   │   ├── user.go          ← Domain model
│   │   └── errors.go        ← Domain error definitions
│   ├── repository/
│   │   ├── user_repository.go      ← Interface
│   │   └── postgres/
│   │       └── user_repository.go  ← Implementation
│   ├── service/
│   │   └── user_service.go  ← Business logic
│   └── handler/
│       ├── user_handler.go  ← HTTP handlers
│       └── middleware/
│           └── auth.go      ← JWT auth middleware
├── pkg/
│   ├── database/
│   │   └── postgres.go      ← DB connection
│   ├── jwt/
│   │   └── jwt.go           ← JWT utilities
│   └── validator/
│       └── validator.go     ← Input validation
├── migrations/              ← SQL migrations
├── Dockerfile
├── docker-compose.yml
├── .github/
│   └── workflows/
│       └── ci.yml
├── CLAUDE.md
├── go.mod
└── go.sum

Initialize go.mod and Install Dependencies

cd go-api
go mod init github.com/yourusername/go-api
 
# Web framework
go get github.com/gin-gonic/gin@v1.10.0
 
# ORM
go get gorm.io/gorm@v1.25.10
go get gorm.io/driver/postgres@v1.5.9
 
# Environment variables
go get github.com/joho/godotenv@v1.5.1
 
# JWT
go get github.com/golang-jwt/jwt/v5@v5.2.1
 
# Validation
go get github.com/go-playground/validator/v10@v10.22.0
 
# Testing
go get github.com/stretchr/testify@v1.9.0
go get github.com/DATA-DOG/go-sqlmock@v1.5.0

Domain Model and Repository Layer

Defining the Domain Model

Prompt Claude Code with:

Create internal/domain/user.go.
The user model needs:
- ID (UUID)
- Email (unique)
- PasswordHash
- Name
- CreatedAt / UpdatedAt / DeletedAt

Use GORM's soft delete support.

Generated internal/domain/user.go:

package domain
 
import (
	"time"
	"github.com/google/uuid"
)
 
// User is the core domain model
type User struct {
	ID           uuid.UUID  `gorm:"type:uuid;primaryKey;default:gen_random_uuid()"`
	Email        string     `gorm:"uniqueIndex;not null;size:255"`
	PasswordHash string     `gorm:"not null"`
	Name         string     `gorm:"not null;size:100"`
	CreatedAt    time.Time
	UpdatedAt    time.Time
	DeletedAt    *time.Time `gorm:"index"`
}
 
// UserRepository defines the data access interface
type UserRepository interface {
	Create(user *User) error
	FindByID(id uuid.UUID) (*User, error)
	FindByEmail(email string) (*User, error)
	Update(user *User) error
	Delete(id uuid.UUID) error
	List(offset, limit int) ([]*User, int64, error)
}
 
// Domain errors
var (
	ErrUserNotFound      = &DomainError{Code: "USER_NOT_FOUND", Message: "User not found"}
	ErrUserAlreadyExists = &DomainError{Code: "USER_ALREADY_EXISTS", Message: "This email address is already in use"}
	ErrInvalidCredential = &DomainError{Code: "INVALID_CREDENTIAL", Message: "Invalid email or password"}
)
 
// DomainError is the domain-layer error type
type DomainError struct {
	Code    string
	Message string
}
 
func (e *DomainError) Error() string {
	return e.Message
}

PostgreSQL Repository Implementation

// internal/repository/postgres/user_repository.go
package postgres
 
import (
	"errors"
	"fmt"
 
	"github.com/google/uuid"
	"gorm.io/gorm"
 
	"github.com/yourusername/go-api/internal/domain"
)
 
type userRepository struct {
	db *gorm.DB
}
 
// NewUserRepository creates a new PostgreSQL user repository
func NewUserRepository(db *gorm.DB) domain.UserRepository {
	return &userRepository{db: db}
}
 
func (r *userRepository) Create(user *domain.User) error {
	result := r.db.Create(user)
	if result.Error != nil {
		if isDuplicateError(result.Error) {
			return domain.ErrUserAlreadyExists
		}
		return fmt.Errorf("failed to create user: %w", result.Error)
	}
	return nil
}
 
func (r *userRepository) FindByID(id uuid.UUID) (*domain.User, error) {
	var user domain.User
	result := r.db.Where("id = ? AND deleted_at IS NULL", id).First(&user)
	if result.Error != nil {
		if errors.Is(result.Error, gorm.ErrRecordNotFound) {
			return nil, domain.ErrUserNotFound
		}
		return nil, fmt.Errorf("failed to find user: %w", result.Error)
	}
	return &user, nil
}
 
func (r *userRepository) FindByEmail(email string) (*domain.User, error) {
	var user domain.User
	result := r.db.Where("email = ? AND deleted_at IS NULL", email).First(&user)
	if result.Error != nil {
		if errors.Is(result.Error, gorm.ErrRecordNotFound) {
			return nil, domain.ErrUserNotFound
		}
		return nil, fmt.Errorf("failed to find user by email: %w", result.Error)
	}
	return &user, nil
}
 
func (r *userRepository) List(offset, limit int) ([]*domain.User, int64, error) {
	var users []*domain.User
	var total int64
 
	r.db.Model(&domain.User{}).Where("deleted_at IS NULL").Count(&total)
 
	result := r.db.Where("deleted_at IS NULL").
		Order("created_at DESC").
		Offset(offset).Limit(limit).
		Find(&users)
 
	if result.Error != nil {
		return nil, 0, fmt.Errorf("failed to list users: %w", result.Error)
	}
	return users, total, nil
}
 
func isDuplicateError(err error) bool {
	return err != nil && (
		errors.Is(err, gorm.ErrDuplicatedKey) ||
		containsString(err.Error(), "duplicate key") ||
		containsString(err.Error(), "UNIQUE constraint failed"))
}

Service Layer and HTTP Handlers

Business Logic (Service Layer)

// internal/service/user_service.go
package service
 
import (
	"fmt"
	"log/slog"
 
	"github.com/google/uuid"
	"golang.org/x/crypto/bcrypt"
 
	"github.com/yourusername/go-api/internal/domain"
	"github.com/yourusername/go-api/pkg/jwt"
)
 
type UserService struct {
	repo       domain.UserRepository
	jwtManager *jwt.Manager
	logger     *slog.Logger
}
 
func NewUserService(repo domain.UserRepository, jwtManager *jwt.Manager, logger *slog.Logger) *UserService {
	return &UserService{repo: repo, jwtManager: jwtManager, logger: logger}
}
 
// Register handles new user registration
func (s *UserService) Register(email, password, name string) (*domain.User, error) {
	// Cost 12 is the production recommendation for bcrypt
	hash, err := bcrypt.GenerateFromPassword([]byte(password), 12)
	if err != nil {
		return nil, fmt.Errorf("failed to hash password: %w", err)
	}
 
	user := &domain.User{
		Email:        email,
		PasswordHash: string(hash),
		Name:         name,
	}
 
	if err := s.repo.Create(user); err != nil {
		return nil, err // Pass domain errors through
	}
 
	s.logger.Info("user registered",
		slog.String("user_id", user.ID.String()),
		slog.String("email", email),
	)
	return user, nil
}
 
// Login authenticates a user and returns a JWT token
func (s *UserService) Login(email, password string) (string, error) {
	user, err := s.repo.FindByEmail(email)
	if err != nil {
		// Return the same error regardless of whether the user exists
		// to prevent timing attacks
		return "", domain.ErrInvalidCredential
	}
 
	if err := bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(password)); err != nil {
		s.logger.Warn("login failed", slog.String("email", email))
		return "", domain.ErrInvalidCredential
	}
 
	token, err := s.jwtManager.Generate(user.ID, user.Email)
	if err != nil {
		return "", fmt.Errorf("failed to generate token: %w", err)
	}
 
	s.logger.Info("user logged in", slog.String("user_id", user.ID.String()))
	return token, nil
}

HTTP Handlers (Gin)

Prompt Claude Code:

Create internal/handler/user_handler.go.
Implement these endpoints:
- POST /api/v1/auth/register
- POST /api/v1/auth/login
- GET /api/v1/users/:id (JWT required)
- GET /api/v1/users (JWT required, with pagination)

Use go-playground/validator for input validation.
Use a unified error response format.

// internal/handler/user_handler.go
package handler
 
import (
	"errors"
	"log/slog"
	"net/http"
	"strconv"
 
	"github.com/gin-gonic/gin"
	"github.com/google/uuid"
 
	"github.com/yourusername/go-api/internal/domain"
	"github.com/yourusername/go-api/internal/service"
)
 
type UserHandler struct {
	service *service.UserService
	logger  *slog.Logger
}
 
func NewUserHandler(service *service.UserService, logger *slog.Logger) *UserHandler {
	return &UserHandler{service: service, logger: logger}
}
 
type ErrorResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}
 
type RegisterRequest struct {
	Email    string `json:"email"    validate:"required,email,max=255"`
	Password string `json:"password" validate:"required,min=8,max=72"`
	Name     string `json:"name"     validate:"required,min=1,max=100"`
}
 
func (h *UserHandler) Register(c *gin.Context) {
	var req RegisterRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, ErrorResponse{
			Code:    "INVALID_REQUEST",
			Message: "Request body is invalid",
		})
		return
	}
 
	user, err := h.service.Register(req.Email, req.Password, req.Name)
	if err != nil {
		h.handleServiceError(c, err)
		return
	}
 
	c.JSON(http.StatusCreated, gin.H{
		"id":         user.ID,
		"email":      user.Email,
		"name":       user.Name,
		"created_at": user.CreatedAt,
	})
}
 
func (h *UserHandler) Login(c *gin.Context) {
	var req struct {
		Email    string `json:"email"    validate:"required,email"`
		Password string `json:"password" validate:"required"`
	}
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, ErrorResponse{Code: "INVALID_REQUEST", Message: "Please check your input"})
		return
	}
 
	token, err := h.service.Login(req.Email, req.Password)
	if err != nil {
		h.handleServiceError(c, err)
		return
	}
 
	c.JSON(http.StatusOK, gin.H{"token": token})
}
 
func (h *UserHandler) GetUser(c *gin.Context) {
	id, err := uuid.Parse(c.Param("id"))
	if err != nil {
		c.JSON(http.StatusBadRequest, ErrorResponse{Code: "INVALID_ID", Message: "Invalid user ID format"})
		return
	}
 
	user, err := h.service.GetByID(id)
	if err != nil {
		h.handleServiceError(c, err)
		return
	}
 
	c.JSON(http.StatusOK, gin.H{
		"id":         user.ID,
		"email":      user.Email,
		"name":       user.Name,
		"created_at": user.CreatedAt,
	})
}
 
func (h *UserHandler) ListUsers(c *gin.Context) {
	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
	perPage, _ := strconv.Atoi(c.DefaultQuery("per_page", "20"))
	if page < 1 { page = 1 }
	if perPage < 1 || perPage > 100 { perPage = 20 }
 
	users, total, err := h.service.List((page-1)*perPage, perPage)
	if err != nil {
		c.JSON(http.StatusInternalServerError, ErrorResponse{Code: "INTERNAL_ERROR", Message: "An unexpected error occurred"})
		return
	}
 
	c.JSON(http.StatusOK, gin.H{
		"users":    users,
		"total":    total,
		"page":     page,
		"per_page": perPage,
	})
}
 
// handleServiceError converts service-layer errors to HTTP responses
func (h *UserHandler) handleServiceError(c *gin.Context, err error) {
	var domainErr *domain.DomainError
	if errors.As(err, &domainErr) {
		status := http.StatusBadRequest
		switch domainErr.Code {
		case "USER_NOT_FOUND":
			status = http.StatusNotFound
		case "INVALID_CREDENTIAL":
			status = http.StatusUnauthorized
		case "USER_ALREADY_EXISTS":
			status = http.StatusConflict
		}
		c.JSON(status, ErrorResponse{Code: domainErr.Code, Message: domainErr.Message})
		return
	}
	h.logger.Error("unexpected error", slog.String("error", err.Error()))
	c.JSON(http.StatusInternalServerError, ErrorResponse{Code: "INTERNAL_ERROR", Message: "An unexpected error occurred"})
}

JWT Middleware and Router Configuration

JWT Manager

// pkg/jwt/jwt.go
package jwt
 
import (
	"fmt"
	"time"
 
	"github.com/golang-jwt/jwt/v5"
	"github.com/google/uuid"
)
 
type Manager struct {
	secretKey []byte
	duration  time.Duration
}
 
type Claims struct {
	UserID string `json:"user_id"`
	Email  string `json:"email"`
	jwt.RegisteredClaims
}
 
func NewManager(secretKey string, duration time.Duration) *Manager {
	return &Manager{secretKey: []byte(secretKey), duration: duration}
}
 
// Generate creates a signed JWT token
func (m *Manager) Generate(userID uuid.UUID, email string) (string, error) {
	claims := &Claims{
		UserID: userID.String(),
		Email:  email,
		RegisteredClaims: jwt.RegisteredClaims{
			ExpiresAt: jwt.NewNumericDate(time.Now().Add(m.duration)),
			IssuedAt:  jwt.NewNumericDate(time.Now()),
			Issuer:    "go-api",
		},
	}
 
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	signed, err := token.SignedString(m.secretKey)
	if err != nil {
		return "", fmt.Errorf("failed to sign JWT: %w", err)
	}
	return signed, nil
}
 
// Verify validates a JWT token and returns the claims
func (m *Manager) Verify(tokenStr string) (*Claims, error) {
	token, err := jwt.ParseWithClaims(tokenStr, &Claims{}, 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 m.secretKey, nil
	}, jwt.WithLeeway(30*time.Second))
 
	if err != nil {
		return nil, fmt.Errorf("token verification failed: %w", err)
	}
 
	claims, ok := token.Claims.(*Claims)
	if !ok || !token.Valid {
		return nil, fmt.Errorf("invalid token")
	}
	return claims, nil
}

Gin Router Setup

// cmd/api/main.go (excerpt)
package main
 
import (
	"log/slog"
	"os"
	"time"
 
	"github.com/gin-gonic/gin"
	"github.com/joho/godotenv"
 
	"github.com/yourusername/go-api/internal/handler"
	"github.com/yourusername/go-api/internal/handler/middleware"
	"github.com/yourusername/go-api/internal/repository/postgres"
	"github.com/yourusername/go-api/internal/service"
	pkgdb "github.com/yourusername/go-api/pkg/database"
	"github.com/yourusername/go-api/pkg/jwt"
)
 
func main() {
	godotenv.Load()
 
	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelInfo,
	}))
	slog.SetDefault(logger)
 
	db, err := pkgdb.NewPostgres(os.Getenv("DATABASE_URL"))
	if err != nil {
		logger.Error("failed to connect to database", slog.String("error", err.Error()))
		os.Exit(1)
	}
 
	// Dependency Injection
	jwtManager := jwt.NewManager(os.Getenv("JWT_SECRET"), 24*time.Hour)
	userRepo := postgres.NewUserRepository(db)
	userSvc := service.NewUserService(userRepo, jwtManager, logger)
	userHandler := handler.NewUserHandler(userSvc, logger)
	authMiddleware := middleware.NewAuthMiddleware(jwtManager)
 
	r := gin.New()
	r.Use(gin.Recovery())
	r.Use(middleware.RequestLogger(logger))
 
	r.GET("/health", func(c *gin.Context) {
		c.JSON(200, gin.H{"status": "ok"})
	})
 
	v1 := r.Group("/api/v1")
	{
		auth := v1.Group("/auth")
		auth.POST("/register", userHandler.Register)
		auth.POST("/login", userHandler.Login)
 
		users := v1.Group("/users")
		users.Use(authMiddleware.Authenticate())
		users.GET("/:id", userHandler.GetUser)
		users.GET("", userHandler.ListUsers)
	}
 
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	logger.Info("server starting", slog.String("port", port))
	r.Run(":" + port)
}

Testing Strategy

Claude Code is particularly effective at generating table-driven tests, which are idiomatic in Go.

Prompt:

Create internal/service/user_service_test.go.
- Test Register: happy path, duplicate email, and invalid password
- Test Login: happy path, user not found, and wrong password
- Use a mock repository (interface-based)
- Use testify assert

// internal/service/user_service_test.go (excerpt)
package service_test
 
import (
	"testing"
 
	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/mock"
 
	"github.com/yourusername/go-api/internal/domain"
	"github.com/yourusername/go-api/internal/service"
)
 
type MockUserRepository struct {
	mock.Mock
}
 
func (m *MockUserRepository) Create(user *domain.User) error {
	return m.Called(user).Error(0)
}
 
func (m *MockUserRepository) FindByEmail(email string) (*domain.User, error) {
	args := m.Called(email)
	if args.Get(0) == nil {
		return nil, args.Error(1)
	}
	return args.Get(0).(*domain.User), args.Error(1)
}
 
func TestRegister_Success(t *testing.T) {
	mockRepo := new(MockUserRepository)
	mockRepo.On("Create", mock.AnythingOfType("*domain.User")).Return(nil)
 
	svc := service.NewUserService(mockRepo, testJWTManager(), testLogger())
	user, err := svc.Register("test@example.com", "SecurePass123!", "Test User")
 
	assert.NoError(t, err)
	assert.NotNil(t, user)
	assert.Equal(t, "test@example.com", user.Email)
	mockRepo.AssertExpectations(t)
}
 
func TestRegister_DuplicateEmail(t *testing.T) {
	mockRepo := new(MockUserRepository)
	mockRepo.On("Create", mock.Anything).Return(domain.ErrUserAlreadyExists)
 
	svc := service.NewUserService(mockRepo, testJWTManager(), testLogger())
	_, err := svc.Register("existing@example.com", "Pass123!", "User")
 
	assert.ErrorIs(t, err, domain.ErrUserAlreadyExists)
}
 
func TestLogin_WrongPassword(t *testing.T) {
	hash := "$2a$12$..." // bcrypt hash of "CorrectPass123!"
	mockRepo := new(MockUserRepository)
	mockRepo.On("FindByEmail", "user@example.com").Return(&domain.User{
		Email: "user@example.com", PasswordHash: hash,
	}, nil)
 
	svc := service.NewUserService(mockRepo, testJWTManager(), testLogger())
	_, err := svc.Login("user@example.com", "WrongPass!")
 
	assert.ErrorIs(t, err, domain.ErrInvalidCredential)
}

Run tests and check coverage:

go test ./... -v -race
 
# Coverage report
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

Target 70%+ coverage for production-grade APIs.

Docker Multi-Stage Build

Go's single binary compilation enables extremely lean Docker images:

# ─── Stage 1: Build ──────────────────────────────────────────────────────────
FROM golang:1.22-alpine AS builder
 
WORKDIR /app
 
COPY go.mod go.sum ./
RUN go mod download
 
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
    -ldflags="-w -s" \
    -o /bin/api \
    ./cmd/api
 
# ─── Stage 2: Runtime ────────────────────────────────────────────────────────
FROM scratch
 
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/api /api
 
EXPOSE 8080
ENTRYPOINT ["/api"]

Using FROM scratch produces final images under 15MB — roughly 1/10th the size of a comparable Node.js API.

# docker-compose.yml (development)
services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://postgres:postgres@db:5432/go_api?sslmode=disable
      JWT_SECRET: your-secret-key-change-in-production
    depends_on:
      db:
        condition: service_healthy
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: go_api
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    volumes:
      - postgres_data:/var/lib/postgresql/data
 
volumes:
  postgres_data:

GitHub Actions CI/CD Pipeline

# .github/workflows/ci.yml
name: CI/CD Pipeline
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
 
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: go_api_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true
 
      - name: Download dependencies
        run: go mod download
 
      - name: Lint
        uses: golangci/golangci-lint-action@v6
        with:
          version: latest
 
      - name: Run tests
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/go_api_test?sslmode=disable
          JWT_SECRET: test-secret-key
        run: |
          go test ./... -v -race -coverprofile=coverage.out
          go tool cover -func=coverage.out | tail -1
 
      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage.out
 
  build:
    name: Docker Build & Push
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}
 
      - name: Build and push image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/go-api:latest
            ${{ secrets.DOCKER_USERNAME }}/go-api:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Common Errors and How to Fix Them

Error 1: Unexpected `gorm: record not found`

Cause: GORM's First() returns ErrRecordNotFound when no record exists, but Find() returns an empty slice. Mixing them up causes confusing behavior.

Fix: Always use First() for single-record lookups and check for gorm.ErrRecordNotFound explicitly:

// ✅ Correct approach
var user domain.User
if err := db.First(&user, "id = ?", id).Error; err != nil {
    if errors.Is(err, gorm.ErrRecordNotFound) {
        return nil, domain.ErrUserNotFound
    }
    return nil, fmt.Errorf("database error: %w", err)
}

Error 2: JWT `token is expired` errors in production

Cause: Clock skew between the JWT issuer and verifier — common in Docker containers and distributed systems.

Fix: Add a leeway to the JWT parser to tolerate small time differences:

token, err := jwt.ParseWithClaims(tokenStr, &Claims{},
    keyFunc,
    jwt.WithLeeway(30*time.Second), // 30-second tolerance
)

Error 3: `bind: address already in use`

Cause: A previous process is still holding the port. Common during hot-reload development with Claude Code.

Fix:

# Find and kill the process on port 8080
lsof -ti:8080 | xargs kill -9

Claude Code Power Techniques for Go Development

Technique 1: Generate consistent error handling across all service methods

Go's explicit error handling can become repetitive. Use this prompt for consistent results:

Implement error handling for all service layer methods following this pattern:
- gorm.ErrRecordNotFound → domain.ErrUserNotFound
- Duplicate key errors → domain.ErrUserAlreadyExists
- All other errors → wrapped with fmt.Errorf

Technique 2: Table-driven tests for handlers

Create user_handler_test.go with table-driven tests using httptest.NewRecorder
for these endpoints:
- POST /api/v1/auth/register
  - Success (201)
  - Duplicate email (409)
  - Validation error (400)
  - Invalid JSON (400)
Organize test cases in a TestCases slice.

Technique 3: Auto-generate SQL migrations

Create SQL migrations in the migrations/ folder for the users table
(UUID primary key, email unique, created_at/updated_at/deleted_at).
Use the naming convention: 001_create_users_table.up.sql / .down.sql

Looking back

In this guide, we walked through the entire lifecycle of building a production-grade Go REST API with Claude Code — from project structure and Clean Architecture design, through JWT authentication, testing, Docker containerization, and GitHub Actions CI/CD.

Key takeaways:

Design: A well-written CLAUDE.md has the largest single impact on Claude Code's output quality. Define your architecture constraints before writing any code.

Implementation: Maintaining Clean Architecture layer separation (Handler → Service → Repository) keeps code testable and maintainable as the project grows.

Testing: Interface-based mock repositories enable fast, database-free unit tests — a pattern Claude Code generates reliably when prompted correctly.

Deployment: Multi-stage Docker builds with FROM scratch produce images under 15MB, dramatically simpler to deploy and scale than interpreted-language equivalents.

CI/CD: Automating golangci-lint static analysis and coverage measurement ensures code quality is continuously enforced rather than manually reviewed.

Go and Claude Code together offer a compelling combination: type-safe code generation, fast compilation, and minimal deployment footprint — suitable for individual developers and enterprise teams alike. As your next step, explore how Claude Code handles the frontend side in the Claude Code × Next.js 15 App Router production guide.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.