Java中Optional应作为API契约语言精准表达“可能无结果”的业务语义，仅用于返回值，禁用于字段和参数；需配合Javadoc说明空值业务含义，并通过map/filter/orElseThrow等语义化方式消费。
Java 中用 Optional 设计清晰的 API 契约接口，关键不是“加个 Optional 就算契约”，而是让它的存在本身成为业务语义的精确表达——调用方一眼看懂“这里可能没结果”，且无法绕过这个事实。
只在返回值中使用 Optional
这是最硬性的边界。Optional 是契约语言，不是空值胶带。
- 服务层查询方法如
findUserById(Long id)、getConfigByKey(String key)必须返回Optional<User>或Optional<Config>，明确告诉调用方：“查不到是合法状态，你得处理” - 禁止把 Optional 当字段类型（如
private Optional<String> email;），它不支持序列化，破坏 DTO/VO 语义，也模糊了“空”到底是业务缺失还是初始化未完成 - 禁止作为参数传入（如
saveUser(Optional<User> user)），这会让调用方困惑：是我该传 empty？还是你不接受 null？语义倒置
用 ofNullable() 封装真实数据源，不用 of() 做防御
Optional.of() 不是空检查工具，它是“我保证非空”的宣言；而真实业务逻辑里，数据库查询、远程调用、缓存读取都天然可能返回 null。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- MyBatis 的
selectOne()、JPA 的findById()返回 null 时，统一用Optional.ofNullable(result) - 不要写
result != null ? Optional.of(result) : Optional.empty()—— 这既冗余又掩盖了 ofNullable 的本意 - 只有在你 100% 确认值存在、且想强制下游以 Optional 方式消费时，才用
of()，例如：配置加载后解析出的必填项、Spring Bean 注入后的非空依赖包装
在接口 Javadoc 中定义“空”的业务含义
Optional 只说“可能为空”，但空代表什么，必须由契约说明。
立即学习“Java免费学习笔记（深入）”；
- 在方法上写明：
@return Optional containing the user if found and active; empty if not found or disabled - 标注触发空的条件：
@throws UserDisabledException if user exists but status is INACTIVE（注意：异常和 Optional 并不互斥，前者是错误，后者是正常流程分支） - 避免模糊描述如 “returns empty if failed”——失败是系统异常，不是业务空值；应区分 “not found”（Optional.empty） 和 “connection timeout”（抛 RuntimeException）
提供语义化消费方式，不暴露 get() 或 isPresent()
如果调用方还能写出 if (opt.isPresent()) { opt.get().xxx(); }，说明契约没立住——这不是 Optional 的用法，是披着 Optional 外衣的 null 检查。
- 推荐组合：
map()转换、filter()校验、orElseThrow()显式转异常、orElseGet()延迟构造默认值 - Controller 层面对前端，常用
orElseThrow(() -> new BusinessException("资源不存在"))统一转 HTTP 404 - 内部服务间调用，可用
map(this::enrich).orElse(null)（仅限不得已向下兼容老代码），但不应出现在新契约接口的文档示例中
