optional仅用于返回值场景，禁止作参数、dto字段或调用get()；应通过checkstyle规则、ai语义审查及团队规范协同防控误用。
不能靠自定义工具类“强制检查”Optional规范——这不是它的设计场景，也违背Java类型系统的设计逻辑。Optional是编译期语义容器，不是运行时校验开关。真正该做的是：用工具链卡住误用、用约定约束使用边界、用代码审查聚焦高频风险点。
明确Optional的合法使用边界
它只应在返回值场景中表达“可能无结果”，比如查询、查找、转换等操作。以下属于典型误用，必须从源头拦截：
- 作为方法参数（如
public void process(Optional<string> name)</string>）——语义混乱，调用方本可直接传null或空字符串 - 在DTO/VO/Controller入参中包装字段（如
@RequestBody UserRequest{Optional<string> phone}</string>）——破坏校验职责，掩盖字段必填性 - 用
Optional.get()代替orElse或ifPresent——等于变相写if (x == null) throw NPE - 嵌套Optional（如
Optional<optional>></optional>）——违反单一抽象，应改用flatMap扁平化
用Checkstyle + 自定义规则堵住常见误用
Checkstyle本身不检查Optional语义，但可通过自定义模块识别危险模式。例如，在checkstyle.xml中添加：
- 禁止
Optional.get()调用：<module name="Regexp"><property name="format" value="\.get\(\)"></property></module> - 禁止参数类型为Optional：
<module name="ParameterName"><property name="format" value="^((?!Optional).)*$"></property></module>（配合正则排除） - 强制Javadoc说明Optional语义：
<module name="JavadocMethod"><property name="allowMissingParamTags" value="false"></property></module>，要求文档注明“返回Optional表示xxx未找到”
这些规则可在Maven构建阶段失败，比Code Review更早拦截问题。
用AI Reviewer代理做语义级把关
everything-claude-code中的Java Reviewer代理（位于agents/java-reviewer.md）能识别Optional的上下文合理性。例如：
- 检测
findUserById返回Optional<user></user>✅ 合理 - 检测
createUser(User user)参数为Optional<user></user>❌ 标记为“参数Optional滥用，应校验非空” - 发现
map(...).get()链式调用 ❌ 提示“避免get()，改用orElse/flatMap”
它不依赖字符串匹配，而是结合AST和Spring Boot项目结构理解业务意图，适合集成进CI流水线做PR自动评论。
团队落地的关键动作
工具只是防线，共识才是根基：
- 在
skills/java-coding-standards/目录下明确定义：“Optional仅用于返回值；所有find/get/lookup类方法必须返回Optional；禁止出现在方法签名左侧” - 新成员入职时，用真实case跑一遍Checkstyle+AI Reviewer报告，现场讲解每条警告背后的故障案例（如某次因
get()导致支付订单状态误判） - 将“Optional误用”纳入线上事故复盘清单——只要因Optional空值未处理引发NPE，就回溯是否Checkstyle漏配、Reviewer未启用、或培训未覆盖
