Controller层不应直接返回Optional作为HTTP响应体，而应解包为Result.success()或抛异常交由@ControllerAdvice统一处理，避免Jackson序列化问题和Swagger文档失效。
Controller 层**不应当直接返回 Optional 作为 HTTP 响应体**——这是 Spring Boot 实战中最常被误用的点之一。它的核心定位是“方法返回值契约表达”，不是数据传输载体。
Controller 层必须解包 Optional
Spring MVC 的返回值需序列化为 JSON（或视图），而 Jackson 默认不识别 Optional，直接返回会导致：
- 空 Optional 序列化为
null或空对象（如{}），前端无法区分“查无结果”和“字段缺失” - 非空 Optional 序列化为包装结构（如
{"present":true,"value":{"id":123,...}}），破坏接口契约 - Swagger 文档无法正确推导响应类型，
@ApiResponse注解失效
正确做法：在 Controller 中调用 Service 返回的 Optional<User> 后，立即用语义化方法解包：
-
.map(user -> Result.success(user))→ 存在则封装成功响应 -
.orElseThrow(() -> new ResourceNotFoundException("用户不存在"))→ 不存在则抛异常，交由@ControllerAdvice统一转为 404 -
.orElse(Result.success(null))→ 明确返回“空数据但操作成功”（如分页列表无记录）
参数接收可简化，但别滥用 Optional 包装
Controller 接收可选请求参数时，可用 Optional<String> 替代 @RequestParam(required = false)，效果等价且更函数式：
立即学习“Java免费学习笔记（深入）”；
-
@RequestParam Optional<Long> userId等同于@RequestParam(required = false) Long userId - 后续用
userId.orElse(0L)或userId.filter(id -> id > 0).orElseThrow(...)处理 - 注意：
Optional仅用于单个参数，不可用于@RequestBodyDTO 字段（DTO 内部仍用String、Integer等原始/包装类型）
配合统一结果类与全局异常
解包后的业务逻辑应输出标准结构，例如 Result<User>：
- Service 返回
Optional<User>→ 显式表达“查不到是正常业务流” - Controller 解包并构造
Result.success(user)或抛ResourceNotFoundException -
@ControllerAdvice捕获该异常，返回Result.fail(404, "用户不存在")
这样既守住 Optional 的契约价值，又保证对外 API 清晰、可测、可文档化。
