Spring WebFlux 注解控制器：响应式编程的优雅入门 🚀

什么是 Spring WebFlux 注解控制器？

Spring WebFlux 提供了一种基于注解的编程模型，让开发者可以使用熟悉的 @Controller 和 @RestController 注解来构建响应式 Web 应用。这种方式让传统 Spring MVC 开发者能够平滑过渡到响应式编程世界。

NOTE

WebFlux 注解控制器与传统 Spring MVC 控制器在语法上几乎相同，但底层运行在响应式技术栈上，能够处理大量并发请求而不阻塞线程。

为什么需要响应式控制器？ 🤔

传统阻塞式 vs 响应式非阻塞式

让我们通过一个生动的比喻来理解：

餐厅服务员的比喻

• 传统阻塞式：服务员接到订单后，必须站在厨房门口等待菜品完成，期间不能服务其他客人
• 响应式非阻塞式：服务员接到订单后，把单子交给厨房就去服务其他客人，菜品好了会主动通知

核心设计哲学

Spring WebFlux 注解控制器的设计哲学体现在以下几个方面：

1. 熟悉性优先 ✅

保持与 Spring MVC 相同的注解语法，降低学习成本

2. 灵活的方法签名 🔧

不需要继承特定基类或实现特定接口，方法签名完全自由

3. 响应式优先 ⚡

底层基于 Reactor 框架，天然支持背压和流式处理

基础示例：Hello WebFlux

让我们从最简单的例子开始：

传统阻塞式

@RestController
class TraditionalController {
    
    @GetMapping("/hello")
    fun hello(): String {
        // 这里可能有耗时操作，会阻塞线程
        Thread.sleep(1000) 
        return "Hello Traditional"
    }
}

响应式非阻塞

@RestController
class ReactiveController {
    
    @GetMapping("/hello")
    fun hello(): Mono<String> { 
        return Mono.just("Hello WebFlux") 
            .delayElement(Duration.ofSeconds(1)) // 模拟异步操作
    }
}

IMPORTANT

注意返回类型的差异：响应式控制器返回 Mono<T> 或 Flux<T>，这些是响应式流的核心类型。

实际业务场景示例

场景：用户信息查询服务

假设我们要构建一个用户信息查询服务，需要从数据库获取用户信息：

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {
    
    // 查询单个用户
    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): Mono<UserDto> { 
        return userService.findById(id) 
            .map { user -> UserDto.from(user) } 
            .switchIfEmpty(Mono.error(UserNotFoundException(id))) 
    }
    
    // 查询所有用户（流式返回）
    @GetMapping
    fun getAllUsers(): Flux<UserDto> { 
        return userService.findAll() 
            .map { user -> UserDto.from(user) } 
    }
    
    // 创建用户
    @PostMapping
    fun createUser(@RequestBody @Valid userRequest: CreateUserRequest): Mono<UserDto> {
        return userService.create(userRequest) 
            .map { user -> UserDto.from(user) } 
    }
}

支持的服务层实现

@Service
class UserService(
    private val userRepository: ReactiveUserRepository
) {
    
    fun findById(id: Long): Mono<User> {
        return userRepository.findById(id) 
    }
    
    fun findAll(): Flux<User> {
        return userRepository.findAll() 
    }
    
    fun create(request: CreateUserRequest): Mono<User> {
        val user = User(
            name = request.name,
            email = request.email
        )
        return userRepository.save(user) 
    }
}

方法签名的灵活性

WebFlux 控制器支持多种方法签名，以下是常见的几种：

1. 简单返回值

@GetMapping("/simple")
fun simple(): String = "Simple response"

2. 响应式返回值

@GetMapping("/mono")
fun mono(): Mono<String> = Mono.just("Mono response") 

@GetMapping("/flux")
fun flux(): Flux<String> = Flux.just("A", "B", "C") 

3. 带参数的方法

@GetMapping("/users/{id}")
fun getUser(
    @PathVariable id: Long, 
    @RequestParam(defaultValue = "false") includeDetails: Boolean, 
    @RequestHeader("User-Agent") userAgent: String
): Mono<UserDto> {
    return userService.findById(id, includeDetails)
        .map { UserDto.from(it) }
}

4. 请求体处理

@PostMapping("/users")
fun createUser(@RequestBody user: Mono<CreateUserRequest>): Mono<UserDto> { 
    return user
        .flatMap { userService.create(it) } 
        .map { UserDto.from(it) }
}

错误处理的响应式方式

@RestController
class UserController {
    
    @GetMapping("/users/{id}")
    fun getUser(@PathVariable id: Long): Mono<UserDto> {
        return userService.findById(id)
            .map { UserDto.from(it) }
            .switchIfEmpty(Mono.error(UserNotFoundException("User not found: $id"))) 
            .onErrorMap { throwable ->
                when (throwable) {
                    is DataAccessException -> ServiceException("Database error", throwable)
                    else -> throwable
                }
            }
    }
    
    // 全局异常处理
    @ExceptionHandler(UserNotFoundException::class)
    fun handleUserNotFound(ex: UserNotFoundException): Mono<ResponseEntity<ErrorResponse>> { 
        val errorResponse = ErrorResponse(
            code = "USER_NOT_FOUND",
            message = ex.message ?: "User not found"
        )
        return Mono.just(ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse)) 
    }
}

性能对比：传统 vs 响应式

让我们通过一个具体的性能测试场景来理解差异：

模拟高并发场景

@RestController
class PerformanceTestController(
    private val externalApiService: ExternalApiService
) {
    
    // 传统阻塞式：每个请求占用一个线程
    @GetMapping("/blocking/data")
    fun getDataBlocking(): String {
        // 模拟调用外部API，耗时1秒
        Thread.sleep(1000) 
        return "Blocking response"
    }
    
    // 响应式非阻塞：线程可以处理其他请求
    @GetMapping("/reactive/data")
    fun getDataReactive(): Mono<String> {
        return externalApiService.fetchData() 
            .map { "Reactive response: $it" }
    }
}

WARNING

在传统阻塞模式下，1000个并发请求需要1000个线程；而响应式模式下，可能只需要几个线程就能处理相同的负载。

最佳实践建议

1. 返回类型选择

返回类型指南

• 单个对象：使用 Mono<T>
• 集合/流：使用 Flux<T>
• 简单值：可以直接返回 T，框架会自动包装

2. 异常处理

@GetMapping("/safe-operation")
fun safeOperation(): Mono<String> {
    return performRiskyOperation()
        .onErrorReturn("Default value") 
        .doOnError { logger.error("Operation failed", it) } 
}

3. 背压处理

@GetMapping(value = ["/stream"], produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun streamData(): Flux<String> {
    return Flux.interval(Duration.ofSeconds(1)) 
        .map { "Data chunk: $it" }
        .take(100) // 限制数据量，避免无限流
}

总结

Spring WebFlux 注解控制器为我们提供了一种优雅的方式来构建高性能的响应式 Web 应用：

✅ 熟悉的语法：与 Spring MVC 几乎相同的注解和用法 ✅ 高性能：非阻塞 I/O，更好的资源利用率
✅ 灵活性：支持多种返回类型和方法签名 ✅ 可扩展性：天然支持流式处理和背压控制

TIP

开始使用 WebFlux 时，可以先从简单的 CRUD 操作开始，逐步探索响应式编程的强大功能。记住，响应式编程的核心是"异步非阻塞"，这将为你的应用带来更好的性能和用户体验！