3. RESTful Service 기능 확장

Validation API

@Valid annotation 사용

1. **pom.xml에 dependency 추가**

<dependency>
           <groupId>org.hibernate.validator</groupId>
           <artifactId>hibernate-validator</artifactId>
           <version>6.0.7.Final</version>
        </dependency>

1. dto에 제약조건 추가

@Data
@AllArgsConstructor
public class User {
	private Integer id;

	@Size(min=2, message = "Name은 2글자 이상 입력해주세요.")
	private String name;
	private String password;
	@Past // 과거 날짜만 가능한 제약 조건
	private Date joinDate;
}

1. controller에 추가

• JDK에 포함된 API와 hibernate library에 포함된 validation 기능
• @Valid : 사용자 추가할 때 validation 검증
• @RequestBody : 현재 variable이 requestBody 형식으로 들어옴을 알림

1. exception handler 추가

@ResponseStatus(HttpStatus.NOT_FOUND) // 응답 상태 코드 값 지정
// CustomizedResponseEntityExceptionHandler.class에서 UserNotFoundException이 발생했을 때, Exception Response를 반환(Http status code도 반환)
// => ResponseStatus 생략 가능
public class UserNotFoundException extends RuntimeException {
	public UserNotFoundException(String message) {
		super(message); // ex.getMessage()
	}
}

다국어 처리를 위한 Internationalization 구현

1. yml 파일에 spring.messages.basename={사용할 properties 파일의 이름}

#다국어 파일 설정
spring:
  messages:
    basename: messages # 우리가 사용할 message 파일의 이름

1. resources 밑에 {yml 파일에서 설정한 이름}.properties를 만들어준다

-> 다국어 버전으로 여러 개 생성

# properties : 자바의 리소스 번들
# 특정 key값과 value를 저장해 놓고 사용할 수 있는 용도로 사용됨
greeting.message=안녕하세요

// messages_fr.properties
greeting.message=Bonjour

1. @SpringBootApplication밑에 @Bean을 생성해서 localeResolver 생성

@Bean
// @SpringBootApplication에 @Bean을 등록하게 되면 Spring Boot가 초기화될 떄,
// 해당 정보에 해당되는 값이 메모리에 올라가서 다른 클래스가 사용할 수 있게 된다.
public LocaleResolver localeResolver() {		
	SessionLocaleResolver localeResolver = new SessionLocaleResolver();
	localeResolver.setDefaultLocale(Locale.KOREA); // default : 한국어 처리
	return localeResolver;
}

1. Controller에서 설정 -> Header로 language 값을 받아서 해당 언어에 맞는 메세지를 출력

@Autowired // annotation을 통한 의존성 주입 : spring framework에 등록되어 있는 bean 중 같은 타입을 가진 bean을 자동으로 주입
private MessageSource messageSource;

@GetMapping(path="/hello-world-internationalized")
	public String helloWorldInternationalized(
		@RequestHeader(name="Accept-Language", required = false) Locale locale) {
		// "Accept-Language" 값이 설정되지 않았을 때는 자동으로 default값인 한국어로 설정(기본 locale 값)
		// "Accept-Language" 가 설정되어 있으면 locale에 저장

		// 첫번째 인자: 설정 파일에서의 key 값
		// 두번째 인자: 만약 parameter를 가진 가변변수라면 parameter 지정
		// 세번째 인자: RequestHeader를 통해 전달받은 locale
		return messageSource.getMessage("greeting.message", null, locale);
	}

@Bean과 @Autowired

1. @Bean @SpringBootApplication에 @Bean을 등록하게 되면 Spring Boot가 초기화될 때, 해당 정보에 해당되는 값이 메모리에 올라가서 다른 클래스가 사용할 수 있게 된다.
2. @Autowired

annotation을 이용한 의존성 주입 : spring framework에 등록되어 있는 bean 중 같은 타입을 가진 bean을 자동으로 주입

Response 데이터 형식 반환 - XML format

1. Postman header에서 key: Accept, value: application/xml로 변환 시 xml파일 호출 가능

2. pom.xml에서 dependency 추가

<!--xml 파일 변환 설정-->
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.10.2</version>
</dependency>

⇒ 설정하지 않을 경우 406 에러가 난다

HTTP(HyperText Transfer Protocol) 406 Not Acceptable 클라이언트 오류 응답 코드는 서버가 요청의 사전 콘텐츠 협상 헤더에 정의된 허용 가능한 값 목록과 일치하는 응답을 생성할 수 없으며 서버가 기본 표현을 제공할 의사가 없음을 나타냅니다.

사전 컨텐츠 협상 헤더에는 다음이 포함됩니다.

• [Accept](<https://runebook.dev/ko/docs/http/headers/accept>)
• [Accept-Encoding](<https://runebook.dev/ko/docs/http/headers/accept-encoding>)
• [Accept-Language](<https://runebook.dev/ko/docs/http/headers/accept-language>)

실제로 이 오류는 거의 사용되지 않습니다. 최종 사용자에게는 암호화되어 수정하기 어려운 이 오류 코드를 사용하여 응답하는 대신 서버는 관련 헤더를 무시하고 사용자에게 실제 페이지를 제공합니다. 사용자가 완전히 만족하지 않더라도 오류 코드보다 선호한다고 가정합니다.

서버가 이러한 오류 상태를 반환하면 메시지 본문에 사용 가능한 리소스 표현 목록이 포함되어 있어야 사용자가 선택할 수 있습니다.

Response 데이터 제어를 위한 Filtering

클라이언트에게 전달되는 정보의 값을 제어

1. 값을 암호화하거나 치환하여 전달
2. null로 반환

⇒ @JsonIgnore , @JsonIgnoreProperties 사용

@JsonIgnore // 반환 시 Json값에 포함되지 않음 ->반환값 제어
privateString password;

@JsonIgnore
privateString ssn;//주민등록번호

//@JsonIgnoreProperties(value={"password", "ssn"}) // 클래스 블록 단위로 필터링

개별 사용자 조회

// domain
// @JsonIgnoreProperties(value={"password", "ssn"}) // 클래스 단위로 필터링
@JsonFilter("UserInfo") // 부여된 필터값은 controller나 service 클래스에서 사용된다

@RequestMapping("/admin") // 모든 api가 공통적으로 가지고 있는 이름을 클래스 블록에 선언

@GetMapping("/users/{id}")
	// setFilters나 setSerialView를 사용 시 꼭 MappingJacksonValue 타입으로 감싸서 반환
	public MappingJacksonValue retrieveUser(@PathVariable int id) { // 관리자 : 유저의 정보를 모두 가져올 수 있도록!
		User user = service.findOne(id);
		if (user == null){
			throw new UserNotFoundException(String.format("ID[%s] is not found", id));
		}

		// bean의 property를 제어
		SimpleBeanPropertyFilter filter = SimpleBeanPropertyFilter
			.filterOutAllExcept("id", "name", "joinDate", "ssn"); // 포함시키고 싶은 필터값 선언

		// User에 @JsonFilter("UserInfo") 지정
		FilterProvider filters = new SimpleFilterProvider().addFilter("UserInfo", filter);

		MappingJacksonValue mapping = new MappingJacksonValue(user); // 유저 데이터 전달
		mapping.setFilters(filters); // 필터 적용

		return mapping;
	}

 

정리

클라이언트에게 전달되는 정보의 값을 제어하는 두 가지 방법 (1) 값을 암호화하거나 치환하여 전달 (2) null을 넣어 전달

-> 우리는 @JsonIgnore, @JsonIgnoreProperties를 사용하여 값을 제어한다

1. @JsonIgnore : 단위 필드 값을 제어할 때 사용. 반환 시 json 값에 포함되지 않는다
2. @JsonIgnoreProperties(value={"필드값"}) : 클래스를 블록 단위로 필터링 -> 조금 더 효율적인 방법 :@JsonFilter 사용
3. domain에 @JsonFilter("필터명") 사용 : 부여된 필터값은 controller나 service 클래스에서 사용
4. controller에서 return값을 MappingJacksonValue로 선언

• SimpleBeanPropertyFilter를 이용하여 포함시키고 싶은 필터값 선언
• FilterProvider에 domain에서 지정한 필터 지정
• MappingJacksonValue에 FilterProvider를 적용하여 리턴

REST API 버전 관리

Richardson Maturity Model

URL을 이용한 버전 관리

url에 버전을 표시함으로써 버전을 표시할 수 있다. 버전 관리는 애플리케이션의 소스 코드 뿐만 아니라 제공하려는 서비스의 리소스에 대해서도 관리해주는 것이 좋다.

// 반환받은 User를 UserV2로 변환
		UserV2 userV2 = new UserV2();
		// 두 인스턴스 간에 공통된 필드가 있을 경우 해당 값을 copy함
		BeanUtils.copyProperties(user, userV2); // id, name, joinDate, password, ssn
		userV2.setGrade("VIP");

Request Parameter를 이용한 버전 관리

// 데이터 뒤에 버전에 대한 정보가 추가적으로 전달되어야 하기 때문에 URI 뒤에 "/"가 붙는다
	@GetMapping(value = "/users/{id}/", params = "version=1")

http://localhost:8088/admin/users/1/?version=1 방식으로 호출

Header를 이용한 버전 관리

@GetMapping(value = "/users/{id}", headers = "X-API-VERSION=2")

MIME 타입을 이용한 버전 관리

MIME 타입 → Multi-Purpose Internet Mail Extension(파일 형식 지정)

이메일과 함께 전송되는 메일를 텍스트 문자로 변환해서 이메일 서버에 전달하기 위한 방법

// 제공하고자 하는 MIME 타입 지정
	// 기존에 없던 새로운 값 -> application
	// 버전 이름 : appv1
	// 전달 시키조자 하는 타입 : json
	@GetMapping(value = "/users/{id}", produces = "application/vnd.company.appv1+json")

 

버전 관리

단순하게 사용자에게 보여주는 항목을 제어하는 용도가 아니라 REST API의 설계가 변경되거나 어플리케이션의 구조가 바뀔 때도 버전을 변경해주어야 함.

사용자에게는 어떠한 API 버전을 사용해야 하는지에 대한 적절한 가이드 제공 필요

• 일반 브라우저에서 실행 가능
  • URI
  • Request Parameter
• 일반 브라우저에서 실행 불가
  • Media type versioning(content negotiation, accept header) → 헤더
  • (custom) headers versioning → MIME 타입
• 유의 사항
  • URI Pollution : 너무 지저분하거나 과도하게 정보를 표기하는 것은 지양
  • Misuse of HTTP headers : 잘못된 헤더값 주의
  • Caching : 적절히 캐시 삭제해서 제대로 된 값을 사용할 수 있도록 함
  • Can we execute the request on browser?
  • API Documentation

•