Optional 不应出现在 RPC 序列化环节，必须剥离后使用原始类型或 POJO；可选性应由 IDL（如 Protobuf optional）定义，SDK 可封装 Optional 但不透传，Builder 构建的请求对象须为干净扁平 POJO。
在 rpc 框架的参数序列化环节，optional 本身不能也不该出现——它不是数据类型，而是 java 的空值语义包装器，没有序列化能力，强行传入会直接导致协议中断、跨语言失联或反序列化失败。所谓“避开断层坑点”，核心是守住边界：让 optional 只存在于服务端内部逻辑或客户端 sdk 封装层，绝不出现在序列化输入侧。
序列化前必须剥离 Optional 包装
所有参与网络传输的请求对象，字段类型必须是可序列化的原始类型、POJO 或标准集合（如 String、int、User、List<Order>），而非 Optional<User>。常见错误写法：
- 定义接口时用
void updateUser(Optional<User> user)—— 序列化器无法识别泛型容器，多数框架直接报错或静默丢弃 - DTO 类中声明
private Optional<String> nickname;—— Protobuf 不支持，JSON 序列化后变成{"nickname":{"present":true,"value":"Alice"}}，破坏契约
正确做法：字段保持非空语义，由调用方决定是否设值；未设字段在协议层天然为“缺失”或“null”，由服务端按业务规则解释。
用 IDL 显式表达可选性，而非靠语言特性
可选字段的语义应由接口定义语言（IDL）承载，而不是 Java 的 Optional：
- Protobuf（proto3 v3.15+）：用
optional string nickname = 2;，生成代码自动提供hasNickname()和getNicknameOrDefault("") - Thrift：用
optional string nickname，生成结构体中该字段默认为 null，无需额外包装 - Dubbo 泛化调用或 JSON-RPC：用 Map<String, Object> 接收参数，通过 key 是否存在判断字段是否提供
IDL 定义的可选性会被所有语言生成器一致理解，不会因 Java 端用了 Optional 而 Go 端无从映射。
客户端 SDK 可封装 Optional 提升调用体验，但绝不透传
SDK 层可以对上层暴露 Optional 风格 API，用于提升空安全和链式可读性，但内部必须解包后再构造真实请求对象：
- 对外：
Optional<User> result = userClient.findById(123); - 对内：SDK 内部调用
rpcStub.getUserById(123)（返回 User 或 null），再用Optional.ofNullable(...)包装返回给调用方 - 关键：Optional 仅在 SDK 返回那一刻创建，不参与任何网络字节流生成
警惕 Builder 模式中隐式 Optional 字段
使用 Builder 构建请求对象时，容易误将“未设置”等同于“Optional.empty()”。例如：
- 错误：Builder 内部用
private Optional<Long> timeoutMs;，setTimeout() 存入 Optional，build() 后仍保留 Optional 字段 - 正确：Builder 字段应为原始类型或 null 允许的引用类型（如
private Long timeoutMs;），build 时直接赋值给 POJO 的对应字段，POJO 中该字段为Long timeoutMs;
Builder 是构造工具，不是数据载体；最终参与序列化的，永远是干净、扁平、IDL 对齐的 POJO 实例。
不复杂但容易忽略：Optional 的归宿是方法返回值与本地处理链，不是网络字节流的起点。守住这个分界线，序列化节点就稳了。
