← 返回筆記列表

从账号模块到身份服务:先画清职责边界

發布于 來自 半盏灯 最近更新

  • Go
  • Gin
  • 架构设计
  • 用户中心

复杂度不是从登录接口开始的

设计统一认证服务时,最容易低估的是「用户」这张表会被多少个业务站各存一份:A 站存了昵称和状态,B 站自己解释权限,C 站又给令牌定了一套失效规则。等到要改密码策略时,才发现没人说得清哪一份是权威。

所以第一件事不是选框架,而是把边界写死:认证中心只负责用户身份、凭证、会话与令牌、用户资料、RBAC 权限基础;业务站只管自己的业务数据,不直连认证数据库,所有能力通过 HTTP 契约获取。

数据 归属 谁能改
账号、密码哈希、密码版本号 认证中心 仅认证中心
角色、权限点、授权关系 认证中心 管理端接口
refresh 会话、审计流水 认证中心 仅认证中心
订单、文章、项目等业务数据 各业务站 各业务站

这条边界的价值在出故障时最明显:认证中心挂掉等于全站无法登录,但它不该让业务站已经验过签的请求跟着一起失效。

分层契约:handler → service → repository

以 Go 技术栈为例,用 Gin 做 HTTP 接入、GORM 做 ORM、PostgreSQL 存权威数据,目录按职责切开,依赖方向单向:

handler      只做参数绑定与响应组装,不写业务规则、不碰 SQL
   ↓
service      业务规则、事务边界、返回业务错误
   ↓
repository   唯一可以出现 ORM / Redis 具体 API 的包
   ↓
PostgreSQL(权威) / Redis(短期状态)

分层不是为了「看起来规整」,而是让 HTTP、业务规则、存储细节可以分别测试:改一条校验规则不必启动数据库,改一条 SQL 不必动接口契约。

几个容易被忽略但很实用的仓储约定:

  • 每个方法必带 context.Context,事务通过 context 传递,仓储方法从 context 里取连接,签名里不需要 tx 参数;
  • 存储错误在仓储层翻译成业务错误:记录不存在 → 用户不存在,唯一冲突 → 账号已存在;
  • Update 走字段白名单,密码哈希 / 密码版本号 / 状态各有专用方法,防止「一次 Update 意外提权」;
  • 分页统一收敛(默认 20、上限 200),LIKE 里的 % / _ / \ 先转义再拼。

错误码按域分段(通用 / 认证与令牌 / 单点登录与授权 / 管理端),前端只依赖 code,message 可以随语言切换。

把认证中心的负载压到最低

认证中心是全站单点,所以设计上刻意让它不参与每一次业务请求:

  1. access token 本地验签:业务站启动时拉一次 JWKS 缓存公钥,之后自己验签,认证中心不参与业务请求;
  2. 会话状态外置:PostgreSQL 是权威,Redis 只做加速,实例可以随意扩缩,不需要 sticky session。
manager := jwt.New(privateKey, publicKey)  // 启动时校验公私钥是否配对
access := manager.SignAccessToken(TokenInput{
    UserID: userID, Roles: []string{"user"}, JTI: jti,
    PasswordVersion: user.PasswordVersion,
})
jwks := manager.JWKS()                     // 暴露给业务站,业务站启动时拉一次

这里有个隐含前提:公钥不是秘密,私钥只留在认证中心。一旦某个业务站需要持有私钥才能验签,边界就又漏了。

先交付单体进程内的清晰模块

落地顺序建议「先模块、后能力」,而不是一上来就拆微服务:

阶段 交付内容
1~3 骨架、配置/日志/模型/迁移、数据库连接、仓储层、核心工具包(JWT / 密码 / 错误码)
4~5 注册登录刷新改密、RBAC、限流、审计;handler + 路由 + 中间件
6~7 单点登录票据、第三方登录、多子域 Cookie、集成测试与部署
8 以后 指标、清理任务、登录页、审计检索、归档与灰度

账号生命周期、凭证校验、会话失效、审计这四件事先稳住,再补接入方管理与单点登录。模块边界稳定后横向扩容,通常只需要把共享状态外置,不需要把每个包都变成独立服务。

三个反复出现的坑

  • handler 越过 service 写 SQL:业务规则散落在接入层,改一处漏一处;
  • 业务站共享认证库:等于把「密码哈希怎么算」复制给了每一方,边界当天就失效;
  • 把缓存当唯一数据源:Redis 一旦清空,一次性票据、黑名单、限流计数全部凭空消失。

还有一个 PostgreSQL 专属的坑:SQL 语句报错会把整个事务置为 aborted(SQLSTATE 25P02)。所以 service 收到「唯一冲突」之后必须结束当前事务,不能在同一事务里继续写;确实要「忽略冲突继续」,得在写入前设 SAVEPOINT 并回滚到该点。

先定义数据归属、接口契约和故障语义,再选框架与部署形态 —— 这个顺序比先堆功能省下的返工,通常比任何技术选型都多。