Go 언어 REST API 서버 튜토리얼 — 환경 설정부터 DB 연동, Docker 배포까지

Go 설치 및 프로젝트 초기화
# macOS
brew install go

# Linux (공식 tar.gz)
wget https://go.dev/dl/go1.22.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.2.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# 버전 확인
go version
# go version go1.22.2 linux/amd64

# 프로젝트 생성
mkdir go-rest-api && cd go-rest-api
go mod init github.com/yourname/go-rest-api

# 디렉토리 구조
mkdir -p cmd/server internal/{handler,middleware,model,repository,service} pkg/database

Chi 라우터로 기본 서버 구성 (cmd/server/main.go)
package main

import (
	"log"
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
	"github.com/yourname/go-rest-api/internal/handler"
)

func main() {
	r := chi.NewRouter()

	// 기본 미들웨어
	r.Use(middleware.Logger)
	r.Use(middleware.Recoverer)
	r.Use(middleware.RequestID)

	// 라우트 등록
	r.Route("/api/v1", func(r chi.Router) {
		r.Route("/users", func(r chi.Router) {
			r.Get("/", handler.ListUsers)
			r.Post("/", handler.CreateUser)
			r.Get("/{id}", handler.GetUser)
			r.Put("/{id}", handler.UpdateUser)
			r.Delete("/{id}", handler.DeleteUser)
		})
	})

	// 헬스체크
	r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("ok"))
	})

	log.Println("서버 시작: :8080")
	log.Fatal(http.ListenAndServe(":8080", r))
}

// go 패키지 설치
// go get github.com/go-chi/chi/v5

모델 정의 및 JSON 핸들러 (internal/handler/user.go)
package handler

import (
	"encoding/json"
	"net/http"
	"strconv"

	"github.com/go-chi/chi/v5"
)

// 모델 정의
type User struct {
	ID    int    `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
	// 응답에서 패스워드 제외
	Password string `json:"-"`
}

type CreateUserRequest struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	Password string `json:"password"`
}

type APIResponse struct {
	Data    any    `json:"data,omitempty"`
	Error   string `json:"error,omitempty"`
	Message string `json:"message,omitempty"`
}

// JSON 응답 헬퍼
func respond(w http.ResponseWriter, status int, data any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(data)
}

func respondError(w http.ResponseWriter, status int, msg string) {
	respond(w, status, APIResponse{Error: msg})
}

// 핸들러
func CreateUser(w http.ResponseWriter, r *http.Request) {
	var req CreateUserRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		respondError(w, http.StatusBadRequest, "잘못된 요청 형식입니다")
		return
	}

	if req.Name == "" || req.Email == "" {
		respondError(w, http.StatusUnprocessableEntity, "name과 email은 필수입니다")
		return
	}

	// 실제 서비스 레이어 호출 (다음 섹션에서 구현)
	user := User{ID: 1, Name: req.Name, Email: req.Email}
	respond(w, http.StatusCreated, APIResponse{Data: user})
}

func GetUser(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.Atoi(chi.URLParam(r, "id"))
	if err != nil {
		respondError(w, http.StatusBadRequest, "유효하지 않은 ID입니다")
		return
	}

	// 서비스 레이어 호출
	_ = id
	user := User{ID: id, Name: "홍길동", Email: "hong@example.com"}
	respond(w, http.StatusOK, APIResponse{Data: user})
}

func ListUsers(w http.ResponseWriter, r *http.Request) {
	users := []User{
		{ID: 1, Name: "홍길동", Email: "hong@example.com"},
	}
	respond(w, http.StatusOK, APIResponse{Data: users})
}

func UpdateUser(w http.ResponseWriter, r *http.Request) {
	respondError(w, http.StatusNotImplemented, "미구현")
}

func DeleteUser(w http.ResponseWriter, r *http.Request) {
	respondError(w, http.StatusNotImplemented, "미구현")
}

PostgreSQL 연결 풀 설정 (pkg/database/postgres.go)
package database

import (
	"database/sql"
	"fmt"
	"os"
	"time"

	_ "github.com/jackc/pgx/v5/stdlib" // pgx를 database/sql 드라이버로 등록
)

type Config struct {
	Host     string
	Port     string
	User     string
	Password string
	DBName   string
	SSLMode  string
}

func NewPostgres(cfg Config) (*sql.DB, error) {
	dsn := fmt.Sprintf(
		"host=%s port=%s user=%s password=%s dbname=%s sslmode=%s",
		cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.DBName, cfg.SSLMode,
	)

	db, err := sql.Open("pgx", dsn)
	if err != nil {
		return nil, fmt.Errorf("DB 연결 실패: %w", err)
	}

	// 연결 풀 설정
	db.SetMaxOpenConns(25)
	db.SetMaxIdleConns(5)
	db.SetConnMaxLifetime(5 * time.Minute)

	if err := db.Ping(); err != nil {
		return nil, fmt.Errorf("DB ping 실패: %w", err)
	}

	return db, nil
}

func ConfigFromEnv() Config {
	return Config{
		Host:     getEnv("DB_HOST", "localhost"),
		Port:     getEnv("DB_PORT", "5432"),
		User:     getEnv("DB_USER", "postgres"),
		Password: os.Getenv("DB_PASSWORD"),
		DBName:   getEnv("DB_NAME", "goapi"),
		SSLMode:  getEnv("DB_SSL_MODE", "disable"),
	}
}

func getEnv(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

// go get github.com/jackc/pgx/v5

유저 Repository 구현 (internal/repository/user.go)
package repository

import (
	"context"
	"database/sql"
	"fmt"
)

type User struct {
	ID    int
	Name  string
	Email string
}

type UserRepository struct {
	db *sql.DB
}

func NewUserRepository(db *sql.DB) *UserRepository {
	return &UserRepository{db: db}
}

func (r *UserRepository) FindByID(ctx context.Context, id int) (*User, error) {
	u := &User{}
	err := r.db.QueryRowContext(ctx,
		"SELECT id, name, email FROM users WHERE id = $1",
		id,
	).Scan(&u.ID, &u.Name, &u.Email)

	if err == sql.ErrNoRows {
		return nil, fmt.Errorf("유저 없음: id=%d", id)
	}
	if err != nil {
		return nil, fmt.Errorf("유저 조회 실패: %w", err)
	}
	return u, nil
}

func (r *UserRepository) Create(ctx context.Context, name, email, hashedPw string) (*User, error) {
	u := &User{}
	err := r.db.QueryRowContext(ctx,
		"INSERT INTO users (name, email, password_hash) VALUES ($1, $2, $3) RETURNING id, name, email",
		name, email, hashedPw,
	).Scan(&u.ID, &u.Name, &u.Email)
	if err != nil {
		return nil, fmt.Errorf("유저 생성 실패: %w", err)
	}
	return u, nil
}

func (r *UserRepository) List(ctx context.Context, limit, offset int) ([]User, error) {
	rows, err := r.db.QueryContext(ctx,
		"SELECT id, name, email FROM users ORDER BY id DESC LIMIT $1 OFFSET $2",
		limit, offset,
	)
	if err != nil {
		return nil, fmt.Errorf("유저 목록 조회 실패: %w", err)
	}
	defer rows.Close()

	var users []User
	for rows.Next() {
		var u User
		if err := rows.Scan(&u.ID, &u.Name, &u.Email); err != nil {
			return nil, err
		}
		users = append(users, u)
	}
	return users, rows.Err()
}

JWT 인증 미들웨어 (internal/middleware/auth.go)
package middleware

import (
	"context"
	"net/http"
	"strings"

	"github.com/golang-jwt/jwt/v5"
)

type contextKey string

const UserIDKey contextKey = "userID"

var jwtSecret = []byte(mustGetEnv("JWT_SECRET"))

func mustGetEnv(key string) string {
	v := os.Getenv(key)
	if v == "" {
		panic("필수 환경변수 누락: " + key)
	}
	return v
}

// JWT 인증 미들웨어
func Auth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		authHeader := r.Header.Get("Authorization")
		if !strings.HasPrefix(authHeader, "Bearer ") {
			http.Error(w, "인증 토큰이 없습니다", http.StatusUnauthorized)
			return
		}

		tokenStr := strings.TrimPrefix(authHeader, "Bearer ")
		token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
			if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
				return nil, jwt.ErrSignatureInvalid
			}
			return jwtSecret, nil
		})

		if err != nil || !token.Valid {
			http.Error(w, "유효하지 않은 토큰", http.StatusUnauthorized)
			return
		}

		claims, ok := token.Claims.(jwt.MapClaims)
		if !ok {
			http.Error(w, "토큰 파싱 실패", http.StatusUnauthorized)
			return
		}

		userID := int(claims["user_id"].(float64))
		ctx := context.WithValue(r.Context(), UserIDKey, userID)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// 라우터에서 인증 그룹 적용
// r.Route("/api/v1/protected", func(r chi.Router) {
//     r.Use(middleware.Auth)
//     r.Get("/me", handler.GetMe)
// })

// go get github.com/golang-jwt/jwt/v5

커스텀 에러 타입과 핸들러 에러 처리
package apierr

import "net/http"

// 도메인 에러 타입
type AppError struct {
	Code    int
	Message string
}

func (e *AppError) Error() string { return e.Message }

// 미리 정의된 에러
var (
	ErrNotFound   = &AppError{Code: http.StatusNotFound, Message: "리소스를 찾을 수 없습니다"}
	ErrBadRequest = &AppError{Code: http.StatusBadRequest, Message: "잘못된 요청입니다"}
	ErrConflict   = &AppError{Code: http.StatusConflict, Message: "이미 존재하는 리소스입니다"}
	ErrInternal   = &AppError{Code: http.StatusInternalServerError, Message: "서버 오류가 발생했습니다"}
)

// 핸들러에서 에러 처리
func HandleError(w http.ResponseWriter, err error) {
	var appErr *AppError
	if errors.As(err, &appErr) {
		respond(w, appErr.Code, APIResponse{Error: appErr.Message})
		return
	}
	// 예상치 못한 에러 — 내부 로그는 남기되 클라이언트에는 일반 메시지
	log.Printf("내부 오류: %v", err)
	respond(w, http.StatusInternalServerError, APIResponse{Error: "서버 오류가 발생했습니다"})
}

// 서비스 레이어에서 사용
func (s *UserService) GetUser(ctx context.Context, id int) (*User, error) {
	u, err := s.repo.FindByID(ctx, id)
	if err != nil {
		// err가 "유저 없음"이면 NotFound 반환
		if strings.Contains(err.Error(), "유저 없음") {
			return nil, apierr.ErrNotFound
		}
		return nil, fmt.Errorf("GetUser: %w", err)
	}
	return u, nil
}

핸들러 단위 테스트 (internal/handler/user_test.go)
package handler_test

import (
	"bytes"
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

func TestCreateUser_Success(t *testing.T) {
	body := map[string]string{
		"name":  "홍길동",
		"email": "hong@example.com",
	}
	bodyBytes, _ := json.Marshal(body)

	req := httptest.NewRequest(http.MethodPost, "/api/v1/users", bytes.NewReader(bodyBytes))
	req.Header.Set("Content-Type", "application/json")
	w := httptest.NewRecorder()

	CreateUser(w, req)

	resp := w.Result()
	assert.Equal(t, http.StatusCreated, resp.StatusCode)

	var result APIResponse
	require.NoError(t, json.NewDecoder(resp.Body).Decode(&result))
	assert.Empty(t, result.Error)
}

func TestCreateUser_MissingEmail(t *testing.T) {
	body := map[string]string{"name": "홍길동"}
	bodyBytes, _ := json.Marshal(body)

	req := httptest.NewRequest(http.MethodPost, "/api/v1/users", bytes.NewReader(bodyBytes))
	req.Header.Set("Content-Type", "application/json")
	w := httptest.NewRecorder()

	CreateUser(w, req)

	assert.Equal(t, http.StatusUnprocessableEntity, w.Code)
}

// 테스트 실행
// go test ./internal/handler/... -v
// go test ./... -race -count=1     (race condition 감지)
// go test ./... -coverprofile=coverage.out
// go tool cover -html=coverage.out  (HTML 커버리지 리포트)

// go get github.com/stretchr/testify

Dockerfile 멀티스테이지 빌드 + docker-compose.yml
# Dockerfile
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 go build -ldflags="-s -w" -o server ./cmd/server

# 최종 이미지 — distroless (CA 인증서 포함)
FROM gcr.io/distroless/static:nonroot

COPY --from=builder /app/server /server

EXPOSE 8080
ENTRYPOINT ["/server"]

---

# docker-compose.yml (로컬 개발)
version: "3.9"

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=secret
      - DB_NAME=goapi
      - DB_SSL_MODE=disable
      - JWT_SECRET=local-dev-secret-change-in-prod
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: goapi
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# 빌드 및 실행
# docker compose up --build
# docker compose down -v   (볼륨 포함 정리)