[TIL] REST API - DTO의 중요성

---

REST API에서 DTO(Data Transfer Object)를 사용하는 이유와 작성 방법

REST API 개발 시 엔티티(Entity)를 그대로 노출하는 경우, 프론트엔드 개발자와의 협업에서 문제가 발생할 수 있습니다. 특히, 엔티티의 필드명이 변경되거나 데이터 형식이 변경될 경우, API를 사용하는 프론트엔드 코드도 함께 수정해야 하기 때문에 많은 비용과 혼란을 초래합니다. 이를 해결하기 위해 DTO(Data Transfer Object)를 사용하는 것이 중요합니다.

---

1. 엔티티(Entity)를 그대로 노출하면 안 되는 이유

1.1. API 안정성

• 엔티티의 필드명이 예를 들어 createdAt에서 createDate로 변경되면, 프론트엔드 코드는 이를 반영하기 위해 반드시 수정되어야 합니다.

• API 양식이 자주 변경되면 프론트엔드 개발자는 지속적인 코드 수정을 강요받아 업무 효율이 떨어집니다.

1.2. 보안 문제

• 엔티티에는 노출되면 안 되는 민감한 정보(예: 비밀번호, 내부 ID 등)가 포함될 수 있습니다.
• 엔티티를 그대로 반환하면 불필요한 데이터가 API를 통해 노출될 가능성이 있습니다.

1.3. 유연성 부족

• 프론트엔드에서 필요한 데이터 형식과 엔티티의 데이터 형식이 항상 일치하지 않을 수 있습니다.
• DTO를 사용하면 프론트엔드 요구사항에 맞는 데이터를 유연하게 조정할 수 있습니다.

---

2. DTO(Data Transfer Object)란?

DTO(Data Transfer Object)는 데이터 전송을 위해 정의된 객체입니다. REST API에서는 엔티티 대신 DTO를 사용하여 데이터를 반환함으로써 API 형식의 일관성과 안정성을 유지할 수 있습니다.

2.1. DTO의 장점

API의 안정성 보장: 엔티티 구조가 변경되어도 DTO 구조는 유지될 수 있어 프론트엔드에 영향을 최소화합니다.

보안 강화: 민감한 데이터를 포함하지 않고, 필요한 데이터만 반환할 수 있습니다.

프론트엔드 요구사항 반영: 프론트엔드에서 필요한 데이터 형식이나 추가 계산된 데이터를 포함할 수 있습니다.

---

3. 다건조회와 단건조회에서 DTO 사용 방법

REST API는 다건조회(리스트)와 단건조회(상세)에서 서로 다른 데이터를 반환할 수 있습니다. 이 경우에도 DTO를 활용하면 API를 효과적으로 설계할 수 있습니다.

3.1. 다건조회용 DTO 예시

다건조회는 보통 리스트 형태로 반환됩니다. 필요한 핵심 데이터만 포함하는 DTO를 설계해야 합니다.

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class PostSummaryDto {
    private Long id;
    private String title;
    private String summary;
    private LocalDateTime createdAt;
}

• 설명: 리스트 조회에서는 Post 엔티티의 모든 데이터를 반환할 필요가 없습니다. 예를 들어, 게시글 본문(content)은 제외하고, 제목, 요약, 생성일 등의 핵심 정보만 반환합니다.

@RestController
@RequestMapping("/api/v1/posts")
public class ApiV1PostController {

    private final PostService postService;

    @GetMapping
    public List<PostSummaryDto> getAllPosts() {
        return postService.getAllPosts()
                .stream()
                .map(post -> new PostSummaryDto(post.getId(), post.getTitle(), post.getSummary(), post.getCreatedAt()))
                .collect(Collectors.toList());
    }
}

3.2. 단건조회용 DTO 예시

단건조회는 상세 데이터를 반환하므로, 더 많은 정보를 포함할 수 있습니다.

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class PostDetailDto {
    private Long id;
    private String title;
    private String content;
    private String authorName;
    private LocalDateTime createdAt;
    private LocalDateTime modifiedAt;
}

• 설명: 단건조회에서는 게시글의 본문, 작성자 정보 등 더 상세한 데이터를 포함할 수 있습니다.

@RestController
@RequestMapping("/api/v1/posts")
public class ApiV1PostController {

    private final PostService postService;

    @GetMapping("/{id}")
    public PostDetailDto getPostById(@PathVariable Long id) {
        Post post = postService.getPostById(id);
        return new PostDetailDto(
            post.getId(),
            post.getTitle(),
            post.getContent(),
            post.getAuthor().getName(),
            post.getCreatedAt(),
            post.getModifiedAt()
        );
    }
}

---

4. DTO 작성 시 주의사항

4.1. 필요한 데이터만 포함

DTO는 데이터 전송을 위한 객체이므로, 클라이언트가 필요로 하는 데이터만 포함해야 합니다.

4.2. 불변성 유지

DTO는 데이터 전달이 목적이므로 가변성을 최소화해야 합니다. 가능하면 final 필드를 사용하거나, 생성자로 초기화하여 불변성을 유지합니다.

4.3. 엔티티와 분리

DTO는 엔티티와 완전히 분리되어야 합니다. 엔티티의 변경이 DTO에 영향을 미치지 않도록 설계합니다.

---

5. 실무에서 자주 사용하는 방법

5.1. ModelMapper 또는 MapStruct 사용

• DTO와 엔티티 간 매핑을 자동화하기 위해 ModelMapper 또는 MapStruct 라이브러리를 사용할 수 있습니다.

@Bean
public ModelMapper modelMapper() {
    return new ModelMapper();
}

PostSummaryDto postSummaryDto = modelMapper.map(post, PostSummaryDto.class);

5.2. 정적 팩토리 메서드 활용

• DTO 클래스 내부에 정적 메서드를 정의하여 엔티티를 DTO로 변환합니다.

public static PostSummaryDto fromEntity(Post post) {
    return new PostSummaryDto(
        post.getId(),
        post.getTitle(),
        post.getSummary(),
        post.getCreatedAt()
    );
}

---

정리

즉, 잘 설계된 REST API는 DTO를 사용하여 다건/단건 조회를 효율적으로 처리합니다.

• REST API는 클라이언트와 서버가 데이터를 주고받는 통신 방식.
• DTO는 REST API에서 데이터를 전달하기 위한 포맷(객체).
• 다건/단건 조회는 REST API의 요청 유형.

1. REST API

정의: 서버와 클라이언트 간의 통신을 효율적으로 처리하는 아키텍처 스타일.
역할: 클라이언트가 리소스를 요청(GET, POST 등)하고 서버가 이에 응답(JSON 등)을 반환하는 방식을 설계.
목표: 일관된 인터페이스와 확장성을 가지는 API 설계.

2. DTO (Data Transfer Object)

정의: 데이터 전송에 특화된 객체 설계.
역할: REST API가 데이터(엔티티)를 클라이언트에 반환하거나 클라이언트로부터 데이터를 받을 때, 불필요한 정보 노출을 방지하고 데이터 구조를 맞추기 위해 사용.
목표: 엔티티(Entity)와 분리된 데이터 전송 객체를 만들어 API 안정성을 높이고, 클라이언트와 서버 간의 데이터를 효율적으로 주고받음.

3. 다건 조회 / 단건 조회

정의: REST API에서 데이터를 반환하는 요청 유형.
역할:

• 다건 조회: 여러 리소스를 반환 (예: /users → 사용자 목록 반환).
• 단건 조회: 특정 리소스를 반환 (예: /users/123 → 특정 사용자 정보 반환).

목표: 요청의 유형에 따라 필요한 데이터를 클라이언트에 제공.

---

참고 문헌

[Spring Boot] 레이어드 아키텍처, REST API
dto(Data Transfer Object)를 사용하는 이유

---