Shipping Production-Quality Go REST APIs with Claude Code — Gin, GORM, Docker, and CI/CD with the Judgment Calls That Matter

go version
# go version go1.25.0 darwin/arm64
 
docker --version
git --version

# Project: Go REST API
 
## Tech Stack
- Go 1.25+ / Gin v1.10+ / GORM v2 / PostgreSQL 16
 
## Architecture
- Clean Architecture (Handler → Service → Repository)
- Dependency injection via constructor functions
 
## Conventions
- Package names: lowercase only
- Always wrap errors (fmt.Errorf("...: %w", err))
- Logging via log/slog (standard library)
- Tests use testify
- Accept context.Context as the first argument
 
## Forbidden
- Global variables
- panic() (always return errors)
- init() outside of DI

cd go-api
go mod init github.com/yourusername/go-api
 
go get github.com/gin-gonic/gin@latest
go get gorm.io/gorm@latest
go get gorm.io/driver/postgres@latest
go get github.com/joho/godotenv@latest
go get github.com/golang-jwt/jwt/v5@latest
go get github.com/go-playground/validator/v10@latest
go get github.com/stretchr/testify@latest

package domain
 
import (
	"time"
 
	"github.com/google/uuid"
)
 
// User is the user 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(ctx context.Context, user *User) error
	FindByID(ctx context.Context, id uuid.UUID) (*User, error)
	FindByEmail(ctx context.Context, email string) (*User, error)
	Update(ctx context.Context, user *User) error
	Delete(ctx context.Context, id uuid.UUID) error
	List(ctx context.Context, 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: "email or password is incorrect"}
)
 
// DomainError is the domain-layer error type
type DomainError struct {
	Code    string
	Message string
}
 
func (e *DomainError) Error() string {
	return e.Message
}

func (r *userRepository) FindByID(ctx context.Context, id uuid.UUID) (*domain.User, error) {
	var user domain.User
	result := r.db.WithContext(ctx).
		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 fetch user: %w", result.Error)
	}
	return &user, nil
}

// Register creates a new user
func (s *UserService) Register(ctx context.Context, email, password, name string) (*domain.User, error) {
	// Hash the password (cost 12 is the recommended production value)
	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(ctx, user); err != nil {
		return nil, err // pass domain errors through unchanged
	}
 
	s.logger.Info("user registered",
		slog.String("user_id", user.ID.String()),
	)
	return user, nil
}
 
// Login authenticates and issues a JWT
func (s *UserService) Login(ctx context.Context, email, password string) (string, error) {
	user, err := s.repo.FindByEmail(ctx, email)
	if err != nil {
		// Return the same error whether the user exists or not (prevents enumeration)
		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("login succeeded", slog.String("user_id", user.ID.String()))
	return token, nil
}

// Unified error response
type ErrorResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}
 
type RegisterRequest struct {
	Email    string `json:"email"    binding:"required,email,max=255"`
	Password string `json:"password" binding:"required,min=8,max=72"`
	Name     string `json:"name"     binding:"required,min=1,max=100"`
}
 
// handleServiceError maps 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 internal error occurred"})
}

// Verify validates a JWT and returns its 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
	})
	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
}

	srv := &http.Server{
		Addr:              ":" + port,
		Handler:           r,
		ReadHeaderTimeout: 5 * time.Second,
	}
 
	// Start the server on its own goroutine
	go func() {
		logger.Info("server starting", slog.String("port", port))
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			logger.Error("server error", slog.String("error", err.Error()))
			os.Exit(1)
		}
	}()
 
	// Wait for SIGINT / SIGTERM
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit
 
	// Graceful shutdown with a 10-second grace period
	logger.Info("shutting down")
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := srv.Shutdown(ctx); err != nil {
		logger.Error("forced shutdown", slog.String("error", err.Error()))
	}
	logger.Info("shutdown complete")

// NewPostgres creates a production-configured PostgreSQL connection
func NewPostgres(dsn string) (*gorm.DB, error) {
	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
		TranslateError: true, // enables translation to gorm.ErrDuplicatedKey etc.
	})
	if err != nil {
		return nil, fmt.Errorf("failed to connect: %w", err)
	}
 
	sqlDB, err := db.DB()
	if err != nil {
		return nil, fmt.Errorf("failed to obtain sql.DB: %w", err)
	}
 
	// Pool settings — coordinate with PostgreSQL's max_connections
	sqlDB.SetMaxOpenConns(25)
	sqlDB.SetMaxIdleConns(10)
	sqlDB.SetConnMaxLifetime(30 * time.Minute)
	sqlDB.SetConnMaxIdleTime(5 * time.Minute)
 
	return db, nil
}

func TestRegister_DuplicateEmail(t *testing.T) {
	mockRepo := new(MockUserRepository)
	mockRepo.On("Create", mock.Anything, mock.Anything).Return(domain.ErrUserAlreadyExists)
 
	svc := service.NewUserService(mockRepo, testJWTManager(), testLogger())
	_, err := svc.Register(context.Background(), "existing@example.com", "Pass1234!", "User")
 
	assert.ErrorIs(t, err, domain.ErrUserAlreadyExists)
}
 
func TestLogin_WrongPassword(t *testing.T) {
	// Use a hash generated beforehand with bcrypt.GenerateFromPassword
	hash := mustHash("CorrectPass123!")
	mockRepo := new(MockUserRepository)
	mockRepo.On("FindByEmail", mock.Anything, "user@example.com").Return(&domain.User{
		Email: "user@example.com", PasswordHash: hash,
	}, nil)
 
	svc := service.NewUserService(mockRepo, testJWTManager(), testLogger())
	_, err := svc.Login(context.Background(), "user@example.com", "WrongPass!")
 
	assert.ErrorIs(t, err, domain.ErrInvalidCredential)
}

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

# ─── Stage 1: build ────────────────────────────────────────────
FROM golang:1.25-alpine AS builder
 
WORKDIR /app
 
# Copy module files first to leverage the build cache
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
 
# CA certificates (required for outbound HTTPS)
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 
COPY --from=builder /bin/api /api
 
EXPOSE 8080
ENTRYPOINT ["/api"]

# Runtime stage when you want to retain debuggability
FROM gcr.io/distroless/static-debian12:nonroot
 
COPY --from=builder /bin/api /api
 
EXPOSE 8080
USER nonroot
ENTRYPOINT ["/api"]

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:

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.25'
          cache: true
 
      - name: Install 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
    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
        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

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

lsof -ti:8080 | xargs kill -9