[스프링] 6. API 통합과 면접 대비

Repository에서 커서 조회를 구현했으니, 이제 Service에서 응답을 조립하고 Controller에서 API로 노출하는 과정을 다룬다. 마지막으로 면접에서 자주 나오는 질문을 정리한다.

Service 레이어 조립

Service는 Repository에서 받은 결과를 가공해서 응답 DTO로 변환한다. 핵심은 limit+1 패턴의 후처리와 커서 값 추출이다.

@Override
@Transactional(readOnly = true)
public FeedGetResponse getFeedsByCursor(FeedGetRequest request) {
    List<Feed> feeds = feedRepository.searchFeeds(request);
    long totalCount = feedRepository.count();

    boolean hasNext = feeds.size() > request.limit();
    if (hasNext) {
        feeds.removeLast();
    }

    String nextCursor = null;
    String nextIdAfter = null;

    if (!feeds.isEmpty() && hasNext) {
        Feed lastFeed = feeds.getLast();
        nextCursor = lastFeed.getCreatedAt().toString();
        nextIdAfter = lastFeed.getId().toString();
    }

    List<FeedDto> data = feeds.stream()
            .map(this::toFeedDto)
            .toList();

    return new FeedGetResponse(
            data, nextCursor, nextIdAfter, hasNext, totalCount,
            request.sortBy(), request.sortDirection()
    );
}

흐름을 정리하면 이렇다.

1. Repository에서 limit + 1개를 조회한다
2. 결과가 limit보다 많으면 hasNext = true이고 마지막 항목을 제거한다
3. 남은 결과의 마지막 항목에서 커서 값을 추출한다
4. DTO로 변환해서 응답을 조립한다

nextCursor 추출 시점

커서 값은 마지막 항목을 제거한 뒤 남은 목록의 마지막에서 추출해야 한다. limit+1번째 항목의 값을 커서로 쓰면, 다음 페이지 요청 시 그 항목이 누락된다.

요청 DTO 설계

커서 조회의 요청 파라미터는 Offset 방식보다 종류가 많다.

public record FeedGetRequest(
        String cursor,
        String idAfter,
        @NotNull int limit,
        @NotNull SortBy sortBy,
        @NotNull SortDirection sortDirection,
        String keywordLike,
        SkyStatus skyStatusEqual,
        PrecipitationType precipitationTypeEqual,
        UUID authorIdEqual
) {}

파라미터를 역할별로 분류하면 세 가지다.

• 페이징 : cursor, idAfter, limit — 어디서부터 몇 개를 가져올지
• 정렬 : sortBy, sortDirection — 어떤 순서로 정렬할지
• 필터 : keywordLike, skyStatusEqual 등 — 어떤 조건으로 걸러낼지

커서 관련 필드는 첫 페이지 요청 시 null이 들어오므로 @NotNull을 붙이지 않는다.

필터 파라미터 네이밍 컨벤션

필터 이름에 비교 연산을 명시하면 API 사용자가 동작을 직관적으로 이해할 수 있다.

• keywordLike → LIKE 검색
• skyStatusEqual → 정확히 일치
• authorIdEqual → 정확히 일치

"keyword"만 쓰면 정확히 일치하는지, 포함하는지, 시작하는지 알 수 없다. 접미사로 의도를 드러내는 게 좋다.

응답 DTO 설계

응답에는 데이터뿐 아니라 페이징 메타데이터가 포함되어야 한다.

public record FeedGetResponse(
        List<FeedDto> data,
        String nextCursor,
        String nextIdAfter,
        boolean hasNext,
        Long totalCount,
        SortBy sortBy,
        SortDirection sortDirection
) {}

클라이언트가 다음 페이지를 요청하려면 nextCursor와 nextIdAfter를 그대로 보내면 된다. hasNext가 false면 더 이상 요청할 필요가 없다.

sortBy와 sortDirection을 응답에 포함하는 이유는, 클라이언트가 현재 어떤 정렬로 조회 중인지 확인할 수 있게 하기 위해서다.

커서 값의 타입

nextCursor와 nextIdAfter는 String으로 선언한다. Instant나 UUID를 그대로 쓰면 직렬화 형식을 서버가 결정하게 되는데, 문자열로 통일하면 클라이언트가 타입을 몰라도 그대로 돌려보내기만 하면 된다.

Controller 설계

GET 요청에서 조회 파라미터를 받는 방법은 두 가지다.

@ModelAttribute 방식

@GetMapping
public ResponseEntity<FeedGetResponse> getFeeds(
        @ModelAttribute @Valid FeedGetRequest request) {
    return ResponseEntity.ok(feedService.getFeedsByCursor(request));
}

쿼리 파라미터를 DTO에 바인딩한다. GET 요청의 표준적인 방법이다.

GET /api/feeds?limit=10&sortBy=CREATED_AT&sortDirection=DESCENDING

@RequestBody 방식

@GetMapping
public ResponseEntity<FeedGetResponse> getFeeds(
        @RequestBody @Valid FeedGetRequest request) {
    return ResponseEntity.ok(feedService.getFeedsByCursor(request));
}

JSON 바디로 파라미터를 받는다. 필터 조건이 복잡할 때 적합하지만, GET 요청에 body를 넣는 것은 HTTP 스펙상 권장되지 않는다.

전체 흐름 정리

요청부터 응답까지의 데이터 흐름이다.

1. 클라이언트가 GET /api/feeds?limit=10&sortBy=CREATED_AT&sortDirection=DESCENDING을 요청한다
2. Controller가 FeedGetRequest로 바인딩한다. cursor와 idAfter는 null이다
3. Service가 Repository의 searchFeeds를 호출한다. limit+1인 11개를 조회한다
4. Repository가 QueryDSL로 커서 조건, 필터, 정렬 쿼리를 실행한다
5. Service가 11개 중 마지막 1개를 제거하고, 10번째의 커서 값을 추출한다
6. FeedGetResponse를 조립해서 반환한다
7. 클라이언트가 nextCursor와 nextIdAfter를 다음 요청에 담아 보낸다
8. hasNext가 false가 될 때까지 2~7을 반복한다

자주 하는 실수

면접 대비