go-zero 多租户 SaaS 架构：行级隔离如何落地

SaaS 应用做多租户改造，难点从来不是加一张租户表，而是让租户身份从网关开始一路可信地传递，最终落到每一条 SQL 的查询条件里。本文以一套基于 go-zero v1.8 的多租户 SaaS 微服务模板为例，拆解它的总体拓扑、行级隔离的完整落地链条，以及错误处理与可观测性设计。

总体拓扑：一个 HTTP 网关加三个 gRPC 服务

整套模板拆成四个进程。gateway 是唯一的 HTTP 入口，监听 8888 端口，承担三件事：通过 go-zero 的 WithJwt 做 JWT 校验；用 TenantContext 中间件解析 token 里的租户声明并写入 context；提供统一错误处理和 Prometheus 指标端点。

网关背后聚合三个 gRPC 服务：identity 负责注册登录、JWT 签发与 RBAC 权限校验；tenant 负责租户、成员管理与配额检查；billing 负责套餐、订阅与用量计量。服务之间用 etcd 做服务发现，跨服务调用链由 Jaeger 采集，指标交给 Prometheus 加 Grafana 呈现。

存储层是 PostgreSQL 加 Redis 的组合：所有业务表带 tenant_id 列做行级隔离，缓存 key 按 t:{tenantId}: 前缀隔离，两个层面都保证租户之间互不可见。

为什么选行级隔离

多租户隔离常见三种模式：独立数据库、独立 Schema、共享表加 tenant_id 列。这套模板选了第三种，也就是行级隔离，理由是成本低、运维简单，适合绝大多数 SaaS 项目的起步阶段。代价是隔离不再由数据库结构天然保证，而要靠应用层每一环都记住租户身份，任何一层漏掉条件都可能造成越权。

为此模板把隔离拆成七个环节，每个环节都有明确落点：

环节	实现方式
认证签发	JWT claims 携带 uid、tenant_id、roles
网关解析	TenantContext 中间件解析 token 写入 context
跨服务透传	ClientAuthUnary 拦截器把 context 写入 gRPC metadata
后端注入	ServerAuthUnary 拦截器把 metadata 读回 context
数据隔离	model 查询强制带 tenant_id 条件
越权防护	AssertSameTenant 校验资源归属
缓存隔离	Redis key 加 t:{tenantId}: 前缀

一次请求的完整数据流

以获取租户成员接口为例。前端带上 Bearer JWT 请求网关，网关先用 WithJwt 验签，再由 TenantContext 中间件解析出 uid、tenant_id 和 roles，写入请求 context。业务逻辑层从 context 取出 tenant_id 后发起 gRPC 调用，ClientAuthUnary 拦截器把身份信息写进 metadata；tenant 服务侧的 ServerAuthUnary 拦截器把 metadata 还原进自己的 context，全程不重复解析 token。最终 model 层生成的查询条件强制带上 tenant_id，缓存 key 也带同样的租户前缀。整条链路上，租户身份只在网关解析一次，其余各层只做透传，不给越权留口子。

统一错误处理

错误码集中在共享包 xerr 里，流程是：logic 层用 NewCode 抛出业务错误，ToGrpcStatus 把业务码编码进 gRPC message 前缀，跨进程传输后在网关侧用 FromGrpcStatus 还原，最后转成带 code 和 message 的 JSON 返回前端。错误码按服务分段：100xxx 通用、101xxx 属于 identity、102xxx 属于 tenant、103xxx 属于 billing，看到码段就能定位是哪个服务的问题。

可观测性

可观测性三件套是内置的。指标方面，每个服务都有 Prometheus 端点，go-zero 自动采集 QPS、延迟与错误率；链路方面，Jaeger 通过各服务配置文件的 Telemetry 段接入，串起跨服务的 gRPC 调用；日志方面，go-zero 的结构化日志自带 traceId，一条请求跨四个服务的轨迹可以关联起来看。