[SpringBoot] #5 API를 작성하는 다양한 방법

스프링 부트 핵심 가이드

 

1. 프로젝트 설정

이전 블로그글에서 소개한 방법과 동일하게 생성

groupId는 'com.springboot'로 설정하고 name과 artifactId는 'api'로 설정

2. GET API 만들기

GET API : 웹 애플리케이션 서버에서 값을 가져올 때 사용하는 API

컨트롤러에 @RestController와 @RequestMapping을 붙여 내부에 선언되는 메서드에서 사용할 공통 URL 설정

• 클래스 수준에서 @RequestMapping을 설정하면 내부에 선언한 메서드의 URL리소스 앞에 @RequestMapping의 값이 공통 값으로 추가됨

2.1 @RequestMapping으로 구현하기

@RequestMapping 어노테이션을 별 다은 설정 없이 선언하면 HTTP의 모든 요청을 받음 -> GET 형식의 요청만 받기 위해선 별도의설정 필요

@RequestMapping 어노테이션의 method 요소의 값을 RequestMapping.GET으로 설정하면 요청 혁싱을 GET으로만 설정 가능

스프링 4.3 버전 이후로는 각 HTTP메서드에 맞는 어노테이션 사용 : @GetMapping, @PostMapping, @PutMapping, @DeleteMapping

2.2 매개변수가 없는 GET 메서드 구현

2.3 @PathVariable을 활용한 GET 메서드 구현

실무 환경에서는 웹 통신의 기본 목적이 데이터를 주고받는 것이기 때문에 대부분 매개변수를 받는 매서드를 작성

@PathVariable : 매개변수를 받을 때 자주 쓰이는 방법 중 하나, URL 자체에 값을 담아 요청하는 것

21번 줄의 요청 예시 URL을 보면 중괄호로 표시된 위치의 값을 받아 요청하는 것을 알 수 있으나 실제 요청 시 중괄호는 들어가지 않으며 값만 존재. 그러나

1. @GetMapping 어노테이션의 값으로 URL을 입력할 때 중괄호를 사용해 어느 위치에서 값을 받을지 지정해야하고
2. 메서드의 매개변수와 그 값을 연결하기 위해 @PathVariable을 명시하며
3. @GetMapping 어노테이션과 @PathVariable에 지정된 변수의 이름을 동일하게 맞춰야함

만약 위의 3번이 불가하다면 28번 라인처럼 @PathVariabl 뒤에 괄호를 열어 @GetMapping 어노테이션의 변수명 지정

2.4 @RequestParam을 활용한 GET 메서드 구현

@RequestParam : 쿼리 형식으로 값을 전달하는 방법. 즉, URI에서 '?'를 기준으로 우측에 '{키}={값}' 형태로 구성된 요청을 전송

매개변수 부분에 @RequestParam 어노테이션을 명시해 쿼리 값과 매핑하면 된다.

35번 라인의 '?' 오른쪽에 쿼리스트링이 명시되어 있음. 쿼리스트링에는 키(변수의 이름)가 모두 적혀 있기 떄문에 이 값을 기준으로 매서드의 매개변수에 이름을 매핑하면 값을 가져올 수 있음

쿼리스트링에 어떤 값이 들어올지 모를 때, 45번 라인과 같이 Map 객체 활용하면 값에 상관없이 요청을 받을 수 있음.

URL : 흔히 말하는 웹 주소를 의미, 리소스가 어느 서버에 위치해 있는지 알려주기 위한 경로
URI : 특정 리소스를 식별할 수 있는 식별자, 서버에 접근해서 리소스에 접근하기 위해 URI가 필요

2.5 DTO 객체를 활용한 GET 메서드 구현

DTO(Data Transfer Object) : 각 클래스 및 인터페이스를 호출하면서 전달하는 매개변수로 사용되는 데이터 객체, 다른 레이어 간의 데이터 교환에 활용

DTO는 데이터를 교환하는 용도롼 사용하는 개체이기 때문에 DTO에는 별도의 로직이 포함되지 않음

1. com.springboot.api 패키지 하단에 dto라는 패키지를 생성, dto 패키지 내부에 MemberDto 클래스 생성

2. DTO 클래스 코드 작성

DTO 클래스에 전달하고자 하는 필드 객체를 선언하고 getter/setter 메서드 구현

DTO 클래스에 선언된 필드는 컨트롤러의 메서드에서 쿼리 파라미터의 키와 매핑 -> DTO 객체를 활용해 코드의 가독성 높임

3. DTO 객체를 활용한 GET 메서드 구현

3. POST API 만들기

POST API : 웹 애플리케이션을 통해 데이터베이스 등의 저장소에 리소스를 저장할 때 사용되는 API

POST API에서는 저장하고자 하는 리소스나 값을 HTTP 바디(body)에 담아 서버에 전달

PostController라는 이름의 컨트롤러 클래스를 생성하고  @RestController와 @RequestMapping 어노테이션을 이용해 선언되는 메서드에서 사용할 공통 URL 설정

3.1 @RequestMapping으로 구현하기

별도의 리소스를 받지 않고 단지 POST 요청만 받는 메서드

일반적으로 POST 형식의 요청은 클라이언트가 서버에 리소스를 저장하는데 사용하기 떄문에 클라이언트 요청 트래픽에 값이 포함되어 있음.

즉, POST 요청에서는 리소스를 담기위해 HTTP Body에 값을 넣어 전송

Body 영역에 작성되는 값은 일반적으로 JSON(JavaScript Object Notation) 형식으로 전송

JSON이란?
JSON(JavaScript Object Notation) : 자바스크립트의 객체 문법을 따르는 문자 기반의 데이터 포캣
대체로 네트워크를 통해 데이터를 전달할 때 사용하며, 문자열 형태로 작성되기 때문에 파싱하기도 쉬움

3.2 @RequestBody를 활용한 POST 메서드 구현

18번 라인과 같이 @RequestMapping 대신 @PostMapping을 사용하면 method 요소를 정의하지 않아도 된다.

19번 라인에서 @RequestBody라는 어노테이션으로 HTTP의 Body 내용을 해당 어노테이션이 지정된 객체에 매핑

Map 객체는 요청을 통해 어떤 값이 들어오게 될지 특정하기 어려울 떄 사용하고, 요청 메세지에 들어갈 값이 정해져 있다면 29번 라인처럼 DTO 객체를 매개변수로 삼아 작성 가능

4. PUT API 만들기

PUT API : 웹 애플리케이션 서버를 통해 데이터베이스 같은 저장소에 존재하는 리소스 값을 업데이트 하는 데 사용

HTTP Body를 활용해야 하기 때문에 POST API와 구현 방법이 거의 동일

4.1 @RequestBody를 활용한 PUT 메서드 구현

POST 메서드와 마찬가지로 HTTP Body에 담아 전달

서버에 어떤 값이 들어올지 모르는 경우에는 Map 객체를 활용해 값을 받음

서버에 들어오는 요청에 담겨 있는 값이 정해져 있는 경우 DTO 객체를 활용해 구현

• 대부분의 경우 API를 개발한 쪽에서 작성한 명세(specification)를 웹 사이트를 통해 클라이언트나 사용자에게 올바른 사용법을 안내
• DTO의 첫 번째 메서드인 postMemberDto1은 리턴 값이 String 타입이고, 두 번째 메서드인 postMemberDto2은 리턴 값이 DTO 타입

BODY로 보낸 요청 내용이 그대로 결괏값으로 전달됨. toString 메서드로 인해 나름의 형식이 갖춰져 전달됐지만 HEADERS 항목의 content-type을 보면 'text/plain'으로서 결괏값으로 일반 문자열이 전달됨을 확인 가능

BODY로 보낸 요청 내용이 형식만 유지한 채 전달됨. HEADERS 항목의 content-type 항목도 'application/json'으로 전달됨을 확인 가능

@ResrController 어노테이션이 지정된 클래스는 @ReponseBody를 생략할 수 있는데, 이 @ReponseBody 어노테이션은 자동으로 값을 JSON과 같은 형식으로 변환해서 전달하는 역할을 수행

4.4 @ResponseEntity를 활용한 PUT 메서드 구현

스프링 프레임워크에는 HttpEntity라는 클래스가 존재

HttpEntity : 헤더(Header)와 Body로 구성된 HTTP 요청과 응답을 구성하는 역할을 수행

public class HttpEntity<T> {
	private final HttpHeaders headers;
    
    @Nullable
    private final T body;
    
    ...
}

RequestEntity와 ResponseEntity는 HttpEntity를 상속받아 구현한 클래스

그 중 ResponseEntity는 서버에 들어온 요청에 대해 응답 데이터를 구성해서 전달할 수 있게 하고 HttpEntity로부터 HttpHeaders와 Body를 가지고 자체적으로 HttpStatus 구현

public class ResponseEntity<T> extends HttpEntity<T> {
	private final Object status;
    
    ...
}

43번 라인의 status에 넣을 수 있는 값은 다양한데, 코드의 HttpStatus.ACCEPTED는 응답 코드 202를 가지고 있어, 이 메서드를 대상으로 요청을 수행하면 응답코드가 202로 변경된다.

5. DELETE API 만들기

DELETE API : 웹 애플리케이션 서버를 거쳐 데이터베이스 등의 저장소에 있는 리소스를 삭제할 때 사용

서버에서는 클라이언트로부터 리소스를 식별할 수 있는 값을 받아 데이터베이스나 캐시에 있는 리소스를 조회하고 삭제

컨트롤러를 통해 값을 받는 단계에서는 간단한 값을 받기 때문에 URI에 값을 넣어 요청을 받는 형식으로 구현 (GET과 유사)

5.1 @PathVariable과  @RequestParam을 활용한 DELETE 메서드 구현

9번 라인 : @PathVariable을 이용하여 URI에 포함된 값을 받아 로직을 처리

15번 라인 : @DeleteMapping 어노테이션에 정의한 value의 이름과 메서드의 매개변수 이름을 동일하게 설정해야 삭제할 값이 주입됨. 또는 @RequestParam 어노테이션을 통해 쿼리스트링 값도 받을 수 있음

6. [한걸음 더] REST API 명세를 문서화하는 방법 - Swagger

API를 개발하면 명세를 관리해야함

• 명세 : 해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤 값을 요청하며, 이에 따른 응답값으로는 무엇을 받을 수 있는지를 정리한 자료

Swagger : 변경되는 API에 맞게 작성한 명세 문서를 주기적으로 업데이트하고 번거로운 명세 작업을 짧은 시간으로 단축시켜주는 오픈소스 프로젝트

1. 교재에서는 pom.xml을 수정하라고 되어있지만 초기 설정 시 gradle을 설정하였기에 build.gradle에 Swagger 의존성을 추가한다.

• 각자 https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui를 참고하여 버전을 선택하면 됩니다. 저는 Swagger 3.0.0 버전을 사용합니다.
• 3.x.x 버전에서는 javax.servlet.http.HttpServletRequest 클래스를 찾을 수 없다는 오류가 발생하기도합니다. 그래서 'javax.servlet:javax.servlet-api:4.0.1' 의존성도 추가해주었습니다.

2. com.springboot.api 하단에 config라는 패키지 생성 후 SwaggerConfiguration.java 클래스를 생성하여 Swagger와 관련된 설정 코드 작성.

** 3.x 버전 부터는 swagger-ui 경로가 다르다고 한다. localhost:8080/swagger-ui/index.html 로 접근

7. [한걸음 더] 로깅 라이브러리 - Logback

로깅(Logging) : 애플리케이션이 동작하는 동안 시스템의 상태나 동작 정보를 시간순으로 기록하는 것, '비기능 요구사항'

• 비기능 요구사항 : 사용자나 고객에게 필요한 기능은 아니지만 디버깅하거나 개발 이후 발생한 문제를 해결할 때 원인을 분석하는 데 꼭 필요한 요소

Logback : 자바 진영에서 가장 많이 사용되는 로깅 프레임워크, slf4j를 기반으로 구현되었으며, 과거에 사용되던 log4fj에 비해 월등한 성능, 스프링 부트의 spring-boot-starter-web 라이브러리 내부에 내장되어 있어 별도의 의존성 추가 필요 없음

Logbak의 특징

1. 크게 5개의 로그 레벨(TRACE, DEBUG, INFO, WARN, ERROR) 설정 가능
   1. ERROR : 로직 수행 중에 시스템에 심각한 문제가 발생해서 애플리케이션의 작동이 불가능한 경우를 의미
   2. WARN : 시스템 에러의 원인이 될 수 있는 경고 레벨을 의미
   3. INFO : 애플리케이션의 상태 변경과 같은 정보 전달을 위해 사용
   4. DEBUG : 애플리케이션의 디버깅을 위한 메시지를 표시하는 레벨을 의미
   5. TRACE : DEBUG 레벨보다 더 상세한 메시지를 표현하기 위한 레벨을 의미
2. 실제 운영 환경과 개발 환경에서 각각 다른 출력 레벨을 설정해서 로그 확인 가능
3. Logback의 설정 파일을 일정 시간마다 스캔해서 애플리케이션을 재가동하지 않아도 설정 변경 가능
4. 별도의 프로그램 지원 없이도 자체적으로 로그 파일을 압축 가능
5. 저장된 로그 파일에 대한 보관 기간 등을 설정해서 관리 가능