业务网关中应统一用Optional构建语义清晰、可复用、易拦截的校验契约，仅在校验入口处封装解析后的关键字段，配合封装的Check工具类与GatewayException实现强校验和标准化错误响应。
在业务网关中统一校验空值，核心不是把 Optional 当“万能胶”贴满各处，而是用它构建**语义清晰、可复用、易拦截**的校验契约。网关作为流量入口，天然适合做前置强校验，而 Optional 的 orElseThrow 配合工具类封装，恰好能承担这个角色。
只在校验入口处用 Optional，不进参数、不进字段
网关层接收的是原始请求（如 HttpServletRequest、DTO、JSON Map），这些对象本身不适合被包装成 Optional 字段或作为方法参数传入。正确做法是：在解析完请求、映射为业务对象后，立即用 Optional 封装关键必填字段，再统一校验。
- ✅ 正确：将解析后的 UserContext userCtx = parseUserContext(request) 包装为 Optional.ofNullable(userCtx)，再链式校验其 ID、token、tenantId
- ❌ 错误：定义方法 void handle(Optional
ctx) 或在网关实体类里加 private OptionalappId; —— JDK 官方明确反对，且破坏序列化与调试体验
封装 Check 工具类，对接网关异常规范
网关通常要求所有校验失败返回统一错误码（如 GATEWAY_PARAM_MISSING）、标准结构（code/msg/data）和 HTTP 状态码（400）。直接写 Optional.ofNullable(x).orElseThrow() 会散落各处，难以维护。应封装静态校验工具：
- Check.notNull(obj, "用户上下文", ErrCode.GATEWAY_USER_CTX_MISSING) → 内部调用 Optional.ofNullable(obj).orElseThrow(() -> new GatewayException(code, msg))
- Check.hasText(str, "渠道编码", ErrCode.GATEWAY_CHANNEL_EMPTY) → 先判 null 再判 blank，同样走 orElseThrow
- 所有异常继承自 GatewayException，由全局 ControllerAdvice 捕获并格式化响应体
多层级嵌套字段校验，用 flatMap + 自定义提取器
网关常需校验深层字段，比如 request.getHeader("X-Trace-ID") → parseTrace(…) → getTenant().getCode()。传统 if 嵌套易漏，纯 Optional 链又冗长。推荐组合方式：
立即学习“Java免费学习笔记（深入）”；
- 定义提取器： static <T> Optional<T> safeGet(Supplier<T> supplier)，内部捕获 NPE 并返回 empty
- 链式调用：safeGet(() → request.getHeader("X-Trace-ID")) .flatMap(trace → safeGet(() → parseTrace(trace))) .flatMap(ctx → safeGet(() → ctx.getTenant())) .flatMap(t → safeGet(() → t.getCode())) .filter(Objects::nonNull) .orElseThrow(() → new GatewayException(ErrCode.GATEWAY_TENANT_CODE_MISSING))
避免 orElseGet 被误用于业务逻辑分支
网关校验必须是“非空即拒”，不能妥协。有人会写：userId = Optional.ofNullable(req.getUserId()).orElseGet(this::generateGuestId) —— 这已不属于校验，而是兜底逻辑，应移出网关，交给下游服务处理。网关只做断言，不做补救。
- ✅ 校验型： Optional.ofNullable(req.getOrderId()).orElseThrow(…)
- ❌ 混淆型： req.getOrderId() == null ? generateOrderId() : req.getOrderId() 或 orElseGet(generateOrderId)
