[Spring Boot + JPA] API 개발과 성능 최적화 - 1. API 개발 기본

📌 회원 등록 API

엔티티 자체를 request 받는 saveMemberV1 코드

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;

    @PostMapping("/api/v1/members")
    public CreateMemberResponse saveMemberV1(@RequestBody @Valid Member member) {
        Long id = memberService.join(member);
        return new CreateMemberResponse(id);
    }
    
    @Data
    static class CreateMemberResponse {
        private Long id;

        public CreateMemberResponse(Long id) {
            this.id = id;
        }
    }
}

 

• @RestController : @Controller + @ResponseBody
• @Data : Lombok의 @toString + @getter + @setter + @RequiredArgsConstructor + @EqualsAndHashCode
  

saveMemberV1 메서드는 요청 값으로 Member 엔티티를 직접 받는다.

 

@Entity
@Getter @Setter
public class Member {
	// ...
	@NotEmpty
	private String name;
	//...
}

Member 엔티티를 직접 받을 경우, request 검증 로직이 필요하다면 엔티티 자체를 수정해야 한다는 치명적인 문제가 있다.
(여기서는 name을 필수 값으로 받아야 한다고 가정하고 @NotEmpty 추가하였음)

 

 

saveMemberV1 코드의 문제점

• 엔티티에 프레젠테이션 계층을 위한 로직이 추가된다.
• 엔티티에 API 검증을 위한 로직이 들어간다. (@NotEmpty 등등)
• 실무에서는 회원 엔티티를 위한 API가 다양하게 만들어지는데, 한 엔티티에 각각의 API를 위한 모든 요청 요구사항을 담기는 어렵다.
• 엔티티가 변경되면 API 스펙이 변한다.

따라서 saveMemberV1 코드는 API 요청 스펙에 맞추어 별도의 DTO를 파라미터로 받도록 수정해야 한다.

 

엔티티와 DTO를 분리하여 DTO가 request 받는 saveMemberV2 코드

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;
    
    @PostMapping("/api/v2/members")
    public CreateMemberResponse saveMemberV2(@RequestBody @Valid CreateMemberRequest request) {
        Member member = new Member();
        member.setName(request.getName());
        Long id = memberService.join(member);
        return new CreateMemberResponse(id);
    }
    
    @Data
    static class CreateMemberRequest {
        private String name;
    }
    
    @Data
    static class CreateMemberResponse {
        private Long id;

        public CreateMemberResponse(Long id) {
            this.id = id;
        }
    }
}

CreateMemberRequest와 CreateMemberResponse DTO를 생성하여 request와 response를 DTO로 주고받도록 변경하였다.
(요청과 응답 항목 가정 후 DTO를 작성. 예제 소스이기에 내부 클래스로 작성하였음)

 

엔티티와 DTO를 분리 시 장점

• 엔티티와 API스택을 명확하게 분리하기 위해  별도의 DTO를 사용하여 엔티티를 변경해도 API 스택이 전혀 바뀌지 않는다.
• API의 요청과 응답 항목이 무엇인지 정리가 된다.
• API 스택에 맞게 별도의 validation 체크가 가능하다. → 유지보수에 용이
  (엔티티 자체에 @NotEmpty를 넣을 경우 API마다 validation 체크가 다를 경우 사이드 임팩트 발생)

 

📌 회원 수정 API

MemberApiController에 updateMemberV2 메서드 및 UPDATE 요청, 응답 DTO 추가

    @PutMapping("/api/v2/members/{id}")
    public UpdateMemberResponse updateMemberV2(
            @PathVariable("id") Long id,
            @RequestBody @Valid UpdateMemberRequest request) {

        memberService.update(id, request.getName());
        Member findMember = memberService.findOne(id);

        return new UpdateMemberResponse(findMember.getId(), findMember.getName());
    }
    
    @Data
    static class UpdateMemberRequest {
        private String name;
    }
    @Data
    @AllArgsConstructor
    static class UpdateMemberResponse {
        private Long id;
        private String name;
    }

 

• @PutMapping : 멱등성을 보장하여 전체 UPDATE 요청에 자주 사용.
   HTTP에서의 멱등성  : HTTP에서 동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이 같은 효과를 지닌다.
                                            (동일한 요청을 보낼 시 한 번만 수행)
• 회원 수정 API updateMemberV2 은 회원 정보를 부분 업데이트 한다. 여기서 PUT 방식을 사용했는데, PUT은 전체 업데이트를 할 때 사용하는 것이 맞다. 부분 업데이트를 하려면 PATCH를 사용하거나 POST를 사용하는 것이 REST 스타일에 맞다.

MemberService에 update 메서드 추가

@Transactional
public void update(Long id, String name) {
   Member member= memberRepository.findOne(id);
   member.setName(name);
}

MemberService의 update 메서드에서 Member를 그대로 반환하지 않은 이유는 커맨드 쿼리를 분리했기 때문이다.

 

Command Query Separation 원칙 : 명령(데이터 변경)과 조회를 분리한다.

• Query
  결괏값을 반환하고, 시스템의 상태를 변화시키지 않는다. 따라서 부작용에서 자유롭다.(free of side effects)
• Command
  결과를 반환하지 않고, 대신 시스템의 상태를 변화시킨다.

조회와 수정 즉, 관심사를 명백하게 분리하여 코드의 유지 보수성을 높일 수 있다. 하지만 Controller에서 응답 값을 위한 조회를 한번 더 필요하기 때문에 상황에 따라 트레이드오프가 있다.

 

 

📌 회원 조회 API

List에 엔티티를 직접 넣어 Array형태로 response 하는 memberV1 코드

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;
    //...    
    
    @GetMapping("/api/v1/members")
    public List<Member> memberV1() {
        return memberService.findMembers();
    }
    
    //...
}

memberV1 API 테스트

memberV1 코드 API 테스트 문제점

• 기본적으로 엔티티의 모든 값이 노출된다.
• Object가 아닌 Array를 반환하기 때문에 추가 요구사항으로 조회 건수의 총 count를 넣어달라는 요청사항이 있으면 json 스펙이 깨지게 된다. Object형태로 반환되게 설계하여 추가 요구사항이 있을 시 데이터만 넣어줄 수 있도록 수정해야 한다.

{
    "count": 4
    "data": [] // Array가 이러한 형태로 들어가게 수정해야한다.
}

 

memberV1 코드의 문제점

• 엔티티에 프레젠테이션 계층을 위한 로직이 추가된다.
• 응답 스펙을 맞추기 위해 로직이 추가되야 한다. (응답 시 제외해야 할 필드에 @JsonIgnore 설정, 별도의 뷰 로직 등등)
• 실무에서는 같은 엔티티에 대해 API가 용도에 따라 다양하게 만들어지는데, 한 엔티티에 각각의 API를 위한 프레젠테이션 응답 로직을 담기는 어렵다.
• 엔티티가 변경되면 API 스펙이 변한다.
• 추가로 컬렉션을 직접 반환하면 향후 API 스펙을 변경하기 어렵다.(별도의 Result 클래스 생성으로 해결)

따라서 memberV1 코드는 API 응답 스펙에 맞추어 별도의 DTO를 반환하도록 수정해야 한다.

 

참고: 엔티티를 외부에 노출하지 마세요!
실무에서는 member 엔티티의 데이터가 필요한 API가 계속 증가하게 된다. 어떤 API는 name 필드가 필요하지만, 어떤 API는 name 필드가 필요 없을 수 있다. 결론적으로 엔티티 대신에 API 스펙에 맞는 별도의 DTO를 노출해야 한다.

 

MemberDTO를 response 하는 memberV2 코드

@RestController
@RequiredArgsConstructor
public class MemberApiController {
    private final MemberService memberService;
    //...
    @GetMapping("/api/v2/members")
    public Result memberV2() {
        List<Member> findMembers = memberService.findMembers();
        List<MemberDTO> collect = findMembers.stream()
                .map(m -> new MemberDTO(m.getName()))
                .collect(Collectors.toList());
        return new Result(collect);
    }
    
    @Data
    @AllArgsConstructor
    static class Result<T> {
        private T data;
    }

    @Data
    @AllArgsConstructor
    static class MemberDTO {
        private String name;
    }
}

 

Result라는 타입을 반환할 수 있는 클래스와 MemberDTO 클래스를 만들어 response를 DTO로 반환하도록 변경하였다.

 

memberV2 API 테스트

• 엔티티를 DTO로 변환해서 반환한다.
• 엔티티가 변해도 API 스펙이 변경되지 않는다.
• 추가로 Result 클래스로 컬렉션을 감싸서 향후 필요한 필드를 추가할 수 있다.

 

 

 

---

해당 글은 인프런의 [실전! 스프링 부트와 JPA 활용 2 - API 개발과 성능 최적화] 강의를 정리한 내용입니다.

실전! 스프링 부트와 JPA 활용2 - API 개발과 성능 최적화 - 인프런 | 강의