• "에러가 발생한 코드는 무엇인지?"
• "어떤 에러가 난 것인지?"

개발뿐 아니라 유지보수 상황에서도 위 두가지 질문은 끊임없이 반복되었고, 이때마다 "로그"를 보고 문제를 해결하곤 했습니다.

로그는 시스템의 모든 중요한 활동, 특히 API 호출에 대한 상세한 기록을 남기는 것입니다. 이러한 기록이 시스템 유지보수, 개발, 확장에 가장 중요한 단서가 됩니다.

로그 남기기의 여러 방식

@PostMapping("/news/{newsId}/like")
public ResponseEntity<Map<String, Object>> toggleLike(...) {
    log.info("사용자 {}가 {}번 뉴스에 '좋아요'를 눌렀습니다.", userId, newsId);
    return ResponseEntity.ok(response);
}

위와 같은 방식은 실제 업무 중 프로젝트에서도 활용되는 아주 흔한 방식입니다. 로그가 필요한 중요한 코드 주변에 로그를 남기는 코드를 작성하는 방식입니다. 하지만 이 방식은 다음과 같은 명백한 단점을 가집니다.

• 코드 중복: 모든 메소드에 거의 동일한 로그 기록 코드가 반복적으로 나타납니다.
• 비즈니스 로직 오염: 컨트롤러는 요청을 받아 서비스를 호출하고 응답을 반환하는 핵심적인 역할에만 집중해야 합니다. 로그 기록과 같은 부가적인 코드가 섞여 들어가면 코드의 가독성과 유지보수성이 크게 저하됩니다.
• 유지보수의 어려움: 로그 형식을 변경하거나 새로운 정보(예: 실행 시간)를 추가하고 싶을 때, 수십 개의 모든 메소드를 일일이 찾아 수정해야 합니다.

이번에는 프로젝트의 꽃! 로그를 기록하는 코드를 진행 중인 프로젝트에 추가하겠습니다. 객체지향적이면서도 간단하게 컨트롤러의 메소드마다 직접 로그를 기록하는 방법으로 진행해보겠습니다.

객체지향적 '로깅' 분리하기

AOP(Aspect-Oriented Programming)는 애플리케이션의 여러 부분에 공통적으로 나타나는 부가 기능(예: 로깅, 트랜잭션, 보안)을 공통 모듈로 분리하여 관리하는 프로그래밍 패러다임입니다. 저는 이번 프로젝트에서 AOP 관점을 활용하여 '활동 로그 기록'이라는 공통 관심사를 모든 컨트롤러의 비즈니스 로직으로부터 완벽하게 분리하기로 결정했습니다.

구현할 아키텍처는 아래와 같습니다.

1. 커스텀 어노테이션 생성: 로그를 기록하고 싶은 컨트롤러 메소드에 붙여주기만 하면 되는 어노테이션을 직접 생성해 보겠습니다.

2. 공통 로깅 클래스 구현: 로깅 어노테이션이 붙은 메소드의 실행을 '가로채서(Advice)', 로그 기록이라는 공통 로직을 실행 전후에 실행시키는 AOP 모듈을 만듭니다.

3. 동작: 특정 API가 호출되면, Spring은 해당 컨트롤러 메소드에 직접 생성한 로깅 어노테이션이 붙어있는지 확인합니다. 만약 붙어있다면, 메소드를 직접 실행하기 전에 ActivityLogAspect를 먼저 실행하여 로그를 기록하고, 그 후에 원래의 메소드를 실행합니다.

이 방식을 통해 메소드의 핵심 로직을 건드리지 않고 로그를 남길 수 있으며, 추후 로깅 정책 개선 시 공통 로깅 클래스만 관리하면 되어 효율적입니다.

구현

1. AOP 의존성 추가

기본적으로 프로젝트에 AOP 관련 의존성을 추가합니다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-aop'
}

2. 로그용 커스텀 어노테이션 생성

로그를 적용할 대상을 지정하기 위한 어노테이션을 직접 생성합니다.

@Target(ElementType.METHOD) // 메소드에만 적용 가능
@Retention(RetentionPolicy.RUNTIME) // 런타임에도 정보 유지
public @interface LogActivity {
    String value() default ""; // 활동 설명을 위한 속성
}

• 메소드에만 적용하겠다는 선언을 합니다.
• 런타임에도 정보가 유지될 수 있도록 합니다.
• 이루어지고 있는 활동에 대한 설명을 String 값으로 받도록 합니다.

3. AOP Aspect 구현

공통 로깅 클래스인 ActivityLogAspect 클래스를 구현합니다.

• @Aspect, @Component: 이 클래스가 Spring Bean으로 관리되는 AOP Aspect임을 선언합니다.
• @Around("@annotation(logActivity)"): @LogActivity가 붙은 모든 메소드를 타겟으로 지정하고, 해당 메소드의 실행 전후에 개입합니다.

package com.ccp.simple.aop;

import jakarta.servlet.http.HttpServletRequest;
import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

@Aspect
@Component
@Slf4j
public class ActivityLogAspect {

    @Around("@annotation(logActivity)")
    public Object logActivity(ProceedingJoinPoint joinPoint, LogActivity logActivity) throws Throwable {
        // 1. 요청 정보 수집
        HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
        String ip = request.getRemoteAddr();
        String method = request.getMethod();
        String url = request.getRequestURI();
        String activity = logActivity.value();

        // 2. 사용자 정보 수집
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        String userId = (authentication != null && authentication.isAuthenticated() && !"anonymousUser".equals(authentication.getPrincipal()))
                ? authentication.getName() : "GUEST";

        // 3. 로그 기록 (메소드 실행 전)
        log.info("[Activity Log] User: {}, IP: {}, Method: {}, URL: {}, Action: {}", userId, ip, method, url, activity);

        try {
            // 4. 원래의 타겟 메소드 실행
            Object result = joinPoint.proceed();

            // 5. 로그 기록 (메소드 성공 후)
            log.info("[Activity Log] Completed: {} - Success", activity);
            return result;
        } catch (Throwable throwable) {
            // 6. 로그 기록 (메소드 실패 시)
            log.error("[Activity Log] Failed: {} - Error: {}", activity, throwable.getMessage());
            throw throwable;
        }
    }
}

API 요청시 받을 수 있는 기본적이면서 중요한 정보를 모두 수집할 수 있도록 하였습니다. 또한 메소드 전, 후, 실패 시 모두 로그가 남을 수 있도록 설정하였습니다.

4. 메소드에 어노테이션 적용

    @LogActivity("뉴스 검색")
    @GetMapping("/news/search")
    public List<NewsResponseDto> searchNews(@RequestParam("q") String query) {
        return newsService.searchNews(query);
    }

• 메소드에 직접 생성한 @LogActivity 을 달고 내용을 작성해줍니다.
• 이렇게 간단하게 어노테이션을 달기만 해도 API 요청시 어노테이션에서 이루어지는 공통 로깅 클래스의 로직 실행 후 본 메소드의 작업이 이루어집니다.
• 추후 로그에 해당 메소드가 동작할 때 내용을 확인할 수 있습니다.

결과

실제로 아래와 같이 로그 정보가 남는 것을 확인할 수 있었습니다. 해당 로그 정보만으로도 어떠한 메소드가 실행되었고, 어떠한 이유로 에러가 났는지 명확하게 확인할 수 있었습니다.

2025-09-11T13:58:38.126+09:00  INFO 26216 --- [nio-8080-exec-1] com.ccp.simple.aop.ActivityLogAspect     : [Activity Log] User: anonymousUser, IP: 0:0:0:0:0:0:0:1, Method: POST, URL: /api/login, Action: 사용자 로그인

2025-09-11T13:58:42.820+09:00  INFO 26216 --- [nio-8080-exec-3] com.ccp.simple.aop.ActivityLogAspect     : [Activity Log] Completed: 뉴스 목록 조회 - Success


2025-09-11T13:58:38.412+09:00 ERROR 26216 --- [nio-8080-exec-1] com.ccp.simple.aop.ActivityLogAspect     : [Activity Log] Failed: 사용자 로그인 - Error: 401 UNAUTHORIZED "Invalid credentials"

결론

AOP 방식으로 로그 남기기를 적용한 결과, 아래와 같은 두 가지 큰 성과를 얻었습니다.

1. 향상된 코드 품질: 로그 기록 코드를 개별적으로 메소드 안에 작성하지 않아도 됩니다. 컨트롤러는 오직 자신의 핵심 책임에만 집중할 수 있게 되어, 코드의 가독성과 유지보수성이 비약적으로 향상되었습니다.

2. 일관된 로그: 모든 API 호출에 대해 "누가, 어디서, 무엇을, 어떻게" 했는지에 대한 일관된 형식의 로그가 자동으로 기록됩니다. 이는 서비스 운영 중 문제 추적과 사용자 행동 분석에 매우 중요한 기록이 됩니다.

Spring AOP를 활용한 로깅 방식은 여러 모듈에 걸쳐 반복적으로 나타나는 작업을 따로 분리하여 관리합니다. 간단하지만 객체 지향적 프로그래밍을 확실하게 해볼 수 있는 기능 구현이였습니다.

실시간 통신 기술에 대해서는 예전부터 익히 들었지만 실제로 사용해본 적이 없는 기술이기 때문에 이번 프로젝트에 기능을 추가하여 직접 경험해보도록 하겠습니다.

실시간 통신 기술 WebSocket과 SSE

서버에서 클라이언트로 실시간 데이터를 전송하는 기술의 양대 산맥은 WebSocket과 SSE(Server-Sent Events)입니다.

WebSocket

클라이언트와 서버 사이에 양방향 통신 채널을 구축하는 프로토콜 입니다. 연결이 되면 클라이언트와 서버 모두 자유롭게 데이터를 주고 받을 수 있습니다. 양방향 통신을 하기 때문에 그만큼 구현이 복잡하고 더 많은 리소스를 필요로 합니다.

• 양방향 통신: 클라이언트가 요청하지 않아도 서버가 클라이언트에게 데이터를 보낼 수 있고, 클라이언트도 서버에 데이터를 보낼 수 있습니다.
• 활용: 실시간성이 중요한 애플리케이션에 적합합니다. 예를 들어, 온라인 게임, 채팅 애플리케이션, 주식 시세, 실시간 협업 도구 등에 사용됩니다.
• 프로토콜: HTTP 프로토콜을 사용해 핸드셰이크(Handshake) 과정을 거쳐 연결을 설정한 후, 독자적인 WebSocket 프로토콜로 전환이 됩니다. 이 덕분에 통신 오버헤드가 적고 효율적입니다.

SSE (Server-Sent Events)

오직 서버에서 클라이언트로 즉, 단방향으로 통신하는 기술입니다.

• 단방향 통신: 서버에서 클라이언트로만 데이터가 전달됩니다. (클라이언트는 서버에 메시지를 보내기 위해 별도의 HTTP 요청을 해야 합니다.)
• 활용: 서버에서 발생하는 이벤트를 실시간으로 클라이언트에게 전달하는 경우에 활용됩니다. 예를 들어, 뉴스 피드 업데이트, 알림, 스포츠 경기 스코어 업데이트 등에 사용됩니다.
• 프로토콜: HTTP를 기반으로 하며, 특별한 Content-Type(text/event-stream)을 사용합니다. 이 때문에 방화벽이나 프록시 서버에 대한 호환성이 좋다는 장점이 있습니다.

주요 차이점 요약

그렇다면 프로젝트에서는 무엇을 써야할까?

이번 프로젝트에서는 스케줄러를 통해 뉴스가 자동으로 수집이 됩니다. 이때 사용자 본인이 등록한 키워드에 해당하는 뉴스가 수집이 되면 "새로운 뉴스가 수집되었음"을 알림으로 제공할 예정입니다. 이 기능을 통해 사용자는 더 이상 중요한 정보를 놓칠까 봐 초조해하며 페이지를 새로고침할 필요 없이, 가장 관심 있는 주제의 최신 뉴스를 누구보다 빠르게 접할 수 있게 됩니다.

"사용자가 관심 키워드로 등록한 새로운 뉴스가 시스템에 수집되는 즉시, 해당 사용자에게 실시간으로 알림을 보내준다."

즉, 현재 요구사항은 "서버가 사용자에게 알림을 보낸다"는 명확한 단방향 통신입니다. 사용자가 알림에 대해 실시간으로 서버에 응답할 필요는 없습니다. 따라서 더 가볍고, 구현이 간단하며, HTTP 표준을 그대로 사용하여 프록시나 방화벽 문제에서 더 자유로운 SSE를 채택하기로 결정했습니다. Spring MVC는 SseEmitter라는 클래스를 통해 SSE를 매우 쉽게 구현할 수 있도록 지원하므로, 별도의 라이브러리 추가도 필요 없었습니다.

구현

실시간 알림 시스템은 크게 세 가지 요소로 구성됩니다.

1. Subscriber (구독자): 알림을 받기 위해 서버에 연결하는 클라이언트
2. Emitter (발신자): 서버에서 생성되어 각 클라이언트와의 연결을 유지하는 '파이프라인'
3. Trigger (방아쇠): 알림을 보내야 할 특정 이벤트가 발생했을 때, Emitter를 통해 메시지를 발송하는 로직

알림 서비스 및 컨트롤러 구현 (Emitter와 Subscriber)

• 가장 먼저, 모든 SSE 연결(SseEmitter)을 관리하고 알림을 전송하는 역할을 전담할 NotificationService를 구현했습니다.

• 연결 관리: ConcurrentHashMap을 사용하여 userId와 SseEmitter 객체를 1:1로 매핑하여 관리합니다. 사용자가 접속을 끊거나 타임아웃이 발생하면, 이 맵에서 자동으로 해당 Emitter를 제거하여 메모리 누수를 방지합니다.

@Slf4j
@Service
public class NotificationServiceImpl implements NotificationService {

    private static final Long DEFAULT_TIMEOUT = 60L * 1000 * 60; // 1시간
    private final Map<String, SseEmitter> emitters = new ConcurrentHashMap<>();

    @Override
    public SseEmitter subscribe(String userId) {
        SseEmitter emitter = new SseEmitter(DEFAULT_TIMEOUT);
        emitters.put(userId, emitter);

        emitter.onCompletion(() -> emitters.remove(userId));
        emitter.onTimeout(() -> emitters.remove(userId));
        emitter.onError(e -> emitters.remove(userId));

        sendToClient(userId, "EventStream Created. [userId=" + userId + "]");

        return emitter;
    }

    @Override
    public void send(String userId, Object data) {
        sendToClient(userId, data);
    }

    private void sendToClient(String userId, Object data) {
        SseEmitter emitter = emitters.get(userId);
        if (emitter != null) {
            try {
                emitter.send(SseEmitter.event()
                        .id(String.valueOf(System.currentTimeMillis()))
                        .name("sse")
                        .data(data));
            } catch (IOException e) {
                emitters.remove(userId);
                log.error("SSE 연결 오류 발생 [userId={}]", userId, e);
            }
        }
    }
}

• 클라이언트가 알림을 구독할 수 있는 API 엔드포인트를 NotificationController에 추가했습니다.

    @GetMapping(value = "/subscribe", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter subscribe(Authentication authentication) {
        String userId = authentication.getName();
        return notificationService.subscribe(userId); // 사용자를 위한 Emitter 생성 및 반환
    }

알림 발생 로직 연동 (Trigger)

1. 구독자 조회: 새로운 뉴스가 어떤 keywordId와 관련 있는지 알고 있으므로, user_keyword_mapping 테이블을 조회하여 해당 keywordId를 구독하는 모든 userId 목록을 가져오는 매퍼 쿼리를 추가했습니다.

2. 알림 전송: insertNews 메소드 안에서, 새로운 뉴스가 DB에 성공적으로 저장된 직후, 위 쿼리를 통해 얻은 모든 구독자에게 NotificationService를 통해 알림을 전송합니다.

List<String> subscribedUserIds = newsMapper.findUserIdsByKeywordId(keywordId);
for (String userId : subscribedUserIds) {
    String notificationMessage = "관심 키워드 관련 새 뉴스가 도착했습니다: " + news.getTitle();
    notificationService.send(userId, notificationMessage);
}

테스트

사용자가 웹사이트에 접속하여 알림 채널을 구독하고 있는 상태에서, 백엔드 스케줄러가 해당 사용자의 관심 키워드와 일치하는 새로운 뉴스를 수집하면, 사용자의 화면에는 페이지 새로고침 없이도 즉시 알림이 표시됩니다.

해당 로직은 curl로 연결하여 테스트를 진행하였습니다.

결론

서버와 클라이언트 간의 실시간 통신 기능은 SSE를 활용해 비교적 간단하게 구현할 수 있었습니다. 직접 구현을 해보니 간단한 기술로 사용자 경험을 극적으로 향상시킬 수 있겠다는 생각이 들었습니다. 특히 이번 구현을 통해 비동기 스케줄러(뉴스 수집)와 실시간 이벤트(알림 전송)라는 두 가지 다른 시간적 흐름을 가진 로직을 자연스럽게 연동하는 경험을 할 수 있었습니다.

추후 기회가 된다면 양방향 통신 기술도 직접 적용하고 활용해보도록 하겠습니다.

    UPDATE TABLE_A SET VIEW_COUNT = VIEW_COUNT + 1 WHERE ID = A;

이 방식은 구현이 매우 간단하지만, 서비스가 성장하고 트래픽이 증가함에 따라 심각한 성능 병목의 주범이 됩니다.

• 과도한 DB 쓰기 부하: 모든 조회 요청이 데이터베이스에 직접적인 쓰기(Write) 작업을 발생시킵니다. 인기 있는 게시물 하나에 트래픽이 집중되면, 해당 테이블의 특정 행(Row)에 엄청난 양의 UPDATE 쿼리가 몰리게 됩니다.
• I/O 병목과 Lock 경쟁: 디스크 기반의 RDBMS에서 쓰기 작업은 비용이 높은 I/O를 동반합니다. 또한, 빈번한 UPDATE는 테이블 또는 행 수준의 락(Lock)을 유발하여, 다른 중요한 트랜잭션(예: 글 작성, 결제)의 성능까지 저하시킬 수 있습니다.
• 응답 시간 저하: DB의 부하가 증가하면, 사용자가 게시물을 조회하는 API의 응답 시간 또한 길어져 전반적인 사용자 경험(UX)을 해치게 됩니다.

Redis + RDBMS 하이브리드 아키텍처

이 문제를 해결하기 위해, 우리는 In-Memory 데이터 저장소인 Redis를 도입하여 RDBMS의 부하를 덜어주는 하이브리드 아키텍처를 설계했습니다.

Redis는 Key-Value 기반의 고성능 데이터 저장소로, 모든 데이터를 디스크가 아닌 메모리에 저장합니다. 이 특징은 '조회수 집계'와 같은 시나리오에서 다음과 같은 결정적인 장점을 제공합니다.

• 원자적 연산(Atomic Operation)과 엄청난 속도: Redis는 특정 키의 숫자 값을 1씩 증가시키는 INCR 명령어를 제공합니다. 이 명령어는 원자성(Atomicity)이 보장되므로, 여러 클라이언트가 동시에 요청해도 데이터의 정합성이 깨지지 않습니다. 또한, 모든 연산이 메모리 상에서 이루어지므로 RDBMS의 UPDATE와는 비교할 수 없는 속도를 자랑합니다.
• DB 부하 분산: 빈번하게 발생하는 모든 조회수 증가 요청을 Redis가 먼저 처리하도록 하여, RDBMS는 더 이상 사소한 UPDATE 작업에 시달리지 않고 데이터의 영구 저장 및 복잡한 조회라는 본연의 역할에 집중할 수 있습니다.

실시간 처리와 비동기 동기화

Redis의 '속도'와 RDBMS의 '안정성'을 모두 보장하기 위해 아래와 같이 설계하였습니다.

1. 실시간 조회수 기록 (Redis): 사용자가 뉴스를 조회하면, API 서버는 즉시 Redis의 INCR 명령어를 호출하여 news:view:{뉴스ID} 형태의 키 값을 1 증가시킵니다. 이 과정은 DB를 전혀 거치지 않으므로 매우 빠릅니다.

2. 주기적인 DB 동기화 (Scheduler): Spring Scheduler를 이용한 배치 작업이 주기적으로(예: 5분마다) 실행됩니다.

3. 최종 결과 업데이트 (RDBMS): 스케줄러는 Redis에 기록된 모든 뉴스의 최종 조회수 값을 가져와, RDBMS(PostgreSQL)의 view_count 컬럼에 한 번에 업데이트합니다.

실시간 처리는 Redis가 전담하고, 데이터의 영구 저장은 스케줄러를 통한 비동기 방식으로 처리함으로써, 시스템의 성능과 안정성을 모두 확보할 수 있습니다.

구현

@PostMapping("/news/{newsId}/view")
public ResponseEntity<Void> incrementViewCount(@PathVariable Long newsId) {
    newsService.incrementViewCount(newsId);
    return ResponseEntity.ok().build();
}

@Override
public void incrementViewCount(Long newsId) {
    String viewKey = "news:view:" + newsId;
    redisTemplate.opsForValue().increment(viewKey);
}

DB 동기화 스케줄러 구현

// ViewCountSyncScheduler.java

@Slf4j
@Component
@RequiredArgsConstructor
public class ViewCountSyncScheduler {

    private final RedisTemplate<String, String> redisTemplate;
    private final NewsService newsService;

    // 5분마다 실행
    @Scheduled(cron = "0 */5 * * * *")
    public void syncViewCountsToDb() {
        log.info("Redis '조회수' DB 동기화 시작");
        // 1. 'news:view:' 패턴의 모든 키를 조회
        Set<String> viewKeys = redisTemplate.keys("news:view:*");

        if (viewKeys == null || viewKeys.isEmpty()) {
            return;
        }

        for (String key : viewKeys) {
            try {
                // 2. 키에서 newsId 파싱
                Long newsId = Long.parseLong(key.split(":")[2]);
                // 3. Redis에서 최종 조회수 GET
                String viewCountStr = redisTemplate.opsForValue().get(key);

                if (viewCountStr != null) {
                    int viewCount = Integer.parseInt(viewCountStr);
                    // 4. 서비스 계층을 통해 DB에 업데이트
                    newsService.updateViewCountInDb(newsId, viewCount);
                }
            } catch (Exception e) {
                log.error("키 '{}' 처리 중 오류 발생: {}", key, e.getMessage());
            }
        }
        log.info("Redis '조회수' DB 동기화 완료");
    }
}

데이터 조회 로직

• DB에 저장된 값이 기본 + Redis에 실시간 값이 존재하면 그 값으로 덮어쓰는 방식으로 구현하였습니다.

// NewsServiceImpl.java - matchEsResultsWithRedisData() 메소드 내부

private void matchEsResultsWithRedisData(List<NewsResponseDto> newsList, String userId) {
    for (NewsResponseDto news : newsList) {
        // ... (기존 좋아요 로직)

        // 실시간 조회수 보강
        String viewKey = "news:view:" + news.getNewsId();
        String viewCountStr = redisTemplate.opsForValue().get(viewKey);

        // Redis에 실시간 조회수 값이 있으면, 그 값으로 DTO의 viewCount를 덮어쓴다.
        if (viewCountStr != null) {
            news.setViewCount(Integer.parseInt(viewCountStr));
        } 
        // Redis에 값이 없으면, DB에서 조회해 온 기존 viewCount 값이 그대로 유지된다.
    }
}

결론

단순한 UPDATE 쿼리 방식에서 벗어나 Redis와 스케줄러를 활용한 비동기 아키텍처를 도입함으로써, 대규모 트래픽 상황에서도 안정적으로 조회수를 집계하고 사용자에게 빠른 응답을 제공할 수 있는 견고한 기반을 마련했습니다. 이 아키텍처는 조회수뿐만 아니라, '좋아요 수', '실시간 랭킹', '재고 관리' 등 빈번한 쓰기 작업이 발생하는 다양한 시나리오에 효과적으로 적용될 수 있는 매우 유연하고 강력한 패턴입니다.

이번에는 "나와 비슷한 취향을 가진 다른 사람들은 무엇을 좋아했을까?"라는 아이디어를 기반으로 뉴스 '추천' 기능을 구현해보겠습니다. 이 방식은 콘텐츠의 내용과는 무관하게, 사용자의 '좋아요' 정보를 활용하여 추천하는 기능입니다.

구현

1. 컨트롤러 계증에 '추천' API 엔드 포인트 추가

// 개인화 추천
@GetMapping("/news/recommend")
public List<NewsResponseDto> getRecommend(Authentication authentication) {
    String userId = authentication.getName();
    return recommendationService.recommendNewsBySimilarUsers(userId, 10); // 상위 10개 추천
}

• NewsController에 GET /api/news/recommend 라는 API 엔드포인트를 만듭니다.
• 이 엔드포인트는 Authentication 정보를 파라미터로 받아 사용자의 정보를 조회한 뒤 해당 정보를 넘겨 '추천' 결과를 반환합니다.

2. '좋아요' 데이터에 기반한 '추천' 메소드 작성

@Service
@RequiredArgsConstructor
public class RecommendationServiceImpl implements RecommendationService {

    private final NewsMapper newsMapper;
    private final RedisTemplate<String, String> redisTemplate;

    @Override
    public List<NewsResponseDto> recommendNewsBySimilarUsers(String userId, int limit) {
        // 1. 현재 사용자와 취향이 비슷한 사용자 조회
        List<String> similarUserIds = newsMapper.searchSimilarUsers(userId, 5);

        if (similarUserIds.isEmpty()) {
            return Collections.emptyList();
        }

        // 2. 유사 사용자들이 좋아한 뉴스 ID 조회
        List<Long> recommendedNewsIds = newsMapper.searchNewsIdsBySimilarUsers(similarUserIds);

        if (recommendedNewsIds.isEmpty()) {
            return Collections.emptyList();
        }

        // 3. 현재 사용자가 이미 좋아요한 뉴스 제외
        List<Long> likedNewsIdsByUser = newsMapper.searchLikedNewsIdsByUser(userId);

        List<Long> distinctRecommendNewsIds = new ArrayList<>();
        Set<Long> set = new HashSet<>();

        for (Long newsId : recommendedNewsIds) {
            if (!likedNewsIdsByUser.contains(newsId) && set.add(newsId)) {
                distinctRecommendNewsIds.add(newsId);
                if (distinctRecommendNewsIds.size() >= limit) break;
            }
        }

        if (distinctRecommendNewsIds.isEmpty()) {
            return Collections.emptyList();
        }

        // 4. 뉴스 상세 조회 + Redis 데이터 결합
        List<NewsResponseDto> recommendations = newsMapper.findNewsByIds(distinctRecommendNewsIds);
        matchEsResultsWithRedisData(recommendations, userId);

        return recommendations;
    }

    // Redis에 저장된 좋아요 수 & 상태 매칭
    private void matchEsResultsWithRedisData(List<NewsResponseDto> newsList, String userId) {
        for (NewsResponseDto news : newsList) {
            String likeKey = "news:like:" + news.getNewsId();
            Long likeCount = redisTemplate.opsForSet().size(likeKey);
            news.setLikeCount(likeCount != null ? likeCount.intValue() : 0);

            if (userId != null) {
                news.setLiked(Boolean.TRUE.equals(redisTemplate.opsForSet().isMember(likeKey, userId)));
            } else {
                news.setLiked(false);
            }
        }
    }
}

    <select id="searchSimilarUsers" resultType="string">
        SELECT u2.user_id
        FROM user_news_like u1
        JOIN user_news_like u2 ON u1.news_id = u2.news_id AND u1.user_id != u2.user_id
        WHERE u1.user_id = #{userId}
        GROUP BY u2.user_id
        ORDER BY COUNT(*) DESC
        LIMIT #{limit}
    </select>

    <select id="searchNewsIdsBySimilarUsers" resultType="long">
        SELECT DISTINCT news_id
        FROM user_news_like
        WHERE user_id IN
        <foreach collection="list" item="id" open="(" separator="," close=")">
            #{id}
        </foreach>
    </select>

    <select id="searchLikedNewsIdsByUser" resultType="long">
        SELECT news_id
        FROM user_news_like
        WHERE user_id = #{userId}
    </select>

이번에 구현한 서비스는 간단히 DB 데이터만 활용하여 구현하였습니다. 기능 구현 과정은 아래와 같이 논리적 설계만 잘하면 추천 기능을 구현할 수 있었습니다.

1. 현재 사용자와 유사한 사용자들('좋아요'한 데이터가 같은 사용자)을 찾는다.
2. 유사한 사용자들이 좋아한 뉴스를 모은다.
3. 현재 사용자가 이미 좋아요한 뉴스는 제외한다.
4. 추천 후보군을 DB에서 조회하고, Redis에 저장된 좋아요 수와 상태를 결합하여 반환한다.

테스트

테스트 시나리오

• 사용자 A: 뉴스 70번, 71번, 69번, 74번 '좋아요'
• 사용자 B: 뉴스 70번, 71번, 73번, 76번 '좋아요' (A와 1, 2번이 겹침 -> 유사도 높음)
• 사용자 C: 뉴스 59번, 62번, 72번 '좋아요' (A와 겹치는 뉴스가 없음 -> 유사도 낮음)

'사용자 A'로 로그인하여 추천을 요청하면, A와 취향이 비슷한 '사용자 B'가 좋아했던 뉴스 중에서 A가 아직 보지 않은 73번, 76번 뉴스가 추천되어야 합니다.

API 요청

1. '사용자 A'로 로그인 합니다.
2. 새 요청을 열고, Method를 GET으로 설정합니다.
3. GET /api/news/recommendations 요청을 보냅니다.

결과 조회

• 위 테스트 시나리오에서 예상한 결과대로 반환된 뉴스 목록은 73번, 76번 뉴스로 확인하였습니다.
• 사용자가 이미 '좋아요'를 누른 뉴스(70, 71, 69, 74번)는 추천 목록에서 제외되어 있는 것을 확인하였습니다.

이번 구현에서는 유사 사용자 기반 추천(Collaborative Filtering)을 단순화해서 적용해봤습니다. 이전에 작업한 콘텐츠 기반 추천(Content-based Filtering) 방식과 더불어 조금 더 편리한 검색, 추천 서비스를 제공할 수 있는 기능을 구현해볼 수 있었습니다.

Elasticsearch 'More Like This'

MLT 쿼리란 ?

우리는 웹, 앱 어디서든 검색 결과와 관련된 '추천' 콘텐츠를 쉽게 마주합니다. 아래 이미지와 같이 벨로그에서도 포스팅 하단에 '관심 있을 만한 포스트'를 제공합니다. Elasticsearch의 MLT 쿼리는 바로 이러한 추천 기술을 가능하게 합니다.

MLT 쿼리는 말 그대로 "이것과 비슷한" 문서를 찾아주는 쿼리입니다. 사용자가 특정한 문서(또는 텍스트)를 선택하면 그것와 내용이 유사한 다른 것들을 추천해주는 기능을 합니다.

MTL 쿼리 방식은 아주 간단하게 아래와 같이 동작합니다.

• "엘라스틱서치 MLT를 활용한 검색 시스템"이라는 뉴스 기사를 기준 문서로 정함
• 엘라스틱서치가 이 문서에서 중요한 단어(키워드)를 뽑음
• 그 키워드들을 기준으로 비슷한 단어가 많이 들어있는 다른 문서를 찾아줌

또한 아래와 같이 쿼리를 작성하여 검색 내용을 설정할 수 있습니다.

GET news/_search
{
  "query": {
    "more_like_this": {                     // MLT 쿼리를 쓰겠다
      "fields": ["title", "content"],    // 어떤 필드에서 비교할지(제목과 콘텐츠)
      "like": [                          // 이 문서와 비슷한 걸 찾아라
        {
          "_index": "news",              // news로 인덱싱 되어 있고,
          "_id": "1"                     // id가 1인 문서
        }
      ],
      "min_term_freq": 1,              // 최소 몇 번은 나와야 키워드로 쓸지(1번 이상)
      "min_doc_freq": 1                // 최소 몇 개 문서에 등장해야 쓸지(1번 이상)
    }
  }
}

• 검색어가 들어오면 어떤 필드와 비교할지를 결정
• 어떤 문서를 대상으로 할지 결정
• 그 문서에서 몇 번 이상 언급되어야 키워드로 취급할지 결정
• 다른 문서 중 몇 번 이상 키워드가 언급되어야 관련 문서로 취급하는지 결정

해당 쿼리는 아주 기본적인 MLT 쿼리 작성 방식이며, 아래의 공식 문서 참고하여 추가적으로 검색 설정을 고급화할 수 있습니다.

• https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-mlt-query

MLT 쿼리 장점

• 강력한 유사도 분석: 단순히 단어의 빈도를 넘어, BM25/TF-IDF 알고리즘을 기반으로 문서(뉴스) 간의 연관성을 지능적으로 분석합니다.
  • 엘라스틱서치 5.x 버전 이후 TF-IDF → BM25 알고리즘으로 변경(TF-IDF를 개선한 가중치 모델)
  • TF-IDF/BM25 알고리즘 비교 참고글 : https://velog.io/@mayhan/Elasticsearch-%EC%9C%A0%EC%82%AC%EB%8F%84-%EC%95%8C%EA%B3%A0%EB%A6%AC%EC%A6%98
• 간결한 구현: 복잡한 유사도 계산 로직을 직접 구현할 필요 없이, 간단한 쿼리 하나로 해결할 수 있습니다.
• 유연한 설정: 최소 단어 빈도, 최소 문서 빈도 등 다양한 파라미터를 조정하여 추천의 정밀도를 튜닝할 수 있습니다.

3. 구현

진행하고 있는 프로젝트에 이미 검색 엔진으로 사용 중인 Elasticsearch 의 내장 기능 More Like This 쿼리를 활영하여 뉴스 목록 검색 시 관련 뉴스도 함께 검색되도록 구현해보겠습니다.

1. '유사 뉴스 검색' 서비스 메소드 작성

• NewsService 인터페이스에 searchSimilarNews(Long newsId) 메소드를 선언합니다.
• NewsServiceImpl에 moreLikeThisQuery를 사용하여 실제 추천 로직을 구현합니다.
• 이 쿼리는 Elasticsearch에게 "이 newsId를 가진 문서와 title, description 필드의 내용이 유사한 다른 문서들을 찾아줘" 라고 요청하는 역할을 부여합니다.
• 반환되는 데이터에 Redis의 정보를 결합(추가 정보 최신화 ex. 좋아요 수, 사용자 정보 등)하여 NewsResponseDto 형태로 제공합니다.

    @Override
    public List<NewsResponseDto> searchSimilarNews(Long newsId) {
        Query esQuery = new Query.Builder()
                .moreLikeThis(mlt -> mlt
                        .fields("title", "description")
                        .like(l -> l.document(d -> d.index("news").id(String.valueOf(newsId))))
                        .minTermFreq(1)
                        .minDocFreq(1)
                )
                .build();
        return searchElasticsearch(esQuery);
    }

    //엘라스틱서치 검색
    private List<NewsResponseDto> searchElasticsearch(Query esQuery) {
        NativeQuery nativeQuery = new NativeQueryBuilder().withQuery(esQuery).build();
        SearchHits<NewsDocument> searchHits = elasticsearchOperations.search(nativeQuery, NewsDocument.class);

        List<Long> newsIds = new ArrayList<>();
        //searchHits에서 newsIds를 반환
        for(SearchHit<NewsDocument> hit : searchHits.getSearchHits()) {
            NewsDocument content = hit.getContent();
            newsIds.add(content.getNewsId());
        }
        return orderResults(newsIds);
    }

    // 결과 유사도 정렬 유지
    private List<NewsResponseDto> orderResults(List<Long> newsIds) {
        if (newsIds.isEmpty()) {
            return Collections.emptyList();
        }

        Map<Long, NewsResponseDto> newsDtoMap = new HashMap<>();
        List<NewsResponseDto> newsByIds = newsMapper.findNewsByIds(newsIds);

        for (NewsResponseDto newsDto : newsByIds) {
            newsDtoMap.put(newsDto.getNewsId(), newsDto);
        }

        List<NewsResponseDto> newsList = (List<NewsResponseDto>) newsDtoMap.values();
        String userId = checkUserId();
        matchEsResultsWithRedisData(newsList, userId);

        List<NewsResponseDto> resultList = new ArrayList<>();
        //검색결과 유사도 정렬 유지
        for (Long newsId : newsIds) {
            NewsResponseDto newsDto = newsDtoMap.get(newsId);
            if (newsDto != null) {
                resultList.add(newsDto);
            }
        }
        return resultList;
    }

1. moreLikeThisQuery를 사용하여 Elasticsearch에 요청할 쿼리를 생성합니다.
2. 아래의 검색 정보를 설정합니다.
   • 어떤 필드를 비교할 것인가: title과 description 필드의 내용을 비교하도록 지정
   • 어떤 문서를 기준으로 할 것인가: like() 메소드에 기준이 되는 뉴스의 ID(newsId)를 전달
   • 최소 빈도 설정: minTermFreq(1), minDocFreq(1) 옵션 설정(너무 드물게 나타나는 단어는 유사도 계산에서 제외)
3. searchNews 메소드에서 구현했던 로직을 재사용하여, Elasticsearch에서 찾은 유사 뉴스 ID 목록에 DB와 Redis의 최신 상태 정보를 결합하여 최종 결과를 반환합니다.

2. 컨트롤러 계층에 유사 검색 API 엔드 포인트 추가

    // 유사 뉴스 추천
    @GetMapping("/news/{newsId}/similar")
    public List<NewsResponseDto> findSimilarNews(@PathVariable Long newsId) {
        return newsService.findSimilarNews(newsId);
    }

• NewsController에 GET /api/news/{newsId}/similar 라는 API 엔드포인트를 만듭니다.
• 이 엔드포인트는 경로의 newsId를 기준으로, 해당 뉴스와 유사한 뉴스 목록을 클라이언트에게 반환합니다.

테스트 및 화면단 코드 추가

위과 같이 백엔드 코드를 추가 후 화면에서 '관련 뉴스'가 표출될 수 있도록 vue.js 코드를 수정 및 추가하여 테스트를 진행하였습니다.

• 기본 엘라스틱서치 검색 후 반환되는 뉴스 중 첫 번째 뉴스(가장 관련도가 높음)를 기준으로
• 유사 뉴스 검색 API 전송
• 일반 뉴스 검색 목록 + 유사 뉴스 목록 구분하여 표출

const news = ref([])
const similarNews = ref([]);
const searchQuery = ref("")

const searchNews = async () => {
    const accessToken = userStore.token;
    if (!accessToken) {
        alert("로그인이 필요합니다.");
        router.push('/');
        return;
    }

    if (!searchQuery.value.trim()) {
        fetchNews();
        similarNews.value = [];
        return;
    }

    //뉴스 초기화
    news.value = [];
    similarNews.value = [];

    try {
        // 뉴스 검색
        const response = await apiRequest(`/api/news/search?q=${encodeURIComponent(searchQuery.value)}`, {
            method: 'GET',
            headers: { Authorization: `Bearer ${accessToken}` },
        });

        if (response.status === 401 || response.status === 403) {
            alert("인증이 필요합니다. 로그인 페이지로 이동합니다.");
            router.push('/');
            return;
        }

        if (!response.ok) {
            throw new Error('뉴스 검색 API 호출 실패');
        }

        const searchData = await response.json();
        news.value = searchData.map(item => ({
            ...item,
            likeCount: item.likeCount || 0,
            isLiked: item.liked || false,
        }));

        // 유사 뉴스 검색
        if (news.value.length > 0) {
            const firstNewsId = news.value[0].newsId; // 첫 번째 뉴스 ID 추출

            const similarNewsResponse = await apiRequest(`/api/news/${firstNewsId}/similar`, {
                method: 'GET',
                headers: { Authorization: `Bearer ${accessToken}` },
            });

            if (similarNewsResponse.ok) {
                const similarNewsData = await similarNewsResponse.json();
                similarNews.value = similarNewsData.map(item => ({
                    ...item,
                    likeCount: item.likeCount || 0,
                    isLiked: item.liked || false,
                }));
            } else {
                console.error('유사 뉴스 API 호출 실패');
                similarNews.value = [];
            }
        }

    } catch (err) {
        console.error('오류 발생:', err);
        alert(err.message || '뉴스 검색 중 오류가 발생했습니다.');
        news.value = [];
        similarNews.value = [];
    } 
};

• 검색 결과뿐만 아니라 '관련 뉴스'도 표출이 되는 것을 확인할 수 있었습니다.
• Redis의 최신 상태 정보를 결합 결과가 표출되는 것을 확인할 수 있었습니다.

결론

Elasticsearch의 More Like This 쿼리를 활용해 복잡한 추천 알고리즘 없이도 간단하게 유사 뉴스 추천 기능을 구현할 수 있었습니다. 처음 접했을 때는 다소 낯설고 어렵게 느껴졌지만, 엘라스틱서치가 제공하는 간단한 설정만으로 서비스에 꼭 필요한 ‘추천’ 기능을 손쉽게 구현할 수 있음을 확인했습니다.

오늘 구현한 작업을 바탕으로 추천 결과에 사용자 행동 데이터(예: 조회수, 좋아요, 클릭 이력)를 반영하거나, 가중치를 조정하는 방식으로 기능을 고도해볼 계획입니다.

현재 프로젝트는 '개인 맞춤형 뉴스 제공'을 목적으로 스프링 스케줄러를 통해 네이버 뉴스 기사를 수집하여 데이터로 활용하고 있습니다. 이에 엘라스틱서치를 활용하여 수집되는 뉴스 데이터를 쌓아두고, 강력한 검색 기능을 제공할 수 있도록 하겠습니다.

Elasticsearch 도입 이유 ?

우선 엘라스틱서치를 도서관을 예를 들어 진행 중인 프로젝트에 어떤 이점이 있는지 살펴보겠습니다.

• PostgreSQL (RDBMS): 도서관의 모든 책(데이터)을 책장에 순서대로 꽂아두는 서고와 같습니다. 특정 책(예: ID가 123인 책)을 찾거나, 특정 저자의 책 목록을 찾는 데에는 매우 효율적입니다. 하지만 "인공지능에 대한 내용이 포함된 모든 책을 찾아줘" 와 같은 내용 기반 검색에는 매우 취약하고 느립니다.

• Elasticsearch: 이 도서관의 슈퍼 파워를 가진 사서 또는 디지털 검색 시스템과 같습니다. 모든 책의 제목, 저자, 목차, 본문 내용을 전부 키워드별로 분석해서 색인(Index)을 만들어 둡니다. 그래서 다음과 같은 복잡하고 강력한 검색이 가능해집니다.

  • "머신러닝"으로 검색했지만 "기계학습"이 포함된 책도 찾아주기 (동의어 처리)
  • "develop"으로 검색했지만 "developing", "developed"가 포함된 책도 찾아주기 (형태소 분석)
  • "인공지능"과 "빅데이터"가 모두 언급된 책 찾아주기 (복합 조건 검색)
  • 오타가 좀 있어도 (예: "머신러닝" -> "머신러니") 알아서 찾아주기 (오타 교정)

이와 같이 '개인 맞춤형 뉴스 제공'을 목표로 하는 프로젝트에 엘라스틱서치를 통해 아래와 같은 이점을 취할 수 있을 것으로 예상됩니다.

1. 강력한 전문(Full-text) 검색 : 사용자가 뉴스 제목이나 내용의 일부만으로 원하는 기사를 빠르고 정확하게 찾을 수 있습니다. (SQL의 LIKE '%...%' 와는 비교할 수 없는 성능과 정확도)

2. 콘텐츠 기반 추천의 초석 : 특정 뉴스 기사와 "유사한 내용의 다른 뉴스"를 찾는 것이 매우 쉬워집니다. 예를 들어, 사용자가 '인공지능'에 대한 뉴스를 좋아했다면, Elasticsearch에 "이 기사와 비슷한 기사들을 찾아줘"라고 요청하여 관련 뉴스를 추천해 줄 수 있습니다.

3. 다양한 통계 및 필터링 : 카테고리별, 기간별, 키워드별 뉴스 집계 및 필터링을 매우 빠른 속도로 처리하여 관리자 대시보드나 사용자 필터 기능을 구현하는 데 유리합니다.

1. Elasticsearch 서버 생성 및 실행

# Docker로 Elasticsearch 8.14.1 버전 실행 명령어
docker run -d --name simple-elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.14.1 

2. 스프링부트 프로젝트 의존성 및 설정 추가

Spring Boot 프로젝트가 Elasticsearch와 통신할 수 있도록 관련 라이브러리를 build.gradle 파일에 추가합니다.

implementation 'org.springframework.boot:spring-boot-starter-data-elasticsearch'

Elasticsearch 서버 연결을 위해 application.yml 에 설정 정보를 추가합니다. 일반적으로 Elasticsearch는 9200번 포트로 통신합니다. 로컬 개발 환경을 기준으로, localhost:9200으로 접속하도록 설정합니다.

  elasticsearch:
    uris: http://localhost:9200

3. Document 모델 생성 (Elasticsearch에 저장될 데이터 설계)

이제 Elasticsearch에 어떤 데이터를, 어떤 형태로 저장할지 설계합니다. 이 역할을 하는 것이 바로 Document 클래스입니다.

@Document

• Elasticsearch에서는 @Document 어노테이션을 붙인 클래스를 만들어 인덱스(Index)에 저장될 문서(Document) 데이터를 표현합니다.

  • 인덱스(Index) : RDBMS의 테이블(Table)과 유사한 개념. 데이터가 저장되는 논리적인 공간
  • 문서(Document) : RDBMS의 행(Row)과 유사한 개념. 실제로는 JSON 객체 형태로 저장

NewsDocument.java 파일 생성:

• 검색에 필요한 필드만 모아서 NewsDocument 라는 새로운 클래스를 만듭니다. 이 클래스는 com.ccp.simple.document 라는 새로운 패키지에 생성하여, DB용 domain 객체와 명확히 분리합니다.

• 이 클래스에는 다음과 같은 어노테이션을 사용하여 각 필드를 어떻게 저장하고 검색할지 Elasticsearch에게 알려줍니다.

@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Document(indexName = "news") // "news"라는 이름의 인덱스에 문서를 저장
@Setting(settingPath = "elasticsearch/nori-settings.json") // nori 분석기 설정 파일 경로 지정
public class NewsDocument {

    @Id
    private Long newsId; // 뉴스 원본 ID

    @Field(type = FieldType.Text, analyzer = "nori_analyzer")
    private String title;

    @Field(type = FieldType.Text, analyzer = "nori_analyzer")
    private String description;

    @Field(type = FieldType.Keyword) // Keyword 타입 사용
    private String link;

    @Field(type = FieldType.Date)
    private LocalDateTime pubDt;
}

{
  "analysis": {
    "analyzer": {
      "nori_analyzer": {
        "tokenizer": "nori_tokenizer"
      }
    }
  }
}

• 이 클래스는 Elasticsearch에 저장된 뉴스 데이터의 '설계도' 역할을 합니다.
• @Document(indexName = "news"): 이 클래스의 데이터는 Elasticsearch의 "news"라는 인덱스에 저장하라는 의미입니다.
• @Id: 이 필드가 문서의 고유 식별자(Primary Key)임을 나타냅니다.
• @Field(type = FieldType.Text): 이 필드는 전문(Full-text) 검색이 가능한 텍스트 데이터임을 나타냅니다. Elasticsearch는 이 필드의 내용을 단어 단위로 쪼개고 분석(Analyze)하여, 내용 기반 검색이 가능하도록 만듭니다. (title, description에 적합)
• @Field(type = FieldType.Date): 날짜 형식의 데이터임을 나타냅니다.

nori 분석기란? Elasticsearch가 한국어 텍스트를 더 잘 이해하도록 도와주는 형태소 분석기입니다. 'nori' 분석을 사용하면 "뉴스를 검색합니다" 라는 문장을 단순히 공백으로 자르는 것이 아니라, 의미를 가진 최소 단위인 형태소, 즉 '뉴스', '검색', '하다'로 분해합니다. 사용자가 "검색하는 뉴스"라고 입력해도 "뉴스를 검색합니다"라는 제목의 기사를 조회할 수 있게 되어 검색 품질이 비약적으로 향상됩니다. Elasitcsearch에 기본적으로 포함되어 있어 별도의 설치 없이 바로 사용할 수 있습니다.

참고!!! nori 플러그인 설치 필요

• 테스트 중 nori가 자동으로 내장 설치되지 않아 오류가 계속 발생하였습니다.
• 도커로 elasticsearch 를 설치하고 bin/bash 안에 nori 플러그인을 직접 설치했습니다.

• nori 설치 > 도커 컨테이서 stop > 도커 컨테이너 run
• nori 분석기 설정 파일 경로로 매핑된 것을 확인
• 노리 플러그인 설치 확인

4. ElasticsearchRepository 상속

Spring Data에서는 ElasticsearchRepository 인터페이스를 상속받아 엘라스틱서치 관련 기본적인 CRUD 메소드를 구현할 수 있습니다. (예전에 공부했던 JPA 와 비슷한 형식) 덕분에 별도의 SQL 쿼리를 작성하지 않고도 newsSearchRepository.save(), newsSearchRepository.findById(), newsSearchRepository.delete() 와 같은 메소드를 바로 사용할 수 있어 매우 편리합니다.

package com.ccp.simple.repository;

import com.ccp.simple.document.NewsDocument;
import org.springframework.data.elasticsearch.repository.ElasticsearchRepository;

public interface NewsSearchRepository extends ElasticsearchRepository<NewsDocument, Long> {
}

데이터 인덱싱 (뉴스 수집 시 Elasticsearch에 저장하기)

뉴스 수집 시 PostgreSQL에 저장함과 동시에 Elasticsearch에도 저장(Indexing) 하도록 기존 뉴스 수집 로직을 수정합니다.

• 기존에는 DB 저장만 진행

// DB 뉴스 저장
newsMapper.insertNews(news);

• DB 저장 + 엘라스틱서치 인덱싱 진행

  // 1. DB 뉴스 저장
  newsMapper.insertNews(news);
  

// 2. Elasticsearch에 뉴스 인덱싱 NewsDocument newsDocument = NewsDocument.builder() .newsId(newsId) .title(news.getTitle()) .description(news.getDescription()) .link(news.getLink()) .pubDt(news.getPubDt()) .build(); newsSearchRepository.save(newsDocument);

---
## Elasticsearch를 활용한 검색 API 구현

### 1. GET 메소드로 요청을 받는 /api/news/search 엔드포인트를 만듭니다.
```java
    // 뉴스 검색
    @GetMapping("/news/search")
    public List<NewsDocument> searchNews(@RequestParam("q") String query) {
        return newsService.searchNews(query);
    }

• @RequestParam("q") 어노테이션을 사용하여, URL의 쿼리 파라미터(예: ?q=검색어)로 들어온 검색어를 query라는 이름의 String 변수로 받습니다.

2. 엘라스틱서치 검색 서비스 코드를 작성합니다.

    @Override
    public List<NewsDocument> searchNews(String query) {
        // 1. multi_match_query 생성
        NativeQuery nativeQuery = new NativeQueryBuilder()
                .withQuery(q -> q
                        .multiMatch(mmq -> mmq
                                .fields("title", "description")
                                .query(query)
                        )
                )
                .build();

        // 2. 검색 실행
        SearchHits<NewsDocument> searchHits = elasticsearchOperations.search(nativeQuery, NewsDocument.class);

        // 3. 결과 반환
        return searchHits.getSearchHits().stream()
                .map(hit -> hit.getContent())
                .collect(Collectors.toList());
    }

• 검색어를 title과 description 필드에서 찾는 multi-match 쿼리를 구현합니다.

인덱싱 및 검색 테스트

1. Elasticsearch 인덱싱 테스트

• Elasticsearch 서버 실행 중
• 뉴스 수집 스케줄러를 실행하여 DB INSERT와 Elasticsearch 에 동일한 데이터가 인덱싱 되도록 함

• DB에 20개의 새로운 뉴스 데이터가 INSERT

• 엘라스틱서치 카운트 확인 결과 20개로 동일

• DB 데이터와 동일한 데이터가 엘라스틱서치에 인덱싱 된 것을 확인

2. 검색 API 테스트

• Postman에 아래와 같은 형식의 URL을 입력하여 GET 요청을 보냅니다.
• 요청 예시 : http://localhost:8080/api/news/search?q=정치

3. 응답값 확인 및 비교:

• 응답(Response)으로 검색어와 일치하는 NewsDocument 객체의 JSON 배열이 반환되는지 확인

• 검색어를 바꿔가며, 제목이나 내용에 해당 검색어가 포함된 뉴스들이 정확히 찾아지는지 테스트 진행

  • 검색어 : 교육과정
  • 엘라스틱서치를 통한 검색으로는 '교육과정'으로 검색을 했을 때 '교육 과정'이 속한 기사뿐만 아니라 '교육' 형태소가 속한 데이터를 결과로 조회하는 것을 확인
  • SQL 검색 결과 '%교육과정%' LIKE 검색이 이루어졌기 때문에 정확히 일치하지 않는 데이터는 조회되지 않음

결과

지금까지 Spring Boot 환경에 Elasticsearch를 성공적으로 연동하고, nori 한국어 분석기를 적용하여 RDBMS의 한계를 뛰어넘는 효율적인 전문 검색 기능을 구현했습니다.

• 다중 필드 동시 검색: 사용자는 검색어 하나만 입력했지만, 시스템은 multi_match 쿼리를 통해 뉴스의 제목과 본문 내용을 동시에 탐색하여 관련도 높은 결과를 찾아냅니다.

• 한국어 형태소 분석: nori 분석기 덕분에, 사용자가 "뉴스를 검색하는 방법"이라고 검색해도, "뉴스 검색 방법"이나 "뉴스의 검색"이 포함된 문서를 찾아낼 수 있습니다. 이처럼 단어의 원형과 조사를 이해하는 지능적인 검색이 가능해졌습니다.

• 높은 성능과 확장성: 수백만 건의 문서가 쌓이더라도 Elasticsearch는 거의 실시간에 가까운 검색 속도를 보장합니다. 이는 사용자에게 쾌적한 검색 경험을 제공할 뿐만 아니라, 향후 데이터가 증가하더라도 안정적인 성능을 유지할 수 있는 확장성을 확보했음을 의미합니다.

Elasticsearch 란?

• 엘라스틱서치는 Apache Lucene 기반의 오픈소스 분산 검색 및 분석 엔진입니다.
• 방대한 데이터를 빠르고 거의 실시간으로 저장하고 검색하고, 효과적으로 분석, 시각화할 수 있습니다.
• 엘라스틱서치는 데이터베이스가 아니라 문서 기반 데이터를 저장하고 이를 기반으로 아주 빠르게 검색할 수 있도록 설계된 시스템입니다.
• 기존 관계형 데이터베이스(RDB)가 복잡한 쿼리로 인해 검색 속도가 느려지는 문제를 해결하기 위해 전문 검색 기능이 특화되어 있습니다.
• 데이터베이스는 구조적 데이터 저장 / 관계 연산에 강하지만, 엘라스틱서치는 비정형 데이터 저장 / 검색과 분석에 강한 특징이 있습니다.

Elasticsearch 특징

1. 분산 검색 엔진

• 엘라스틱서치는 분산형 시스템(구조)로 설계되어 있습니다.
• 여러 서버(노드)에 데이터를 분산해 저장하거나 검색하여, 확장성과 고가용성을 제공합니다.
• 데이터를 여러 서버에 분산하여 저장하고 처리하기 때문에, 단일 서버의 한계를 뛰어넘어 대규모 데이터를 처리할 수 있고, 장애가 발생해도 시스템이 멈추지 않았기 때문에 안정적인 서비스를 제공할 수 있습니다.

2. 역색인 구조

• SQL과 달리 색인된 데이터에서 효율적으로 문서를 찾을 수 있는 방식(inverted index)으로 동작합니다.

• 일반적인 데이터베이스는 문서(document)를 기준으로 단어를 찾아야 해서 느리지만, 역색인은 단어를 기준으로 그 단어가 포함된 문서를 검색합니다.

• 이러한 검색 방법을 통해 엘라스틱서치의 검색 속도가 매우 빠를 수 있습니다.

• 예시) "자바 스프링부트" 라는 문서가 있으면 역색인은 다음과 같이 구성됩니다.

  • "자바" : [문서1, 문서2]
  • "스프링부트" " [문서1, 문서3]
    • 이렇게 미리 단어별로 문서를 매핑해두면, "자바"를 검색할 때 전체 문서를 훑어보지 않고, 바로 해당 문서 목록을 찾아내기 때문에 검색 속도가 매우 빨라집니다.

3. RESTful API 제공

• 데이터를 저장(CREATE), 검색(READ), 수정(UPDATE), 삭제(DELETE) 등의 작업을 HTTP 기반의 API로 할 수 있습니다.

4. 모든 데이터 지원

• 정형 및 비정형 데이터(텍스트, 숫자, 위치 등)를 인덱싱하고 분석할 수 있습니다.

5. 실시간성

• Near Real Time으로 데이터를 거의 즉시 검색·분석할 수 있습니다.

6. ELK 스택의 핵심

• Logstash(수집), Elasticsearch(검색/분석), Kibana(시각화)로 이루어진 ELK 스택에서 주로 사용됩니다.

Elasticsearch 핵심 개념

Index (인덱스) : 관계형 DB의 Database랑 비슷. 데이터를 모아두는 공간.

Document (문서) : DB의 Row에 해당. JSON 형태로 저장됨.

Field (필드) : DB의 Column처럼 각 문서의 속성.

예시) 뉴스 기사 데이터

{
  "title": "스프링부트에 엘라스틱서치 도입",
  "author": "홍길동",
  "content": "오늘부터 우리 프로젝트에 엘라스틱서치를 적용한다.",
  "published_date": "2025-09-02"
}

• 이 JSON 하나가 Document
• 여러 개가 모이면 하나의 Index (예: "news")

RDBMS와 Elasticsearch의 차이점

데이터 저장 구조

• RDBMS는 테이블, 열(컬럼), 행(로우), 스키마에 기반해서 데이터를 정형화하여 저장합니다.
• 엘라스틱서치는 JSON 문서 형태로 데이터를 저장하며, 필드와 구조가 자유롭고, 스키마가 유연합니다.

검색 방식

• RDBMS는 SQL 쿼리와 전통적인 B-Tree, 해시 인덱스 등을 사용하여 컬럼 값 기반 조회에 최적화되어 있습니다.
• 엘라스틱서치는 역색인(inverted index) 구조 및 텍스트 분석 기반의 검색을 기본으로 하여, 대규모 텍스트 및 비정형 데이터의 빠른 '키워드', 'Full-text' 검색에 매우 강점을 가집니다.

확장성과 처리 성능

• RDBMS는 수직 확장(CPU, 메모리 업그레이드)에 기반하며, 분산과 대용량 처리에 한계가 있을 수 있습니다.
• 엘라스틱서치는 분산형 아키텍처이므로, 수평 확장(노드 추가)을 통해 대용량 데이터를 빠르고 효율적으로 관리할 수 있습니다.

트랜잭션 및 데이터 일관성

• RDBMS는 ACID(Atomicity, Consistency, Isolation, Durability) 성질을 갖추고 있어 트랜잭션과 데이터 무결성, 복잡한 조인과 관리에 강합니다.
• 엘라스틱서치는 트랜잭션 처리, 롤백, 일관성이 약하거나 제공되지 않으며, 검색과 집계에 특화되어 있습니다.

활용 및 목적

• RDBMS: 비즈니스·업무 시스템에서 정형 데이터 관리와 복잡한 관계 처리, 데이터의 정확성과 안정성이 반드시 필요한 경우 사용합니다.
• 엘라스틱서치: 로그, 텍스트, 다양한 형태의 비정형 데이터에 대해 빠른 검색·집계·분석이 필요할 때 적합합니다.

DB vs Elasticsearch 예시

DB 검색

SELECT * FROM news WHERE content LIKE '%엘라스틱 서치%';

• 단순한 LIKE 매칭만 가능
• 테이블 전체를 스캔해야 하므로 시간이 오래 걸림

엘라스틱서치 검색

{
  "query": {
    "match": {
      "content": "엘라스틱"
    }
  }
}

• 미리 생성된 역색인에서 "엘라스틱"과 "서치"라는 단어가 포함된 모든 문서 검색 가능
• 형태소 분석, 유사어 검색, 점수(관련도)순 정렬까지 가능
• 오타 보정 및 유사어 제안 기능도 쉽게 구현 가능

Elasticsearch의 활용

위와 같은 특장점을 가지고 있기에 엘라스틱서치는 검색 성능과 확장성, 실시간 분석 기능 때문에 많이 사용되고 있습니다.

• 검색 기능: 쇼핑몰 상품 검색, 블로그/뉴스 검색
• 로그/모니터링: 서버 로그, 사용자 이벤트 데이터 (보통 ELK Stack: Elasticsearch + Logstash + Kibana)
• 실시간 분석: 유저 행동 데이터, 클릭/조회수 통계
• 쇼핑몰 검색 기능: 고객이 상품 이름이나 설명을 자유롭게 검색 가능
• 로그 분석: 서버 로그 데이터를 실시간으로 수집·검색
• 위치 기반 서비스: 지도/위치 데이터에 대한 검색 및 분석
• 대규모 데이터 분석: 수백만 건의 데이터에 대한 빠른 탐색과 집계.

내용 심화 참고 https://velog.io/@big9810/%EC%97%98%EB%9D%BC%EC%8A%A4%ED%8B%B1%EC%84%9C%EC%B9%98

기존에는 사용자가 '좋아요' 버튼을 클릭할 때마다 RDBMS의 특정 테이블에 UPDATE 쿼리를 실행하는 방식을 사용했습니다.

• 장점: 구현이 단순하고 직관적
• 단점: 1) 좋아요 수를 보여주려면 항상 COUNT(*) 쿼리를 날려야 함 2) 사용자가 많아질수록 조회 성능 저하 3) 좋아요 버튼 클릭이 늘어나면 DB에 잦은 쓰기 부하 발생

=> 성능 병목(Performance Bottleneck): 디스크 기반의 RDBMS는 메모리 기반 스토리지에 비해 쓰기 작업의 비용이 높음. 트래픽이 집중될 경우, 잦은 I/O 작업으로 인해 DB에 과도한 부하가 발생하며 이는 전체 애플리케이션의 응답 시간 저하로 이어짐.

=> 확장성 한계: DB 커넥션 풀이 고갈되거나 테이블에 락(Lock)이 발생하여 다른 중요한 트랜잭션 처리를 방해할 수 있음.

이러한 문제를 해결하기 위해, 실시간 데이터 처리를 위한 In-Memory 데이터 저장소인 Redis를 도입하여 시스템 아키텍처를 개선하기로 결정했습니다.

Redis란 무엇인가?

Redis는 In-Memory 기반의 데이터 저장소로, 데이터를 메모리에 올려두기 때문에 DB보다 훨씬 빠른 속도로 읽고 쓸 수 있습니다.

• Key-Value 형태로 데이터를 저장
• 다양한 자료구조 지원 (String, List, Set, Sorted Set, Hash 등)
• 빠른 속도: 밀리초 단위 응답
• 캐시 & 실시간 데이터 처리에 강점

즉, 빠르게 바뀌고 자주 읽히는 데이터 관리에 특화된 저장소라고 할 수 있습니다.

Redis는 대규모 트래픽을 처리하는 서비스에서 사용하는 매우 효율적이고 표준적인 아키텍처입니다. 사용자가 '좋아요'를 누를 때마다 RDBMS에 직접 쓰기 작업을 하면 부하가 상당한데, 이를 Redis를 통해 비동기적으로 처리하면 다음과 같은 큰 이점을 얻을 수 있습니다.

Redis를 도입하면 좋은 이유?

(1) 빠른 좋아요 수 조회

• 기존: SELECT COUNT(*) FROM USER_NEWS_LIKE WHERE news_id = ?
• Redis: SCARD news:like:{newsId} (SET의 크기 조회) => O(1) 연산으로 즉시 결과 제공

(2) 중복 방지 및 상태 관리

순서가 없고, 중복된 데이터를 허용하지 않는 집합인 Set 자료구조를 사용해,

• 새로운 사용자가 '좋아요'를 누르면: SADD 명령어로 그냥 집합에 원소를 추가
• 기존 사용자가 '좋아요'를 취소하면: SREM 명령어로 그냥 집합에서 원소를 제거

특정 사용자가 좋아요 했는지 확인도 SISMEMBER로 즉시 확인 가능

(3) DB 부하 감소

• 모든 요청을 DB까지 보내지 않고, Redis에서 처리
• Redis는 메모리 기반이라 초당 수만~수십만 요청도 무난히 처리 가능

(4) 확장성과 실시간성

• 좋아요 수는 실시간으로 변하는 데이터
• 캐싱을 두지 않으면 매번 DB를 조회해야 해서 느려짐
• Redis는 실시간 업데이트 + 실시간 조회에 최적화

(5) 장애 대응 전략

• Redis는 메모리 기반이라 장애 시 데이터 유실 가능성 있음

• 따라서 USER_NEWS_LIKE 테이블에는 기록을 유지하고, 주기적으로 Redis의 데이터를 DB like_count와 동기화하는 방식을 채택 => 안정성과 성능을 모두 확보

• 응답성 향상: 사용자는 Redis에만 데이터가 기록되므로 '좋아요' 요청에 대한 응답을 즉시 받게 되어 UX가 향상됩니다.

• DB 부하 감소: 빈번한 쓰기 작업이 DB가 아닌 메모리 기반의 Redis에서 처리되므로, DB는 더 중요한 읽기나 트랜잭션 처리에 집중할 수 있습니다.

• 확장성: 트래픽이 증가하더라도 Redis 클러스터링 등을 통해 쉽게 확장할 수 있습니다.

Redis 활용한 대규모 트래픽 관리

전체적인 작업 흐름은 다음과 같습니다.

1. Redis 의존성 추가: build.gradle에 Spring Data Redis 라이브러리를 추가 2. Redis 접속 정보 설정: application.yml에 Redis 서버 접속 정보를 추가 3. 데이터 모델 및 매퍼 수정: 4. 서비스 로직 변경: NewsServiceImpl의 toggleLike 메소드가 DB 대신 Redis와 상호작용하도록 수정 5. 배치 스케줄러 생성: 주기적으로 Redis의 '좋아요' 수를 DB에 동기화하는 스케줄러 생성

아키텍처 설계

본 프로젝트는 Redis의 성능적 이점과 RDBMS의 데이터 영속성 및 일관성의 장점을 모두 취하는 하이브리드 아키텍처를 채택했습니다.

이점

1. 실시간 처리 (Redis): 사용자의 '좋아요' 요청은 즉시 Redis에만 기록됩니다. DB 접근이 없으므로 사용자에게 매우 빠른 응답을 제공할 수 있습니다.

   • Redis의 Set 자료구조를 사용하여 news:like:{뉴스ID} 형태의 Key에 '좋아요'를 누른 사용자ID를 저장합니다. Set은 중복된 원소를 허용하지 않으므로, 한 사용자가 중복으로 '좋아요'를 누르는 것을 원천적으로 방지합니다.

2. 비동기 동기화 (Scheduler -> RDBMS): Spring Scheduler를 이용한 배치 작업이 주기적으로 실행됩니다.

   • 스케줄러는 Redis에 저장된 모든 '좋아요' 키를 조회하여, SCARD 명령어로 각 뉴스의 최종 '좋아요' 개수를 집계합니다.
   • 집계된 최종 결과만을 RDBMS(PostgreSQL)의 like_count 컬럼에 UPDATE 합니다.

3. *상태 기반(State-based) * : Redis와 스케줄러는 "변경 내역(Delta)을 추적" 하는 것이 아니라, 매번 "전체 상태(Full State)를 기준으로" 동작합니다.

   • 로직이 매우 간단하여 버그가 발생할 확률이 적습니다.
   • 중간에 스케줄러가 실패하더라도 다음 스케줄러 동작에서 동기화가 가능합니다(멱등성 보장)
   • Redis에서 SCARD(전체 개수 세기) 속도가 매우 빨라 성능이 좋습니다.

이를 통해 빈번한 쓰기 작업을 Redis가 흡수하도록 하여 DB 부하를 최소화하고, 스케줄러를 통해 데이터의 최종 일관성을 보장합니다.

Redis (Set)

• '좋아요'를 누른 사용자 목록을 실시간으로 관리
• SADD (추가), SREM (삭제), SISMEMBER (멤버 확인)
• 현재 누가 '좋아요'를 누르고 있는가? (상태)를 확인

스케줄러

• Redis와 DB를 연결하는 데이터 동기화 파이프라인
• Redis에서 SCARD (개수 세기), DB에 UPDATE (집계 결과 저장)
• 특정 시점의 '좋아요' 개수를 집계
• 이때 스케줄러는 "지난번 동기화 이후에 새로 추가된 데이터만 찾아서 더한다"는 식으로 복잡하게 동작하지 않음
• 스케줄러가 동작하는 "현재" Redis에서 데이터를 전체 카운팅해서 DB를 덮어쓰는 식으로 진행

RDBMS

• 집계된 '좋아요' 수를 저장하는 캐시 또는 요약 정보
• 주요 연산: SELECT (뉴스 목록과 함께 '좋아요' 수를 빠르게 조회)
• 데이터의 의미: 특정 과거 시점에 집계된 '좋아요' 총 개수

구현 상세

1. 환경 설정: 의존성 및 설정 추가

• Redis 서버를 도커로 설치하고 실행합니다.

• build.gradle 파일에 Spring Data Redis 의존성을 추가합니다.

  dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
  }

  다음으로 application.yml에 Redis 서버 접속 정보를 추가합니다.

# application.yml
spring:
  # ... datasource 등 기존 설정
  data:
    redis:
      host: localhost
      port: 6379

2. 데이터베이스 및 모델 수정

RDBMS의 NEWS_INFO 테이블에 '좋아요' 수를 저장할 컬럼을 추가합니다.

ALTER TABLE NEWS_INFO
ADD COLUMN like_count INT NOT NULL DEFAULT 0;

News 엔티티와 프론트엔드로 데이터를 전달할 NewsResponseDto에도 likeCount 필드를 추가합니다.

@Data
@NoArgsConstructor
public class News {
    private int likeCount; // 좋아요 수
}

// NewsResponseDto.java
@Data
public class NewsResponseDto {
    private int likeCount;
}

3. Redis 설정 클래스 추가

RedisTemplate을 프로젝트 전반에서 편리하게 사용하기 위해, Key와 Value를 문자열로 직렬화하는 설정 클래스를 만듭니다.

@Configuration
public class RedisConfig {

    @Bean
    public RedisTemplate<String, String> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, String> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new StringRedisSerializer());
        template.setHashKeySerializer(new StringRedisSerializer());
        template.setHashValueSerializer(new StringRedisSerializer());
        return template;
    }
}

4. MyBatis 매퍼 수정

스케줄러가 DB에 '좋아요' 수를 업데이트할 수 있도록 NewsMapper.xml에 update 구문을 추가하고, 뉴스 목록 조회 시 like_count를 포함하도록 수정합니다.

<mapper namespace="com.ccp.simple.mapper.NewsMapper">
    <update id="updateLikeCount">
        UPDATE NEWS_INFO
        SET like_count = #{likeCount}
        WHERE news_id = #{newsId}
    </update>
</mapper>

NewsMapper.java 인터페이스에도 해당 메소드를 추가합니다.

@Mapper
public interface NewsMapper {
    void updateLikeCount(@Param("newsId") Long newsId, @Param("likeCount") int likeCount);
}

5. 서비스 로직 변경: DB 대신 Redis와 통신

NewsServiceImpl의 toggleLike 메소드가 DB 대신 Redis와 통신하도록 수정합니다.

    @Override
    @Transactional
    public boolean toggleLike(String userId, Long newsId) {
        String likeKey = "news:like:" + newsId;
        Boolean isMember = redisTemplate.opsForSet().isMember(likeKey, userId);

        if (Boolean.TRUE.equals(isMember)) {
            // Redis 좋아요 취소
            redisTemplate.opsForSet().remove(likeKey, userId);
            newsMapper.deleteLike(userId, newsId);

            String countKey = "news:like_count:" + newsId;
            redisTemplate.opsForValue().decrement(countKey);

            return false;
        } else {
            // Redis 좋아요 추가
            redisTemplate.opsForSet().add(likeKey, userId);
            newsMapper.insertLike(userId, newsId);

            String countKey = "news:like_count:" + newsId;
            redisTemplate.opsForValue().increment(countKey);

            return true;
        }
    }

6. DB 동기화 스케줄러 생성

주기적으로 Redis의 '좋아요' 수를 DB에 동기화할 스케줄러를 만듭니다.

@Slf4j
@Component
@RequiredArgsConstructor
public class LikeCountSyncScheduler {

    private final RedisTemplate<String, String> redisTemplate;
    private final NewsService newsService;

    // 10분마다 실행
    @Scheduled(cron = "0 */10 * * * *")
    public void syncLikeCountsToDb() {
        log.info("Redis '좋아요' 수 DB 동기화 시작");
        Set<String> likeKeys = redisTemplate.keys("news:like:*");

        if (likeKeys == null || likeKeys.isEmpty()) {
            log.info("동기화할 '좋아요' 데이터가 없습니다.");
            return;
        }

        for (String key : likeKeys) {
            try {
                Long newsId = Long.parseLong(key.split(":")[2]);
                Long likeCount = redisTemplate.opsForSet().size(key);
                if (likeCount != null) {
                    newsService.updateLikeCount(newsId, likeCount.intValue());
                }
            } catch (Exception e) {
                log.error("키 '{}' 처리 중 오류 발생: {}", key, e.getMessage());
            }
        }
        log.info("Redis '좋아요' 수 DB 동기화 완료");
    }
}

7. API 컨트롤러 수정

NewsController에서 toggleLike 서비스를 호출하고 인증된 사용자 정보를 넘겨줍니다.

    @PostMapping("/news/{newsId}/like")
    public ResponseEntity<Map<String, Object>> toggleLike(@PathVariable Long newsId, Authentication authentication) {
        String userId = authentication.getName();
        boolean isLiked = newsService.toggleLike(userId, newsId);

        Map<String, Object> response = new HashMap<>();
        response.put("isLiked", isLiked);
        response.put("message", isLiked ? "좋아요를 눌렀습니다." : "좋아요를 취소했습니다.");

        return ResponseEntity.ok(response);
    }

사용자가 좋아요 후 새로고침을 했을 때 Redis의 정보와 DB 불일치를 방지하기 위해 본인의 좋아요 정보를 Redis에서 조회하여 표출합니다.

@Override
    public List<NewsResponseDto> getAllNews() {
        String userId = null;
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication != null && authentication.isAuthenticated()) {
            userId = authentication.getName();
        }

        List<NewsResponseDto> newsList = newsMapper.getAllNews();

        for (NewsResponseDto news : newsList) {
            String likeKey = "news:like:" + news.getNewsId();

            // Redis에서 실시간 좋아요 개수 가져오기
            Long likeCount = redisTemplate.opsForSet().size(likeKey);
            news.setLikeCount(likeCount != null ? likeCount.intValue() : 0);

            // 현재 사용자가 좋아요를 눌렀는지 확인
            if (userId != null) {
                Boolean isMember = redisTemplate.opsForSet().isMember(likeKey, userId);
                news.setLiked(Boolean.TRUE.equals(isMember));
            } else {
                news.setLiked(false); // 로그인하지 않은 사용자는 항상 false
            }
        }
        return newsList;
    }

테스트 진행

1. 좋아요 토글 API 테스트

2. Redis 데이터 직접 확인

C:\Users\hyjan>docker ps
CONTAINER ID   IMAGE     COMMAND                   CREATED        STATUS          PORTS                                         NAMES
bd7980a61b9a   redis     "docker-entrypoint.s…"   17 hours ago   Up 11 minutes   0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp   simple-redis

C:\Users\hyjan>docker exec -it simple-redis redis-cli
127.0.0.1:6379> SMEMBERS news:like:1
(empty array)  <= 좋아요 취소 했을 때
127.0.0.1:6379> SMEMBERS news:like:1
1) "aaa" <= 좋아요 했을 때
127.0.0.1:6379> keys *
1) "news:like:1" <= 저장된 모든 키 목록 확인

• '좋아요'를 했을 때 로그인 사용자의 아이디를 반환
• '좋아요'를 취소했을 때 로그인 사용자의 아이디가 비어있음(empty)을 출력
• 저장된 모든 키 목록 확인 news → 도메인/리소스 이름 (뉴스) like → 동작/속성 (좋아요) 1 → 특정 엔티티의 ID (뉴스 ID = 1)

3. DB 동기화 스케줄러 확인

• 5개의 아이디로 좋아요를 누른 후 redis 서버에만 집계

• 디비 UPDATE 스케줄러 동작

• 디비 UPDATE 된 결과 확인

결론

Redis-스케줄러를 활용한 하이브리드 아키텍처 도입을 통해, 한 번에 많은 요청이 발생하는 '좋아요' 기능을 RDBMS의 부하 없이 안정적이고 확장성 있게 구현할 수 있었습니다.

이 접근 방식은 실시간 랭킹, 조회수 집계 등 유사한 요구사항을 가진 다른 기능에도 동일하게 적용될 수 있으며, 대규모 트래픽을 처리해야 하는 작업에서 유용하게 활용될 수 있습니다.

Spring Scheduler의 핵심 개념

Spring Scheduler는 특정 시간에 또는 주기적으로 특정 메소드를 실행하도록 예약하는 기능입니다. Spring 프레임워크에 내장되어 있어 별도의 라이브러리 추가 없이 바로 사용할 수 있습니다.

1. 스케줄링 활성화: @EnableScheduling

가장 먼저 해야 할 일은 Spring Boot 애플리케이션에 스케줄링 기능이 켜져 있음을 알려주는 것입니다. 보통 메인 애플리케이션 클래스에 @EnableScheduling 어노테이션을 추가하여 활성화합니다.

@SpringBootApplication
@EnableScheduling // 스케줄링 기능을 활성화합니다.
public class SimpleApplication {
    public static void main(String[] args) {
        SpringApplication.run(SimpleApplication.class, args);
    }
}

이 어노테이션이 없으면 @Scheduled가 붙은 메소드는 스케줄링되지 않고 일반 메소드처럼 동작합니다.

2. 작업 예약: @Scheduled

스케줄링할 메소드 위에 @Scheduled 어노테이션을 붙여줍니다. 이 어노테이션은 다양한 속성을 통해 실행 주기를 설정할 수 있습니다.

주요 속성

1. cron: 가장 유연하고 강력한 방법입니다. Cron 표현식을 사용하여 매우 구체적인 실행 시간을 예약할 수 있습니다.

• 형식: 초 분 시 일 월 요일
• 예시:
  • @Scheduled(cron = "0 0 0 * * MON") : 매주 월요일 자정에 실행
  • @Scheduled(cron = "0/10 * * * * ?") : 매 10초마다 실행
  • @Scheduled(cron = "0 0 12 * * ?") : 매일 정오(12시)에 실행

2.fixedRate: 이전 작업의 시작 시간을 기준으로, 정해진 시간(밀리초)마다 작업을 실행합니다.

• 만약 작업 실행 시간이 fixedRate보다 길어지면, 이전 작업이 끝나자마자 다음 작업이 바로 시작됩니다. => 병렬로 실행되지는 않음
• 예시: @Scheduled(fixedRate = 60000): 1분마다 실행 (이전 작업이 30초 걸렸다면, 30초 후에 다음 작업 시작)

3.fixedDelay: 이전 작업이 끝난 시간을 기준으로, 정해진 시간(밀리초) 후에 다음 작업을 실행합니다.

• 항상 이전 작업의 완료와 다음 작업의 시작 사이에 일정한 지연 시간을 보장합니다.
• 예시: @Scheduled(fixedDelay = 60000): 이전 작업이 끝난 후 1분 뒤에 실행 (이전 작업이 30초 걸렸다면, 1분 30초 후에 다음 작업 시작)

4.initialDelay: 스케줄링된 작업이 처음 실행되기 전의 대기 시간(밀리초)을 설정합니다. fixedRate나 fixedDelay와 함께 사용됩니다.

• 예시: @Scheduled(initialDelay = 10000, fixedRate = 60000): 애플리케이션 시작 후 10초 뒤에 첫 실행, 그 후 1분마다 실행

스케줄링 동작 방식 (스레드)

• 기본적으로 Spring Scheduler는 단일 스레드로 동작합니다.
• 즉, 여러 개의 @Scheduled 메소드가 있더라도 동시에 실행되지 않고 순차적으로 실행됩니다. 만약 하나의 작업이 오래 걸리면 다른 작업들이 지연될 수 있습니다.
• 만약 병렬 실행이 필요하거나 더 복잡한 스케줄링이 필요하다면, 별도의 TaskScheduler 빈을 등록하여 스레드 풀의 크기를 조절하는 등 세부적인 설정을 할 수 있습니다.

1. 기존 코드: 수동으로 실행해야 하는 데이터 수집

처음 작성했던 코드는 다음과 같습니다.

NewsApiController.java (수정 전)

@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class NewsApiController {

    private final NewsService newsService;

    @GetMapping("/newsCollect")
    public void collectNews() throws JsonProcessingException {
        // ... 네이버 API를 통해 뉴스를 수집하는 로직 ...
        newsService.insertNews(responseBody);
    }

    @GetMapping("/news")
    public List<News> getAllNews() {
        return newsService.getAllNews();
    }

    // ... API 호출 관련 private 메서드들 ...
}

/api/newsCollect 라는 API 엔드포인트를 호출해야만 네이버 뉴스 API에서 '날씨' 관련 뉴스를 가져오는 collectNews() 메서드가 실행되는 구조였습니다.

이 방식은

• 누군가 직접 API를 호출해야만 데이터가 수집되고,
• 컨트롤러가 API 요청 처리와 스케줄링(수동)이라는 두 가지 책임을 갖게 됩니다.

이번 목표는 스프링 스케줄러를 활용하여 collectNews() 로직을 매주 월요일 00시에 자동으로 실행하는 것입니다.

2. Spring Scheduler 적용하기

1. 스케줄링 기능 활성화 (@EnableScheduling)

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableScheduling;

@SpringBootApplication
@EnableScheduling // 스케줄링 기능을 활성화합니다!
public class SimpleApplication {

    public static void main(String[] args) {
        SpringApplication.run(SimpleApplication.class, args);
    }

}

2. 역할 분리 - 스케줄러 클래스 생성

스케줄링 관련 로직을 컨트롤러에서 분리하여 별도의 클래스로 만드는 것이 좋습니다. 이는 코드의 역할을 명확히 나누어 유지보수를 쉽게 만듭니다. scheduler 패키지를 만들고 NewsCollectScheduler 클래스를 생성한 뒤, 기존 NewsApiController에 있던 뉴스 수집 로직을 그대로 옮겨옵니다.

package com.ccp.simple.scheduler;

@Component
@RequiredArgsConstructor
public class NewsCollectScheduler {

    private final NewsService newsService;

    /**
     * 매주 월요일 00:00에 실행
     */
    @Scheduled(cron = "0 0 0 * * MON")
    public void collectNews() throws JsonProcessingException {
        // ... NewsApiController에서 가져온 뉴스 수집 로직 ...
    }

    // ... API 호출 관련 private 메서드들 ...
}

3. 작업 예약 (@Scheduled)

새로 만든 collectNews() 메서드 위에 @Scheduled 어노테이션을 추가하여 실행 주기를 설정합니다.

@Scheduled(cron = "0 0 0 * * MON")
public void collectNews() { ... }

4. 컨트롤러 리팩토링

이제 스케줄러가 뉴스 수집을 담당하므로, NewsApiController는 본연의 임무인 '수집된 뉴스 데이터를 제공하는 API' 역할만 수행하도록 코드를 정리합니다.

package com.ccp.simple.controller;

@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class NewsApiController {

    private final NewsService newsService;

    //뉴스 수집
    @GetMapping("/news")
    public List<News> getAllNews() {
        return newsService.getAllNews();
    }
}

마무리

Spring Scheduler를 사용하면 @EnableScheduling과 @Scheduled 단 두 개의 어노테이션만으로 복잡한 주기적 작업을 손쉽게 구현할 수 있습니다.

• 별도 라이브러리 없이 바로 사용 가능한 간단한 기능입니다.
• 스케줄링 로직을 분리하여 코드 구조를 개선할 수 있습니다.
• cron, fixedRate, fixedDelay 등 다양한 옵션으로 원하는 거의 모든 스케줄링 시나리오를 구현할 수 있습니다.

1. 문제 발생: 새로고침하면 로그아웃되는 현상

로그인 후 router.push('/newsBoard')로 이동하면 뉴스 목록이 정상적으로 보입니다. 하지만 이 상태에서 F5(새로고침)를 누르면 "로그인이 필요합니다"라는 메시지와 함께 로그인 페이지로 돌아가는 현상이 발생했습니다.

원인 분석:

문제의 핵심은 Pinia의 상태는 페이지를 새로고침하면 초기화된다는 점입니다.

• 로그인 코드: Access Token을 Pinia Store에 저장합니다.

userStore.setToken(accessToken); // Pinia에 저장
localStorage.setItem("refreshToken", refreshToken); // localStorage에 저장

• 목록 코드: Pinia Store에서 Access Token을 가져와 사용합니다.

const accessToken = userStore.token; // 새로고침하면 이 값이 null이 됨

Pinia는 Vue 애플리케이션의 메모리에 데이터를 저장하기 때문에, 새로고침 시 이 데이터가 모두 사라집니다. 반면, localStorage는 브라우저에 데이터를 영구적으로 저장하므로 새로고침해도 데이터가 유지됩니다. 이렇게 두 가지 저장소를 혼용하면서 데이터 불일치가 발생했습니다.

2. 해결책: Pinia와 localStorage 동기화하기

새로고침 시에도 로그인 상태를 유지하려면, Pinia Store의 상태를 localStorage에 자동으로 저장하고 불러오는 작업이 필요합니다. => 이를 위해 pinia-plugin-persistedstate라는 유용한 라이브러리를 사용했습니다.

1단계: 라이브러리 설치 및 Pinia 설정

먼저, 라이브러리를 설치하고 Pinia 인스턴스에 플러그인을 등록합니다.

npm install pinia-plugin-persistedstate

main.js 파일을 열어 아래와 같이 수정합니다.

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { createPinia } from "pinia";
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'; //추가

const app = createApp(App);
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate); // Pinia에 플러그인 등록

app.use(router);
app.use(pinia);
app.mount('#app');

2단계: Pinia Store에 persist 옵션 추가

이제 Pinia Store(stores/user.js)에서 persist: true 옵션을 추가하여 어떤 상태를 영구적으로 저장할지 지정합니다. 이때 persist 옵션의 위치가 매우 중요합니다. state, getters, actions와 같은 최상위 레벨에 위치해야 합니다.

// stores/user.js
import { defineStore } from "pinia";
import { jwtDecode } from "jwt-decode"; 

export const useUserStore = defineStore("user", {
  state: () => ({
    token: null,
    role: null,
    userId: null,
  }),
  getters: {
    isAdmin: (state) => state.role === "ROLE_ADMIN",
    isLoggedIn: (state) => !!state.userId,
  },
  actions: {
    setToken(token) {
      this.token = token;
      const decoded = jwtDecode(token);
      this.role = decoded.role;
      this.userId = decoded.sub;
    },
    logout() {
      this.$reset();
      localStorage.removeItem("refreshToken");
    },
  },
  // 해당 내용 추가
  persist: {
    storage : localStorage,
    paths: ["token", "role", "userId"],
  },
});

3단계: 컴포넌트 코드 수정

이제 목록 컴포넌트에서 userStore.token을 가져와도 새로고침 시 null이 되지 않습니다.

logout 함수 역시 Pinia Store의 logout 액션을 호출하도록 수정하여 코드의 일관성을 높일 수 있습니다.

// NewsBoard.vue
<script setup>
import { onMounted } from 'vue';
import { useRouter } from 'vue-router';
import { useUserStore } from "@/stores/user"; //Pinia Store 임포트
// ... (나머지 임포트)

const router = useRouter();
const userStore = useUserStore();
// ... (나머지 코드)

const fetchNews = async () => {
  const accessToken = userStore.token; //Pinia에서 직접 가져옴
  if (!accessToken) {
    alert("로그인이 필요합니다.");
    router.push('/');
    return;
  }
  // ... (API 호출 코드)
};

onMounted(() => {
  fetchNews();
});

const logout = async () => {
  // ... (기존 API 호출 코드)
  if (!response.ok) {
    throw new Error(data.message || "로그아웃 실패");
  }
  userStore.logout(); //Pinia의 logout 액션 호출
  // ... (나머지 코드)
};
</script>

결론

Pinia는 Vue.js의 강력한 상태 관리 도구이지만, 웹페이지 새로고침과 같은 비동기적인 환경에서는 데이터가 휘발되는 문제가 발생합니다. pinia-plugin-persistedstate를 사용하면 Pinia 상태를 localStorage에 쉽게 동기화하여 이 문제를 해결할 수 있습니다.

이번 글에서는 Pinia를 사용해 전역 상태로 관리하고, JWT 토큰에서 role 추출 → 메뉴 권한 제어까지 구현하는 방법을 정리해보겠습니다.

1. 문제 상황

예를 들어, 관리자만 접근할 수 있는 메뉴가 있다고 가정해봅시다.

<li class="nav-item mb-2" v-if="isAdmin">
  <a class="nav-link" href="/manageBoard">관리 페이지</a>
</li>

매 페이지마다 localStorage에서 토큰을 읽고 decode해서 role을 확인하려면 코드가 반복되고 관리가 어렵습니다.

토큰이 refresh로 갱신될 때 화면 반영도 자동으로 되지 않습니다.

2. Pinia란?

Pinia는 Vue 3 공식 상태 관리 라이브러리입니다.

Vue 컴포넌트는 보통 자기 자신 내부의 상태만 관리하는데, 로그인 정보(토큰, 사용자 역할, 이름 등)처럼 앱 전역에서 필요한 데이터는 각 컴포넌트마다 props로 주고받기엔 불편하죠.

쉽게 말해, localStorage는 단순 저장소지만, Pinia store는 Vue가 반응형으로 바라보는 전역 상태 저장소(store) 라고 생각하면 됩니다.

왜 Pinia를 쓰냐?

1. 중앙 집중 관리 로그인 유저 정보(role, userId, isAdmin) 같은 걸 한 곳에서 관리 → 여러 컴포넌트에서 동일한 데이터 보장

2. 반응성 유지 store 값이 바뀌면(store.state.role 같은 거) → 그 값을 쓰는 모든 컴포넌트가 자동 업데이트됨

3. 토큰 갱신 자동 반영 지금 만든 apiRequest에서 새 토큰을 발급받으면 → store 안의 role도 자동 업데이트 그럼 메뉴 같은 UI가 즉시 바뀌어요 (새로고침 필요 없음)

4. Vue 3와 궁합 최고 Vuex의 차세대 버전인데 훨씬 가볍고, TypeScript 지원도 잘됨

예시 상황

지금 관리자 페이지 메뉴를 관리자만 보이게 하고 싶은데?

• Pinia store 없으면 → 매 페이지마다 localStorage.getItem("accessToken") → jwtDecode() → role 뽑기 해야 해요(localStorage = 그냥 로컬에 저장된 값 (변경돼도 Vue는 모름))

• Pinia store 쓰면 → 로그인 시 한 번만 role을 저장해두고, userStore.role이나 userStore.isAdmin만 체크하면 끝!(Pinia store = Vue 반응형 데이터 창고 (바뀌면 화면도 자동 반영))

Pinia 없이(localStorage 직접) 구현

-> 모든 컴포넌트에서 role을 확인하려면 매번 decode 해야 함

<script setup>
import jwtDecode from "jwt-decode";

const token = localStorage.getItem("accessToken");
let role = null;

if (token) {
  try {
    const decoded = jwtDecode(token);
    role = decoded.role;
  } catch (e) {
    console.error("토큰 decode 실패", e);
  }
}
</script>

<template>
  <div>
    <a v-if="role === 'ADMIN'" href="/manageBoard">관리 페이지</a>
  </div>
</template>

문제점:

• 모든 컴포넌트에서 중복 코드 (localStorage → jwtDecode → role)
• 토큰이 refresh로 바뀌면 화면 자동 반영 X (새로고침 해야 반영됨)
• 상태 동기화 어려움 (A 컴포넌트에서 로그인 했는데, B 컴포넌트는 아직 로그아웃 상태처럼 보이는 문제)

3. pnia Store 구성

stores/user.js로 유저 정보를 관리합니다.

import { defineStore } from "pinia";
import { jwtDecode } from "jwt-decode";

export const useUserStore = defineStore("user", {
  state: () => ({
    role: null,
    userId: null,
  }),
  getters: {
    isAdmin: (state) => state.role === "ADMIN",
    isLoggedIn: (state) => !!state.userId,
  },
  actions: {
    setToken(token) {
      localStorage.setItem("accessToken", token);
      const decoded = jwtDecode(token);
      this.role = decoded.role;
      this.userId = decoded.sub;
    },
    logout() {
      localStorage.clear();
      this.role = null;
      this.userId = null;
    }
  }
});

• setToken()으로 JWT 토큰을 decode하여 role과 userId를 store에 저장
• logout()으로 모든 상태와 localStorage 초기화

4. Pinia 앱 등록

main.js에서 Pinia를 Vue 앱에 등록합니다.

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { createPinia } from "pinia";

const app = createApp(App);
const pinia = createPinia();

app.use(router);
app.use(pinia);  // 반드시 필요
app.mount('#app');

5. API 요청과 토큰 갱신 연동

apiRequest.js에서 AccessToken 만료 시 RefreshToken으로 갱신하고, 갱신된 토큰으로 store를 업데이트합니다.

import { useUserStore } from "@/stores/user";

export async function apiRequest(url, options = {}) {
  const userStore = useUserStore();
  let accessToken = localStorage.getItem("accessToken");
  const refreshToken = localStorage.getItem("refreshToken");

  options.headers = {
    ...options.headers,
    "Content-Type": "application/json",
    "Authorization": accessToken ? `Bearer ${accessToken}` : undefined
  };

  let response = await fetch(url, options);

  if (response.status === 401 || response.status === 403) {
    if (!refreshToken) {
      alert("로그인이 필요합니다.");
      userStore.logout();
      window.location.href = "/";
      return;
    }

    const refreshResponse = await fetch("/refresh", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refreshToken })
    });

    if (!refreshResponse.ok) {
      alert("세션 만료. 다시 로그인 해주세요.");
      userStore.logout();
      window.location.href = "/";
      return;
    }

    const data = await refreshResponse.json();
    localStorage.setItem("accessToken", data.accessToken);
    accessToken = data.accessToken;

    // Pinia store 업데이트
    userStore.setToken(accessToken);

    options.headers["Authorization"] = `Bearer ${accessToken}`;
    response = await fetch(url, options);
  }

  return response;
}

• 토큰 갱신 시 store가 자동 업데이트 되므로, 화면은 새로고침 없이도 변경 사항이 반영됩니다.

6. 컴포넌트에서 role 확인

<script setup>
import { useUserStore } from "@/stores/user";
const userStore = useUserStore();
</script>

<template>
  <li class="nav-item mb-2" v-if="userStore.isAdmin">
    <a class="nav-link" href="/manageBoard">관리 페이지</a>
  </li>
</template>

이렇게 하면

• 로그인 후 토큰 저장 → userStore에 role 자동 반영
• 토큰이 만료돼서 갱신되더라도 → apiRequest가 새 토큰 decode 해서 userStore 갱신
• 로그아웃(세션 만료) → userStore.clear()

즉, 모든 페이지에서 userStore.isAdmin만 보면 끝입니다.

7. 결론

• localStorage만 사용: 코드 중복, 토큰 갱신 시 UI 반영 안됨
• Pinia + store: 전역 상태 관리, 반응형 UI, 코드 재사용성 높음
• 프로젝트가 클수록 Pinia를 사용하는 것이 훨씬 편하고 유지보수가 쉽습니다.
• 로그인/권한 관리 같은 전역 상태는 store로 관리하는 것이 효율적입니다.

사전 준비

검색 API를 사용해 뉴스 검색을 실행하려면 먼저 네이버 개발자 센터에서 애플리케이션을 등록하고 클라이언트 아이디와 클라이언트 시크릿을 발급받아야 합니다.

오픈 API 이용 신청 버튼 클릭 > 로그인 > 이용 약관 동의 > 애플리케이션 등록 하는 과정을 순조롭게 진행합니다.

위와 같이 클라이언트 아이디와 클라이언트 시크릿이 발급된 것을 확인할 수 있습니다. API 요청에 필요한 필수 정보입니다.

여기까지 네이버 검색을 위한 사전 준비가 마무리 되었습니다!

네이버 검색 API 정보

네이버에서 제공하는 뉴스 검색 API 에 대한 모든 정보는 아래의 페이지에서 제공합니다. https://developers.naver.com/docs/serviceapi/search/news/news.md#%EB%89%B4%EC%8A%A4

• 해당 페이지에서는 API 래퍼런스 즉, 검색 결과를 조회하는 HTTP 메서드, 파라미터 등의 정보를 제공합니다.
• 또한 요청과 응답 예시 코드 뿐만 아니라 오류 메시지에 대한 정보도 제공합니다.
• 핵심적인 정보를 아래에 정리해 놓았습니다.

HTTP 메서드 => GET

요청 파라미터

응답 요소 및 정보

오류 코드

구현 예제

https://developers.naver.com/docs/serviceapi/search/blog/blog.md#java 네이버 디벨로퍼스에서는 친절하게 다양한 프로그래밍 언어로 구현 예제를 제공합니다. 해당 내용만 보고도 기능을 구현할 수 있을 정도로 정확한 정보를 제공합니다.

뉴스 검색 기능 구현

API 래퍼런스를 참고하여 네이버 뉴스를 검색한 결과를 수집하는 기능을 구현해보도록 하겠습니다.

package com.ccp.simple.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class NewsApiController {

    @GetMapping("/news")
    public String collectNews() {
        String clientId = ""; //애플리케이션 클라이언트 아이디
        String clientSecret = ""; //애플리케이션 클라이언트 시크릿

        String searchKeyword = "네이버";   // 검색어
        if (searchKeyword == null || searchKeyword.isEmpty()) {
            throw new RuntimeException("검색어가 비어 있습니다.");
        }
        String encodeQuery;
        try {
            encodeQuery = URLEncoder.encode(searchKeyword, "UTF-8");
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException("검색어 인코딩 실패",e);
        }

        String apiURL = "https://openapi.naver.com/v1/search/news?query=" + encodeQuery;

        Map <String, String> requestHeaders = new HashMap<>();
        requestHeaders.put("X-Naver-Client-Id", clientId);
        requestHeaders.put("X-Naver-Client-Secret", clientSecret);

        String responseBody = get(apiURL,requestHeaders);
        //responseBody 의 내용을 db에 insert 하기
        return "";
    }

    private static String get(String apiUrl, Map<String, String> requestHeaders){
        HttpURLConnection con = connect(apiUrl);
        try {
            con.setRequestMethod("GET");
            for(Map.Entry<String, String> header :requestHeaders.entrySet()) {
                con.setRequestProperty(header.getKey(), header.getValue());
            }
            int responseCode = con.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) { // 정상 호출
                return readBody(con.getInputStream());
            } else { // 오류 발생
                return readBody(con.getErrorStream());
            }
        } catch (IOException e) {
            throw new RuntimeException("API 요청과 응답 실패", e);
        } finally {
            con.disconnect();
        }
    }

    private static HttpURLConnection connect(String apiUrl){
        try {
            URL url = new URL(apiUrl);
            return (HttpURLConnection)url.openConnection();
        } catch (MalformedURLException e) {
            throw new RuntimeException("API URL이 잘못되었습니다. : " + apiUrl, e);
        } catch (IOException e) {
            throw new RuntimeException("연결이 실패했습니다. : " + apiUrl, e);
        }
    }

    private static String readBody(InputStream body){
        InputStreamReader streamReader = new InputStreamReader(body);
        try (BufferedReader lineReader = new BufferedReader(streamReader)) {
            StringBuilder responseBody = new StringBuilder();
            String line;
            while ((line = lineReader.readLine()) != null) {
                responseBody.append(line);
            }
            return responseBody.toString();
        } catch (IOException e) {
            throw new RuntimeException("API 응답을 읽는 데 실패했습니다.", e);
        }
    }
}

코드에서 변경한 내용은 고작 검색 키워드의 변수 정도입니다. 클라이언트 아이디와 시크릿키의 값만 잘 넣으면 성공적으로 결과를 조회할 수 있습니다.

이와 같이 단 10분만에 네이버에서 뉴스를 검색한 결과를 조회하는 기능을 구현할 수 있었습니다. 네이버 덕분에 쉽고 빠르게 고품질의 데이터를 제공받을 수 있어 기쁩니다.

1. 개발 환경

2. Node.js 설치

Vue 프로젝트를 생성하려면 Node.js가 필요합니다. Node.js 공식 홈페이지에서 LTS 버전을 설치합니다.

• 설치 후 버전 확인 명령어

node -v
npm -v

3. Vue 프로젝트 생성

Spring Boot 프로젝트 루트와는 별도로 frontend 폴더를 만들어 Vue 프로젝트를 생성합니다.

npm create vite@latest simple-app

• 프로젝트 이름: simple-app
• 프레임워크: Vue
• Variant: JavaScript

D:\>npm create vue@latest simple-app

> npx
> create-vue simple-app

T  Vue.js - The Progressive JavaScript Framework
|
o  Select features to include in your project: (↑/↓ to navigate, space to select, a to toggle all, enter to confirm)
|  Router (SPA development), Pinia (state management)
|
o  Select experimental features to include in your project: (↑/↓ to navigate, space to select, a to toggle all, enter to
confirm)
|  none
|
o  Skip all example code and start with a blank Vue project?
|  Yes

Scaffolding project in D:\simple-app...
|
—  Done. Now run:

   cd simple-app
   npm install
   npm run dev

| Optional: Initialize Git in your project directory with:

   git init && git add -A && git commit -m "initial commit"


D:\>cd simple-app

D:\simple-app>npm install

added 152 packages, and audited 153 packages in 10s

47 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

D:\simple-app>npm run dev

> simple-app@0.0.0 dev
> vite


  VITE v7.1.1  ready in 722 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  Vue DevTools: Open http://localhost:5173/__devtools__/ as a separate window
  ➜  Vue DevTools: Press Alt(⌥)+Shift(⇧)+D in App to toggle the Vue DevTools
  ➜  press h + enter to show help

4. 프로젝트 실행

cd simple-app
npm install
npm run dev

기본적으로 http://localhost:5173에서 Vue 개발 서버가 실행됩니다.

5. Bootstrap 설치

기존 HTML에서 Bootstrap을 사용했다면, Vue 프로젝트에도 설치합니다.

npm install bootstrap

main.js에 CSS를 추가:

import { createApp } from 'vue'
import App from './App.vue'
import 'bootstrap/dist/css/bootstrap.min.css'

createApp(App).mount('#app')

6. 프로젝트 구조

simple-app/
├── public/            # 정적 파일들 (index.html, 이미지 등)
├── src/
│   ├── assets/        # 이미지, 스타일 등 자원
│   ├── components/    # Vue 컴포넌트들
│   ├── router/        # Vue Router 설정 (SPA 라우팅)
│   ├── api/           # API 요청 관련 모듈 (apiRequest.js)
│   ├── App.vue        # 최상위 컴포넌트
│   └── main.js        # 진입점 스크립트
├── package.json
├── vite.config.js
└── ...

7. HTML → Vue 컴포넌트 변환

기존 Spring Boot resources/templates의 HTML 파일들을 Vue 컴포넌트로 변환합니다.

예: login.html → Login.vue

<template>
  <div class="login-page">
    <h1>로그인</h1>
    <form @submit.prevent="handleLogin">
      <input type="text" v-model="username" placeholder="아이디" />
      <input type="password" v-model="password" placeholder="비밀번호" />
      <button type="submit">로그인</button>
    </form>
  </div>
</template>

<script>
export default {
  data() {
    return {
      username: '',
      password: ''
    }
  },
  methods: {
    handleLogin() {
      console.log('로그인 요청', this.username, this.password)
    }
  }
}
</script>

8. API 호출 공통 함수 만들기 (apiRequest.js)

src/js/apiRequest.js 생성:

export async function apiRequest(url, options = {}) {
  let accessToken = localStorage.getItem("accessToken");

  options.headers = {
    ...options.headers,
    "Content-Type": "application/json",
    "Authorization": accessToken ? `Bearer ${accessToken}` : undefined
  };

  let response = await fetch(url, options);

  if (response.status === 401) {
    console.error("인증 실패");
  }

  return response.json();
}

9. Vite에서 백엔드 API 프록시 설정

vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

10. Spring Boot CORS 설정

백엔드 @Configuration에 다음 설정 추가:

@Bean
public WebMvcConfigurer corsConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            registry.addMapping("/**")
                    .allowedOrigins("http://localhost:5173")
                    .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                    .allowCredentials(true);
        }
    };
}

11. 실행 및 테스트

• 백엔드: ./gradlew bootRun (포트: 8080)
• 프론트엔드: npm run dev (포트: 5173)

브라우저에서 Vue 페이지 접속 후 API 요청이 정상적으로 작동하는지 확인합니다.

12. 마이그레이션 시 팁

• HTML을 Vue로 옮길 때, 템플릿 구조 + CSS 클래스는 그대로 두고, id/onclick 대신 Vue의 v-model, @click 등을 사용합니다.
• 공통 CSS는 src/assets에 넣고 main.js에서 import합니다.
• Vue Router를 사용하면 기존 HTML 페이지 전환을 SPA 방식으로 처리할 수 있습니다.

이렇게 하면 기존 Spring Boot HTML 기반 프론트를 Vue로 완전히 분리하고, API 연동까지 마칠 수 있습니다.

H2에서 PostgreSQL로 전환해야 하는 이유

로컬 개발 환경에서는 H2와 같은 내장 DB를 사용하면 편리하지만, 실제 서비스 환경에서는 데이터 영속성을 보장하고 여러 사용자가 동시에 접근할 수 있는 독립된 DB 서버가 필요합니다. Render는 PostgreSQL DB를 무료로 제공하므로 개인 프로젝트에 적합한 솔루션입니다.

Redner PostgreSQL 프로젝트 생성

PostgreSQL 새 프로젝트 생성

• Render 사이트에서 postgresql 프로젝트를 아래와 같이 생성합니다.

• 프로젝트가 성공적으로 생성되면 Connections 정보가 채워집니다.
• 해당 정보를 데이터베이스 연결에 활용합니다.

2. 스프링부트에 PostgreSQL 연동

1. PostgreSQL 드라이버 의존성 추가

Spring Boot가 PostgreSQL에 연결할 수 있도록 프로젝트에 드라이버 의존성을 추가해야 합니다. build.gradle(Gradle) 파일에 postgresql을 추가해 주세요.

• 기존 h2 데이터베이스를 주석처리한 후 postgresql 데이터베이스로 변경하였습니다.

2. application.yml 설정 변경

• H2 관련 설정은 모두 지우고, Render에서 제공하는 PostgreSQL 연결 정보를 application.yml에 추가해야 합니다.
• src/main/resources/application.yml 파일에 다음 내용을 작성해 주세요. {}로 표시된 부분은 반드시 본인의 Render DB 정보로 바꿔야 합니다.

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://{host_value}:5432/simple_iltf
    username: simple_iltf_user
    password: {password_value}

• spring.datasource.url: Render 대시보드의 External Database URL에서 호스트 주소를 복사하여 입력합니다.
• spring.datasource.username & password: Render DB 사용자 이름과 비밀번호를 정확하게 입력합니다.

3. 데이터베이스 연결 확인

로그 확인

• 위의 설정을 마친 뒤 프로젝트를 실행해 보았습니다.
• 로그를 통해 PostgreSQL 데이터베이스로 변경된 것을 확인할 수 있습니다.

디비버 연결 및 조회

추가로 백엔드와 DB 연결이 완료되었다면, DBeaver를 사용해 GUI 환경에서 데이터를 직접 확인하고 관리할 수 있습니다.

• Render에서 제공하는 Connections 정보를 바탕으로 데이터베이스 연결에 성공했습니다.

• 기존 테이블의 내용이 조회되는 것도 확인할 수 있습니다.

API 전송 테스트

백엔드와 데이터베이스 연결이 되었는지 확인하기 위해 API 요청을 보내 테스트를 진행하였습니다. 성공적으로 데이터를 조회하는 것을 확인할 수 있었습니다.

구현 목표

• Access Token + Refresh Token 기반 인증 구조 설계
• Access Token 만료 시 Refresh Token으로 재발급
• Refresh Token 저장·관리
• 로그아웃 시 Refresh Token 삭제 처리
• Postman을 활용한 전체 테스트

1. Refresh Token 설계

저장 위치

• DB에 저장하여 관리 (user_info 테이블에 컬럼 추가)

  ALTER TABLE user_info ADD refresh_token VARCHAR(255);

저장 이유

• Refresh Token은 장기 보관이 필요한 토큰이므로 서버에서 안전하게 관리
• 클라이언트와 서버 양쪽에서 토큰을 검증 가능

2. JWT 발급 구조

Access Token

• 만료 시간: 짧게 (예: 1시간)
• 인증/인가 요청 시 사용
• 탈취 시 피해를 최소화하기 위해 짧은 수명 설정

Refresh Token

• 만료 시간: 길게 (예: 7일)
• Access Token이 만료됐을 때 새로운 Access Token 발급에만 사용
• DB에 저장하여 유효성 검증 가능

3. API 설계

4. 구현 핵심 코드

로그인 시 Refresh Token 저장

String refreshToken = jwtUtil.createRefreshToken(username);
userMapper.updateRefreshToken(username, refreshToken);

return Map.of(
    "accessToken", accessToken,
    "refreshToken", refreshToken
);

토큰 재발급

@PostMapping("/api/refresh")
public Map<String, String> refreshToken(@RequestBody Map<String, String> request) {
    String refreshToken = request.get("refreshToken");

    if (!jwtUtil.validateToken(refreshToken)) {
        throw new RuntimeException("Refresh Token이 유효하지 않습니다.");
    }

    String username = jwtUtil.getUsername(refreshToken);
    String savedRefreshToken = userMapper.findRefreshToken(username);

    if (!refreshToken.equals(savedRefreshToken)) {
        throw new RuntimeException("Refresh Token 불일치");
    }

    String newAccessToken = jwtUtil.createAccessToken(username);
    return Map.of("accessToken", newAccessToken);
}

로그아웃 처리

@PostMapping("/api/logout")
public void logout(@RequestBody Map<String, String> request) {
    String refreshToken = request.get("refreshToken");
    String username = jwtUtil.getUsername(refreshToken);
    userMapper.updateRefreshToken(username, null);
}

5. Postman 테스트 시퀀스

1) 로그인 요청

• POST /api/login
• Body(JSON)

  json
  { "username": "testuser", "password": "1234" }
  응답: Access Token + Refresh Token

  2) 인증 API 호출

• GET /api/user/test
• Header

css
Authorization: Bearer {accessToken}

3) Access Token 만료 시 재발급

• POST /api/refresh
• Body(JSON)

json
{ "refreshToken": "발급받은_refresh_token" }
응답: 새 Access Token

4) 로그아웃

• POST /api/logout
• Body(JSON)

json
{ "refreshToken": "발급받은_refresh_token" }

5) 로그아웃 후 재발급 요청 테스트

• POST /api/refresh
• Body(JSON)

  json
  { "refreshToken": "발급받은_refresh_token" }

• 응답:

  mathematica
  Refresh Token 불일치

• 로그아웃 후에는 DB에서 Refresh Token이 삭제되어 재발급 불가

6. 마무리

• JWT 기반의 인증/인가 구조 완성
• Refresh Token을 통한 안전한 Access Token 재발급
• 로그아웃 시 Refresh Token 무효화
• Postman으로 로그인 → 인증 → 재발급 → 로그아웃 → 재발급 실패 시나리오 검증 완료

다음 단계에서는:

• Refresh Token을 Redis 같은 인메모리 저장소로 관리
• HTTPS 적용
• 토큰 탈취 방지 로직 추가

1. 사용자 권한 정보(DB 컬럼) 추가하기

JWT 권한 인증을 위해선 토큰에 권한 정보가 포함되어야 합니다.
그래서 기존 사용자 테이블에 권한을 저장하는 컬럼을 추가했습니다.

예를 들어, 다음과 같이 두 사용자 계정을 준비했습니다:

권한은 반드시 ROLE_ 접두사가 붙는 형태로 저장하거나, 애플리케이션 코드에서 접두사를 붙여 일관성 있게 관리하는 것이 중요합니다.

2. 로그인 시 권한 정보를 포함한 JWT 토큰 발급

AuthController에서 로그인 성공 후, DB에서 권한 정보를 읽어 JWT 토큰에 포함시켰습니다.

String role = userService.getRoleByUserId(userId); // DB에서 권한 조회
String roleClaim = role.startsWith("ROLE_") ? role : "ROLE_" + role;
String token = jwtTokenProvider.createToken(userId, roleClaim);

이렇게 발급된 토큰은 내부에 role 클레임을 포함하고 있으며, 클라이언트는 이 토큰을 API 요청 시 헤더에 담아 전송합니다.

3. JWT 토큰에서 권한 정보 파싱 및 SecurityContext에 권한 부여

JwtAuthenticationFilter에서 요청 헤더의 토큰을 꺼내 검증하고, 토큰의 role 클레임을 추출해 SimpleGrantedAuthority 리스트로 변환합니다.

String role = jwtTokenProvider.getUserRole(token);
List<SimpleGrantedAuthority> authorities = Collections.singletonList(new SimpleGrantedAuthority(role));

UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(userId, null, authorities);
SecurityContextHolder.getContext().setAuthentication(authentication);

이 과정을 통해 Spring Security가 현재 요청 사용자의 권한을 인식할 수 있게 됩니다.

4. SecurityFilterChain에서 권한별 API 접근 제한 설정

SecurityConfig에서는 다음과 같이 경로별 권한을 제한합니다.

java .authorizeHttpRequests(auth -> auth .requestMatchers("/api/admin/**").hasRole("ADMIN") .requestMatchers("/api/user/**").hasAnyRole("USER", "ADMIN") .anyRequest().authenticated() )

즉, /api/admin/** 경로는 ADMIN 권한을 가진 사용자만 접근 가능하고, /api/user/** 경로는 USER 권한 또는 ADMIN 권한 사용자 모두 접근 가능합니다.

5. Postman으로 권한별 API 호출 테스트하기

• 로그인 : /api/login에 ID, PW 전송 → 토큰 수신
• USER 권한 테스트 : /api/user/test 호출 → 정상 접근(200 OK)
• ADMIN 권한 테스트 : /api/admin/test 호출 → USER 권한이면 403 Forbidden, ADMIN 권한이면 200 OK
• 토큰 미포함 요청 : 401 Unauthorized 또는 403 Forbidden

마무리

이번 글에서는 DB에 권한 정보를 추가하고 JWT 토큰에 권한을 포함하여, Spring Security와 연동해 권한별 API 접근 제어를 구현하는 방법을 살펴봤습니다. 다음 글에서는 Refresh Token 구현과 토큰 만료 시 자동 갱신 방법, 로그아웃 처리 등을 다룰 예정입니다.

이번 포스트에서는 Spring Boot를 기반으로 JWT(Json Web Token)를 이용한 로그인 인증 기능을 구현하는 과정을 단계별로 정리합니다.

✅ 사용 기술 스택

• Java 17
• Spring Boot
• Spring Security
• H2 Database
• Lombok
• jjwt (JWT 라이브러리)

📁 프로젝트 구조 개요

src/ └─ com.ccp.simple ├─ controller │ └─ AuthController.java ├─ security │ └─ JwtTokenProvider.java ├─ config │ └─ SecurityConfig.java ├─ service │ └─ UserService.java └─ dto └─ LoginRequestDto.java

🔐 JWT란? 왜 사용하는가?

JWT (JSON Web Token)는 사용자의 인증 정보를 안전하게 전달하기 위한 토큰 기반 인증 방식입니다.

✅ 특징

• Stateless: 서버가 세션/쿠키를 저장하지 않음 → 서버 확장에 유리
• Self-contained: 토큰 자체에 유저 정보(예: ID, Role 등)를 담고 있어 별도 DB 조회 없이 인증 가능
• Bearer Token 방식 → HTTP 요청의 Authorization 헤더에 담아 전달

🔁 전체 인증 흐름 요약

1. 로그인 요청 : 사용자가 /api/login에 ID/PW를 보내면 서버는

• 사용자 인증 (UserService에서 유효성 확인)
• JWT 토큰 생성 (JwtTokenProvider.createToken)
• Authorization: Bearer {token} 헤더에 담아 응답

2. 클라이언트는 받은 토큰을 저장 : 로컬 스토리지 / 세션 스토리지 / 쿠키 등에 저장

3. 인증이 필요한 요청마다 토큰을 같이 전송 GET /api/me HTTP/1.1 Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

4. 서버는 요청 시 토큰을 검증 JwtTokenProvider.validateToken()으로 유효성 체크 토큰이 유효하면 SecurityContext에 사용자 정보 설정 이후 컨트롤러 등에서 Authentication 객체로 사용자 정보 사용 가능

✅ 정리

1. 로그인 : ID/PW로 JWT 토큰 발급
2. 클라이언트 저장 : 받은 토큰을 저장 후 인증 요청에 포함
3. 인증 요청 : Authorization 헤더에 Bearer {token} 포함
4. 토큰 검증 : 서버에서 토큰 검증 후 사용자 인증 처리
5. 사용자 정보 접근 : Authentication 객체로 현재 사용자 확인 가능

🔧 1. JWT 토큰 생성 및 검증 클래스

// JwtTokenProvider.java
@Component
public class JwtTokenProvider {

    private final Key key = Keys.secretKeyFor(SignatureAlgorithm.HS256);
    private final long validityInMilliseconds = 3600000; // 1시간

    public String createToken(String userId) {
        Claims claims = Jwts.claims().setSubject(userId);
        Date now = new Date();
        Date expiry = new Date(now.getTime() + validityInMilliseconds);
        return Jwts.builder()
                .setClaims(claims)
                .setIssuedAt(now)
                .setExpiration(expiry)
                .signWith(key)
                .compact();
    }

    public boolean validateToken(String token) {
        try {
            Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            return false;
        }
    }

    public String getUserId(String token) {
        return Jwts.parserBuilder().setSigningKey(key).build()
                .parseClaimsJws(token).getBody().getSubject();
    }
}

🛡️ 2. Spring Security 설정

// SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .headers(headers -> headers.frameOptions().disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/h2-console/**", "/api/login", "/login.html").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

/h2-console/**, /api/login 경로는 인증 없이 접근 가능하도록 허용합니다.

🧪 3. 로그인 및 인증 컨트롤러

// AuthController.java
@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class AuthController {

    private final UserService userService;
    private final JwtTokenProvider jwtTokenProvider;

    @PostMapping("/login")
    public String login(@RequestBody LoginRequestDto request, HttpServletResponse response) {
        boolean valid = userService.validateUser(request.getUserId(), request.getUserPassword());
        if (valid) {
            String token = jwtTokenProvider.createToken(request.getUserId());
            response.setHeader("Authorization", "Bearer " + token);
            return "Login successful";
        } else {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            return "Invalid credentials";
        }
    }

    @GetMapping("/me")
    public String currentUser(Authentication authentication) {
        if (authentication == null) {
            return "No Authentication found";
        }
        return "Current User ID : " + authentication.getPrincipal();
    }
}

📬 4. Postman으로 테스트

✔️ 1) 로그인 요청 (POST) URL: http://localhost:8080/api/login

✔️ 2) 인증된 사용자 정보 요청 (GET) URL: http://localhost:8080/api/me

🔧 사용하는 기술 스택

• Java 17
• Spring Boot 3.5.x
• Gradle
• H2 Database
• MyBatis
• Springdoc OpenAPI (Swagger)

🚀 Springdoc OpenAPI 의존성 추가

build.gradle 파일에 아래 의존성을 추가합니다:

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

✅ 의존성 추가 후에는 Gradle 프로젝트를 리프레시하거나 빌드해줘야 합니다.

🧩 Swagger 설정 (선택)

Swagger 문서의 제목, 설명 등을 직접 설정하고 싶다면 아래처럼 Config 클래스를 만들어줍니다:

package com.ccp.simple.controller;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("회원 관리 API")
                        .description("Spring Boot + MyBatis 기반 회원관리 시스템 API 문서")
                        .version("v1.0"));
    }
}

✅ 이 설정은 필수는 아니며, 생략해도 기본 UI는 잘 작동합니다.

🌐 Swagger UI 접속 방법

Spring Boot 앱을 실행한 후 아래 URL로 접속하면 Swagger UI를 확인할 수 있습니다. http://localhost:8080/swagger-ui/index.html 참고) /v3/api-docs 경로는 Swagger가 내부적으로 사용하는 JSON 문서입니다.

📌 참고) 정상 노출을 위한 조건

• @RestController, @RequestMapping, @GetMapping, @PostMapping 등이 제대로 선언되어 있어야 합니다.
• DTO, Controller가 @ComponentScan 범위에 포함되어야 합니다.

✍️ 마무리

Swagger는 API 서버를 개발할 때 문서화 자동화 + 테스트 편의성을 동시에 잡을 수 있는 좋은 도구입니다. 간단한 설정으로 프로젝트의 퀄리티를 높일 수 있으니 꼭 한 번 적용해보세요!

스프링부트 프로젝트 세팅

프로젝트 생성

이번 프로젝트는 Spring Boot 애플리케이션을 Docker로 컨테이너화하고, Render를 통해 자동 배포하는 것을 목표로 합니다. 먼저 Spring Initializr를 이용해 기본 프로젝트를 생성했습니다.

• Framework: Spring Boot 3.5.3 → 최신 버전의 Spring Boot로, Java 17 이상에서 실행 가능
• Build Tool: Gradle → 의존성 관리가 편리하고 빌드 속도가 빠름
• JDK: Java 17 → LTS(Long Term Support) 버전으로 안정성이 높음

프로젝트 실행 테스트

프로젝트를 생성한 직후, IDE에서 바로 실행해 보고 Spring Boot 로고와 함께 Started Application 로그가 나오면 성공입니다. 이 단계에서 실행이 안 되면 Gradle 설정이나 JDK 경로부터 점검해야 합니다.

데이터베이스 연결 (H2 Database)

이번 예제에서는 개발 단계에서만 H2 Database를 사용합니다. H2는 가볍고 메모리 모드 지원 덕분에 빠른 테스트에 유리합니다.

1. build.gradle에 의존성 추가

  runtimeOnly 'com.h2database:h2'

2. application.yml에 데이터베이스 설정 추가
3. H2 1.4.198 이후 버전에서는 보안 정책 변경으로 파일 기반 DB가 자동 생성되지 않음 따라서 DB 파일을 직접 생성해야 할 수 있습니다.

위 위치에 test.mv.db 파일을 생성한 뒤 접속하면 정상적으로 접근됩니다.

H2 콘솔 접속 후 테스트용 테이블을 만들어 확인합니다.

메모리 모드 사용 예시

테스트용 데이터베이스를 메모리에만 유지하려면 아래와 같이 설정합니다. 이 경우 애플리케이션이 종료되면 데이터는 사라집니다.

datasource:  
  url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1  
  driver-class-name: org.h2.Driver  
  username: sa  
  password:

로깅 설정

Spring Boot의 기본 로깅 레벨은 INFO입니다. 전체 로그를 보고 싶다면 application.yml에 다음과 같이 설정합니다.

logging:
  level:
    root: INFO

• 개발 중에는 DEBUG로 변경하면 쿼리 실행 로그까지 확인 가능하지만, 운영 환경에서는 성능 저하를 막기 위해 INFO 또는 WARN을 권장합니다.

MyBatis 연결 설정

MyBatis를 사용해 DB와 연동하기 위한 기본 설정입니다.

mybatis:  
  mapper-locations: classpath:/mapper/**/*.xml  
  type-aliases-package: com.ccp.simple.domain  
  configuration:  
    map-underscore-to-camel-case: true

• mapper-locations: XML 매퍼 파일 위치 지정
• type-aliases-package: DTO/VO 클래스의 패키지 경로 → 클래스명을 짧게 사용할 수 있음
• map-underscore-to-camel-case: DB 컬럼명(user_name)을 Java 필드명(userName)으로 자동 변환

설정파일 전체 예시

아래는 지금까지의 설정을 합친 application.yml 예시입니다.

spring:  
  datasource:  
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1  
    driver-class-name: org.h2.Driver  
    username: sa  
    password:  
  h2:  
    console:  
      enabled: true  
  sql:  
    init:  
      schema-locations: classpath:schema.sql  
      data-locations: classpath:data.sql  
      mode: always  

mybatis:  
  mapper-locations: classpath:/mapper/**/*.xml  
  type-aliases-package: com.ccp.simple.domain  
  configuration:  
    map-underscore-to-camel-case: true  

logging:  
  level:  
    root: INFO

프로젝트 및 테이블 구조

프로젝트 구조

테이블 구조

• 참고: bbs 테이블은 생성하지 않음

조회 기능 테스트

@RestController
@RequiredArgsConstructor
@RequestMapping("user")
public class UserController {
    private final UserService userService;

    @GetMapping()
    public List<User> getUsers() {
        return userService.getUsers();
    }
}

도커 배포

데이터베이스 메모리 모드 변경

datasource:  
  url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1  
  driver-class-name: org.h2.Driver  
  username: sa  
  password:

• H2 메모리 모드 사용 시 앱 종료하면 데이터 초기화됨
• 파일 모드로 변경 필요

datasource:  
  url: jdbc:h2:file:./data/testdb;DB_CLOSE_ON_EXIT=FALSE  
  driver-class-name: org.h2.Driver  
  username: sa  
  password:

• 도커 컨테이너에 데이터 파일 복사 또는 볼륨 마운트 예정

빌드 (Jar 파일 생성)

./gradlew clean build

• build/libs/ 폴더 내 yourprojectname-version.jar 생성됨

도커 설치

• Docker Desktop (Windows용) 설치
• docker --version으로 설치 확인
• Docker는 WSL2 위에서 작동하므로 WSL 설치 및 업데이트 필요

WSL 업데이트 이슈 참고

• wsl --update 실패 시 해결책 링크
• GitHub Issue
• 블로그 글

1. Dockerfile 생성

• 프로젝트 루트(예: build.gradle 위치)에 생성

FROM openjdk:17-jdk-slim
WORKDIR /app
COPY build/libs/simple-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

2. Docker 이미지 빌드

docker build -t simple-app .

• 이미지 확인

docker images

3. Docker 컨테이너 실행

docker run -d -p 8080:8080 --name simple-container simple-app

• 컨테이너 실행 확인

docker ps

자동 배포

GitHub Push → 자동 빌드 → 자동 Docker 배포

Render 자동 배포 과정

1. Render 가입 (https://render.com)
2. Web Service 선택

3. GitHub 연결
4. 레포지토리 선택, Language는 Docker 설정

5. 배포 버튼 클릭

배포 중 발생한 오류

error: failed to solve: failed to compute cache key: failed to calculate checksum of ref ... no such file or directory

• 원인: Render가 Dockerfile만 보고 빌드 시도하는데, 빌드된 Jar가 없어 실패

• 해결법

  1. Jar 파일을 깃허브에 수동 업로드 (비효율)
  2. Dockerfile에 Gradle 빌드 명령어 포함 (추천)

Dockerfile 수정 전

FROM openjdk:17-jdk-slim
WORKDIR /app
COPY build/libs/simple-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

Dockerfile 수정 후 (빌드 포함)

# Build stage
FROM gradle:8.5-jdk17 AS builder
COPY --chown=gradle:gradle . /home/gradle/project
WORKDIR /home/gradle/project
RUN gradle build --no-daemon

# Run stage
FROM openjdk:17-jdk-slim
WORKDIR /app
COPY --from=builder /home/gradle/project/build/libs/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

배포 재시도 결과

자동 배포 테스트 성공 화면

마무리

• Render를 이용한 자동 배포는 설정이 매우 간단해서 초보자도 쉽게 따라할 수 있음
• Dockerfile 내에서 Gradle 빌드 포함은 자동화에 필수적
• 앞으로도 GitHub Push → Render 자동 배포 흐름으로 운영 가능

• 사용자가 동시에 여러 세션을 생성하는 것을 관리
• 사용자의 인증 후 활성화된 세션의 수가 설정된 maximumSession 값과 비교하여 제어 여부를 결정

1. 사용자 세션 강제 만료
2. 사용자 인증 시도 차단

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.sessionManagement(session -> session
    .invalidSessionUrl(“/invalidSessionUrl”) // 이미 만료된 세션으로 요청을 하는 사용자를 특정 엔드포인트로 리다이렉션 할 Url 을 지정한다
    .maximumSessions(1) // 사용자당 최대 세션 수를 제어한다. 기본값은 무제한 세션을 허용한다
    .maxSessionsPreventsLogin(true) // true 이면 최대 세션 수(maximumSessions(int))에 도달했을 때 사용자의 인증을 방지한다
// false(기본 설정)이면 인증하는 사용자에게 접근을 허용하고 기존 사용자의 세션은 만료된다
.expiredUrl("/expired") // 세션을 만료하고 나서 리다이렉션 할 URL 을 지정한다
 );
     return http.build();
}

세션 고정 보호

• 악의적인 공격자가 사이트에 접근하여 세션을 생성한 다음 다른 사용자가 같은 세션으로 로그인하도록 유도하는 위험
• 스프링 시큐리티는 사용자가 로그인할 때 새로운 세션을 생성하거나 세션 ID를 변경하여 자동 대응

세션 고정 보호 전략

• changeSessionId() : 기존 세션을 유지하면서 세션 ID만 변경하여 인증 과정에서 세션 고정 공격을 방지하는 방식이다. 기본 값으로 설정되어 있다
• newSession() : 새로운 세션을 생성하고 기존 세션 데이터를 복사하지 않는 방식이다(SPRING_SECURITY_ 로 시작하는 속성은 복사한다)
• migrateSession() : 새로운 세션을 생성하고 모든 기존 세션 속성을 새 세션으로 복사한다
• none() : 기존 세션을 그대로 사용한다

세션 정책

• 인증된 사용자에 대한 세션 생성 정책을 설정하여 어떻게 세션을 관리할지 결정할 수 있으며 이 정책은 SessionCreationPolicy 로 설정

세션 생성 정책 전략

1. SessionCreationPolicy. ALWAYS

• 인증 여부에 상관없이 항상 세션을 생성한다
• ForceEagerSessionCreationFilter 클래스를 추가 구성하고 세션을 강제로 생성시킨다

2. SessionCreationPolicy. NEVER

• 스프링 시큐리티가 세션을 생성하지 않지만 애플리케이션이 이미 생성한 세션은 사용할 수 있다

3. SessionCreationPolicy. IF_REQUIRED

• 필요한 경우에만 세션을 생성한다. 예를 들어 인증이 필요한 자원에 접근할 때 세션을 생성한다

4. SessionCreationPolicy. STATELESS

• 세션을 전혀 생성하거나 사용하지 않는다
• 인증 필터는 인증 완료 후 SecurityContext 를 세션에 저장하지 않으며 JWT 와 같이 세션을 사용하지 않는 방식으로 인증을 관리할 때 유용할 수 있다
• SecurityContextHolderFilter 는 세션 단위가 아닌 요청 단위로 항상 새로운 SecurityContext 객체를 생성하므로 컨텍스트 영속성이 유지되지 않는다

4. STATELESS 설정에도 세션이 생성될 수 있다

• 스프링 시큐리티에서 CSRF 기능이 활성화 되어 있고 CSRF 기능이 수행 될 경우 사용자의 세션을 생성해서 CSRF 토큰을 저장하게 된다
• 세션은 생성되지만 CSRF 기능을 위해서 사용될 뿐 인증 프로세스의 SecurityContext 영속성에 영향을 미치지는 않는다

SessionManagementFilter & ConcurrentSessionFilter

• 요청이 시작된 이후 사용자가 인증되었는지 감지하고, 인증된 경우에는 세션 고정 보호 메커니즘을 활성화하거나 동시 다중 로그인을 확인하는 등 세션 관련 활동을 수행하기 위해 설정된 세션 인증 전략(SessionAuthenticationStrategy)을 호출하는 필터 클래스
• 스프링 시큐리티 6 이상에서는 SessionManagementFilter 가 기본적으로 설정 되지 않으며 세션관리 API 를 설정을 통해 생성할 수 있음

ConcurrentSessionFilter

• 각 요청에 대해 SessionRegistry에서 SessionInformation 을 검색하고 세션이 만료로 표시되었는지 확인하고 만료로 표시된 경우 로그아웃 처리를 수행한다(세션 무효화)
• 각 요청에 대해 SessionRegistry.refreshLastRequest(String)를 호출하여 등록된 세션들이 항상 '마지막 업데이트' 날짜/시간을 가지도록 한다