Optional设计意图是显式表达“值可能存在/不存在”，避免NPE；使用边界为仅作返回值、禁作参数/字段/集合元素/接口返回；关键操作包括ofNullable/map/flatMap/orElseGet；典型误用有map内返回null、强制包装非空对象、isPresent+get反模式。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
一、为什么需要 Optional
• 解决传统 null 检查的痛点：避免层层嵌套（如 if (u != null && u.getAddr() != null && u.getAddr().getCity() != null)）
• 显式表达语义：“这个返回值可能不存在”比返回 null 更具契约感
• 编译期友好：调用方必须处理空场景（map/orElse/ifPresent 等强制介入），降低 NPE 概率
二、能做什么 & 不能做什么
✅ 推荐场景：
• 作为方法返回值（尤其查询类接口：如 findById、findByName）
• 链式转换单个对象（map、flatMap、filter）
• 提供默认逻辑（orElse、orElseGet、orElseThrow）
❌ 明确禁止：
• 不作方法参数（调用方传 Optional.empty() 还是 null？语义混乱）
• 不作类字段（破坏封装，序列化/反射/ORM 易出问题）
• 不放进集合（如 List<optional>></optional> —— 应该用 List<string></string> + 过滤）
• 不用于 Web 接口返回体（JSON 序列化为 null 或空对象，丢失语义，且前端无法区分“没数据”和“字段缺失”）
三、创建与判断：3 种创建方式 + 2 种判断习惯
• Optional.of(value) → 值确定非 null时用（否则立即抛 NPE）
• Optional.ofNullable(value) → 最常用，安全封装可能为 null 的结果（如 DAO 查询）
• Optional.empty() → 主动返回“无结果”，语义比 null 更清晰
• 判断存在性：
– isPresent() + get() 是反模式（破坏函数式风格，易漏检查）
– 推荐用 ifPresent()（消费）、map()（转换）、orElseXXX()（兜底）
四、高频操作与避坑点
• map()：适合值存在时做类型不变的转换（如 opt.map(String::toUpperCase)）
• flatMap()：适合转换后仍返回 Optional 的场景（避免 Optional<optional>></optional> 嵌套）
• filter()：按条件“二次筛选”，值存在但不满足 predicate 时返回 empty
• orElse() vs orElseGet()：
– orElse("default")：无论是否空，都执行右侧表达式（可能有副作用或开销）
– orElseGet(() -> loadDefault())：仅在空时才调用 Supplier（推荐用于耗时/有副作用逻辑）
• 致命误用：
– 在 map 内部返回 null（会变成 Optional.empty()，但掩盖了业务逻辑错误）
– 对已知非空对象强行包装（如 Optional.of(service.getUser())）—— 失去语义价值
