此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Framework 6.2.0spring-doc.cadn.net.cn

功能端点

Spring Web MVC 包括 WebMvc.fn,这是一个轻量级函数式编程模型,其中函数 用于路由和处理请求,而 Contract 旨在实现不变性。 它是基于 Comments 的编程模型的替代方案,但在其他方面运行 相同的 DispatcherServletspring-doc.cadn.net.cn

概述

在 WebMvc.fn 中,HTTP 请求使用HandlerFunction:一个函数,该函数采用ServerRequest并返回一个ServerResponse. 请求和响应对象都有不可变的契约,这些契约提供对 JDK 8 友好的 访问 HTTP 请求和响应。HandlerFunction等价于@RequestMapping方法中的 基于注释的编程模型。spring-doc.cadn.net.cn

传入请求被路由到具有RouterFunction:一个函数,该函数 需要ServerRequest并返回一个可选的HandlerFunction(即Optional<HandlerFunction>). 当 router 函数匹配时,将返回一个处理程序函数;否则为空 Optional。RouterFunction等价于@RequestMapping注解,但带有 major 不同之处在于 router 函数不仅提供数据,还提供行为。spring-doc.cadn.net.cn

RouterFunctions.route()提供便于创建路由器的 Router 构建器, 如下例所示: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 使用 创建 routerroute().

如果您注册了RouterFunction作为 Bean 进行 Bean 处理,例如,通过在@Configuration类中,它将由 Servlet 自动检测,如 运行服务器中所述。spring-doc.cadn.net.cn

HandlerFunction 函数

ServerRequestServerResponse是提供 JDK 8 友好的不可变接口 访问 HTTP 请求和响应,包括标头、正文、方法和状态代码。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);

以下示例将主体提取到List<Person>, 哪里Person对象从序列化形式(如 JSON 或 XML)解码:spring-doc.cadn.net.cn

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

以下示例显示如何访问参数:spring-doc.cadn.net.cn

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

服务器响应

ServerResponse提供对 HTTP 响应的访问,并且由于它是不可变的,因此您可以使用 一个build方法创建它。您可以使用生成器设置响应状态,以添加响应 headers 或提供正文。以下示例使用 JSON 创建 200 (OK) 响应 内容:spring-doc.cadn.net.cn

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

以下示例显示了如何使用Locationheader 且没有正文:spring-doc.cadn.net.cn

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

您还可以使用异步结果作为正文,采用CompletableFuture,PublisherReactiveAdapterRegistry.例如:spring-doc.cadn.net.cn

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

如果不仅 body 基于 body,而且 status 或 headers 都基于异步类型, 您可以使用 staticasyncmethod 开启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 可以通过 静态的ssemethod 开启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();

处理程序类

我们可以将处理程序函数编写为 lambda,如下例所示:spring-doc.cadn.net.cn

HandlerFunction<ServerResponse> helloWorld =
  request -> 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 的 JSON 格式。
2 createPerson是一个处理程序函数,它将新的Person包含在请求正文中。
3 getPerson是一个处理程序函数,它返回一个 person,由id路径 变量。我们检索该Person并创建 JSON 响应(如果是 发现。如果未找到,我们将返回 404 Not Found 响应。

验证

功能性端点可以使用 Spring 的验证工具来 对请求正文应用验证。例如,给定一个自定义的 Spring Validator 实现Person: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 响应的异常。

处理程序还可以通过创建和注入来使用标准 bean 验证 API (JSR-303) 一个全局Validator实例基于LocalValidatorFactoryBean. 参见 Spring Validationspring-doc.cadn.net.cn

RouterFunction

Router 函数用于将请求路由到相应的HandlerFunction. 通常,您不会自己编写 router 函数,而是在RouterFunctionsUtility 类来创建一个。RouterFunctions.route()(无参数)为您提供用于创建路由器的 Fluent 构建器 函数,而RouterFunctions.route(RequestPredicate, HandlerFunction)提供直接方式 创建路由器。spring-doc.cadn.net.cn

通常建议使用route()builder,因为它提供了 适用于典型映射场景的便捷捷径,无需难以发现 static imports。 例如,router 函数构建器提供了GET(String, HandlerFunction)为 GET 请求创建映射;和POST(String, HandlerFunction)用于 POST。spring-doc.cadn.net.cn

除了基于 HTTP 方法的映射之外,路由构建器还提供了一种引入其他 谓词。 对于每个 HTTP 方法,都有一个重载的变体,它采用RequestPredicate作为 参数,通过该参数可以表示其他约束。spring-doc.cadn.net.cn

谓词

您可以编写自己的RequestPredicate,但RequestPredicatesUtility 类 提供常用的实现,基于请求路径、HTTP 方法、内容类型、 等等。 以下示例使用请求谓词基于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();

您可以使用以下方法将多个请求谓词组合在一起:spring-doc.cadn.net.cn

许多来自RequestPredicates组成。 例如RequestPredicates.GET(String)RequestPredicates.method(HttpMethod)RequestPredicates.path(String). 上面显示的示例还使用了两个请求谓词,因为生成器使用RequestPredicates.GET内部,并使用accept谓语。spring-doc.cadn.net.cn

路线

路由器功能按顺序评估:如果第一个路由不匹配,则 second 被评估,依此类推。 因此,在一般路由之前声明更具体的路由是有意义的。 在将路由器函数注册为 Spring bean 时,这一点也很重要,也是如此 稍后描述。 请注意,此行为与基于 Comments 的编程模型不同,其中 “最具体”控制器方法会自动选取。spring-doc.cadn.net.cn

当使用 router 函数构建器时,所有定义的路由都组合成一个RouterFunction即从build(). 还有其他方法可以将多个 router 功能组合在一起: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 GET /person/{id}替换为Accept匹配 JSON 的标头将路由到PersonHandler.getPerson
2 GET /person替换为Accept匹配 JSON 的标头将路由到PersonHandler.listPeople
3 POST /person没有其他谓词映射到PersonHandler.createPerson
4 otherRoute是在其他地方创建并添加到 Route built 的 router 函数。

嵌套路由

一组 router 函数通常具有共享谓词,例如共享的 路径。 在上面的示例中,共享谓词将是匹配的路径谓词/person, 由其中 3 条路由使用。 使用注释时,可以使用类型级@RequestMapping注解,映射到/person. 在 WebMvc.fn 中,可以通过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是采用 router builder 的 consumer。

尽管基于路径的嵌套是最常见的,但你可以使用 这nest方法。 以上仍然包含一些共享Accept-header 谓词。 我们可以通过使用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();

服务资源

WebMvc.fn 提供对服务资源的内置支持。spring-doc.cadn.net.cn

除了下面描述的功能之外,还可以实现更灵活的资源处理,这要归功于RouterFunctions#resource(java.util.function.Function).

重定向到资源

可以将与指定谓词匹配的请求重定向到资源。这可能很有用,例如, 用于处理单页应用程序中的重定向。spring-doc.cadn.net.cn

   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")).or(pathExtension(extensions::contains)).negate();
RouterFunction<ServerResponse> redirectToIndex = route()
	.resource(spaPredicate, index)
	.build();

从根位置提供资源

还可以将匹配给定模式的请求路由到相对于给定根位置的资源。spring-doc.cadn.net.cn

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

运行 Server

通常在DispatcherHandler-based 设置,它使用 Spring 配置来声明 处理请求所需的组件。MVC Java 配置声明以下内容 支持功能终端节点的基础设施组件:spring-doc.cadn.net.cn

  • RouterFunctionMapping:检测到一个或多个RouterFunction<?>Spring的咖啡豆 配置、排序、组合RouterFunction.andOther,并将请求路由到生成的 composeRouterFunction.spring-doc.cadn.net.cn

  • HandlerFunctionAdapter:简单的适配器,让DispatcherHandler调用 一个HandlerFunction该请求已映射到一个请求。spring-doc.cadn.net.cn

前面的组件允许功能端点适应DispatcherServlet请求 处理生命周期,并且(可能)与带注释的控制器并行运行,如果 任何 (any) 都已声明。这也是 Spring Boot Web 启用功能端点的方式 起动机。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...
	}
}

筛选处理程序函数

您可以使用before,afterfilter路由上的 methods 函数构建器。 通过 annotations,您可以通过使用@ControllerAdvice一个ServletFilter和/或两者。 该筛选条件将应用于构建器构建的所有路由。 这意味着嵌套路由中定义的筛选条件不适用于 “top-level” 路由。 例如,请考虑以下示例: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 before添加自定义请求标头的 filter 仅适用于两个 GET 路由。
2 afterfilter 记录响应的 filter 应用于所有路由,包括嵌套路由。

filter方法采用HandlerFilterFunction:一个 函数,该函数采用ServerRequestHandlerFunction并返回一个ServerResponse. handler 函数参数表示链中的下一个元素。 这通常是路由到的处理程序,但也可以是另一个 filter (如果应用了多个)。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();

前面的示例演示了调用next.handle(ServerRequest)是可选的。 我们只允许在允许访问时运行处理程序函数。spring-doc.cadn.net.cn

除了使用filter方法,则可以应用 过滤到现有的 router 函数RouterFunction.filter(HandlerFilterFunction).spring-doc.cadn.net.cn

对功能端点的 CORS 支持通过专用的CorsFilter.

APP信息