对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

函数式端点

Spring Web MVC 包含 WebMvc.fn，这是一种轻量级的函数式编程模型，使用函数来路由和处理请求，并且其契约设计为不可变。 它是基于注解的编程模型的一种替代方案，但除此之外，它仍运行在相同的 DispatcherServlet 上。spring-doc.cadn.net.cn

概述

参见响应式栈中的等效内容spring-doc.cadn.net.cn

在 WebMvc.fn 中，HTTP 请求由一个 HandlerFunction 处理：这是一个接收 ServerRequest 并返回 ServerResponse 的函数。 请求和响应对象均具有不可变的契约，提供了对 HTTP 请求和响应的 JDK 8 友好式访问方式。 HandlerFunction 在基于注解的编程模型中相当于 @RequestMapping 方法的方法体。spring-doc.cadn.net.cn

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

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

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 将自动检测到它。spring-doc.cadn.net.cn

处理器函数

参见响应式栈中的等效内容spring-doc.cadn.net.cn

ServerRequest 和 ServerResponse 是不可变的接口，提供了对 HTTP 请求和响应（包括头信息、正文、方法和状态码）的 JDK 8 友好访问方式。spring-doc.cadn.net.cn

服务器请求

ServerRequest 提供对 HTTP 方法、URI、请求头和查询参数的访问，而对请求体的访问则通过 body 方法提供。spring-doc.cadn.net.cn

以下示例将请求体提取为 String：spring-doc.cadn.net.cn

String string = request.body(String.class);
val string = request.body<String>()

以下示例将请求体提取为一个 List<Person>，其中 Person 对象从序列化格式（例如 JSON 或 XML）中解码得到：spring-doc.cadn.net.cn

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

以下示例展示了如何访问参数：spring-doc.cadn.net.cn

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

服务器响应

ServerResponse 提供对 HTTP 响应的访问，并且由于它是不可变的，你可以使用 build 方法来创建它。你可以使用构建器来设置响应状态、添加响应头，或者提供响应体。以下示例创建了一个包含 JSON 内容的 200（OK）响应：spring-doc.cadn.net.cn

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

以下示例展示了如何构建一个带有 Location 头部且无响应体的 201（CREATED）响应：spring-doc.cadn.net.cn

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

你也可以使用异步结果作为响应体，形式可以是 CompletableFuture、Publisher，或 ReactiveAdapterRegistry 所支持的任何其他类型。例如：spring-doc.cadn.net.cn

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)

如果不仅响应体，而且状态或头部也依赖于异步类型， 你可以使用 async 上的静态 ServerResponse 方法，该方法接受 CompletableFuture<ServerResponse>、Publisher<ServerResponse>， 或 ReactiveAdapterRegistry 所支持的任何其他异步类型。例如：spring-doc.cadn.net.cn

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

服务器发送事件（Server-Sent Events）可以通过sse上的静态ServerResponse方法提供。该方法所提供的构建器允许你以字符串形式发送数据，或以 JSON 格式发送其他对象。例如：spring-doc.cadn.net.cn

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 表达式，如下例所示：spring-doc.cadn.net.cn

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

这样做很方便，但在实际应用中我们需要多个函数，而多个内联的 lambda 表达式可能会变得混乱。 因此，将相关的处理函数组合到一个处理类中会很有用，该类在基于注解的应用程序中扮演的角色类似于 @Controller。 例如，下面的类暴露了一个响应式的 Person 仓库：spring-doc.cadn.net.cn

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 是一个处理函数，它将仓库中找到的所有 Person 对象以 JSON 格式返回。
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 是一个处理函数，它将仓库中找到的所有 Person 对象以 JSON 格式返回。
2 createPerson 是一个处理函数，用于存储请求体中包含的新 Person 对象。
3 getPerson 是一个处理函数，它返回由路径变量 id 标识的单个人员。我们从仓库中检索该 Person 并创建一个 JSON 响应（如果找到）。如果未找到，则返回 404 Not Found 响应。

验证

函数式端点可以使用 Spring 的验证功能对请求体进行验证。例如，针对 xref page 类提供一个自定义的 Spring Validator 实现：spring-doc.cadn.net.cn

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 响应抛出异常。

处理器也可以通过创建并注入一个基于 Validator 的全局 LocalValidatorFactoryBean 实例，来使用标准的 Bean Validation API（JSR-303）。 参见Spring 验证。spring-doc.cadn.net.cn

RouterFunction

参见响应式栈中的等效内容spring-doc.cadn.net.cn

路由函数（Router functions）用于将请求路由到相应的HandlerFunction。 通常，您不会自己编写路由函数，而是使用 RouterFunctions 工具类上的方法来创建路由函数。 RouterFunctions.route()（无参数）为您提供了一个流畅的构建器（fluent builder）来创建路由 函数，而 RouterFunctions.route(RequestPredicate, HandlerFunction) 则提供了一种直接创建路由函数的方式。spring-doc.cadn.net.cn

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

除了基于 HTTP 方法的映射之外，路由构建器还提供了一种在映射请求时引入额外谓词（predicates）的方式。 对于每种 HTTP 方法，都提供了一个重载的变体，该变体接受一个 RequestPredicate 参数，通过该参数可以表达额外的约束条件。spring-doc.cadn.net.cn

谓词

你可以编写自己的 RequestPredicate，但 RequestPredicates 工具类提供了常用的实现，这些实现基于请求路径、HTTP 方法、内容类型（content-type）等。 以下示例使用一个请求谓词（request predicate）根据 Accept 请求头创建约束条件：spring-doc.cadn.net.cn

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")
	}
}

你可以通过使用以下方式将多个请求谓词组合在一起：spring-doc.cadn.net.cn

RequestPredicates 中的许多谓词都是组合而成的。 例如，RequestPredicates.GET(String) 就是由 RequestPredicates.method(HttpMethod) 和 RequestPredicates.path(String) 组合而成的。 上面所示的示例也使用了两个请求谓词，因为构建器在内部使用了 RequestPredicates.GET，并将其与 accept 谓词进行组合。spring-doc.cadn.net.cn

路由

路由函数按照声明顺序进行匹配：如果第一个路由不匹配，则评估第二个，依此类推。 因此，将更具体的路由声明在通用路由之前是有意义的。 这一点在将路由函数注册为 Spring Bean 时尤为重要，稍后将对此进行说明。 请注意，这种行为与基于注解的编程模型不同，在后者中会自动选择“最具体”的控制器方法。spring-doc.cadn.net.cn

使用路由函数构建器时，所有定义的路由会被组合成一个RouterFunction，并通过build()方法返回。 还有其他方式可以将多个路由函数组合在一起：spring-doc.cadn.net.cn

以下示例展示了四条路由的组合：spring-doc.cadn.net.cn

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 带有匹配 JSON 的 GET /person/{id} 请求头的 Accept 请求会被路由到 PersonHandler.getPerson
2 带有匹配 JSON 的 GET /person 请求头的 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 带有匹配 JSON 的 GET /person/{id} 请求头的 Accept 请求会被路由到 PersonHandler.getPerson
2 带有匹配 JSON 的 GET /person 请求头的 Accept 请求会被路由到 PersonHandler.listPeople
3 POST /person 请求在没有附加谓词的情况下被映射到 PersonHandler.createPerson，并且
4 otherRoute 是在其他地方创建的路由器函数，并被添加到所构建的路由中。

嵌套路由

通常，一组路由函数会共享一个相同的谓词（predicate），例如共享一个路径。 在上面的示例中，共享的谓词是一个路径谓词，匹配 /person， 被其中三个路由所使用。 使用注解时，你可以通过在类级别上使用 @RequestMapping 注解 来映射到 /person，从而消除这种重复。 在 WebMvc.fn 中，可以通过路由器函数构建器（router function builder）上的 path 方法 来共享路径谓词。 例如，可以通过使用嵌套路由，以如下方式改进上述示例的最后几行代码：spring-doc.cadn.net.cn

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 的第二个参数是一个接收路由构建器的消费者（Consumer）。 
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 结合使用来进一步优化：spring-doc.cadn.net.cn

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)
		}
	}
}

运行服务器

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您通常通过 DispatcherHandler 配置运行路由函数，该配置借助 Spring 配置声明处理请求所需的组件。MVC 配置 会声明以下基础设施组件以支持函数式端点：spring-doc.cadn.net.cn

  • RouterFunctionMapping：检测 Spring 配置中一个或多个 RouterFunction<?> Bean，对它们进行排序，通过 RouterFunction.andOther 将其组合，并将请求路由到最终合成的 RouterFunction。spring-doc.cadn.net.cn

  • HandlerFunctionAdapter：一个简单的适配器，允许 DispatcherHandler 调用已映射到请求的 HandlerFunction。spring-doc.cadn.net.cn

上述组件使函数式端点能够融入 DispatcherServlet 的请求处理生命周期，并且（如果存在）还可以与注解式控制器并行运行。这也是 Spring Boot Web Starter 启用函数式端点的方式。spring-doc.cadn.net.cn

以下示例展示了一个 WebFlux Java 配置：spring-doc.cadn.net.cn

@Configuration
@EnableMvc
public class WebConfig implements WebMvcConfigurer {

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

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

	// ...

	@Override
	public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
		// configure message conversion...
	}

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

	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		// configure view resolution for HTML rendering...
	}
}
@Configuration
@EnableMvc
class WebConfig : WebMvcConfigurer {

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

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

	// ...

	override fun configureMessageConverters(converters: List<HttpMessageConverter<*>>) {
		// configure message conversion...
	}

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

	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		// configure view resolution for HTML rendering...
	}
}

过滤处理函数

参见响应式栈中的等效内容spring-doc.cadn.net.cn

你可以通过在路由函数构建器（routing function builder）上使用 before、after 或 filter 方法来过滤处理函数。 使用注解时，你可以通过 @ControllerAdvice、ServletFilter 或两者结合来实现类似的功能。 该过滤器将应用于由该构建器创建的所有路由。 这意味着在嵌套路由中定义的过滤器不会应用于“顶层”路由。 例如，考虑以下示例：spring-doc.cadn.net.cn

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 仅对两个 GET 路由应用了添加自定义请求头的 before 过滤器。
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 仅对两个 GET 路由应用了添加自定义请求头的 before 过滤器。
2 应用于所有路由（包括嵌套路由）的after过滤器用于记录响应。

路由器构建器上的 filter 方法接收一个 HandlerFilterFunction： 这是一个函数，它接收一个 ServerRequest 和一个 HandlerFunction，并返回一个 ServerResponse。 其中的处理器函数参数代表链中的下一个元素。 这通常是被路由到的处理器，但如果应用了多个过滤器，它也可以是另一个过滤器。spring-doc.cadn.net.cn

现在，我们可以为路由添加一个简单的安全过滤器，前提是假设我们有一个 SecurityManager， 它能够判断某个特定路径是否被允许。 以下示例展示了如何实现这一点：spring-doc.cadn.net.cn

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) 是可选的。 我们仅在允许访问时才执行处理函数。spring-doc.cadn.net.cn

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

函数式端点的 CORS 支持是通过专用的 CorsFilter 提供的。