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

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

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
}

// 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"))
}

// 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
}

// 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"})
}

// 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
}

// 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)
}

// 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)
}

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

# ─── 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"]

# 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/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

// ✅ 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)
}

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

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