函式式端點
Spring Web MVC 包含 WebMvc.fn,這是一種輕量級的函數語言程式設計模型,其中函式用於路由和處理請求,並且契約被設計為不可變的。它是基於註解的程式設計模型的替代方案,但它執行在相同的 DispatcherServlet 上。
概述
在 WebMvc.fn 中,HTTP 請求由 HandlerFunction
處理:這是一個接受 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 自動檢測到,如 執行伺服器 中所述。
HandlerFunction
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
方法來建立它。你可以使用構建器來設定響應狀態、新增響應頭部或提供響應體。以下示例建立一個狀態為 200 (OK) 且內容為 JSON 的響應
-
Java
-
Kotlin
Person person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);
val person: Person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person)
以下示例展示瞭如何構建一個狀態為 201 (CREATED) 且包含 Location
頭部但沒有響應體的響應
-
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
方法提供 Server-Sent Events。該方法提供的構建器允許你傳送 String 或其他物件作為 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()
Handler 類
我們可以將處理函式寫成 Lambda 表示式,示例如下
-
Java
-
Kotlin
HandlerFunction<ServerResponse> helloWorld =
request -> ServerResponse.ok().body("Hello World");
val helloWorld: (ServerRequest) -> ServerResponse =
{ ServerResponse.ok().body("Hello World") }
這很方便,但在一個應用中我們需要多個函式,而多個內聯 Lambda 表示式可能會變得雜亂。因此,將相關的處理函式組合到一個 Handler 類中很有用,Handler 類在基於註解的應用中扮演著類似於 @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 是一個處理函式,它將倉庫中找到的所有 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 響應。 |
驗證
-
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 響應丟擲異常。 |
Handler 還可以透過建立和注入基於 LocalValidatorFactoryBean
的全域性 Validator
例項來使用標準的 bean 驗證 API (JSR-303)。請參閱 Spring Validation。
RouterFunction
路由函式用於將請求路由到相應的 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 | 包含與 JSON 匹配的 Accept 頭部 的 GET /person/{id} 請求被路由到 PersonHandler.getPerson |
2 | 包含與 JSON 匹配的 Accept 頭部 的 GET /person 請求被路由到 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 匹配的 Accept 頭部 的 GET /person/{id} 請求被路由到 PersonHandler.getPerson |
2 | 包含與 JSON 匹配的 Accept 頭部 的 GET /person 請求被路由到 PersonHandler.listPeople |
3 | 不帶附加謂詞的 POST /person 請求被對映到 PersonHandler.createPerson ,並且 |
4 | otherRoute 是一個在別處建立並新增到所構建路由中的路由函式。 |
巢狀路由
一組路由函式通常有一個共享謂詞,例如共享路徑。在上面的示例中,共享謂詞是一個匹配 /person
的路徑謂詞,被三個路由使用。使用註解時,你可以透過使用對映到 /person
的類級別 @RequestMapping
註解來消除這種重複。在 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 = 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();
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 FileUrlResource("public-resources/");
RouterFunction<ServerResponse> resources = RouterFunctions.resources("/resources/**", location);
val location = FileUrlResource("public-resources/")
val resources = router { resources("/resources/**", location) }
執行伺服器
你通常透過 MVC 配置 在基於 DispatcherHandler
的設定中執行路由函式,該配置使用 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) {
// 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...
}
}
過濾 Handler 函式
你可以使用路由函式構建器上的 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 提供。 |