参考：异常抛出场景

参数校验失败（走 i18n）

public void createOrder(OrderCreateDTO dto) {
    if (dto == null) {
        // 不传自定义消息，让框架走 i18n 解析枚举 defaultMsg
        throw BusinessException.error(XxxOfBusinessExceptionCodeEnum.ERR_INVALID_PARAMS);
    }
    if (StringUtils.isBlank(dto.getProductId())) {
        // 使用 args 传参，配合 i18n 占位符 {0}
        // 资源文件: ERR_REQUIRED_FIELD_MISSING=必填字段缺失: {0}
        throw BusinessException.error(
            XxxOfBusinessExceptionCodeEnum.ERR_REQUIRED_FIELD_MISSING,
            "productId"
        );
    }
    // ...
}

数据不存在（走 i18n）

public User getUserById(String userId) {
    User user = userMapper.selectById(userId);
    if (user == null) {
        // 枚举 defaultMsg 为 "数据不存在"，同时 i18n 资源文件也有对应 key
        // 框架会自动根据 Accept-Language 返回中文或英文
        throw BusinessException.error(XxxOfBusinessExceptionCodeEnum.ERR_DATA_NOT_FOUND);
    }
    return user;
}

业务规则校验（i18n 占位符）

public void approveTask(String taskId) {
    Task task = taskMapper.selectById(taskId);
    if (task == null) {
        throw BusinessException.error(XxxOfBusinessExceptionCodeEnum.ERR_DATA_NOT_FOUND);
    }
    if (task.getStatus() != TaskStatus.PENDING) {
        // 资源文件:
        //   ERR_STATUS_NOT_ALLOWED=当前状态 [{0}] 不允许审批
        //   ERR_STATUS_NOT_ALLOWED=Current status [{0}] does not allow approval
        throw BusinessException.error(
            XxxOfBusinessExceptionCodeEnum.ERR_STATUS_NOT_ALLOWED,
            task.getStatus().getDesc()
        );
    }
    // ...
}

用户提示场景（不记录日志）

public void checkUserQuota(String userId) {
    Quota quota = quotaService.getQuota(userId);
    if (quota == null || quota.getRemaining() <= 0) {
        // 提示用户额度不足，但不需要记录 error 日志
        // 消息同样走 i18n 解析
        throw BusinessHintException.error(
            XxxOfBusinessExceptionCodeEnum.ERR_NO_PERMISSION,
            "您的额度已用完，请联系管理员"
        );
    }
}

包装第三方异常

public DingTalkUser getDingTalkUser(String userId) {
    try {
        DingTalkResponse response = dingTalkClient.getUser(userId);
        if (response.getErrcode() != 0) {
            throw new BusinessException(
                XxxOfBusinessExceptionCodeEnum.ERR_RPC_FAIL,
                "钉钉接口错误: " + response.getErrmsg()
            );
        }
        return response.getUser();
    } catch (ApiException e) {
        throw new BusinessException(
            XxxOfBusinessExceptionCodeEnum.ERR_RPC_FAIL,
            "调用钉钉接口失败: " + e.getMessage(),
            e
        );
    }
}

多参数 i18n 占位符

// 枚举定义
public enum XxxOfBusinessExceptionCodeEnum implements IBusinessExceptionCodeConfiguration {
    ERR_SIZE_LIMIT("字段 {0} 长度必须在 {1} 到 {2} 之间");
    // ...
}

# messages.properties
ERR_SIZE_LIMIT=字段 {0} 长度必须在 {1} 到 {2} 之间

# messages_en.properties
ERR_SIZE_LIMIT=Field {0} length must be between {1} and {2}

public void validateField(String fieldName, String value) {
    if (value.length() < 10 || value.length() > 200) {
        throw BusinessException.error(
            XxxOfBusinessExceptionCodeEnum.ERR_SIZE_LIMIT,
            fieldName, 10, 200
        );
        // 中文结果: "字段 description 长度必须在 10 到 200 之间"
        // 英文结果: "Field description length must be between 10 and 200"
    }
}