com.first-ticket.common

🚀 배포 방법

cp .env.example .env

# .env
GITHUB_USER=깃허브유저명
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

// 기능 추가 시 버전 올리기
version = '0.0.1-SNAPSHOT'
version = '0.0.2-SNAPSHOT'

./gradlew publish

📝 버전

📦 의존성 추가

def env = [:]
def envFile = rootProject.file(".env")
if (envFile.exists()) {
 envFile.eachLine { line ->
 if (line && !line.startsWith("#") && line.contains("=")) {
 def (key, value) = line.split("=", 2)
 env[key.trim()] = value.trim()
 }
 }
}
repositories {
 mavenCentral()
 maven {
 url = 'https://maven.pkg.github.com/first-ticket/common'
 credentials {
 username = env['GITHUB_USER']
 password = env['GITHUB_TOKEN']
 }
 }
}
dependencies {
 implementation 'com.first-ticket:common:0.0.3-SNAPSHOT'
}

# .env
GITHUB_USER=깃허브유저명
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

🗂️ 패키지 구조

com.firstticket.common
├── exception
│ ├── BusinessException.java ← 베이스 예외
│ └── GlobalExceptionHandler.java ← 전역 예외 처리
├── response
│ ├── ApiResponse.java ← 공통 응답 래퍼
│ ├── ErrorCode.java ← 에러 코드 interface
│ ├── SuccessCode.java ← 성공 코드 interface
│ ├── CommonErrorCode.java ← 공통 에러 코드
│ └── CommonSuccessCode.java ← 공통 성공 코드
├── feign
│ ├── FeignConfig.java ← Feign 설정, 헤더 전파
│ └── FeignErrorDecoder.java ← Feign 에러 처리
├── web
│ ├── WebConfig.java ← CustomPageableResolver 등록
│ ├── CustomPageableResolver.java ← 페이지 크기 강제
│ ├── AuthContext.java ← Gateway 주입 헤더 → 정적 메서드로 추출
│ └── UserRole.java ← 공통 사용자 역할 enum (CUSTOMER / HOST / ADMIN)
└── json
 ├── JsonConfig.java ← ObjectMapper 빈 등록
 └── JsonUtil.java ← JSON 직렬화/역직렬화 정적 유틸

🚀 사용 방법

1. 서비스 전용 예외 클래스 생성

// domain/exception/SampleException.java
public class SampleException extends BusinessException {
 public SampleException(SampleErrorCode errorCode) {
 super(errorCode);
 }
}

2. 서비스 전용 에러 코드 생성

// domain/exception/SampleErrorCode.java
@Getter
@RequiredArgsConstructor
public enum SampleErrorCode implements ErrorCode {
 SAMPLE_NOT_FOUND(HttpStatus.NOT_FOUND, "샘플을 찾을 수 없습니다"),
 ALREADY_CANCELLED(HttpStatus.BAD_REQUEST, "이미 취소된 샘플입니다"),
 INVALID_AMOUNT(HttpStatus.BAD_REQUEST, "유효하지 않은 금액입니다");
 private final HttpStatus status;
 private final String message;
}

3. 서비스 전용 성공 코드 생성

// presentation/SampleSuccessCode.java
@Getter
@RequiredArgsConstructor
public enum SampleSuccessCode implements SuccessCode {
 SAMPLE_CREATED(HttpStatus.CREATED, "샘플이 생성되었습니다"),
 SAMPLE_UPDATED(HttpStatus.OK, "샘플이 수정되었습니다"),
 SAMPLE_DELETED(HttpStatus.OK, "샘플이 삭제되었습니다"),
 SAMPLE_FOUND(HttpStatus.OK, "샘플을 조회했습니다");
 private final HttpStatus status;
 private final String message;
}

4. 예외 발생

throw new SampleException(SampleErrorCode.ALREADY_CANCELLED);

5. 컨트롤러에서 응답 반환

// presentation/SampleController.java
@RestController
@RequiredArgsConstructor
@RequestMapping("/samples")
public class SampleController {
 private final SampleService sampleService;
 @PostMapping
 public ResponseEntity<ApiResponse<SampleResponse>> create(
 @RequestBody SampleCreateRequest request) {
 SampleResult result = sampleService.create(request.toCommand());
 return ApiResponse.success(SampleSuccessCode.SAMPLE_CREATED,
 SampleResponse.from(result));
 }
 @DeleteMapping("/{id}")
 public ResponseEntity<ApiResponse<Void>> delete(@PathVariable Long id) {
 sampleService.delete(id);
 return ApiResponse.success(SampleSuccessCode.SAMPLE_DELETED);
 }
}

📋 응답 형식

✅ 성공 응답

{
 "success": true,
 "code": "SAMPLE_CREATED",
 "message": "샘플이 생성되었습니다",
 "timestamp": "2024年01月01日T00:00:00",
 "data": {
 "id": 1,
 "name": "샘플"
 }
}

❌ 에러 응답

{
 "success": false,
 "code": "ALREADY_CANCELLED",
 "message": "이미 취소된 샘플입니다",
 "timestamp": "2024年01月01日T00:00:00"
}

🔗 Feign

FeignClient 사용

// infrastructure/client/UserClient.java
@FeignClient(name = "user-service")
public interface UserClient {
 @GetMapping("/users/{id}")
 UserResponse getUser(@PathVariable UUID id);
}

헤더 자동 전파

Feign 에러 코드

📄 CustomPageableResolver

import org.springframework.data.domain.Pageable;
@GetMapping
public ResponseEntity<ApiResponse<SampleListResponse>> getList(Pageable pageable) {
 ...
}

요청 방법

GET /samples?page=0&size=30&sort=createdAt

GET /samples?size=100 → size=10 으로 강제 적용

🔧 JsonUtil

// 직렬화
String json = JsonUtil.toJson(sampleDto);
// 역직렬화
SampleDto dto = JsonUtil.fromJson(json, SampleDto.class);
// 제네릭 타입 역직렬화
List<SampleDto> list = JsonUtil.fromJson(json, new TypeReference<List<SampleDto>>() {});

ObjectMapper 설정

🔐 AuthContext

사용 방법

UUID userId = AuthContext.getUserId(); // X-User-Id → UUID
UserRole role = AuthContext.getRole(); // X-User-Role → UserRole

동작 규칙

주의 사항

👤 UserRole

역할 목록

사용 예시

UserRole role = AuthContext.getRole();
switch (role) {
 case ADMIN -> // 관리자 전용 로직
 case HOST -> // 호스트 전용 로직
 case CUSTOMER -> // 일반 사용자 로직
}

🔴 공통 에러 코드

🟢 공통 성공 코드