在 Spring WebFlux 中，返回多个对象时应直接使用 Flux 作为控制器方法返回类型；ResponseEntity 合法且非阻塞，而 Flux 反而不符合设计意图，且易引发错误。
在 spring webflux 中，返回多个对象时应直接使用 `flux
在响应式 Web 开发中，正确选择返回类型是保障异步、非阻塞行为的关键。许多开发者初接触 WebFlux 时会自然沿用 Spring MVC 的习惯——将响应体包裹在 ResponseEntity 中，并尝试组合为 ResponseEntity
✅ 推荐做法：直接返回 Flux
当无需动态定制 HTTP 状态码、响应头或重定向等元信息时，最简洁、高效且符合响应式语义的方式是直接返回 Flux
@GetMapping(value = "/to-do",
produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
public Flux<ToDo> getToDos() {
return repository.findAll(); // 非阻塞流式推送，自动适配 chunked transfer encoding
}同理，单对象场景下优先使用 Mono
@GetMapping(value = "/to-do/{toDoId}",
produces = {MediaType.APPLICATION_JSON_VALUE})
public Mono<ToDo> getToDo(@Valid @PathVariable Long toDoId) {
return repository.findById(toDoId);
}Spring WebFlux 会自动将 Flux
✅ 进阶需求：需自定义状态/头？用 ResponseEntity
若必须设置特定状态码（如 206 Partial Content）、自定义 Header（如 X-Total-Count）或 ETag，可安全使用 ResponseEntity
@GetMapping("/to-do")
public ResponseEntity<Flux<ToDo>> getToDosWithHeader() {
Flux<ToDo> flux = repository.findAll();
return ResponseEntity.ok()
.header("X-Backend", "Reactive-DB")
.body(flux); // ✅ 异步流体，状态与头立即写出，body 延迟推送
}根据 Spring 官方文档，ResponseEntity
❌ 避免 Flux
该类型语义错误：它表示“返回多个独立 HTTP 响应”，而 HTTP 协议规定一个请求只能对应一个响应（含状态行、头、体）。Spring 不支持此模式，强行使用会导致编译通过但运行时报 IllegalStateException 或静默失败，且无法实现预期的流式传输。
⚠️ 注意事项总结：
- 不要为“统一包装”而强行套用 ResponseEntity —— 简洁即安全；
- Flux
默认以 application/json 流式输出（JSON Array 模式需显式配置 spring.codec.json.array=true 或使用 @ResponseBody + 自定义 HttpMessageWriter）； - 若需对每个元素添加元数据（如时间戳、ID），应在 Flux 内部 map 转换，而非拆分为多个 ResponseEntity；
- 所有数据库操作（如 repository.findAll()）必须基于响应式驱动（如 R2DBC、Mongo Reactive）才能真正非阻塞。
掌握这一原则，即可在保持代码清晰性的同时，充分发挥 WebFlux 的响应式优势。
