跳到主要内容
版本：7.0.3

功能端点

Hunyuan 7b 中英对照 Functional Endpoints

Spring Web MVC 包含了 WebMvc.fn，这是一种轻量级的函数式编程模型，在该模型中，函数被用来路由和处理请求，并且契约设计为不可变的。它是基于注解的编程模型的替代方案，但在其他方面仍然运行在相同的 DispatcherServlet 上。

概述​

在 WebMvc.fn 中，HTTP 请求是通过 HandlerFunction 来处理的：这个函数接收一个 ServerRequest 并返回一个 ServerResponse。请求对象和响应对象都具有不可变的协议（immutable contracts），这些协议提供了对 HTTP 请求和响应的、与 JDK 8 兼容的访问方式。HandlerFunction 相当于基于注解的编程模型中 @RequestMapping 方法的实现体（body）。

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

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

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) {
		// ...
	}
}

  • 使用 route() 创建路由器。

如果你将RouterFunction注册为bean，例如通过在一个@Configuration类中公开它，那么servlet会自动检测到它，如运行服务器中所解释的那样。

HandlerFunction​

ServerRequest 和 ServerResponse 是不可变接口，它们提供了对 HTTP 请求和响应的访问，包括请求头（headers）、请求体（body）、请求方法（method）以及状态码（status code），并且与 JDK 8 兼容。

ServerRequest​

ServerRequest 提供了对 HTTP 方法、URI、头部信息和查询参数的访问权限，而通过 body 方法可以访问请求体（request body）。

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

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

以下示例将正文提取到一个List<Person>中，其中Person对象是从序列化形式（如JSON或XML）解码而来的：

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

以下示例展示了如何访问参数：

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

以下展示了如何通过DataBinder绑定请求参数、URI变量或请求头，同时也展示了如何自定义DataBinder：

Pet pet = request.bind(Pet.class, dataBinder -> dataBinder.setAllowedFields("name"));

ServerResponse​

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

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

以下示例展示了如何构建一个带有Location头部但没有正文的201（CREATED）响应：

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

你也可以使用异步结果作为主体，形式可以是CompletableFuture、Publisher，或者是ReactiveAdapterRegistry支持的任何其他类型。例如：

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

如果不仅响应体（body），还有响应状态（status）或响应头（headers）都是异步类型的，那么你可以在ServerResponse上使用静态的async方法，该方法接受CompletableFuture<ServerResponse>、Publisher<ServerResponse>，或者ReactiveAdapterRegistry支持的任何其他异步类型。例如：

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 格式发送其他对象。例如：

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();

处理器类​

我们可以像下面的例子所示，将处理函数写成lambda表达式：

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

那很方便，但在一个应用程序中我们需要多个功能，而过多的内联lambda表达式会让人感到困惑。因此，将相关的处理函数组合到一个处理类中是有用的，这个类的作用类似于基于注解的应用程序中的@Controller。例如，以下类暴露了一个响应式的Person仓库：

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

}

  • listPeople 是一个处理函数，它将仓库中找到的所有 Person 对象以 JSON 格式返回。

  • createPerson 是一个处理函数，用于存储请求体中包含的新 Person 对象。

  • getPerson 是一个处理函数，根据 id 路径变量来获取单个人员。如果找到该人员，就从仓库中检索并返回 JSON 响应；如果没有找到，则返回 404 “未找到” 响应。

验证​

一个功能性的端点可以使用Spring的验证机制对请求体进行验证。例如，对于一个为Person类实现的自定义Spring Validator，可以这样做：

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

  • 创建 Validator 实例。

  • 应用验证。

  • 为 400 响应抛出异常。

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

RouterFunction #webmvc-fn-router-functions​

路由器函数用于将请求路由到相应的HandlerFunction。通常，你不需要自己编写路由器函数，而是使用RouterFunctions工具类中的方法来创建它们。RouterFunctions.route()（无参数）提供了一个流畅的构建器来创建路由器函数，而RouterFunctions.route(RequestPredicate, HandlerFunction)则提供了一种直接创建路由器的方法。

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

除了基于HTTP方法的映射之外，路由构建器还提供了一种在映射请求时引入额外谓词（predicates）的方法。对于每种HTTP方法，都有一个重载版本（overloaded variant），该版本接受一个RequestPredicate作为参数，通过这个参数可以表达额外的约束条件。

谓词​

你可以编写自己的RequestPredicate，但是RequestPredicates工具类提供了基于HTTP方法、请求路径、头部信息、API版本等常见匹配需求的内置选项。

以下示例使用了Accept头和请求谓词：

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

您可以使用以下方法将多个请求谓词组合在一起：

  • 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) —— 这是带有嵌套 RouterFunctions.route() 的 RouterFunction.and() 的快捷方式。

以下示例展示了四条路由的组成：

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();

  • GET /person/{id} 请求若带有匹配 JSON 的 Accept 头部，则会路由到 PersonHandler.getPerson

  • GET /person 请求若带有匹配 JSON 的 Accept 头部，则会路由到 PersonHandler.listPeople

  • \ [#3] 不带其他条件的 POST /person 请求会映射到 PersonHandler.createPerson
  • \ [#4] otherRoute 是在其他地方创建的路由函数，然后被添加到此路由中。

嵌套路由​

通常情况下，一组路由函数会共享一个谓词（predicate），例如一个共同的路径。在上面的例子中，这个共享的谓词就是一个匹配 /person 的路径谓词，被三条路由所使用。当使用注解时，可以通过使用类型级别的 @RequestMapping 注解来消除这种重复，该注解映射到 /person。在 WebMvc.fn 中，可以通过路由器函数构建器（router function builder）上的 path 方法来共享路径谓词。例如，上面例子中的最后几行可以通过使用嵌套路由（nested routes）以以下方式进行优化：

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();

  • 注意 path 方法的第二个参数是一个接收路由器构建器的函数。

尽管基于路径的嵌套是最常见的，但你可以使用构建器上的nest方法对任何类型的谓词进行嵌套。上述代码中仍然存在一些重复，例如共享的Accept头部谓词。我们可以通过结合使用nest方法和accept来进一步优化：

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();

API版本​

路由器功能支持按API版本进行匹配。

首先，在MVC配置中启用API版本控制，然后你就可以按照以下方式使用version谓词了：

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

version谓词可以是：

  • 固定版本（“1.2”）——仅匹配给定的版本。
  • 基线版本（“1.2+”）——匹配给定版本及以上的版本，直至最高的[支持版本]（webmvc/mvc-config/api-version.md）。

有关底层基础设施和API版本控制支持的更多详细信息，请参阅API版本控制。

提供资源​

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

备注

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

重定向到资源​

可以将与指定谓词匹配的请求重定向到某个资源。例如，在单页应用（Single Page Applications）中处理重定向时，这种方法会非常有用。

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

从根目录位置提供资源​

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

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

运行服务器​

在基于 DispatcherHandler 的设置中，你通常会通过 MVC Config 来运行路由器功能，该配置使用 Spring 配置来声明处理请求所需的组件。MVC Java 配置声明了以下基础设施组件以支持功能端点：

  • RouterFunctionMapping: 检测Spring配置中一个或多个RouterFunction<?> bean，按顺序排列它们，通过RouterFunction.andOther将它们组合起来，然后将请求路由到生成的复合RouterFunction。

  • HandlerFunctionAdapter: 一个简单的适配器，允许DispatcherHandler调用被映射到请求的HandlerFunction。

上述组件使得功能型端点能够适应DispatcherServlet的请求处理生命周期，同时（如果声明了注解控制器的话）也有可能与这些控制器并行运行。这也是Spring Boot Web启动器启用功能型端点的方式。

以下示例展示了一个相关的Spring MVC配置：

@Configuration
public class WebConfiguration implements WebMvcConfigurer {

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

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

	@Override
	public void configureMessageConverters(HttpMessageConverters.ServerBuilder builder) {
		// configure message conversion...
	}

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

	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		// configure view resolution for HTML rendering...
	}
}

过滤处理函数​

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

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();

  • before过滤器用于添加自定义请求头，仅适用于这两个GET路由。

  • after过滤器用于记录响应，适用于所有路由，包括嵌套路由。

路由器构建器（router builder）上的filter方法接受一个HandlerFilterFunction：这个函数接收一个ServerRequest和一个HandlerFunction，并返回一个ServerResponse。HandlerFunction参数代表处理链中的下一个元素。这通常是会被路由到的处理函数（handler），但如果应用了多个过滤器（filters），它也可以是指另一个过滤器。

现在我们可以在路由中添加一个简单的安全过滤器，前提是我们有一个SecurityManager，它能够判断某个路径是否被允许。以下示例展示了如何实现这一点：

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();

前面的例子说明了调用next.handle(ServerRequest)是可选的。我们只有在允许访问时才会运行处理函数。

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

备注

函数端点的CORS支持是通过一个专门的CorsFilter提供的。