[스프링 부트와 JPA 활용2] 1. API 개발 기본

회원 등록 API

@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;
        }
    }
}

@Entity
@Getter @Setter
public class Member {

    @Id @GeneratedValue
    @Column(name = "member_id")
    private Long id;

    private String name;

    @Embedded
    private Address address;

    @JsonIgnore
    @OneToMany(mappedBy = "member")
    private List<Order> orders = new ArrayList<>();

}

@RestController 는 @Controller와 @ResponseBody를 합친 것으로ㅡ 스프링이 제공해준다.

@RequestBody 는 JSON으로 온 데이터를 엔티티로 바꿔준다.

• 만약 Member 엔티티의 필드 name의 필드명을 username2로 수정한다면?
  • 이전에는 동작했던 API에서 오류가 발생한다.
  • 엔티티를 수정했더니 API 스펙 자체가 변하는 문제가 발생하는 것이다.
• 엔티티는 굉장히 많은 곳에서 사용하기 때문에 변경가능성이 높다.
• 따라서 API 스펙을 위한 별도의 DTO(Data Transfer Object)를 만들어야 한다 !
• 위 v1 코드처럼 엔티티를 외부에서 오는 JSON에 바인딩 받는 데 쓰면 안된다 !

@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;
        }
    }

v2 - 요청값으로 Member 엔티티 대신에 별도의 DTO를 받는다.

회원 수정 API

@PutMapping("/api/v2/members/update/{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;
    }

• memberService의 메서드인 update()가 member 엔티티를 반환하도록 하는 것보다는, 커맨드와 쿼리를 분리하기 위해 id만 반환해주거나 아무 것도 반환하지 않도록 개발할 때 유지보수성이 증대한다.

회원 조회 API

조회 V1: 응답값으로 엔티티를 직접 외부에 노출

 @GetMapping("/api/v1/members")
    public List<Member> getMemberV1() {
        return memberService.findMembers();
    }

• 문제점

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

• 결론

  • API 응답 스펙에 맞추어 별도의 DTO를 반환한다.

회원조회 V2: 응답 값으로 엔티티가 아닌 별도의 DTO 사용

@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;
    }

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