53.7 커스텀 엔드포인트 확장 by ks

엔드포인트란 앱을 모니터링 하고 상호작용 할 수 있도록 해주는 것. 모니터링 뿐 아니라 트래픽, DB의 상태도 확인할 수 있다. 스프링 부트는 여러 빌트인된 엔드포인트들이 있다. 이 기능을 사용하려면 actuator 프로젝트를 추가해주고 속성을 true로 변경해주면 된다. 인증이 기본이긴 한데 없이 사용할 수도 있다.

@Endpoint 어노테이션으로 엔드포인트를 지정해주고(예제에서는 클래스 위에 선언하던데..!!) 지정된 url로 요청하면 노출된다. 엔드포인트 사용 예제.

JMX는 앱 모니터링 표준. 자바 앱이랑 jmx 모니터링 툴이랑 연결해서 데이터를 본다고 하면 되고, 실행시킬 때 옵션을 사용해주면 된다. java -jar com.sun.management.jmxremote=true 이런식으로!

@Endpoint 어노테이트된 @Bean을 추가한다면, @ReadOperation, @WriteOperation, @DeleteOperation과 같이 어노테이트된 메소드들은 자동적으로 JMX와 웹앱에서 HTTP를 통해 노출된다. 엔드포인트들은 Jersey, 스프링 MVC나 Spring WebFlux를 사용해서 노출될 수 있다.

@WebEndpoint, @JmxEndpoint를 사용해서 특정 기술 엔드포인트를 쓸 수 있다. 이 엔드포인트들은 해당 기술로 제한된다. 예를 들어서, @WebEndpoint는 JMX가 아니라 오직 HTTP를 통해서 노출된다.

@EndpointWebExtension과 @EndpointJmxExtension을 사용해서 특정 기술 엔드포인트를 쓸 수 있다. 이 어노테이션들은 존재하는 엔드포인트를 보완하는 특정 기술 동작을 제공하게 한다.

웹 프레임 워크 특정 기능에 액세스해야하는 경우 JMX를 통해 사용할 수 없거나 다른 웹 프레임 워크를 사용할 때 Servlet 또는 Spring @Controller 및 @RestController 엔드포인트 구현할 수 있다.

53.7.1 인풋 받기

엔드 포인트에서의 조작은 매개 변수를 통해 입력을 받는다. 웹을 통해 노출되면 이러한 매개 변수의 값은 URL의 쿼리 매개 변수 및 JSON 요청 본문에서 가져온다. JMX를 통해 노출되면 매개 변수가 MBean의 작업 매개 변수에 매핑된다. 매개 변수는 기본적으로 필요하다. @org.springframework.lang.Nullable 과 어노테이트해서 옵션화할 수 있다. JSON 요청 바디에서각 루트 프로퍼티는 엔드포인트의 파라미터로 매핑될 수 있다.

{ 
    "name" : "test" , 
    "counter" : 42 
}

String name과 int counter 파라미터를 사용하는 쓰기 동작을 호출하는데 사용할 수 있다.

엔드 포인트는 기술에 독립적이므로 메소드 시그니처에 단순 유형 만 지정할 수 있다. 특히 name 및 counter속성을 정의하는 사용자 정의 유형이 있는 단일 매개 변수 선언하는 것은 지원되지 않는다. ! 메소드 시그니처란? (Method Signature. 메소드 생성 규칙들 중에서 메소드의 이름, 파라미터를 메소드의 시그니처라고한다. 따라서 위에서 하는 말은 name이랑 counter를 갖는 오브젝트를 하나 만들어서 그걸 인자로 받는 커스텀한 경우는 지원되지 않는다는 말!! 입력을 조작 메소드의 매개 변수에 맵핑하려면 엔드 포인트를 구현하는 Java 코드를 -parameters로 컴파일해야하며 엔드 포인트를 구현하는 Kotlin 코드는 -java-parameters로 컴파일해야한다. 이것은 Spring Boot의 Gradle 플러그인을 사용하거나 Maven과 spring-boot-starter-parent를 사용하는 경우 자동으로 발생한다.

입력 유형 변환

엔드포인트 동작 메소드에 전달된 매개 변수는 필요한 경우 자동으로 필수 유형으로 변환된다. 동작 메소드를 호출하기 전에, JMX 또는 HTTP 요청을 통해 수신된 입력은 ApplicationConversionService 인스턴스를 사용해서 요구되는 타입으로 변환된다.

!ApplicationConversionService : Environment, BeanFactory와 함께 등록되어 우리가 쓰는 @Value()에서 이 컨버터를 써서 바인딩해준다.

53.7.2 커스텀 웹 엔드포인트

@Endpoint, @WebEndpoint, @EndpointWebExtension 동작은 자동적으로 Jersey, 스프링 MVC, 스프링 Webflux를 사용해서 HTTP 로 노출된다.

!Jersey란? Resful 웹서비스용 자바 API. JSR 311에서 구현됨.

웹 엔드포인트 요청 Predicates(동작들)

요청 Predicates는 자동적으로 웹에 노출되는 엔드포인트에 각 동작을 일반화한다.

? predicates는.. 술어? 함수?

Path

prediacate의 path는 웹에 노출된 엔드포인트의 기본 path와 엔드포인트의 ID에 의해 결정된다. 기본 path는 /actuator이다. 예를 들어서 sessions라는 ID를 가진 엔드포인트는 /actuator/sessions을 사용할 것이다. @Selector를 사용하여 하나 이상의 조작 메소드 매개 변수에 주석을 달아 경로를 추가로 사용자 정의 할 수 있다. 이러한 매개 변수는 경로 변수로 경로 조건 자에 추가된다. 변수의 값은 엔드 포인트 조작이 호출 될 때 조작 메소드에 전달된다.

HTTP 메소드

predicate 의 HTTP메소드는 동작 타입에 의해 결정된다. 아래 테이블을 보자.

Operation	HTTP method
@ReadOperation	GET
@WriteOperation	POST
@DeleteOperation	DELETE

Consumes

@WriteOperation(HTTP POST) 를 request body 에 사용하면 predicate의 consumes 구문은 application/vnd.spring-boot.actuator.v2+json, application/json이다. consume구문의 다른 모든 동작은 비어있다.

Produces

predicate의 produces 구문은 @DeleteOperation, @ReadOperation, @WriteOperation 어노테이션의 produces 속성에 의해 결정될 수 있다. 그 옵션은 선택적이다. 사용하지 않는다면, produces 구문은 자동적으로 결정된다.

오퍼레이션 메소드가 void 또는 Void를 리턴하면 produce 절이 비어 있다. 조작 메소드가 org.springframework.core.io.Resource를 리턴하면 produce 절은 application / octet-stream이다. 다른 모든 작업의 ​​경우 produce 절은 application / vnd.spring-boot.actuator.v2 + json, application / json이다.

웹 엔드포인트 응답 스테이터스

엔드포인트 동작을 위한 기본 응답 스테이터스는 타입(read, write, delete)과 리턴 값에 의존한다. @ReadOperation 은 값을 리턴하면 응답코드를 200 OK로 응답한다. 값은 반환하지 않으면 404(Not found)를 응답할 것이다. @WriteOpearion이나 @DeleteOperation이 값을 반환하면 200 OK를 반환할 것이다. 값을 반환하지 않으면 204 (No Content)를 반환할 것이다. 동작이 요구된 파라미터 없이 호출하거나 요구되는 타입으로 컨버팅될 수 없다면 메소드는 불리지 않을 것이고 응답 스테이터스도 400(bad request) 일 것이다.

웹 엔드포인트 범위 요청 (scope request)

HTTP 범위 요청은 HTTP 리소스의 요청 부분에 사용될 수 있다. 스프링 MVC나 스프링 웹 플럭스를 사용할 때 org.springframework.core.io.Resource 를 리턴하는 동작은 자동적으로 범위 요청을 지원한다.

범위 요청은 Jersey를 사용할 때는 지원하지 않는다.

웹 엔드포인트 시큐리티

웹 엔드 포인트 또는 웹 특정 엔드 포인트 확장에 대한 동작은 현재 java.security.Principal 또는 org.springframework.boot.actuate.endpoint.SecurityContext를 메소드 매개 변수로 수신 할 수 있다. 전자는 일반적으로 @Nullable과 함께 사용되어 인증 된 사용자와 인증되지 않은 사용자에 대해 다른 동작을 제공한다. 후자는 일반적으로 isUserInRole (String) 메소드를 사용하여 권한 부여 검사를 수행하는 데 사용다.

53.7.3 서블릿 엔드포인트

공급자 도 구현하는 @ServletEndpoint로 주석이 달린 클래스를 구현하여 서블릿을 엔드 포인트로 노출 할 수 있다. 서블릿 엔드 포인트는 서블릿 컨테이너와의 긴밀한 통합을 제공하지만 이식성을 희생한다. 기존 서블릿을 엔드 포인트로 노출하는 데 사용한다. 새로운 엔드포인트의 경우 가능한 @Endpoint 및 @WebEndpoint 어노테이션을 선호해야 한다.

53.7.4 컨트롤러 엔드포인트

@ControllerEndpoint와 @RestControllerEndpoint는 Spring MVC 또는 Spring WebFlux에서만 노출되는 엔드 포인트를 구현하는 데 사용할 수 있다. 메소드는 @RequestMapping 및 @GetMapping과 같은 Spring MVC 및 Spring WebFlux의 표준 어노테이션을 사용하여 맵핑되며 엔드 포인트의 ID는 경로의 접두부로 사용된다. 컨트롤러 엔드 포인트는 Spring의 웹 프레임 워크와 보다 긴밀한 통합을 제공하지만 이식성을 희생한다. @Endpoint 및 @WebEndpoint 어노테이션은 가능할 때마다 선호되어야 한다.