플랫폼 백엔드 개발 가이드

root/
├── users/            # 회원 관리 (/users) — ort 8081
├── platform-service/ # 플랫폼 관리 (/platform) — Port 8082
├── plan/             # 사업 관리 (/plan) — Port 8083
├── contents/         # 컨텐츠 (/contents) — Port 8084
└── library/          # 공통 모듈 (공유 컴포넌트)

git clone https://github.com/your-org/platform.git
cd platform

# 전체 빌드
./gradlew clean build
 
# 특정 서비스만 빌드
./gradlew :users:build
./gradlew :platform-service:build
./gradlew :plan:build
./gradlew :contents:build

# 기본 실행 (캐시 없음)
./gradlew :users:bootRun             # http://localhost:8081
./gradlew :platform-service:bootRun  # http://localhost:8082
./gradlew :plan:bootRun              # http://localhost:8083
./gradlew :contents:bootRun          # http://localhost:8084
 
# Redis/Valkey와 함께 실행 (예: Users Service)
valkey-server --port 6380 &
./gradlew :users:bootRun \
  --args='--spring.profiles.active=local --spring.data.redis.enabled=true'

spring:
  config:
    activate:
      on-profile: local
  datasource:
    url: jdbc:mysql://localhost:3307/platform
    driverClassName: com.mysql.cj.jdbc.Driver
    username: bp_user
    password: bp_pass
  jpa:
    database-platform: org.hibernate.dialect.MySQL8Dialect
    hibernate:
      ddl-auto: none
    show-sql: true
    defer-datasource-initialization: false
  sql:
    init:
      mode: never
  h2:
    console:
      enabled: true
  data:
    redis:
      enabled: true
      host: localhost
      port: 6380
      timeout: 2000ms
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
Accept: application/json

@PostMapping("/notification")
public Rest<?> saveNotification(
        @RequestHeader("Authorization") String accessToken,
        @RequestBody NotificationRequest request
) {
    // 수동으로 JWT 파싱 필요
    String userId = tokenProvider.getUseridFromToken(accessToken);
    platformService.saveNotificationInfo(userId, request);
    return Rest.success();
}

@PostMapping("/notification")
public Rest<?> saveNotification(
        @ParsedAuthToken String userId,  // JWT에서 자동으로 userId 추출
        @RequestBody NotificationRequest request
) {
    platformService.saveNotificationInfo(userId, request);
    return Rest.success();
}

@Component
public class UsersValidatorImpl implements UserValidator {
    private final UsersRepository usersRepository;
 
    @Override
    public boolean existsById(String userId) {
        return usersRepository.existsById(userId);
    }
}

@Component
public class PlatformUserValidatorImpl implements UserValidator {
    private final UsersConnector usersConnector;
 
    @Override
    public boolean existsById(String userId) {
        Users users = usersConnector.getUserById(userId);
        return users != null && StringUtils.isNotEmpty(users.email());
    }
}

@RestController
public class ExampleController {
 
    @ValidateUser  // 사용자 검증 AOP 활성화
    @PostMapping("/example")
    public Rest<?> createExample(
            @ParsedAuthToken String userId,
            @RequestBody ExampleRequest request
    ) {
        // userId는 이미 검증된 상태로 전달됨
        // DB에 없는 사용자라면 이 메서드가 실행되기 전에 예외 발생
        return exampleService.create(userId, request);
    }
}

HTTP 요청
  → JWT 토큰에서 userId 추출 (@ParsedAuthToken)
  → AOP Aspect가 메서드 실행 전 인터셉트 (@ValidateUser)
  → UserValidator를 통해 DB에서 사용자 존재 여부 확인
      ├─ 존재 O → 정상 메서드 실행
      └─ 존재 X → UserNotFoundException 발생 → 404 응답

@FeignClient(
    name = "users-service",
    url = "${interface.endpoint.users}",
    fallbackFactory = UsersClientFallbackFactory.class
)
public interface UsersClient {
    @GetMapping("/users/{userId}")
    Rest<Users> getUserById(@PathVariable("userId") String userId);
}

@Component
public class UsersConnector {
    private final UsersClient usersClient;
    private final VirtualThreadRunner virtualThreadRunner;
 
    public Users getUserById(String userId) {
        return virtualThreadRunner.runInVirtualThread(() ->
            usersClient.getUserById(userId).data()
        );
    }
}

@Service
public class PlatformService {
    private final UsersConnector usersConnector;
 
    public void processUserData(String userId) {
        // 가상 스레드에서 비동기로 실행되지만 동기 코드처럼 작성
        Users user = usersConnector.getUserById(userId);
        processUser(user);
    }
}

@Service
public class DataAggregationService {
 
    public AggregatedData getAggregatedData(String userId) {
        // 여러 API를 병렬로 호출 (각각 가상 스레드에서 실행)
        CompletableFuture<Users> userFuture =
            CompletableFuture.supplyAsync(() -> usersConnector.getUserById(userId));
 
        CompletableFuture<Vehicle> vehicleFuture =
            CompletableFuture.supplyAsync(() -> vehicleConnector.getVehicleByUserId(userId));
 
        CompletableFuture<Content> contentFuture =
            CompletableFuture.supplyAsync(() -> contentConnector.getContentByUserId(userId));
 
        return new AggregatedData(
            userFuture.join(),
            vehicleFuture.join(),
            contentFuture.join()
        );
    }
}

src/main/kotlin/com/example/platform/{service}/
├── controller/   # REST API 컨트롤러
├── service/      # 비즈니스 로직
├── repository/   # 데이터 접근 계층
├── dto/          # 데이터 전송 객체
├── config/       # 설정 클래스 (Security, SpringDoc 등)
└── remote/       # 외부 서비스 연동 (Feign Client)

library/src/main/kotlin/com/example/platform/library/
├── entity/     # 공통 JPA 엔티티
├── response/   # 공통 응답 포맷
├── service/    # AWS SQS 등 공통 서비스
├── util/       # 유틸리티 클래스
└── config/     # 공통 설정

// 조회 (GET)
public Rest<UsersSimpleInfo> getUserById(@PathVariable String id)
public Rest<List<NotificationResponse>> getUsersNotifications(@RequestParam String id)
 
// 저장 (POST)
public Rest<?> saveNotification(
    @ParsedAuthToken String userId,
    @RequestBody NotificationRequest request
)

// 조회 (GET) — Kotlin
fun getUserInfos(@PathVariable userId: String)
fun getCategoriesById(@RequestParam id: String)

// 조회
public Optional<UsersSimpleInfo> findById(String id)
public List<NotificationResponse> getUsersLanguageByEmail(String userId)
 
// 저장
public void saveNotificationInfo(String userId, NotificationRequest request)

// 조회 — Kotlin
fun getUserInfos(userId: String)
fun findCategories(id: String)

// JPA Repository
Optional<UserInfo> findById(String id)
 
// MyBatis Mapper
int insertNotification(NotificationInfo notificationInfo)
List<NotificationInfoMap> selectNotificationsByUserId(String userId)

// JPA Repository — Kotlin
fun findByEmail(email: String): List<UserInfo>
fun findCategoriesByCategoryId(categoryId: String)

// 팩토리 메서드 — of 패턴
companion object {
    fun of(userInfo: UserInfo): UsersSimpleInfo
    fun of(categoryInfo: CategoryInfo, users: Users?): CategoriesAndUsers
}
 
// Getter
fun getPeriodStart(): Long = DateUtils.toTimestamp(periodStart)
fun getScoreCalculatedAt(): Long? = scoreCalculatedAt?.let { DateUtils.toTimestamp(it) }

// 현재값 조회
public static String getCurrentTimeString()
public static LocalDateTime getCurrentUtcLocalDateTime()
public static Long getCurrentUtcTimestamp()
 
// 변환
public static Long toTimestamp(LocalDateTime localDateTime)
public static LocalDateTime toLocalDateTime(Long timestamp)
 
// 포매팅
public static String formatDateTime(LocalDateTime dateTime)
 
// JWT
public String getUseridFromToken(String accessToken)
public Authentication getAuthentication(String accessToken)
public long getTokenExpiredDays(String token)