Go Web Application Server

Go 언어로 구축한 RESTful API 웹 애플리케이션 서버입니다. Clean Architecture를 적용하여 유지보수성과 테스트 용이성을 확보했습니다.

목차

• 기술 스택
• 아키텍처
• 프로젝트 구조
• 시작하기
• API 문서
• 개발 가이드
• 마이그레이션

---

기술 스택

핵심 라이브러리

라이브러리	용도	선택 이유
Gin	HTTP 웹 프레임워크	빠른 성능, 미들웨어 지원, 풍부한 생태계
ent	ORM (데이터베이스)	타입 안전성, 코드 생성, 관계 관리 용이
zerolog	구조화된 로깅	고성능, JSON 출력, 제로 할당
swag	Swagger 문서 생성	주석 기반 자동 생성, Gin 통합
godotenv	환경 변수 관리	.env 파일 로드, 설정 분리
valkey-go	캐시 클라이언트	Redis 호환, 고성능

인프라

서비스	용도	포트
PostgreSQL 16	메인 데이터베이스	5433
Valkey 8	캐시 (Redis 호환)	6380

---

아키텍처

Clean Architecture

이 프로젝트는 Clean Architecture를 적용했습니다. 각 계층은 명확한 책임을 가지며, 의존성은 항상 안쪽(도메인)을 향합니다.

graph TB
    subgraph "외부 계층"
        A[HTTP Request] --> B[Middleware]
        B --> C[Handler]
    end

    subgraph "애플리케이션 계층"
        C --> D[Usecase]
    end

    subgraph "인프라 계층"
        D --> E[Repository]
        E --> F[ent Client]
        F --> G[(PostgreSQL)]
    end

    subgraph "도메인 계층"
        H[DTO / Entity]
    end

    D -.-> H
    E -.-> H
    C -.-> H

Loading

계층별 역할

flowchart LR
    subgraph Handler["Handler (Presentation)"]
        direction TB
        H1[HTTP 요청/응답 처리]
        H2[입력 유효성 검사]
        H3[DTO 변환]
    end

    subgraph Usecase["Usecase (Business Logic)"]
        direction TB
        U1[비즈니스 규칙 적용]
        U2[트랜잭션 관리]
        U3[에러 처리]
    end

    subgraph Repository["Repository (Data Access)"]
        direction TB
        R1[데이터 CRUD]
        R2[쿼리 빌더]
        R3[캐시 처리]
    end

    Handler --> Usecase --> Repository

Loading

왜 Clean Architecture인가?

장점	설명
테스트 용이성	각 계층을 독립적으로 테스트 가능 (Mock 주입)
유지보수성	변경 영향 범위가 해당 계층에 국한됨
확장성	새로운 기능 추가 시 기존 코드 수정 최소화
의존성 역전	인터페이스를 통해 구현체 교체 용이

요청 흐름 예시

사용자 생성 요청의 전체 흐름:

sequenceDiagram
    participant Client
    participant Middleware
    participant Handler
    participant Usecase
    participant Repository
    participant Database

    Client->>Middleware: POST /api/v1/users
    Middleware->>Middleware: Trace ID 생성
    Middleware->>Middleware: 로깅 시작
    Middleware->>Handler: 요청 전달

    Handler->>Handler: JSON 바인딩 & 유효성 검사
    Handler->>Usecase: Create(ctx, CreateRequest)

    Usecase->>Repository: GetByEmail(ctx, email)
    Repository->>Database: SELECT * FROM users WHERE email = ?
    Database-->>Repository: 결과 (없음)
    Repository-->>Usecase: nil

    Usecase->>Usecase: 비밀번호 해싱
    Usecase->>Repository: Create(ctx, name, email, password)
    Repository->>Database: INSERT INTO users ...
    Database-->>Repository: 생성된 User
    Repository-->>Usecase: *ent.User

    Usecase->>Usecase: DTO 변환
    Usecase-->>Handler: *user.Response

    Handler-->>Middleware: JSON 응답
    Middleware->>Middleware: 로깅 완료 (latency 포함)
    Middleware-->>Client: 201 Created + X-Response-Time

Loading

---

프로젝트 구조

go-webserver/
├── cmd/
│   └── server/
│       └── main.go              # 애플리케이션 진입점
├── internal/                    # 비공개 애플리케이션 코드
│   ├── config/
│   │   └── config.go            # 환경 설정 로드
│   ├── domain/                  # 도메인 DTO
│   │   ├── user/
│   │   │   └── dto.go           # 사용자 요청/응답 DTO
│   │   ├── product/
│   │   │   └── dto.go
│   │   └── order/
│   │       └── dto.go
│   ├── handler/                 # HTTP 핸들러 (Controller)
│   │   ├── router.go            # 라우터 설정
│   │   ├── user_handler.go
│   │   ├── product_handler.go
│   │   ├── order_handler.go
│   │   └── health_handler.go
│   ├── usecase/                 # 비즈니스 로직
│   │   ├── user_usecase.go
│   │   ├── product_usecase.go
│   │   └── order_usecase.go
│   ├── repository/              # 데이터 접근 계층
│   │   ├── user_repository.go
│   │   ├── product_repository.go
│   │   └── order_repository.go
│   ├── middleware/              # HTTP 미들웨어
│   │   ├── logger.go            # 요청 로깅 + Latency
│   │   ├── trace.go             # Trace ID 생성
│   │   ├── cors.go              # CORS 설정
│   │   └── recovery.go          # 패닉 복구
│   └── infrastructure/          # 외부 서비스 연결
│       ├── database/
│       │   └── database.go      # PostgreSQL 연결
│       ├── cache/
│       │   └── cache.go         # Valkey 연결
│       └── logger/
│           └── logger.go        # zerolog 설정
├── ent/                         # ent ORM (자동 생성)
│   ├── schema/                  # 스키마 정의 (직접 작성)
│   │   ├── user.go
│   │   ├── product.go
│   │   ├── order.go
│   │   └── orderitem.go
│   └── migrate/
│       └── main.go              # 마이그레이션 생성기
├── migrations/                  # SQL 마이그레이션 파일
├── docs/                        # Swagger 문서 (자동 생성)
├── .air.toml                    # Hot reload 설정
├── .env                         # 환경 변수
├── docker-compose.yml           # Docker 설정
├── Makefile                     # 빌드 스크립트
└── go.mod                       # Go 모듈 정의

디렉토리 규칙

디렉토리	규칙
cmd/	실행 파일별 진입점. 최소한의 코드만 포함
internal/	외부 패키지에서 import 불가. 애플리케이션 전용 코드
ent/schema/	직접 작성. 나머지 ent 코드는 자동 생성
docs/	swag 명령으로 자동 생성. 직접 수정 금지

---

시작하기

필수 도구

• Go 1.21+
• Docker & Docker Compose
• Make

설치 및 실행

# 1. 저장소 클론
git clone <repository-url>
cd go-webserver

# 2. 환경 변수 설정
cp .env.example .env  # 또는 기존 .env 사용

# 3. Docker 컨테이너 시작 (PostgreSQL, Valkey)
make docker-up

# 4. 의존성 설치 및 코드 생성
make setup

# 5. 마이그레이션 적용
make migrate-up

# 6. 서버 실행
make run

개발 모드 (Hot Reload)

# air 설치 (최초 1회)
go install github.com/air-verse/air@latest

# 개발 서버 실행
make dev
# 또는
make air

주요 Make 명령어

make build          # 바이너리 빌드
make run            # 서버 실행
make dev            # 개발 모드 (hot reload)
make test           # 테스트 실행
make test-coverage  # 테스트 커버리지 리포트

make docker-up      # Docker 컨테이너 시작
make docker-down    # Docker 컨테이너 종료
make docker-logs    # Docker 로그 확인

make generate       # ent 코드 생성
make swagger        # Swagger 문서 생성
make lint           # 코드 린트

make migrate name=init    # 마이그레이션 파일 생성
make migrate-up           # 마이그레이션 적용
make migrate-down         # 마이그레이션 롤백
make migrate-status       # 마이그레이션 상태 확인

---

API 문서

서버 실행 후 Swagger UI에서 API를 확인하고 테스트할 수 있습니다:

http://localhost:8080/swagger/index.html

주요 엔드포인트

메서드	경로	설명
GET	/api/v1/health	헬스 체크
Users
POST	/api/v1/users	사용자 생성
GET	/api/v1/users	사용자 목록 조회
GET	/api/v1/users/:id	사용자 상세 조회
PUT	/api/v1/users/:id	사용자 수정
DELETE	/api/v1/users/:id	사용자 삭제
Products
POST	/api/v1/products	상품 생성
GET	/api/v1/products	상품 목록 조회
GET	/api/v1/products/:id	상품 상세 조회
PUT	/api/v1/products/:id	상품 수정
DELETE	/api/v1/products/:id	상품 삭제
Orders
POST	/api/v1/orders	주문 생성
GET	/api/v1/orders/:id	주문 상세 조회
PATCH	/api/v1/orders/:id/status	주문 상태 변경
DELETE	/api/v1/orders/:id	주문 삭제
GET	/api/v1/users/:id/orders	사용자별 주문 조회

---

개발 가이드

새로운 도메인 추가하기

1. ent 스키마 정의 (ent/schema/)

// ent/schema/category.go
package schema

import (
    "entgo.io/ent"
    "entgo.io/ent/schema/field"
)

type Category struct {
    ent.Schema
}

func (Category) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").NotEmpty(),
        field.String("description").Optional(),
    }
}

2. ent 코드 생성

make generate

3. DTO 정의 (internal/domain/category/)

// internal/domain/category/dto.go
package category

type CreateRequest struct {
    Name        string `json:"name" binding:"required"`
    Description string `json:"description"`
}

type Response struct {
    ID          int    `json:"id"`
    Name        string `json:"name"`
    Description string `json:"description"`
}

4. Repository 작성 (internal/repository/)

5. Usecase 작성 (internal/usecase/)

6. Handler 작성 (internal/handler/)

7. 라우터 등록 (internal/handler/router.go)

8. Swagger 문서 생성

make swagger

Context 전파

Go에서는 context.Context를 모든 계층에 명시적으로 전달합니다:

// Handler
func (h *UserHandler) GetByID(c *gin.Context) {
    ctx := c.Request.Context()  // gin.Context에서 추출
    user, err := h.usecase.GetByID(ctx, id)
    // ...
}

// Usecase
func (u *userUsecase) GetByID(ctx context.Context, id int) (*user.Response, error) {
    found, err := u.repo.GetByID(ctx, id)
    // ...
}

// Repository
func (r *userRepository) GetByID(ctx context.Context, id int) (*ent.User, error) {
    return r.client.User.Get(ctx, id)  // ent에 전달
}

이렇게 하면:

• Trace ID가 모든 로그에 자동 포함
• 요청 취소가 DB 쿼리까지 전파
• 타임아웃 설정 가능

로깅

import "go-webserver/internal/infrastructure/logger"

// 기본 로깅
logger.Info().Str("key", "value").Msg("메시지")

// Context 기반 로깅 (Trace ID 자동 포함)
logger.Ctx(ctx).Debug().Interface("user", user).Msg("사용자 조회")

// 로그 레벨
logger.Debug()  // 개발용 상세 정보
logger.Info()   // 일반 정보
logger.Warn()   // 경고
logger.Error()  // 에러
logger.Fatal()  // 치명적 에러 (프로그램 종료)

테스트

// usecase 테스트 예시
func TestUserUsecase_Create(t *testing.T) {
    // Mock repository 설정
    mockRepo := new(MockUserRepository)
    usecase := NewUserUsecase(mockRepo)

    // Given
    req := user.CreateRequest{
        Name:     "테스트",
        Email:    "test@example.com",
        Password: "password123",
    }

    // When
    result, err := usecase.Create(context.Background(), req)

    // Then
    assert.NoError(t, err)
    assert.Equal(t, "테스트", result.Name)
}

---

마이그레이션

이 프로젝트는 golang-migrate를 사용합니다.

마이그레이션 파일 생성

# ent 스키마를 기반으로 SQL 생성
make migrate name=add_categories

생성되는 파일:

• migrations/20240118120000_add_categories.up.sql
• migrations/20240118120000_add_categories.down.sql

마이그레이션 적용

# 새로운 마이그레이션만 적용 (이미 적용된 것은 스킵)
make migrate-up

# 1단계 롤백
make migrate-down

# 현재 버전 확인
make migrate-status

마이그레이션 테이블

schema_migrations 테이블에서 적용된 마이그레이션을 추적합니다:

SELECT * FROM schema_migrations;
-- version | dirty
-- 20240118120000 | false

---

응답 헤더

모든 API 응답에 다음 헤더가 포함됩니다:

헤더	설명	예시
X-Trace-ID	요청 추적 ID	a838ac04
X-Response-Time	응답 시간 (ms)	1.234

---

라이선스

MIT License