架构与系统设计 / 系统课时

项目架构整合

项目架构整合

本课把网关、认证、租户、权限、业务与基础设施模块串成一条可运行的请求链路。完成后,你将得到清晰的模块边界、统一的租户上下文传递方式,以及一套可以验证登录、鉴权、租户隔离和业务访问是否协同生效的整合方案。

学习目标

  • 理清六类核心模块的职责与依赖方向
  • 配置网关路由、认证校验和租户上下文透传
  • 使用端到端请求验证整合结果

划分模块边界

综合项目首先要解决的不是“把所有代码放到一起”,而是让每个模块只承担一种稳定职责。推荐按入口、身份、租户、授权、业务和基础设施六个方向拆分,业务模块只能通过公开接口使用底层能力,不能反向依赖网关或认证实现。

模块 核心职责 不应承担的职责
gateway 路由、限流、统一入口、请求头清洗 查询业务表、计算权限
auth 登录、令牌签发与解析 保存租户业务配置
tenant 租户识别、状态校验、上下文管理 处理具体订单或商品
permission 功能权限与数据范围判断 维护网关路由
business 实现具体业务用例 自行解析令牌
infrastructure 数据库、Redis、消息、日志等适配 决定业务规则

多租户综合项目模块架构图

依赖方向应保持单向:入口层调用应用能力,应用层调用领域能力,领域层通过接口使用基础设施。这样即使以后把单体拆成微服务,认证、租户和权限规则也不需要整体重写。

串联请求处理链路

一次受保护请求建议按固定顺序处理:网关先清理外部伪造的内部请求头,再解析令牌并写入可信用户信息;业务服务读取租户标识,校验租户状态,建立租户上下文;权限组件完成接口权限和数据范围判断,最后才进入业务逻辑。

该顺序有两个关键原因。第一,租户标识必须来自可信令牌或服务端映射,不能直接相信客户端传入值。第二,租户上下文必须在数据库访问前建立,并在请求结束后清理,避免线程复用造成串租户。

配置网关与下游服务

下面是网关侧的片段示例,依赖 Spring Cloud Gateway,并假设认证过滤器会在校验令牌后写入 X-User-Id 与 X-Tenant-Id。配置同时删除客户端可能伪造的同名请求头,再把请求转发到业务服务。

yaml
spring:
  cloud:
    gateway:
      routes:
        - id: saas-business
          uri: lb://saas-business-service
          predicates:
            - Path=/api/business/**
          filters:
            - RemoveRequestHeader=X-User-Id
            - RemoveRequestHeader=X-Tenant-Id
            - StripPrefix=1

这段配置生效后,外部请求 /api/business/orders 会被转发为下游的 /business/orders。认证过滤器应运行在路由过滤链中,并在 RemoveRequestHeader 之后写入可信请求头。验证时同时检查路由地址、下游收到的用户编号和租户编号。

业务服务可以用一次性过滤器建立并清理租户上下文。下面是片段示例,依赖项目中已有的 TenantContext、令牌校验结果和异常响应组件。

java
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

@Component
public class TenantContextFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        String tenantId = request.getHeader("X-Tenant-Id");
        if (tenantId == null || tenantId.isBlank()) {
            response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Missing tenant context");
            return;
        }

        try {
            // 数据库访问前建立上下文,供拦截器和业务服务统一读取
            TenantContext.setTenantId(tenantId);
            filterChain.doFilter(request, response);
        } finally {
            // 容器线程会复用,必须在请求结束后清理
            TenantContext.clear();
        }
    }
}

该过滤器的生效行为是:缺少可信租户标识时返回 401;存在租户标识时,在整个请求期间提供统一上下文;无论请求成功还是异常,最终都会清理线程变量。

完成端到端验证

整合完成后,不要只验证单个 Bean 是否启动,应从网关发起真实请求。下面命令假设系统已提供登录接口和订单查询接口,端口以实际部署值替换。

bash
TOKEN=$(curl -s -X POST "http://localhost:<PORT>/auth/login" -H "Content-Type: application/json" -d '{"username":"tenant_admin","password":"<PASSWORD>"}' | jq -r '.data.accessToken')

curl -i "http://localhost:<PORT>/api/business/orders" -H "Authorization: Bearer ${TOKEN}"

预期结果:

text
HTTP/1.1 200 OK
Content-Type: application/json

{"code":"0","message":"success","data":[]}

实际返回中的订单数据可能不同,但状态码应为 200,且日志中应能看到同一请求的用户编号、租户编号和追踪编号。随后使用另一个租户的令牌重复请求,确认两次结果不会互相包含对方数据。

检查常见整合故障

出现 401 时,先确认网关是否成功解析令牌,再检查可信请求头是否在过滤链后半段被覆盖。出现 403 时,重点检查权限标识、角色绑定和套餐功能是否一致。出现空数据或串租户时,应检查租户上下文建立时机、SQL 拦截器是否启用,以及异步任务是否显式传递租户编号。

服务间调用也必须使用可信内部签名或服务身份,不应把外部用户令牌原样传播到所有服务。内部调用仍需携带租户编号,但接收方必须验证调用方身份,防止客户端绕过网关直接伪造内部请求头。

本课总结

  • 模块整合的核心是稳定边界和单向依赖,而不是简单合并代码
  • 请求必须按认证、租户、权限、业务的顺序处理,并在结束时清理上下文
  • 验收应从网关执行端到端请求,同时验证身份、租户隔离和权限结果

下一课预告

下一课将基于这套整合架构实现完整的租户管理功能,包括开通、配置、状态变更、套餐绑定和管理员初始化。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目架构整合

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通