架构与系统设计 / 系统课时
项目架构整合
项目架构整合
本课把网关、认证、租户、权限、业务与基础设施模块串成一条可运行的请求链路。完成后,你将得到清晰的模块边界、统一的租户上下文传递方式,以及一套可以验证登录、鉴权、租户隔离和业务访问是否协同生效的整合方案。
学习目标
- 理清六类核心模块的职责与依赖方向
- 配置网关路由、认证校验和租户上下文透传
- 使用端到端请求验证整合结果
划分模块边界
综合项目首先要解决的不是“把所有代码放到一起”,而是让每个模块只承担一种稳定职责。推荐按入口、身份、租户、授权、业务和基础设施六个方向拆分,业务模块只能通过公开接口使用底层能力,不能反向依赖网关或认证实现。
| 模块 | 核心职责 | 不应承担的职责 |
|---|---|---|
| gateway | 路由、限流、统一入口、请求头清洗 | 查询业务表、计算权限 |
| auth | 登录、令牌签发与解析 | 保存租户业务配置 |
| tenant | 租户识别、状态校验、上下文管理 | 处理具体订单或商品 |
| permission | 功能权限与数据范围判断 | 维护网关路由 |
| business | 实现具体业务用例 | 自行解析令牌 |
| infrastructure | 数据库、Redis、消息、日志等适配 | 决定业务规则 |

依赖方向应保持单向:入口层调用应用能力,应用层调用领域能力,领域层通过接口使用基础设施。这样即使以后把单体拆成微服务,认证、租户和权限规则也不需要整体重写。
串联请求处理链路
一次受保护请求建议按固定顺序处理:网关先清理外部伪造的内部请求头,再解析令牌并写入可信用户信息;业务服务读取租户标识,校验租户状态,建立租户上下文;权限组件完成接口权限和数据范围判断,最后才进入业务逻辑。
该顺序有两个关键原因。第一,租户标识必须来自可信令牌或服务端映射,不能直接相信客户端传入值。第二,租户上下文必须在数据库访问前建立,并在请求结束后清理,避免线程复用造成串租户。
配置网关与下游服务
下面是网关侧的片段示例,依赖 Spring Cloud Gateway,并假设认证过滤器会在校验令牌后写入 X-User-Id 与 X-Tenant-Id。配置同时删除客户端可能伪造的同名请求头,再把请求转发到业务服务。
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、令牌校验结果和异常响应组件。
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 是否启动,应从网关发起真实请求。下面命令假设系统已提供登录接口和订单查询接口,端口以实际部署值替换。
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}"预期结果:
HTTP/1.1 200 OK
Content-Type: application/json
{"code":"0","message":"success","data":[]}实际返回中的订单数据可能不同,但状态码应为 200,且日志中应能看到同一请求的用户编号、租户编号和追踪编号。随后使用另一个租户的令牌重复请求,确认两次结果不会互相包含对方数据。
检查常见整合故障
出现 401 时,先确认网关是否成功解析令牌,再检查可信请求头是否在过滤链后半段被覆盖。出现 403 时,重点检查权限标识、角色绑定和套餐功能是否一致。出现空数据或串租户时,应检查租户上下文建立时机、SQL 拦截器是否启用,以及异步任务是否显式传递租户编号。
服务间调用也必须使用可信内部签名或服务身份,不应把外部用户令牌原样传播到所有服务。内部调用仍需携带租户编号,但接收方必须验证调用方身份,防止客户端绕过网关直接伪造内部请求头。
本课总结
- 模块整合的核心是稳定边界和单向依赖,而不是简单合并代码
- 请求必须按认证、租户、权限、业务的顺序处理,并在结束时清理上下文
- 验收应从网关执行端到端请求,同时验证身份、租户隔离和权限结果
下一课预告
下一课将基于这套整合架构实现完整的租户管理功能,包括开通、配置、状态变更、套餐绑定和管理员初始化。