📚 课程目录第1章课程导论

1. 课程导论：多租户SaaS架构面临的错误处理挑战与升级必要性

1.1 传统单体架构的错误处理模型及其局限

在传统单体应用中，错误处理通常采用“全有或全无”的事务回滚模式，鉴权与拦截逻辑作为中间件嵌入在请求管道中。这种模型在单一租户、低并发场景下尚可运转，但在多租户SaaS架构中暴露出以下根本性缺陷：

维度	单体架构	多租户SaaS架构
租户隔离	无租户概念，错误影响全局	一个租户的鉴权失败不应影响其他租户
鉴权粒度	统一鉴权，无租户级策略	需支持租户级、角色级、资源级多层鉴权
拦截链路	线性拦截，失败即终止	需熔断、降级、异步补偿等弹性机制
错误传播	异常向上抛，无上下文	需携带租户ID、请求ID、链路追踪上下文
可用性要求	99.9% 可接受	99.99%+，需应对突发流量与局部故障

  核心矛盾： 多租户SaaS的鉴权拦截链路不再是“一次通过”的简单检查，而是需要处理租户级策略、动态配置、外部依赖（如身份提供商IDP）的复杂管道。传统错误处理模型无法满足这种场景下的隔离性、弹性与可观测性要求。

1.2 多租户鉴权拦截链路的典型故障模式

在实际生产环境中，鉴权拦截链路是SaaS系统的第一道防线，也是最容易发生级联故障的环节。以下是我们在多个企业级SaaS项目中总结的六种典型故障模式：

外部IDP（身份提供商）超时或不可用 — 如Azure AD、Okta、自建OAuth服务响应缓慢，导致整个鉴权线程阻塞。
租户配置缓存雪崩 — 大量租户同时刷新鉴权策略，导致Redis/本地缓存穿透，DB压力激增。
恶意请求风暴 — 针对特定租户的凭证伪造攻击，引发鉴权服务CPU/内存飙升。
跨租户数据泄露 — 鉴权上下文未正确隔离，导致租户A的Token被用于访问租户B的资源。
鉴权策略热加载失败 — 动态更新租户权限规则时出现配置解析异常，导致该租户所有请求被拒绝。
链路超时累积 — 单个慢请求占用连接池，逐步扩散至整个网关集群。

关键洞察： 上述故障中，超过70%的故障并非由业务逻辑错误引起，而是由鉴权拦截链路本身的弹性缺失和错误处理不当导致。这正是本课程要解决的核心问题。

1.3 为什么需要升级错误处理框架？

传统的 try-catch 模式在分布式多租户场景下已不足以应对。升级的必要性体现在四个层面：

层面	现状问题	升级目标
隔离性	一个租户的鉴权异常可能拖垮全局线程池	租户级线程隔离 + 舱壁模式
弹性	外部依赖故障时无降级策略，直接返回500	熔断 + 降级 + 静默失败 + 默认策略兜底
可观测性	错误日志散落，无法关联租户与请求链路	结构化错误 + 链路追踪 + 租户维度指标
可演进性	鉴权逻辑与业务代码耦合，难以独立升级	插件化拦截链 + 策略热更新 + 灰度发布

1.4 升级后的错误处理框架全景

本课程将构建一个分层、可插拔、面向多租户的错误处理框架。下图展示了该框架的核心组件与数据流：

1.5 本课程的核心交付与学习路径

本课程将围绕以下五个模块展开，每个模块都包含可运行的代码示例与架构决策记录：

模块	核心内容	关键产出
模块一	多租户鉴权上下文设计与隔离	租户上下文传递规范 + ThreadLocal/ReactiveContext 实现
模块二	插件化鉴权拦截链编排	责任链模式 + SPI 插件加载 + 动态排序
模块三	租户级熔断与舱壁隔离	基于Resilience4j的租户级熔断器 + 信号量隔离
模块四	降级策略与默认权限兜底	降级策略配置中心 + 默认权限模板 + 静默失败模式
模块五	可观测性与生产运维	结构化错误日志 + Prometheus指标 + 链路追踪集成

学习建议： 本课程假设你已具备Spring Boot/Cloud微服务开发基础，并对多租户数据隔离有基本了解。建议在学习过程中，结合课程提供的示例代码仓库，在本地搭建一个模拟多租户环境进行实操验证。

1.6 升级前后的错误处理对比

为了更直观地展示升级的必要性，下面通过一个具体的代码片段对比升级前后的鉴权拦截错误处理方式：

升级前（传统 try-catch 模式）：

// 传统鉴权拦截器
public class LegacyAuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, Object handler) {
        try {
            String token = request.getHeader("Authorization");
            // 直接调用外部IDP验证
            AuthResult result = idpClient.validateToken(token);
            if (!result.isValid()) {
                throw new AuthException("Token invalid");
            }
            // 设置用户上下文
            SecurityContextHolder.setContext(result.getContext());
            return true;
        } catch (Exception e) {
            // 所有异常统一返回500
            response.setStatus(500);
            return false;
        }
    }
}

升级后（熔断降级模式）：

// 升级后的鉴权拦截器（含熔断降级）
public class ResilientAuthInterceptor implements HandlerInterceptor {
    private final TenantCircuitBreaker breaker;
    private final AuthFallbackStrategy fallback;

    @Override
    public boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, Object handler) {
        String tenantId = extractTenantId(request);
        
        // 租户级熔断检查
        if (breaker.isOpen(tenantId)) {
            // 执行降级策略：返回默认权限或拒绝
            return fallback.execute(tenantId, request, response);
        }

        return breaker.runSupplier(tenantId, () -> {
            String token = request.getHeader("Authorization");
            AuthResult result = idpClient.validateToken(token);
            if (!result.isValid()) {
                // 结构化错误，携带租户上下文
                throw new TenantAuthException(tenantId, "Token invalid");
            }
            TenantContextHolder.set(tenantId, result.getContext());
            return true;
        }, throwable -> {
            // 熔断后的降级处理
            return fallback.execute(tenantId, request, response);
        });
    }
}