服务层接口返回值应使用Optional包装以显式表达“可能无结果”的契约，仅限返回值中使用，禁止用于字段或参数；需用orElse、map、orElseThrow等语义化方法处理，避免isPresent()+get()及跨层透传。

服务层接口返回值用 Optional 包装，核心是把“可能无结果”这一语义显式暴露给调用方，从而让上层无需再做 == null 判空——这不是省几行代码的事，而是契约升级。

只在方法返回值中使用 Optional

这是最根本的规范。例如查询类操作：

• ✅ 推荐：public Optional findUserById(Long id)
• ❌ 禁止：private Optional name;（字段）、void process(Optional order)（参数）

Spring Data JPA 的 JpaRepository.findById() 就是标准范例：它保证返回非 null 的 Optional 实例，哪怕查不到也返回 Optional.empty()。这意味着上层变量本身绝不会为 null，对它写 if (userOpt == null) 不仅多余，还会被 SonarQube 报告为反模式。

用语义化方法替代手动判空

拿到 Optional 后，别写 isPresent() + get() 套壳。这既没消除风险（get() 可能抛 NoSuchElementException），又掩盖了业务意图。

• 要默认值 → 用 orElse("guest") 或 orElseGet(() -> loadDefault())
• 要转换后取值 → 用 map(User::getEmail).orElse("no-email@example.com")
• 要查不到就报错 → 用 orElseThrow(() -> new UserNotFoundException(id))

避免跨层透传 Optional

Optional 不是数据载体，不能当 DTO 字段或 JSON 响应体直接返回：

• MyBatis、Jackson 2.8 之前不识别 Optional，序列化会失败或返回空对象
• 前端无法解析 Optional，EL 表达式如 ${user.name} 拿到的是 Optional 实例而非字符串
• 正确做法：Service 层返回 Optional，Controller 层解包后转成确定类型再响应

配合注解与工具强化契约

Optional 是语义表达，不是安全兜底。建议叠加以下手段：

• 在返回 Optional 的方法上加 @Nonnull（表明 Optional 本身非 null）
• 对底层可能返回 null 的调用，统一用 Optional.ofNullable(...) 封装，杜绝 Optional.of(null)
• 静态检查工具（如 SpotBugs）可配置规则，拦截 Optional 作为参数或字段的误用