发生了什么

网点是平台在线下经营的一个点位,先和场地方(下称房东)签一份场地合同,才有权在那里经营;合同到期前要发起续签。系统里房东并不只有一条记录:同一个房东可以同时登记多个经营主体,常见的是一个个人商户加一个企业商户,各自是一份独立的商户档案。网点签约时要选定用哪个主体来签,这个选择在页面上叫签约类型。

正常流程是:运营在网点页发起续签,系统先读这个网点当前挂的合同和签约主体,再校验本次选的签约类型是否允许——同一份合同的主体类型不能就地变更;校验通过才生成续签合同,进入审批和电子签署;校验不通过就应当停下,并告诉运营哪一条不满足、下一步该怎么做。

这次的房东名下同时有个人商户和企业商户。原网点当初是按企业主体签的,运营在续签时选了个人。系统按规则拦住了:网点签约后,签约类型不能就地由企业改成个人,真要改只能按新的类型重新建一个网点再签。这条规则本身是对的,问题出在拦下来之后——拒绝的原因没有被包装成业务提示,原始异常被直接抛了出来,一线看到的是一个技术性报错,而不是“签约类型不能变更、需要新建网点”。已确认的影响是提示不友好、拿不到真实原因,会把规则问题当成系统故障去找产品和研发,沟通与理解成本都上去了。这次续签没有继续,也没有生成合同,没有看到数据被写坏的证据。

本质

一句话:规则拦得对,错在拒绝的方式——本该走业务异常的那条路,最后走了系统异常的兜底分支。

  1. 按设计,续签入口对不满足规则的情况应抛出业务异常;统一异常处理层负责把它转成“哪条规则不满足、下一步做什么”返回给页面,运营据此改操作或改走另一条流程。
  2. 这次的判断。房东有两个主体,续签选的签约类型与原合同不一致,命中“签约类型不可变更”这条规则,校验按预期返回不通过。
  3. 出错的一步在异常的分流上。这一层没有把业务拒绝单独识别出来,校验抛出的异常按系统异常原样返回,于是一次正确的业务拒绝被当成系统故障处理,页面拿到的只有技术描述或一句通用失败。
  4. 页面按系统错误展示这条响应,一线既看不出是规则不允许,也看不出该找谁、该做什么,最后只能把问题抛回产品和研发。
  5. 结果是一次本可自助解决的规则问题,被升级成跨角色排查。数据层面只是续签没发起成功,流程没有继续往下走。

修复方向有两层:一层在统一异常处理,把业务异常单独分支,返回业务错误码和给运营看的文案,只有未知异常才走兜底提示并记录日志、触发告警;另一层在续签入口,把这条规则的不满足显式转成业务异常,并把下一步写进文案。修复是否上线,记录没有说明。

下面两段为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;异常类名、错误码与提示文案均为示意。

错误代码

// 续签入口:主体类型不一致时直接抛运行时异常(脱敏教学示例)
public RenewResult renew(RenewRequest req) {
    NodeContract current = contractMapper.selectCurrent(req.getNodeId());
    if (req.getSignType() != current.getSignType()) {
        // 为什么错:这是一次正常的业务拒绝,抛的却是普通运行时异常、
        // 不带业务错误码,异常封装层分不出它和程序故障的区别
        throw new IllegalStateException("signType cannot change");
    }
    return contractService.createRenew(current, req);
}

// 统一异常封装:只分“参数错”和“其他”,业务拒绝落到了兜底分支
@ExceptionHandler(Throwable.class)
public ApiResult<?> handle(Throwable e) {
    // 为什么错:兜底把业务拒绝也当成系统异常,
    // 返回体里只有技术描述或通用失败,看不出是规则还是故障
    log.error("renew failed", e);
    return ApiResult.fail("SYSTEM_ERROR", "系统异常");
}

修复代码示例

// 修复:业务异常单独一类,带错误码,也带能直接给运营看的话
class BizException extends RuntimeException {
    final String code;
    BizException(String code, String msg) { super(msg); this.code = code; }
}

// 续签入口:规则不满足时抛业务异常,文案写清原因和下一步
public RenewResult renew(RenewRequest req) {
    NodeContract current = contractMapper.selectCurrent(req.getNodeId());
    if (req.getSignType() != current.getSignType()) {
        // 为什么这样改:同一次拒绝改为带错误码的业务异常,
        // 页面能直接展示原因,运营知道要新建网点而不是等人排查
        throw new BizException("SIGN_TYPE_NOT_CHANGEABLE",
                "该网点已按企业主体签约,签约类型不能直接改成个人;如确需变更,请新建网点后重新签约");
    }
    return contractService.createRenew(current, req);
}

// 统一异常封装:业务异常在前,未知异常兜底在后并告警
@ExceptionHandler(BizException.class)
public ApiResult<?> handleBiz(BizException e) {
    log.warn("biz reject, code={}", e.code); // 业务拒绝留 warn,不按 error 告警
    return ApiResult.fail(e.code, e.getMessage());
}

两段代码改的是同一处判断:错误版抛的是普通运行时异常、不带业务错误码,兜底分支只能把它当系统错误返回;修复版换成带错误码的业务异常,文案里写清原因和下一步,并把业务异常接在兜底之前。未知异常那条分支仍要保留,用于真正的系统故障。

下次遇到这些场景要警惕

  • 给校验新增一条“业务上不允许”的分支时:先确认这个分支抛的异常在统一异常处理里有对应分支,再走一遍页面;看到的应该是原因和下一步动作,而不是通用系统错误。
  • 排查“页面只报错、看不出原因”的问题时:先按错误文案反查它从哪个异常分支出来,确认是规则拦的还是程序崩的,再决定改代码还是改数据;不要因为文案写着系统异常就认定是故障。
  • 新增业务异常类型或调整统一异常处理时:把匹配顺序过一遍,业务异常在前、未知异常兜底在后,并用一条真实的拒绝请求验证返回体里的错误码和文案。
  • 做签约主体这类跨合同的变更限制时:除了拦住,还要给出可执行的下一步,比如按新主体重新建网点,并在提示里写明是规则不允许,不是系统出错。