Functional Endpoints :: Spring Framework

概述

在WebMvc.fn中，使用HandlerFunction处理HTTP请求：一个接受ServerRequest并返回ServerResponse的函数。请求和响应对象都具有不可变的合同，提供了与HTTP请求和响应的JDK 8友好访问。HandlerFunction相当于注解驱动编程模型中@RequestMapping方法的主体。

传入请求通过RouterFunction路由到处理函数：一个接受ServerRequest并返回可选的HandlerFunction（即Optional<HandlerFunction>）的函数。当路由函数匹配时，返回处理函数；否则返回空的Optional。RouterFunction相当于@RequestMapping注解，但主要区别在于路由函数不仅提供数据，还提供行为。

RouterFunctions.route()提供了一个路由构建器，便于创建路由器，如下例所示：

Java
Kotlin

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.servlet.function.RequestPredicates.*;
import static org.springframework.web.servlet.function.RouterFunctions.route;

PersonRepository repository = ...
PersonHandler handler = new PersonHandler(repository);

RouterFunction<ServerResponse> route = route() (1)
	.GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson)
	.GET("/person", accept(APPLICATION_JSON), handler::listPeople)
	.POST("/person", handler::createPerson)
	.build();


public class PersonHandler {

	// ...

	public ServerResponse listPeople(ServerRequest request) {
		// ...
	}

	public ServerResponse createPerson(ServerRequest request) {
		// ...
	}

	public ServerResponse getPerson(ServerRequest request) {
		// ...
	}
}

1	使用`route()`创建路由器。

import org.springframework.web.servlet.function.router

val repository: PersonRepository = ...
val handler = PersonHandler(repository)

val route = router { (1)
	accept(APPLICATION_JSON).nest {
		GET("/person/{id}", handler::getPerson)
		GET("/person", handler::listPeople)
	}
	POST("/person", handler::createPerson)
}


class PersonHandler(private val repository: PersonRepository) {

	// ...

	fun listPeople(request: ServerRequest): ServerResponse {
		// ...
	}

	fun createPerson(request: ServerRequest): ServerResponse {
		// ...
	}

	fun getPerson(request: ServerRequest): ServerResponse {
		// ...
	}
}

1	使用路由DSL创建路由器。

如果将RouterFunction注册为一个bean，例如通过在@Configuration类中公开它，它将被Servlet自动检测，如运行服务器中所述。

处理函数

查看在响应式堆栈中的等效内容

ServerRequest和ServerResponse是不可变接口，提供了对HTTP请求和响应的访问，包括头部、主体、方法和状态码，与JDK 8兼容。

ServerRequest

ServerRequest提供对HTTP方法、URI、头部和查询参数的访问，而对主体的访问通过body方法提供。

以下示例将请求主体提取为String：

Java
Kotlin

String string = request.body(String.class);

val string = request.body<String>()

以下示例将主体提取为List<Person>，其中Person对象从序列化形式（如JSON或XML）解码：

Java
Kotlin

List<Person> people = request.body(new ParameterizedTypeReference<List<Person>>() {});

val people = request.body<Person>()

以下示例显示如何访问参数：

Java
Kotlin

MultiValueMap<String, String> params = request.params();

val map = request.params()

ServerResponse

ServerResponse提供对HTTP响应的访问，并且由于其是不可变的，您可以使用build方法来创建它。您可以使用构建器设置响应状态、添加响应头或提供主体。以下示例创建一个带有JSON内容的200（OK）响应：

Java
Kotlin

Person person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);

val person: Person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person)

以下示例显示如何构建一个带有Location头和无主体的201（CREATED）响应：

Java
Kotlin

URI location = ...
ServerResponse.created(location).build();

val location: URI = ...
ServerResponse.created(location).build()

您还可以将异步结果作为主体，以CompletableFuture、Publisher或ReactiveAdapterRegistry支持的任何其他类型的形式。例如：

Java
Kotlin

Mono<Person> person = webClient.get().retrieve().bodyToMono(Person.class);
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);

val person = webClient.get().retrieve().awaitBody<Person>()
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person)

如果不仅主体，而且状态或头部基于异步类型，您可以在ServerResponse上使用静态async方法，该方法接受CompletableFuture<ServerResponse>、Publisher<ServerResponse>或ReactiveAdapterRegistry支持的任何其他异步类型。例如：

Java

Mono<ServerResponse> asyncResponse = webClient.get().retrieve().bodyToMono(Person.class)
  .map(p -> ServerResponse.ok().header("Name", p.name()).body(p));
ServerResponse.async(asyncResponse);

服务器发送事件可以通过ServerResponse上的静态sse方法提供。该方法提供的构建器允许您发送字符串或其他对象作为JSON。例如：

Java
Kotlin

public RouterFunction<ServerResponse> sse() {
	return route(GET("/sse"), request -> ServerResponse.sse(sseBuilder -> {
				// Save the sseBuilder object somewhere..
			}));
}

// In some other thread, sending a String
sseBuilder.send("Hello world");

// Or an object, which will be transformed into JSON
Person person = ...
sseBuilder.send(person);

// Customize the event by using the other methods
sseBuilder.id("42")
		.event("sse event")
		.data(person);

// and done at some point
sseBuilder.complete();

fun sse(): RouterFunction<ServerResponse> = router {
	GET("/sse") { request -> ServerResponse.sse { sseBuilder ->
		// Save the sseBuilder object somewhere..
	}
}

// In some other thread, sending a String
sseBuilder.send("Hello world")

// Or an object, which will be transformed into JSON
val person = ...
sseBuilder.send(person)

// Customize the event by using the other methods
sseBuilder.id("42")
		.event("sse event")
		.data(person)

// and done at some point
sseBuilder.complete()

处理程序类

我们可以将处理程序函数编写为lambda表达式，如下例所示：

Java
Kotlin

HandlerFunction<ServerResponse> helloWorld =
  request -> ServerResponse.ok().body("Hello World");

val helloWorld: (ServerRequest) -> ServerResponse =
  { ServerResponse.ok().body("Hello World") }

这样做很方便，但在应用程序中，我们需要多个函数，多个内联lambda可能会变得混乱。因此，将相关的处理程序函数组合到一个处理程序类中是有用的，它的作用类似于注解驱动应用程序中的@Controller。例如，以下类公开了一个响应式Person存储库：

Java
Kotlin

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.reactive.function.server.ServerResponse.ok;

public class PersonHandler {

	private final PersonRepository repository;

	public PersonHandler(PersonRepository repository) {
		this.repository = repository;
	}

	public ServerResponse listPeople(ServerRequest request) { (1)
		List<Person> people = repository.allPeople();
		return ok().contentType(APPLICATION_JSON).body(people);
	}

	public ServerResponse createPerson(ServerRequest request) throws Exception { (2)
		Person person = request.body(Person.class);
		repository.savePerson(person);
		return ok().build();
	}

	public ServerResponse getPerson(ServerRequest request) { (3)
		int personId = Integer.parseInt(request.pathVariable("id"));
		Person person = repository.getPerson(personId);
		if (person != null) {
			return ok().contentType(APPLICATION_JSON).body(person);
		}
		else {
			return ServerResponse.notFound().build();
		}
	}

}

1	`listPeople`是一个处理程序函数，以JSON格式返回存储库中找到的所有`Person`对象。
2	`createPerson`是一个处理程序函数，用于存储请求体中包含的新`Person`。
3	`getPerson`是一个处理程序函数，根据`id`路径变量返回单个人员。我们从存储库中检索该`Person`，如果找到，则创建一个JSON响应。如果未找到，则返回404 Not Found响应。

class PersonHandler(private val repository: PersonRepository) {

	fun listPeople(request: ServerRequest): ServerResponse { (1)
		val people: List<Person> = repository.allPeople()
		return ok().contentType(APPLICATION_JSON).body(people);
	}

	fun createPerson(request: ServerRequest): ServerResponse { (2)
		val person = request.body<Person>()
		repository.savePerson(person)
		return ok().build()
	}

	fun getPerson(request: ServerRequest): ServerResponse { (3)
		val personId = request.pathVariable("id").toInt()
		return repository.getPerson(personId)?.let { ok().contentType(APPLICATION_JSON).body(it) }
				?: ServerResponse.notFound().build()

	}
}

1	`listPeople`是一个处理程序函数，以JSON格式返回存储库中找到的所有`Person`对象。
2	`createPerson`是一个处理程序函数，用于存储请求体中包含的新`Person`。
3	`getPerson`是一个处理程序函数，根据`id`路径变量返回单个人员。我们从存储库中检索该`Person`，如果找到，则创建一个JSON响应。如果未找到，则返回404 Not Found响应。

验证

函数端点可以使用Spring的验证工具对请求体应用验证。例如，给定一个用于Person的自定义Spring验证器实现：

Java
Kotlin

public class PersonHandler {

	private final Validator validator = new PersonValidator(); (1)

	// ...

	public ServerResponse createPerson(ServerRequest request) {
		Person person = request.body(Person.class);
		validate(person); (2)
		repository.savePerson(person);
		return ok().build();
	}

	private void validate(Person person) {
		Errors errors = new BeanPropertyBindingResult(person, "person");
		validator.validate(person, errors);
		if (errors.hasErrors()) {
			throw new ServerWebInputException(errors.toString()); (3)
		}
	}
}

1	创建`Validator`实例。
2	应用验证。
3	为400响应引发异常。

class PersonHandler(private val repository: PersonRepository) {

	private val validator = PersonValidator() (1)

	// ...

	fun createPerson(request: ServerRequest): ServerResponse {
		val person = request.body<Person>()
		validate(person) (2)
		repository.savePerson(person)
		return ok().build()
	}

	private fun validate(person: Person) {
		val errors: Errors = BeanPropertyBindingResult(person, "person")
		validator.validate(person, errors)
		if (errors.hasErrors()) {
			throw ServerWebInputException(errors.toString()) (3)
		}
	}
}

1	创建`Validator`实例。
2	应用验证。
3	为400响应引发异常。

处理程序还可以使用标准的bean验证API（JSR-303），通过基于LocalValidatorFactoryBean创建和注入全局Validator实例。请参阅Spring验证。

`路由函数`

查看在响应式堆栈中的等效部分

路由函数用于将请求路由到相应的HandlerFunction。通常情况下，您不会自己编写路由函数，而是使用RouterFunctions实用类上的方法来创建一个。 RouterFunctions.route()（无参数）为您提供了一个流畅的构建器，用于创建路由函数，而RouterFunctions.route(RequestPredicate, HandlerFunction)提供了一种直接创建路由的方式。

通常建议使用route()构建器，因为它为典型的映射场景提供了方便的快捷方式，而无需硬编码难以发现的静态导入。例如，路由函数构建器提供了GET(String, HandlerFunction)方法用于创建GET请求的映射；以及POST(String, HandlerFunction)用于POST请求。

除了基于HTTP方法的映射，路由构建器还提供了一种在映射到请求时引入附加谓词的方法。对于每种HTTP方法，都有一个重载变体，它以RequestPredicate作为参数，通过它可以表达附加约束。

谓词

您可以编写自己的RequestPredicate，但RequestPredicates实用类提供了基于请求路径、HTTP方法、内容类型等常用实现。以下示例使用请求谓词基于Accept标头创建约束：

Java
Kotlin

RouterFunction<ServerResponse> route = RouterFunctions.route()
	.GET("/hello-world", accept(MediaType.TEXT_PLAIN),
		request -> ServerResponse.ok().body("Hello World")).build();

import org.springframework.web.servlet.function.router

val route = router {
	GET("/hello-world", accept(TEXT_PLAIN)) {
		ServerResponse.ok().body("Hello World")
	}
}

您可以通过使用以下方式组合多个请求谓词：

RequestPredicate.and(RequestPredicate) — 两者都必须匹配。
RequestPredicate.or(RequestPredicate) — 任一者可以匹配。

RequestPredicates中的许多谓词是组合的。例如，RequestPredicates.GET(String)由RequestPredicates.method(HttpMethod)和RequestPredicates.path(String)组成。上面显示的示例也使用了两个请求谓词，因为构建器内部使用了RequestPredicates.GET，并将其与accept谓词组合。

路由

路由函数按顺序进行评估：如果第一个路由不匹配，则评估第二个，依此类推。因此，在通用路由之前声明更具体的路由是有意义的。当将路由函数注册为Spring bean时，这也很重要，稍后将进行描述。请注意，此行为与基于注解的编程模型不同，后者会自动选择“最具体”的控制器方法。

使用路由函数构建器时，所有定义的路由都组合成一个RouterFunction，并从build()返回。还有其他将多个路由函数组合在一起的方法：

RouterFunctions.route()构建器上的add(RouterFunction)
RouterFunction.and(RouterFunction)
RouterFunction.andRoute(RequestPredicate, HandlerFunction) — RouterFunction.and()的快捷方式，带有嵌套的RouterFunctions.route()。

以下示例展示了四个路由的组合：

Java
Kotlin

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.servlet.function.RequestPredicates.*;

PersonRepository repository = ...
PersonHandler handler = new PersonHandler(repository);

RouterFunction<ServerResponse> otherRoute = ...

RouterFunction<ServerResponse> route = route()
	.GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)
	.GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)
	.POST("/person", handler::createPerson) (3)
	.add(otherRoute) (4)
	.build();

1	`GET /person/{id}`，带有匹配JSON的`Accept`标头，路由到`PersonHandler.getPerson`
2	`GET /person`，带有匹配JSON的`Accept`标头，路由到`PersonHandler.listPeople`
3	`POST /person`，没有附加谓词，映射到`PersonHandler.createPerson`，以及
4	`otherRoute`是在其他地方创建的路由函数，并添加到构建的路由中。

import org.springframework.http.MediaType.APPLICATION_JSON
import org.springframework.web.servlet.function.router

val repository: PersonRepository = ...
val handler = PersonHandler(repository);

val otherRoute = router {  }

val route = router {
	GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)
	GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)
	POST("/person", handler::createPerson) (3)
}.and(otherRoute) (4)

1	`GET /person/{id}`，带有匹配JSON的`Accept`标头，路由到`PersonHandler.getPerson`
2	`GET /person`，带有匹配JSON的`Accept`标头，路由到`PersonHandler.listPeople`
3	`POST /person`，没有附加谓词，映射到`PersonHandler.createPerson`，以及
4	`otherRoute`是在其他地方创建的路由函数，并添加到构建的路由中。

嵌套路由

一组路由函数通常具有共享的谓词，例如共享路径。在上面的示例中，共享的谓词将是一个路径谓词，匹配/person，被三个路由使用。在使用注解时，您可以通过使用类型级别的@RequestMapping注解来消除这种重复，该注解映射到/person。在WebMvc.fn中，路径谓词可以通过路由函数构建器上的path方法共享。例如，通过使用嵌套路由，上面示例的最后几行可以通过以下方式改进：

Java
Kotlin

RouterFunction<ServerResponse> route = route()
	.path("/person", builder -> builder (1)
		.GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)
		.GET(accept(APPLICATION_JSON), handler::listPeople)
		.POST(handler::createPerson))
	.build();

1	注意`path`的第二个参数是一个接受路由构建器的消费者。

import org.springframework.web.servlet.function.router

val route = router {
	"/person".nest { (1)
		GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)
		GET(accept(APPLICATION_JSON), handler::listPeople)
		POST(handler::createPerson)
	}
}

1	使用`nest` DSL。

虽然基于路径的嵌套是最常见的，但您可以通过在构建器上使用nest方法在任何类型的谓词上进行嵌套。上面的示例仍然包含一些重复，即共享的Accept头谓词。我们可以通过结合nest方法和accept进一步改进：

Java
Kotlin

RouterFunction<ServerResponse> route = route()
	.path("/person", b1 -> b1
		.nest(accept(APPLICATION_JSON), b2 -> b2
			.GET("/{id}", handler::getPerson)
			.GET(handler::listPeople))
		.POST(handler::createPerson))
	.build();

import org.springframework.web.servlet.function.router

val route = router {
	"/person".nest {
		accept(APPLICATION_JSON).nest {
			GET("/{id}", handler::getPerson)
			GET("", handler::listPeople)
			POST(handler::createPerson)
		}
	}
}

资源提供

WebMvc.fn提供了内置支持来提供资源。

除了下面描述的功能外，还可以通过RouterFunctions#resource(java.util.function.Function)实现更灵活的资源处理。

重定向到资源

可以将匹配指定谓词的请求重定向到资源。例如，这对于处理单页应用程序中的重定向非常有用。

Java
Kotlin

   ClassPathResource index = new ClassPathResource("static/index.html");
List<String> extensions = Arrays.asList("js", "css", "ico", "png", "jpg", "gif");
RequestPredicate spaPredicate = path("/api/**").or(path("/error")).or(pathExtension(extensions::contains)).negate();
RouterFunction<ServerResponse> redirectToIndex = route()
	.resource(spaPredicate, index)
	.build();

   val redirectToIndex = router {
	val index = ClassPathResource("static/index.html")
	val extensions = listOf("js", "css", "ico", "png", "jpg", "gif")
	val spaPredicate = !(path("/api/**") or path("/error") or
		pathExtension(extensions::contains))
	resource(spaPredicate, index)
}

从根位置提供资源

还可以将匹配给定模式的请求路由到相对于给定根位置的资源。

Java
Kotlin

Resource location = new FileSystemResource("public-resources/");
RouterFunction<ServerResponse> resources = RouterFunctions.resources("/resources/**", location);

val location = FileSystemResource("public-resources/")
val resources = router { resources("/resources/**", location) }

运行服务器

查看响应式堆栈中的等效部分

通常，您可以通过DispatcherHandler为基础的设置来运行路由函数，通过MVC配置，使用Spring配置声明处理请求所需的组件。 MVC Java配置声明以下基础设施组件以支持功能端点：

RouterFunctionMapping：在Spring配置中检测一个或多个RouterFunction<?> bean，对其进行排序，通过RouterFunction.andOther组合它们，并将请求路由到生成的组合RouterFunction。
HandlerFunctionAdapter：简单的适配器，让DispatcherHandler调用映射到请求的HandlerFunction。

上述组件使功能端点适应DispatcherServlet请求处理生命周期，并且（可能）与已声明的注释控制器并行运行。这也是Spring Boot Web starter启用功能端点的方式。

以下示例显示了WebFlux Java配置：

Java
Kotlin

@Configuration
@EnableMvc
public class WebConfig implements WebMvcConfigurer {

	@Bean
	public RouterFunction<?> routerFunctionA() {
		// ...
	}

	@Bean
	public RouterFunction<?> routerFunctionB() {
		// ...
	}

	// ...

	@Override
	public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
		// 配置消息转换...
	}

	@Override
	public void addCorsMappings(CorsRegistry registry) {
		// 配置CORS...
	}

	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		// 配置用于HTML渲染的视图解析器...
	}
}

@Configuration
@EnableMvc
class WebConfig : WebMvcConfigurer {

	@Bean
	fun routerFunctionA(): RouterFunction<*> {
		// ...
	}

	@Bean
	fun routerFunctionB(): RouterFunction<*> {
		// ...
	}

	// ...

	override fun configureMessageConverters(converters: List<HttpMessageConverter<*>>) {
		// 配置消息转换...
	}

	override fun addCorsMappings(registry: CorsRegistry) {
		// 配置CORS...
	}

	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		// 配置用于HTML渲染的视图解析器...
	}
}

过滤处理函数

查看响应式堆栈中的等效内容

您可以通过在路由函数构建器上使用before、after或filter方法来过滤处理函数。使用注解时，您可以通过使用@ControllerAdvice、ServletFilter或两者来实现类似的功能。过滤器将应用于构建器构建的所有路由。这意味着在嵌套路由中定义的过滤器不适用于“顶级”路由。例如，请考虑以下示例：

Java
Kotlin

RouterFunction<ServerResponse> route = route()
	.path("/person", b1 -> b1
		.nest(accept(APPLICATION_JSON), b2 -> b2
			.GET("/{id}", handler::getPerson)
			.GET(handler::listPeople)
			.before(request -> ServerRequest.from(request) (1)
				.header("X-RequestHeader", "Value")
				.build()))
		.POST(handler::createPerson))
	.after((request, response) -> logResponse(response)) (2)
	.build();

1	`before`过滤器仅应用于两个GET路由。
2	`after`过滤器记录响应应用于所有路由，包括嵌套路由。

import org.springframework.web.servlet.function.router

val route = router {
	"/person".nest {
		GET("/{id}", handler::getPerson)
		GET(handler::listPeople)
		before { (1)
			ServerRequest.from(it)
					.header("X-RequestHeader", "Value").build()
		}
	}
	POST(handler::createPerson)
	after { _, response -> (2)
		logResponse(response)
	}
}

1	`before`过滤器仅应用于两个GET路由。
2	`after`过滤器记录响应应用于所有路由，包括嵌套路由。

路由构建器上的filter方法接受一个HandlerFilterFunction：一个接受ServerRequest和HandlerFunction并返回ServerResponse的函数。处理函数参数表示链中的下一个元素。这通常是路由到的处理程序，但如果应用多个过滤器，它也可以是另一个过滤器。

现在我们可以为我们的路由添加一个简单的安全过滤器，假设我们有一个SecurityManager可以确定特定路径是否允许。以下示例展示了如何实现：

Java
Kotlin

SecurityManager securityManager = ...

RouterFunction<ServerResponse> route = route()
	.path("/person", b1 -> b1
		.nest(accept(APPLICATION_JSON), b2 -> b2
			.GET("/{id}", handler::getPerson)
			.GET(handler::listPeople))
		.POST(handler::createPerson))
	.filter((request, next) -> {
		if (securityManager.allowAccessTo(request.path())) {
			return next.handle(request);
		}
		else {
			return ServerResponse.status(UNAUTHORIZED).build();
		}
	})
	.build();

import org.springframework.web.servlet.function.router

val securityManager: SecurityManager = ...

val route = router {
	("/person" and accept(APPLICATION_JSON)).nest {
		GET("/{id}", handler::getPerson)
		GET("", handler::listPeople)
		POST(handler::createPerson)
		filter { request, next ->
			if (securityManager.allowAccessTo(request.path())) {
				next(request)
			}
			else {
				status(UNAUTHORIZED).build();
			}
		}
	}
}

上面的示例演示了调用next.handle(ServerRequest)是可选的。只有在允许访问时，我们才让处理函数运行。

除了在路由函数构建器上使用filter方法外，还可以通过RouterFunction.filter(HandlerFilterFunction)将过滤器应用于现有的路由函数。

功能端点的CORS支持通过专用的CorsFilter提供。

功能性端点

概述