shootingstar-1117 님의 블로그

[회고] CI/CD 파이프라인 구축 및 자동화 배포 후기

shootingstar-1117 — Fri, 6 Feb 2026 16:47:42 +0900

1. CI/CD 파이프라인 설계 (Data Flow)

Local (Dev Environment)
- 개발자는 로컬에서 docker-compose up -d pace-db pace-redis를 통해 인프라를 띄우고, IntelliJ에서 서버를 실행하여 개발합니다.
- 코드 수정 후 develop 브랜치에 push 하면 파이프라인이 시작됩니다.
GitHub Actions (CI)
- Build: 소스 코드를 체크아웃하고 Dockerfile을 기반으로 이미지를 빌드합니다.
- Push: 빌드된 이미지를 Docker Hub 레지스트리로 전송합니다. (push)
AWS EC2 (CD)
- Connect: SSH(appleboy/ssh-action)를 통해 서버에 접속합니다.
- Pull: Docker Hub에서 최신 이미지를 pull 받아옵니다.
- Env Generation: GitHub Secrets에 저장된 민감한 정보들을 사용하여 서버 내부에서 .env 파일을 동적으로 생성합니다.
- Run: docker-compose up -d 명령어로 변경된 컨테이너만 스마트하게 교체하고 실행합니다.
- Health Check: 서버가 정상적으로 떴는지 curl 명령어로 확인 후 배포를 완료합니다.

2. 주요 트러블슈팅 및 해결 과정 (Learning Points)

Issue 1: "포트가 이미 사용 중입니다" (Bind for 0.0.0.0:3306 failed)

현상: 배포 스크립트 실행 시 MySQL 포트 충돌 에러(driver failed programming external connectivity)가 발생하며 배포가 실패했습니다.
원인:
1. 초기 설정에서 DB 포트를 0.0.0.0:3306으로 열어두었는데, 이를 보안 강화를 위해 127.0.0.1:3306으로 변경하는 과정에서 Docker의 네트워크 설정(iptables)이 꼬였습니다.
2. docker-compose down을 해도 docker-proxy 프로세스가 좀비처럼 남아 포트를 점유하고 있었습니다.
해결:
- 서버에 직접 접속하여 sudo lsof -i :3306으로 범인 프로세스를 색출하고 kill 했습니다.
- docker network prune -f와 sudo systemctl restart docker 명령어로 꼬인 네트워크 규칙을 강제로 초기화하여 해결했습니다.
- 배운점: 설정이 크게 바뀔 때는 prune이나 서비스 재시작 같은 작업이 필요함을 배웠습니다.

Issue 2: 환경변수의 미로 (.env vs yaml vs compose)

현상: 로컬에서는 잘 되는데 배포만 하면 DB 접속이 안되는 에러가 발생했습니다.
원인: application.yaml, docker-compose.yml, 그리고 실제 주입되는 환경변수의 이름이 서로 미묘하게 달랐습니다.
해결: "Single Source of Truth (.env)" 전략을 도입했습니다.
- 모든 변수명을 .env 기준으로 통일했습니다.
- docker-compose.yml은 .env를 읽어 컨테이너에 주입하고, 앱은 그 값을 그대로 받도록 설정을 일원화하여 혼란을 잠재웠습니다.

Issue 3: Redis 보안과 데이터 증발

현상: 코드 리뷰 중 "Redis 포트가 외부에 열려있어 위험하다"는 지적과 "컨테이너 재시작 시 데이터가 날아간다"는 문제를 확인했습니다.
해결:
- 보안: ports: 127.0.0.1:6379:6379 설정을 통해 외부 접속을 원천 차단하고, 로컬(앱)에서만 접속 가능하게 변경했습니다.
- 데이터: volumes 설정을 추가하고, redis-server --appendonly yes 옵션을 통해 데이터 영속성을 확보했습니다.

3. 성찰 및 향후 계획

깨달은 점: 단순히 "배포가 된다"를 넘어 "안전하고 효율적으로" 배포하는 것이 얼마나 어려운지 깨달았습니다. 특히 Docker Compose가 제공하는 코드로써의 인프라 덕분에, 팀원들이 복잡한 설치 과정 없이 명령어 한 줄로 동일한 개발 환경을 갖게 된 것이 가장 큰 수확인 것 같습니다.
아쉬운 점: 현재는 배포 시 약 10~30초 정도의 다운타임(서버 끊김)이 발생합니다. 프론트엔드 팀원들이 테스트 중에 불편을 겪기도 했습니다.
향후 계획: 다음 단계로는 Blue/Green 배포 전략을 도입하여, 사용자가 배포 중에도 끊김 없이 서비스를 이용할 수 있는 무중단 배포 환경을 구축하고 싶습니다.
후기: 정말 좋은 경험이었습니다!! 인프라 구축을 바닥부터 하나하나 쌓아가며 경험을 얻은 귀중한 시간이었습니다.

[회고] Cloudtype 배포 성공기: MariaDB와 환경 변수 트러블슈팅

shootingstar-1117 — Thu, 15 Jan 2026 15:59:34 +0900

로컬 환경(Local)에서 개발하던 스프링 부트 프로젝트를 실제 클라우드 환경(Cloudtype)에 배포하며 겪은 시행착오와 해결 과정을 정리합니다. 이번 경험을 통해 인프라 설정과 데이터베이스 연결의 핵심 원리를 깊이 이해하게 되었습니다.

1. 개요

프로젝트명: Pace
배포 환경: Cloudtype (Spring Boot, MariaDB)
주요 기술: Java 21, Spring Boot 3.x, Spring Data JPA, MySQL

2. 주요 트러블슈팅 (Troubleshooting)

2.1 환경 변수 주입 문제

문제: java.lang.RuntimeException: Driver claims to not accept jdbcUrl, ${DATABASE_URL}
원인: 로컬의 .env 파일은 깃에 올리지 않으므로, 서버는 ${DATABASE_URL}이라는 변수의 실제 값을 찾지 못해 발생한 문제.
해결: 클라우드타입 콘솔의 환경 변수(Environment Variables) 설정 메뉴에서 DATABASE_URL, DATABASE_USERNAME, DATABASE_PASSWORD를 직접 등록하여 해결.
학습: 배포 환경에서는 민감한 정보를 외부 환경 변수를 통해 주입(Injection)받는 것이 정석임을 이해함.

2.2 MariaDB 호환성 및 접속 주소

문제: 클라우드타입 서비스 목록에 MySQL이 없어 MariaDB를 선택하며 발생한 혼란.
원인: MySQL과 MariaDB는 뿌리가 같아 호환되지만, 접속 주소 형식을 맞추는 작업이 필요했음.
해결: 주소 형식을 jdbc:mysql://로 유지하여 기존 MySQL 드라이버가 MariaDB와 대화할 수 있도록 설정.

2.3 URL 문법 오타

문제: jdbc:mysql//... (콜론 누락) 에러 발생.
원인: 주소를 수동 입력하는 과정에서 프로토콜 구분자인 :를 누락하여 드라이버가 주소를 인식하지 못함.
해결: jdbc:mysql:// 형식으로 정확히 수정.
교훈: 인프라 설정 시 문자 하나가 시스템 전체의 실행 여부를 결정하므로 극도의 세밀함이 필요함.

2.4 하이버네이트 방언(Dialect) 에러

문제: java.sql.SQLSyntaxErrorException: Unknown column 'RESERVED' in 'WHERE'
원인: MySQL 드라이버가 MariaDB의 시스템 테이블 구조를 잘못 파악하여 발생한 문법 오류.
해결: 환경 변수에 SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT를 추가하고 값을 org.hibernate.dialect.MariaDBDialect로 명시하여 해결.
학습: JPA가 SQL을 번역할 때 사용하는 방언(Dialect)의 개념과 자동 판별이 실패할 경우의 수동 설정법을 익힘.

3. 결과 및 성과

다양한 네트워크 및 설정 에러를 해결한 끝에 다음과 같이 서버가 정상 구동됨을 확인하였다.

Tomcat started on port 8080 (http) with context path '/'
Started PaceApplication in 114.597 seconds

4. 향후 배포 고도화 계획

현재는 클라우드타입의 간단하게 UI 기반 배포를 사용했으나, 다음 단계로 CI/CD 파이프라인을 직접 구축할 계획이다.

GitHub Actions: 코드 푸시 시 자동 빌드 및 JAR 생성.
Docker Hub: 생성된 이미지를 가상화하여 보관.
AWS EC2 & Docker Compose: 서버에서 이미지를 내려받아 앱과 DB를 컨테이너로 묶어 실행.

5. 마치며

"삽질은 배신하지 않는다"는 말을 체감한 하루였습니다. 단순히 코드를 짜는 것만큼이나 내가 짠 코드가 어떤 환경에서 어떻게 돌아가는지 이해하는 것이 백엔드 개발자의 핵심 역량임을 깨달았습니다..

[Spring Boot] 페이징 기법에 대한 이해

shootingstar-1117 — Sun, 21 Dec 2025 00:33:03 +0900

1. 페이징 기법, 왜 필요할까?

페이징(Paging): 많은 양의 데이터를 한 번에 보여주는 대신, 정해진 갯수만큼의 페이지(Page) 단위로 나누어 보여주는 기법
"그냥 데이터가 많으면 전부 다 보내주고, 클라이언트(브라우저)에서 알아서 나눠서 보여주면 안되나?" 라고 생각할 수도 있습니다. 하지만 그렇게 하면, 대부분의 서비스에서 다음과 같은 재앙이 발생됩니다.
1. 데이터베이스가 비명을 지릅니다.
  - 예를 들어 데이터베이스에 'post' 라는 테이블에 1억 건의 레코드가 있다고 해봅시다. "SELECT * FROM post;" 같은 쿼리는 1억 개의 데이터를 모두 디스크에서 읽어와야 합니다. 이 작업 하나만으로도 데이터베이스는 엄청난 부하를 받게 되며, 데이터베이스 서버의 CPU와 메모리 자원을 크게 소진시킵니다.
  - 결과적으로 쿼리 하나 때문에, 다른 모든 API 요청들까지 느려지거나 응답 불가능 상태에 빠질 수 있게됩니다.
2. 네트워크가 막혀버립니다. (네트워크 과부화)
  - 서버가 1억 건의 게시글 데이터를 JSON 형태로 만들어 클라이언트에게 보내는 데는 엄청난 시간이 걸립니다. 그리고 수십 mb, 수백 mb에 달하는 데이터를 인터넷을 통해 전송하는 것은 매우매우!!! 비효율적입니다.
  - 결과적으로 사용자는 하얀 화면만 보면서 하염없이 기다려야 합니다.. 모바일 환경에서는 사용자의 소중한 데이터를 순식간에 전부 소진시켜 버릴 수도 있습니다.
3. 사용자의 기기(브라우저, 앱)가 멈춰버립니다. (클라이언트 성능 저하)
  - 어찌저찌 수백 mb의 데이터를 모두 받은 브라우저나 앱은 이제 그 데이터를 화면에 그려내야 합니다. 1억 개의 데이터에 대한 UI 컴포넌트를 한 번에 렌더링하려고 시도하면, 기기의 메모리를 초과하여 앱이 느려지거나, 멈추거나, 강제 종료될 수 있습니다.
  - 결과적으로 사용자 경험은 최악으로 치닫고, 다시는 그 서비스를 이용하지 않을 겁니다..

뿔난 사용자

2. Spring Boot 에서 페이징 기법 사용을 위한 유용한 도구들

위에서 얘기했던 문제들처럼 우리는 페이징 없이 대용량의 데이터를 처리하는 서비스를 만들기가 거의 불가능하다는 것을 확인했습니다! 그렇다면 복잡한 페이징 로직(LIMIT, OFFSET, COUNT, WHERE 쿼리 등)을 개발자가 매번 직접 구현해야 할까요?
다행히도 스프링의 JPA는 이 모든 과정을 거의 자동화해주는 강력한 "페이징 삼총사"를 제공합니다!
1. Pageable 인터페이스
  - "어떻게 데이터를 가져올지"에 대한 요청 규격(인터페이스)입니다.
  - 페이징을 요청하려면 "페이지 번호", "페이지 크기", "정렬 방식" 정보가 필요하다는 약속입니다.
  - 다음은 가장 기본적이고 널리 쓰이는 표준 방식 예시 코드입니다. (후술할 커스텀 validator 어노테이션 사용 방법도 있음)
```
@GetMapping("/api/posts")
public ApiResponse<...> getPosts(Pageable pageable){ // Pageable 객체를 직접 받음
  // 여기에서 서비스로 Pageable 객체를 넘겨서 로직 처리
  // pageable.getPageNumber(); -> 인덱스처럼 처음이 0인 0-based 페이지 번호
  // pageable.getPageSize(); -> 페이지의 크기 (기본값 20)
  // pageable.getSort(); -> 정렬 정보
  return ...;
}
```
  - 위 코드처럼 Pageable 인터페이스를 선언해두면, 스프링이 url의 쿼리 파라미터(?page=...&size=...&sort=...)를 보고 알아서 해당 규격에 맞는 객체(pageable)를 만들어줍니다.
2. PageRequest 객체
  - Pageable 이라는 '양식'에 구체적인 내용을 채워넣은 실제 요청서(클래스) 입니다.
  - 예를 들어 "3번 페이지의 데이터 10개를 최신순으로 정렬해서 주세요~" 라는 구체적인 요청 내용을 담고 있는 객체입니다. 주로 PageRequest.of(...) 메서드를 통해 생성하며, 서비스 계층에서 데이터베이스에 요청을 보내기 직전에 사용됩니다.
  - 다음은 실제 사용되는 객체 사용 예시입니다.
```
// 3번 페이지의 데이터 10개를 최신순으로 정렬
// PageRequest.of(페이지, 갯수(limit 절과 동일), 정렬 방식), 페이지는 0부터 시작
Pageable pageRequest = PageRequest.of(2, 10, Sort.by("createdAt").descending());
```
  - 위 코드처럼 작성하여 페이징을 할 조건을 지정하면 됩니다! 반환되는 타입은 PageRequest 이나, 보통 JpaRepository는 더 넓은 범위인, Pageable 인터페이스 타입을 원합니다.(다형성)
3. Page 인터페이스
  - 페이징 쿼리의 결과를 담는 그릇(인터페이스)입니다. 단순한 데이터 목록(List)이 절대 아닙니다!
  - 작성된 요청서(PageRequest)에 따라 데이터베이스의 조회를 마친 후, 실제 데이터와 함께 온갖 유용한 통계 정보들을 함께 담아주는 "종합 보고서" 역할을 합니다. 다음은 그 보고서의 내용물(주요 메서드)을 소개하겠습니다. 소개하려는 메서드 외에도 더욱 많습니다!
    1. getContent(): 이번 페이지에 해당하는 실제 데이터 목록 (List)
    2. getTotalElements(): 필터링된 전체 데이터의 총 갯수 (Integer)
    3. getTotalPages(): 전체 페이지 수 (Integer)
    4. isFirst(), isLast(): 첫 페이지인지, 마지막 페이지인지 여부 (true/false)
    5. getSize(), getNumber(), hasNext()... 등등이 있습니다..!!

3. 페이징 삼총사들을 어떻게 써먹을 것인가? (표준 방식)

위에서 Page, PageRequest, Pageable 라는 JPA에서 제공하는 페이징 삼총사들의 개념을 살펴보았습니다. 이제 이 삼총사가 실제 프로젝트의 각 계층(Controller, Service, Repository)에서 어떻게 유기적으로 협력하여 페이징 API를 완성하는지, '가게 리뷰 목록 조회' 기능을 예시로 단계별로 설명해 보겠습니다.

가장 먼저, 데이터베이스와 통신하는 Repository 계층에 페이징을 위한 '규격'을 정의합니다.

@Repository
public interface ReviewRepository extends JpaRepository<Review, Long> {
    // storeId(기본키)로 리뷰를 찾는데, Pageable 정보에 맞춰서 페이징 해달라고 약속
    Page<Review> findByStoreId(Long storeId, Pageable pageable);
}

다음으로, Service 계층에서 위의 Repository를 호출하여 비즈니스 로직을 수행합니다. 여기서는 스프링의 표준 방식을 최대한 활용하여, Pageable 객체를 그대로 전달하는 간결한 형태로 구현해 보겠습니다. 먼저 인터페이스를 통해 메서드를 정의합니다.

public interface ReviewService {
	// Pageable 객체를 그대로 받는 메서드를 인터페이스에서 정의
    Page<Review> getReviewByStoreId(Long storeId, Pageable pageable);
}

그 후, 해당 인터페이스의 구현체를 구현합니다. Service의 역할은 Controller로부터 페이징 요청을 받아 Repository에 그대로 '전달'하는 것입니다. 이 방식의 장점은 Service가 페이징의 세부 구현(페이지 크기, 정렬 방식 등)에 얽매이지 않고, 오직 비즈니스 로직에만 집중할 수 있다는 점입니다.

@Repository
@RequiredArgsConstructor
public class ReviewServiceImpl implements ReviewService {
    private final JPAQueryFactory queryFactory;
    private final ReviewRepository reviewRepository;
    private final StoreRepository storeRepository;
    
    @Transaction(readOnly = true)
    @Override
    public Page<Review> getReviewByStoreId(Long storeId, Pageable pageable) {
        // 가게 존재 여부 확인
        storeRepository.findById(storeId)
                .orElseThrow(() -> new StoreHandler(StoreErrorCode.NOT_FOUND));
        
        // Controller로부터 받은 Pageable 객체를 Repository에 그대로 전달
        return reviewRepository.findByStoreId(storeId, pageable);
    }
}

Service로부터 받은 Page<Review> 객체를 클라이언트가 보기 좋게끔 최종 DTO로 변환합니다. Page 객체는 단순한 리스트가 아니라, 페이징에 필요한 모든 정보를 담고 있습니다.
Converter에서는 이 객체의 실제 내용물(getContent())과 페이지의 통계 정보(getTotalPages(), getTotalElements(), isLast() ... 등)를 꺼내서, 설계한 최종 응답 DTO에 맞게 채워넣는 역할을 합니다!

public class ReviewConverter {
	public static ReviewResDTO.ReviewPreviewListDTO toReviewPreviewListDTO(Page<Review> reviewPage) {
    	List<ReviewResDTO.ReviewPreviewDTO> reviewList = reviewPage.getContent().
        	.stream().map(ReviewConverter::toReviewDTO).toList();
            
        return ReviewResDTO.ReviewPreviewListDTO.builder()
                 .isLast(reviewPage.isLast())
                 .isFirst(reviewPage.isFirst())
                 .totalPage(reviewPage.getTotalPages())
                 .totalElements(reviewPage.getTotalElements())
                 .listSize(reviewList.size())
                 .reviewList(reviewList)
                  .build();
    }
    
    public static toReviewDTO(Review review) {
    	return ...
    }
}

이제 클라이언트의 http 요청을 받는 Controller를 구현합니다. 파라미터에 Pageable을 선언하면, 스프링 MVC가 ?page=1&size=10&sort=createdAt,desc 와 같은 쿼리 파라미터를 자동으로 해석하여 Pageable 객체를 만들어줍니다.
Controller에서는 편리하게 만들어진 이 객체를 받아 Service에 전달하고, Service로부터 받은 Page 라는 "결과 보고서"를 Converter를 통해 최종 응답 형태로 가공해서 return 하면 됩니다!

@RestController
@RequiredArgsConstructor
@RequestMapping("/api")
public class ReviewController {
	private final ReviewQueryService reviewQueryService;
    private final ReviewConverter reviewConverter;
    
    @GetMapping("/stores/{storeId}/reviews")
    public ApiResponse<ReviewResDTO.ReviewPreviewListDTO> getStoreReviewList(
    	@PathVariable Long storeId,
        Pageable pageable // Pageable을 파라미터로 선언!!
    ) {
    	Page<Review> reviewPage = reviewQueryService.getStoreReviewList(storeId, pageable);
        
        return ApiResponse.onSuccess(
        	reviewConverter.toReviewPreviewListDTO(reviewPage);
        )
    }
}

4. 살짝 아쉬운 표준 방식..? (커스텀 어노테이션)

앞서 우리는 Pageable 인터페이스를 이용해 얼마나 간편하게 페이징 API를 구현할 수 있는지 확인했습니다. Repository에 메서드 한 줄만 추가하면 페이징 쿼리가 완성이 됐었습니다!
하지만 이 순정 옵션(?)을 실제 프로젝트에 그대로 적용시키기에는 몇 가지 아쉬운 점들이 존재합니다. 이번 챕터에서는 그 아쉬운 점들이 무엇인지 함께 살펴보겠습니다.
1. "0-based 인덱스" - 개발자는 편할 수 있어도, 클라이언트는 헷갈릴 수 있다.
  - 스프링의 JPA의 Pageable은 기본적으로 페이지 번호를 0부터 시작(0-based index)하는 것으로 인식합니다. 즉, 첫 번째 페이지를 조회하려면 클라이언트는 ?page=0 으로 요청을 보내야 합니다.
  - 직관적으로 생각했을 때 당연히 첫 번째 페이지는 page=1 이라고 생각합니다. 하지만 이 작은 차이인 0부터 시작하는 것은 페이지가 하나씩 밀리는 혼란스러운 버그의 원인이 될 수도 있습니다.
2. 유효하지 않은 입력값에 대한 방어 부재 (유효성 검증 관련)
  - 스프링의 기본 HandlerMethodArgumentResolver(인자 검사기 역할, 인터페이스)는 Pageable 파라미터의 유효성을 직접적으로 검증해주지 않습니다. 만약 클라이언트가 유효하지 않은 값을 보내면 어떻게 될까요? 그러면 클라이언트는 의미를 알 수 없는 500 Internal Server Error 응답을 받게 됩니다. 커스텀 예외 처리를 통해 어떤 것이 잘못인지 알려주는 것이 더 좋지 않을까요?!
  - 다음은 간단한 유효하지 않은 값에 대한 예시입니다.
    1. 음수 값 요청 (?page=-1)
    2. 숫자가 아닌 값 요청 (?page=abc)
3. 서비스 계층에서의 책임 증가와 코드 중복
```
public Page<Review> getStoreReviewList(Long storeId, int page) {
	// 클라이언트가 1부터 요청한다고 가정하고, 서비스에서 검증 및 변환
    if(page < 1 || page == null) {
    	throw new MyException(...);
    }
    
    // page - 1에서, 한 페이지 당 5개씩 
	Pageable pageRequest = PageRequest.of(page - 1, 5);
    
    // ...
}
```
  - 서비스 계층의 본질적인 책임은 비즈니스 로직 처리입니다. 하지만 위 코드는 웹 파라미터 변환이라는, 웹 계층에 더 가까운 책임을 떠안게 되었습니다. 그리고 페이징이 필요한 메서드마다 저 if문과 page - 1 변환 코드가 반복적으로 사용됩니다.
  - 나중에 페이지 정책이 바뀌면(페이지 당 데이터 갯수를 5개에서 10개로 바뀌다던가..), 이 모든 메서드를 찾아서 수정해야 합니다. 당연히 유지보수도 힘들겠죠?!
나만의 어노테이션으로 문제를 해결해보자!
```
@Target(ElementType.PARAMETER) // 메서드의 파라미터에만 붙일 수 있다는 조건
@Retention(RetentionPolicy.RUNTIME) // 런타임에도 해당 어노테이션의 정보를 유지함을 알림
public @interface CheckPage {
}
```
```
@Configuration // 해당 클래스가 Spring의 설정 파일임을 알림
public class WebConfig implements WebMvcConfigurer {
	@Override
    public void addArgumentResolvers(
        List<HandlerMethodArgumentResolver> resolvers
    ) {
        // 직접 만든 CheckPageArgumentResolver를 Spring MVC의 Argument Resolver 목록에 등록
        resolvers.add(new CheckPageArgumentResolver());
    }
}
```
이제 실제로 테스트를 해보겠습니다. 테스트 요청 및 응답 확인은 기존에 제가 사용하던 Swaager UI로 확인을 해보겠습니다!
저는 테스트 데이터를 MySQL 데이터베이스에 미리 삽입을 해놓았습니다!
가게의 id 및 1부터 시작하는 페이지 번호를 입력 후 요청을 아래 사진과 같이 날리게 되면..!!

다음과 같이 결과가 나오는 것을 확인할 수 있습니다! 상세 응답 데이터는 코드 블럭으로 넣어두겠습니다.

{
  "isSuccess": true,
  "code": "REVIEW200_1",
  "message": "리뷰가 성공적으로 조회되었습니다.",
  "result": {
    "reviewList": [
      {
        "ownerNickname": "슈팅스타",
        "rating": 4.5,
        "body": "정말 맛있어요! 첫 번째 리뷰입니다.",
        "createdAt": "2025-12-20T14:48:27"
      },
      {
        "ownerNickname": "슈팅스타",
        "rating": 5,
        "body": "분위기가 너무 좋아요. 강추!",
        "createdAt": "2025-12-20T14:48:27"
      },
      {
        "ownerNickname": "슈팅스타",
        "rating": 3.5,
        "body": "가격이 조금 비싸지만 맛은 있네요.",
        "createdAt": "2025-12-20T14:48:27"
      },
      {
        "ownerNickname": "슈팅스타",
        "rating": 4,
        "body": "직원분들이 친절해서 좋았어요.",
        "createdAt": "2025-12-20T14:48:27"
      },
      {
        "ownerNickname": "슈팅스타",
        "rating": 2.5,
        "body": "기대보다는 별로였어요.",
        "createdAt": "2025-12-20T14:48:27"
      }
    ],
    "listSize": 5,
    "totalPage": 4,
    "totalElements": 20,
    "isFirst": true,
    "isLast": false
  }
}

결과는 대성공! 총 20개의 데이터 중 5개만 가져온 것을 확인할 수 있으며, 정상적으로 페이지 번호 1번이 첫 번째 페이지로 인식되고 있는 것을 확인할 수 있습니다.

5. 마치며...

위에서 진행했던 내용들을 요약하자면 다음과 같습니다.
- Q. 페이징 처리를 왜 하는가?
- A. 안하면 많은 데이터를 한꺼번에 요청으로 보낼 때, 별의별 큰 문제들이 생기기 때문입니다.
- Q. Spring Boot에서 페이징 기법을 무엇으로 구현하면 되겠는가?
- A. SQL 구문으로 직접적으로 페이징 처리를 할 수 있지만 Spring Boot의 JPA는 Pageable, PageRequest, Page 와 같은 도구가 있어, 더욱 간단하게 구현이 가능합니다. 하지만 실제로 SQL 구문으로 직접 OFFSET 페이징이나, CURSOR 페이징을 구현해보는 것도 좋을 것 같습니다! 참고로, 페이징 객체들로 구현한 방식은 내부적으로 OFFSET 페이징 방식으로 동작한다는 것을 알아두셨으면 좋겠습니다!
- Q. 왜 굳이 복잡하게 커스텀 어노테이션을 직접 만들어서 사용하는가?
- A. 페이지 번호의 유효성 검증 및 page -1 로직 같은 것을 Service 계층에서 처리하는 것은 코드의 중복이 많아져 비효율적이고, 유지보수성이 저하됩니다. 그래서 중앙화된 관리를 위해 어노테이션 방식으로 진행을 했습니다.

부족하고, 긴 글이지만 읽어주셔서 감사합니다! 피드백은 언제나 환영입니다! ☺️

[Django] 직렬화 / 역직렬화(serialization / deserialization)의 이해

shootingstar-1117 — Sat, 9 Aug 2025 01:15:14 +0900

1. 직렬화와 역직렬화, 왜 필요할까?

직렬화(Serialization): Django 서버는 파이썬 객체(object)로써 데이터를 이해합니다. 하지만 클라이언트(웹, 모바일 앱 등)는 파이썬 객체를 알지 못합니다. 그래서 클라이언트는 보통 json이나 xml 형태의 데이터를 사용합니다. 여기서 직렬화는 파이썬 객체를 json, xml 같이 클라이언트가 이해할 수 있는 데이터 형태로 변환하는 과정을 뜻합니다. 보통 서버에서 클라이언트로 데이터를 보낼 때 해당 과정을 거칩니다.
역직렬화(Deserialization): 직렬화의 반대입니다. 예를 들어서, 클라이언트가 서버에게 "내가 보낸 데이터로 새로운 게시물을 만들어줘!" 라고 요청할 때, json 데이터를 보냅니다. 그럼 Django 서버는 해당 json 데이터를 그대로 이해할 수 없으므로, 서버에서 알아들을 수 있는 파이썬 객체로 다시 번역하는 과정이 필요합니다. 여기서 역직렬화는 json, xml 같은 데이터를 파이썬 객체로써 Django 서버가 이해할 수 있는 데이터로 변환하는 과정을 뜻합니다. 보통 클라이언트가 서버로부터 데이터를 보낼 때(요청할 때) 해당 과정을 거칩니다.

2. 직렬화를 통해 파이썬 객체를 json으로 변환하기

직렬화는 보통 데이터베이스에 이미 존재하는 데이터를 클라이언트에게 보여줄 때 사용된다고 앞서 말씀드렸습니다. http 메서드로 따지면 GET 요청을 처리하는 경우입니다.
예를 들어, 다음과 같이 사용자가 했던 질문에 관한 모델 Question과 해당 모델을 역/직렬화 하는 QuestionSerializer가 있다고 해봅시다.

 class Question(models.Model):
    question_text = models.CharField(max_length=200) # 질문에 대한 텍스트 필드
    pub_date = models.DateTimeField('date published') # 해당 질문이 생성된 날짜 필드
    owner = models.ForeignKey(User, related_name='questions', on_delete=models.CASCADE) # 질문에 대한 사용자 필드

각 클래스 변수가 의미하는 바는 데이터베이스의 필드와 같다고 생각하시면 됩니다.
owner 필드는 ForeignKey, 즉 외래키입니다. Django는 기본적으로 유저를 관리하기 위해django.contrib.auth.models 내부에 User 라는 테이블을 가지고 있습니다. settings.py에서 유저를 관리하는 테이블을 따로 지정할 수 있지만, 저는 기본 제공되는 유저 테이블을 사용해 보았습니다.

class QuestionSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source="owner.username")
    
    class Meta:
        model = Question
        fields = ["id", "question_text", "pub_date", "owner"]

serializers.ReadOnlyField는 클라이언트 측에서 읽기만 가능하게 접근을 제한하는 필드를 나타냅니다.
source="owner.username" 인수는 owner 필드를 직렬화 할건데, 실제 직렬화 데이터를 owner 안에 있는 username 속성으로 지정하겠다. 라는 의미입니다.
클래스 내부에 Meta 클래스에서 model은 어떤 모델을 역/직렬화 할 것인지를 나타내고, fields는 데이터베이스의 어떤 필드를 역/직렬화 할 것인지 설정합니다.

2-1. Question 객체를 직렬화하는 과정의 흐름 살펴보기

Primary Key(이하 pk) 값이 1인 Question 객체를 직렬화하는 과정을 Django shell 환경에서 살펴보겠습니다.

>>> from polls.models import Question
>>> from polls_api.serializers import QuestionSerializer

우선, 임의로 만든 앱들에서 Question 모델과 QuestionSerializer를 import 해옵니다.

>>> question = Question.objects.get(pk=14)
>>> serializer = QuestionSerializer(instance=question)
>>> serializer.data
{'id': 14, 'question_text': 'postman에서 보는 제목', 'pub_date': '2025-07-29T02:06:36.926054Z', 'owner': 'user1'}

question 변수에 pk 값이 14인 Question 객체를 할당합니다.
QuestionSerializer 클래스의 instance 인수로 Question 객체를 넘겨 serializer 변수에 할당합니다.
instance 인수에 모델 객체를 설정하면 기존의 데이터베이스에서 그 객체를 가져와 직렬화를 수행합니다.
serializer의 data 값을 출력하면, Question의 각 필드 값이 나오게 됩니다. ({'id': 14, 'question_text': 'postman에서 보는 제목', 'pub_date': '2025-07-29T02:06:36.926054Z', 'owner': 'user1'})

여기서 중요한 포인트!

직렬화를 할 때는 반드시 "instance" 키워드 인자를 사용하여 변환할 객체를 지정해줘야 합니다.
serializer.data의 결과물은 아직 json 문자열이 아닙니다. 파이썬의 딕셔너리('dict') 형태입니다. 해당 파이썬 딕셔너리를 클라이언트에게 보내기 위해서는 JSONRenderer를 통해 최종적으로 클라이언트가 이해할 수 있는 json 문자열로 변환하여 응답해야 합니다.

2-2. Postman에서 응답 확인해보기

GET 요청을 통해 해당 값을 조회해보겠습니다. api 요청 경로는 http://127.0.0.1:8000/rest/question/14/ 으로 설정해두었습니다.

GET 요청을 보내서 응답 받은 JSON 형태의 데이터

해당 과정을 요약하자면 클라이언트 측에서 특정 데이터를 요청, 조회할 때 Django의 파이썬 객체를 직렬화하여 클라이언트가 확인할 수 있는 형태로 데이터를 가공하여 응답을 보내줍니다.

3. 역직렬화를 통해 json을 파이썬 객체로 변환하기

역직렬화는 클라이언트로부터 받은 데이터로 새로운 객체를 만들거나(POST), 기존 객체를 수정할 때(PUT, PATCH) 사용됩니다. 이 과정은 직렬화보다 조금 더 복잡하고 중요합니다.
클라이언트가 다음과 같은 json 데이터를 보내서 새로운 질문을 생성한다고 해봅시다.

POST 요청을 보내서 body의 내용을 Question 테이블에 저장(csrf token 값과 session id 값은 보안상 임의 값으로 대체)

성공적으로 질문이 등록되었습니다. Django shell에서 실제로 데이터베이스에 해당 데이터가 잘 저장됐는지와, 구체적으로 역직렬화 과정이 어떻게 이루어지는지 살펴보겠습니다.

>>> question = Question.objects.get(pk=10002)
>>> question
<Question: new!!! 제목: 내일의 날씨는 어떨까?, 날짜: 2025-08-08 12:41:16.083128+00:00>

서버에서 이 데이터를 처리하는 흐름은 다음과 같습니다.

# views.py (간략화된 예시)
@api_view(["POST"])
def question_create(request):
    if(request.method == "POST"):
        # 1. 클라이언트가 보낸 JSON 데이터를 파이썬 dict로 변환 (DRF가 자동으로 처리)
        request_data = request.data
        # 2. 'data' 인자로 데이터를 넘겨 Serializer를 초기화한다.
        serializer = QuestionSerializer(data=request_data)

        # 3. 유효성 검사! (가장 중요한 단계)
        if serializer.is_valid(raise_exception=True):
        # 4. 유효성 검사를 통과한 데이터로 객체를 저장한다.
            serializer.save() # 이 안에서 create() 또는 update()가 호출됨
            return Response(serializer.data, status=status.HTTP_201_CREATED)

클라이언트 측에서 보낸 요청이 request 매개변수에 할당됩니다. 그리고 request.data에 실제 요청 본문(body)이 파이썬 딕셔너리 형태로 담겨있습니다.
역직렬화를 하기 위해 QuestionSerializer 클래스의 data 인수로 request.data 값을 넘겨서 serializer를 초기화(할당) 합니다. *여기서 request.data의 값은 QuestionSerializer의 필드 형식에 맞아야 합니다.*
is_valid()를 통해 유효성 검사를 진행합니다. request.data의 값이 실제 models.py에 Question 테이블의 필드의 조건(데이터 타입, 필드 옵션, 제약 조건 등)을 충족하는지 검사합니다. 모든 검사를 통과하면, True를 반환하고, 검증 과정에서 정제된 데이터를 serializer.validated_data(파이썬 객체) 라는 속성에 저장합니다.
유효성 검사를 통과한 데이터는 serializer.save() 메서드를 통해, 새로 만들거나(create) 수정(update)합니다. 보통 Serializer 인수에 data만 들어가는 경우는 create되고, instance와 data 인수 값이 넘겨지는 경우가 update 입니다.
최종적으로 클라이언트의 응답에 최종 결과물인 serializer.data와 정상적으로 등록 처리되었다는 응답 코드인 201번을 반환합니다.

마치며..

직렬화(instance=...)는 데이터베이스의 객체를 외부(클라이언트)로 보여주기 위한 "출력" 과정입니다.
역직렬화(data=..., instance=...)는 클라이언트로부터 받은 데이터를 검증하고 데이터베이스에 저장하기 위한 "입력" 과정입니다.
is_valid() 메서드는 데이터의 안정성을 보장하는 방화벽 역할을 합니다.
Serializer의 save()는 상황에 맞게 create()나 update()를 호출하는 지휘자 역할을 합니다.

긴 글 읽어주셔서 감사합니다.