API 개발 기본

회원 등록 API

package jpabook.jpashop.api;

import jakarta.validation.Valid;
import jpabook.jpashop.domain.Member;
import jpabook.jpashop.service.MemberService;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.stream.Collectors;

@RestController //@Controller와 @Responsebody를 합친 것 / 데이터 자체를 바로 JSON이나 XML로 보낼 때 사용
@RequiredArgsConstructor
public class MemberApiController {

    private final MemberService memberService;

    /**
     * 조회 V1: 응답 값으로 엔티티를 직접 외부에 노출한다.
     * 문제점
     * - 엔티티에 프레젠테이션 계층을 위한 로직이 추가된다.
     * - 기본적으로 엔티티의 모든 값이 노출된다.
     * - 응답 스펙을 맞추기 위해 로직이 추가된다. (@JsonIgnore, 별도의 뷰 로직 등등)
     * - 실무에서는 같은 엔티티에 대해 API가 용도에 따라 다양하게 만들어지는데, 한 엔티티에 각각의
     API를 위한 프레젠테이션 응답 로직을 담기는 어렵다.
     * - 엔티티가 변경되면 API 스펙이 변한다.
     * - 추가로 컬렉션을 직접 반환하면 항후 API 스펙을 변경하기 어렵다.(별도의 Result 클래스
     생성으로 해결)
     * 결론
     * - API 응답 스펙에 맞추어 별도의 DTO를 반환한다.
     */
    //조회 V1: 안 좋은 버전, 모든 엔티티가 노출, @JsonIgnore -> 이건 정말 최악, api가 이거하나인가! 화면에 종속적이지 마라!
    @GetMapping("/api/v1/members") //회원을 조회하는 api / orders도 같이 호출되는데 그걸 방지하기 위해 @JsonIgnore 추가
    public List<Member> membersV1() { //그렇지만 다른 api 만들 때 멘붕 / 회원과 관련된 조회 api가 하나가 아닐거임 / 어디는 orders가 필요없고 어디는 address가 필요없고 등등
        return memberService.findMembers(); //또한 엔티티를 직접 노출하면 문제가 큼. 예를들어 협업시 name 을 username으로 바꾸면 api 스펙 자체가 바뀌어버림
    }

    /**
     * 조회 V2: 응답 값으로 엔티티가 아닌 별도의 DTO를 반환한다.
     */
    @GetMapping("/api/v2/members") //위의 문제를 해결하기 위한 v2 api
    public Result memberV2() { //응답값자체를 v2라 하고
        List<Member> findMembers = memberService.findMembers();
        List<MemberDto> collect = findMembers.stream()
                .map(m -> new MemberDto(m.getName())) //멤버 엔티티에서 이름을 꺼내와서 Dto에 넣고 map을 이용해 바꿔치기
                .collect(Collectors.toList());

        return new Result(collect); //아래의 result로 반환 / 이런식으로 감싸줘야함
    }                               //왜냐하면 리스트가 바로 나가면 JSON 배열 타입으로 나가버리기 때문에 유연성이 확 떨어짐

    @Data
    @AllArgsConstructor
    static class Result<T> {
        private T data; //데이터 생성
    }

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

    /**
     * 등록 V1: 요청 값으로 Member 엔티티를 직접 받는다.
     * 문제점
     * - 엔티티에 프레젠테이션 계층을 위한 로직이 추가된다.
     * - 엔티티에 API 검증을 위한 로직이 들어간다. (@NotEmpty 등등)
     * - 실무에서는 회원 엔티티를 위한 API가 다양하게 만들어지는데, 한 엔티티에 각각의 API를
     위한 모든 요청 요구사항을 담기는 어렵다.
     * - 엔티티가 변경되면 API 스펙이 변한다.
     * 결론
     * - API 요청 스펙에 맞추어 별도의 DTO를 파라미터로 받는다.
     */
    @PostMapping("/api/v1/members") //회원을 등록하는 api / 등록이니까 @PostMapping 사용
    public CreateMemberResponse saveMemberV1(@RequestBody @Valid Member member){ //@RequestBody : JSON으로 온 body를 Member에 그대로 매핑해서 쫙 넣어줌
        Long id = memberService.join(member);
        return new CreateMemberResponse(id);
    }

    /**
     * 등록 V2: 요청 값으로 Member 엔티티 대신에 별도의 DTO를 받는다.
     */
    @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);
    }

    /**
     * 수정 API
     */
    @PutMapping("api/v2/members/{id}")   //업데이트용 응답 DTO
    public UpdateMemberResponse updateMemberV2(
            @PathVariable("id") Long id, //URI를 이용해 파라미터 처리
            @RequestBody @Valid UpdateMemberRequest request) { //name 넘어옴(업데이트 할 이름)

        memberService.update(id, request.getName());
        Member findMember = memberService.findOne(id);
        return new UpdateMemberResponse(findMember.getId(), findMember.getName()); //UpdateMemberResponse객체 생성/ @AllArgsConstructor를 사용했기 때문에 모든 파라미터를 넘기는 생성자 필요
    }

    @Data
    static class UpdateMemberRequest {
        private String name;
    }

    @Data
    @AllArgsConstructor //여기에 필드에 쓴 모든생성자만 만들어줌
    static class UpdateMemberResponse {
        private Long id;
        private String name;
    }

    @Data
    static class CreateMemberRequest { //업데이트용 request DTO
        private String name;
    }

    @Data
    static class CreateMemberResponse {
        private Long id; //회원등록되면 등록된 id값 반환

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

V1 엔티티를 RequestBody에 직접 매핑

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

 

V2 엔티티 대신에 DTO를 RequestBody에 매핑

• CreateMemberRequest 를 Member 엔티티 대신에 RequestBody와 매핑한다.
• 엔티티와 프레젠테이션 계층을 위한 로직을 분리할 수 있다.
• 엔티티와 API 스펙을 명확하게 분리할 수 있다.
• 엔티티가 변해도 API 스펙이 변하지 않는다.

 

참고: 실무에서는 엔티티를 API 스펙에 노출하면 안된다!

 

회원 수정 API

• 회원 수정도 DTO를 요청 파라미터에 매핑

MemberService 에 추가

    /**
     * 회원 수정
     */
    @Transactional
    public void update(Long id, String name) {
        Member member = memberRepository.findOne(id); //memberRepository에서 id로 찾아온 다음 / 영속성콘텍스트가 id를 DB에서 가져오고 member로 반환
        member.setName(name); //member가 꺼내지면 setName으로 이름을 바꿔준다(변경감지에 의해서). 영속성컨텍스트가 플러쉬하고 DB가 트랜젝션 커밋
    }
}

• 변경 감지를 사용해서 데이터를 수정

 

회원 조 API

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

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

 

엔티티를 외부에 노출하지 마라!

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

 

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

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