概述
这次改造把交友项目从「只有 C 端」补成了「双端形态」:前面加一层网关做统一入口和统一鉴权,后面新建 mf-admin 承载管理员登录和用户管理,管理端自己的业务很少,四件查询全部经 Dubbo 复用 C 端已有的域服务。本文是一次架构复盘:不重讲每一步怎么配,而是把套路提炼出来、把踩过的坑集中回顾,最后给一份可勾选的自检清单和后续可动手的改造方向。
纲要
- 一句话总结与知识地图
- 可复用套路清单(重点)
- 网关统一鉴权:AuthFilter + excludedUrls 白名单
- 双体系账号映射:管理员 JWT 与用户 JWT 同工具不同 payload
- 管理端复用域服务:Dubbo 调用,管理端零直连数据库
- 分页两种形态:MySQL selectPage 自动 count vs Mongo skip/limit 手工 count
- 浏览器端聚合 vs 后端聚合
- 关键坑回顾(12 条,含实测代码依据)
- 自检清单(可勾选)
- 后续改造任务(6 项,每项给「改哪里 / 怎么验证」)
- 常见误解澄清
- 后续方向
一句话总结
引入 SpringCloud Gateway 统一鉴权与路由(/app/** 到 mf-app-server,/admin/** 到 mf-admin),搭建 B 端管理后台完成管理员登录三接口 + 用户管理四件查询,管理端经 Dubbo 复用 C 端域服务,全程零直连业务库(自己的 admin 库除外)。
知识地图
一条链路读图:Vue 页面请求 localhost:8088/management/... → Nginx 转发到 127.0.0.1:8888/admin/... → 网关白名单判定 + token 校验 → StripPrefix 去掉 /admin 前缀路由到 mf-admin → 后端拦截器解析 token 存 AdminHolder → Service 经 Dubbo 调域服务返回数据。
改造后的工程形态
mf
├── mf-gateway # 本次新增:网关
│ └── src/main/java/com/mf/gateway
│ ├── GatewayApplication.java
│ ├── config/CorsConfig.java # reactive 版 CorsWebFilter
│ └── filters/AuthFilter.java # GlobalFilter 统一鉴权
├── mf-admin # 本次新增:B 端管理后台
│ └── src/main/java/com/mf/admin
│ ├── AdminServerApplication.java
│ ├── controller/SystemController.java # verification / login / profile
│ ├── controller/ManagerController.java # users / users/{id} / videos / messages
│ ├── service/AdminService.java
│ ├── service/ManagerService.java
│ ├── interceptor/TokenInterceptor.java # 解析 JWT 存 AdminHolder
│ ├── interceptor/AdminHolder.java # ThreadLocal 身份持有
│ ├── interceptor/WebConfig.java # 注册拦截器 + 排除登录路径
│ ├── exception/{BusinessException,ExceptionAdvice}.java
│ └── mapper/AdminMapper.java # 只连自己的 mf-admin 库
├── mf-app-server # C 端接入层(既有成果)
├── mf-dubbo # 域服务:interface / db / mongo(被两端复用)
├── mf-commons # JwtUtils 等公共工具
└── mf-model # Admin / UserInfo / Video / Movement 等实体
API 速览
| 接口 | 方法 | 归属 | 数据来源 | 说明 |
|---|---|---|---|---|
/system/users/verification | GET | 管理员登录 | Redis | Hutool LineCaptcha 出图,验证码存 Redis |
/system/users/login | POST | 管理员登录 | MySQL tb_admin | 校验验证码 + MD5 密码,签发 JWT |
/system/users/profile | POST | 管理员登录 | MySQL tb_admin | 从 AdminHolder 取 id 回查资料 |
/manage/users | GET | 用户管理 | Dubbo → MySQL | selectPage 分页查用户列表 |
/manage/users/{userId} | GET | 用户管理 | Dubbo → MySQL | 用户详情 |
/manage/videos | GET | 用户管理 | Dubbo → Mongo | 指定用户视频列表,skip/limit 分页 |
/manage/messages | GET | 用户管理 | Dubbo → Mongo | 指定用户动态列表,支持 state 筛选 |
可复用套路清单
这五个套路的价值不止于单个项目,换个项目照搬即可,是全文最值得带走的部分。
| 套路 | 具体做法 | 适用场景 |
|---|---|---|
| 网关统一鉴权:校验上移网关、解析下沉保留 | AuthFilter implements GlobalFilter, Ordered,@Value("${gateway.excludedUrls}") 读白名单,命中直接 chain.filter 放行;校验失败写回 401 JSON。白名单只有 4 条:APP 登录两个 + 后台登录两个 | 任何微服务项目的第一层防线;后续内容审核同样会在网关层挂全局过滤器 |
| 双体系账号映射与 JWT 双体系 | 管理员和用户是两套账号、两张表、两种 token,但签发用的是同一个 JwtUtils,区别只在 payload:用户 token 放 mobile/id,管理员 token 放 username/id。路由层面用 /app/** 和 /admin/** 前缀物理隔离,管理端 token 打不进 APP 接口 | 任何「一套系统两类操作员」的场景:前台用户 + 运营后台。核心是同工具、不同 payload、路径隔离三件套 |
| 管理端复用域服务 | 四件查询全部走 Dubbo:admin 模块里只有 Controller/Service 薄薄一层,Mapper 一个都没有。业务数据查询全在 mf-dubbo-db(MySQL)和 mf-dubbo-mongo(Mongo)实现 | B 端永远不该直连业务库。管理端只做「编排 + VO 转换」,数据能力统一沉到域服务层,避免两套查询逻辑漂移 |
| 管理端分页两种形态 | MySQL 侧:userInfoMapper.selectPage(new Page<>(page,pagesize), null) 一行搞定,MyBatis-Plus 拦截器自动 count。Mongo 侧:先 mongoTemplate.count(query) 拿总数,再 query.limit(pagesize).skip((page-1)*pagesize).with(Sort...) 手工拼 | 所有 MySQL + Mongo 混合项目。记住分野:关系库 ORM 帮你 count,文档库必须自己 count,漏了 count 前端分页条就是 0 |
| 浏览器端聚合 vs 后端聚合 | 用户详情页的「基本资料 / 视频记录 / 动态记录」是三个独立接口、各自独立分页,而不是一个巨型详情接口一次拉全 | 独立分页的数据块不要硬塞进一个接口,分页参数会打架,任一模块变慢会拖死整个详情页。反过来,一屏固定要展示的小数据(如用户卡片附带粉丝数)才适合后端聚合 |
关键坑回顾
这 12 条里大部分能在最终代码里找到原始现场,标注了出处。
| # | 坑 | 现象 / 依据 | 解法 |
|---|---|---|---|
| 1 | Gateway 与 starter-web 冲突 | 网关是 WebFlux 体系,classpath 里混入 spring-boot-starter-web 会直接启动失败 | 网关模块只留 spring-cloud-starter-gateway;跨域用 org.springframework.web.cors.reactive 包下的 CorsWebFilter,别 import 错成 servlet 包 |
| 2 | StripPrefix 忘配 | 路由配了 Path=/admin/**,请求打到后端变成 /admin/system/users/login,Controller 里没有这个路径,404 | filters: - StripPrefix= 1 去掉一级前缀;后端 Controller 路径按去前缀后的写 |
| 3 | 白名单漏配 | 登录页第一步 /system/users/verification 都拿不到,控制台一路 401 | 对照白名单逐个验证:/user/login,/user/loginVerification,/system/users/verification,/system/users/login |
| 4 | 校验上移后,后端解析仍要保留 | 网关只做 verifyToken 放行/拦截,不会把身份传给后端;后端 TokenInterceptor 仍需自己 getClaims 解析出 id/username 存 ThreadLocal | 职责划分:网关管「有没有效」,后端管「是谁」。两层缺一不可 |
| 5 | AdminHolder.remove() 无人调用 | 实读 mf-admin/interceptor/TokenInterceptor.java:只有 preHandle,没有 afterCompletion,remove() 是死代码。Tomcat 线程复用,上一个管理员的身份会残留给下一个请求 | 补 afterCompletion 调 AdminHolder.remove()(见任务 1) |
| 6 | TokenInterceptor 直接 getClaims 未 verifyToken | App 端 TokenInterceptor 里 verifyToken 那段被注释掉了,admin 端同样直接 getClaims。token 过期时 parseClaimsJws 抛 ExpiredJwtException → 500 而不是 401 | 解析前先 verify,失败返回 401(见任务 2) |
| 7 | JwtUtils 注释与实际不符 | mf-commons/utils/JwtUtils.java 注释写「有效期1小时」,实际 TOKEN_TIME_OUT = 7 * 24 * 3600,7 天 | 注释改对;生产环境有效期应收敛到分钟级 + 刷新机制 |
| 8 | 验证码未设 TTL | redisTemplate.opsForValue().set(CAP_CODE+uuid, code) 没给过期时间,验证码永久有效,可被慢速爆破 | set 加超时参数:set(key, code, 5, TimeUnit.MINUTES) |
| 9 | 验证码对但密码错,验证码也被消费 | 示例 login 代码里 redisTemplate.delete(key) 在密码校验之前执行。用户手输验证码 + 密码打错一次,就得刷新验证码重来 | 验证码校验通过先不删,登录成功或验证码明确错误时才删;或校验通过后立即删但前端只要求密码重输 |
| 10 | frinedId / total 写死系列 | 此前留下的债:加好友时 frinedId 硬编码、部分列表 total 不真实。复盘时属于「已知工程缺口」 | 已列进任务 5,借这套 Dubbo 结构补齐 |
| 11 | uid 空校验缺失,in(null)/is(null) 查全量 | 实读 VideoApiImpl.findByUserId:Criteria.where("userId").in(userId) 没判空,uid 不传就查整表前 N 条;对比 MovementApiImpl 有 if(uid != null) 判断 | 查询条件参数判空,空就构造空 PageResult 快速返回,而不是放行全表 |
| 12 | Page 跨 Dubbo,两端依赖一致 | IPage 经 Dubbo 序列化传输,hessian 反序列化要求两端 mybatis-plus 版本一致,否则 PageResult 转换时报 ClassNotFound 或字段丢失 | 父 pom 统一管版本,interface 模块的依赖同步到消费端 |
另有一处示例代码里的小笔误顺手记下:login 方法里「用户名或密码为空」分支写的是 map.put("message",...),put 进了入参 map 而不是刚 new 的 map1,典型的复制粘贴 bug,能发现它说明代码真看进去了。
自检清单
按顺序勾,前 4 项不过就不用往下测:
- 网关路由正确:
localhost:8888/app/**走 mf-app-server,localhost:8888/admin/**走 mf-admin(看网关控制台打印的 url 日志) - StripPrefix 生效:后端 Controller 收到的路径不含
/admin、/app前缀(断点或看 404 与否) - 白名单放行:不带任何 token 请求
/system/users/verification能拿到图片 - 拦截生效:不带 token 请求
/manage/users返回 401 JSON(errCode=401) - 管理员登录链路:verification 出图 → login 带 username/password/verificationCode/uuid 换到 token
- profile 正常:带上
Bearer <token>请求 profile,返回登录管理员自己的 username 和 avatar - 用户列表分页:
/manage/users?page=2&pagesize=5返回 5 条且 total 正确 - 四件查询打通:详情、视频、动态三个接口各返回数据,动态接口传
state=1能筛出已审核动态 - 跨域正常:Nginx 8088 打开页面能登录、列表页能出数据(F12 无 CORS 报错)
后续改造任务
每项都是真实工程缺口,给到「改哪里」和「怎么验证」。
任务 1:修 AdminHolder 线程残留
- 改哪里:
mf-admin/interceptor/TokenInterceptor.java加afterCompletion方法,内部调AdminHolder.remove()。 - 怎么验证:profile 里打一个断点,两次用不同管理员账号登录后请求,第二次请求进入 profile 时
AdminHolder.getAdmin()必须是当前账号而非上次残留。
任务 2:TokenInterceptor 补 verifyToken
- 改哪里:
preHandle里getClaims之前先JwtUtils.verifyToken(token),失败设置response.setStatus(401)并 return false。App 端被注释掉的那段同理放开。顺手处理 token 为 null 的 NPE:先判空再 replace。 - 怎么验证:手工构造过期 token(把 JwtUtils 的 TOKEN_TIME_OUT 临时改成 1 秒生成一个),请求应得 401 而不是 500。
任务 3:验证码加 TTL + 消费时机调整
- 改哪里:SystemController.verification 里 set 加
5, TimeUnit.MINUTES;AdminService.login 里把redisTemplate.delete(key)挪到密码校验通过之后。 - 怎么验证:等 5 分钟后用旧验证码登录,应提示「验证码错误」;验证码对、密码错一次后,同一验证码再配正确密码应能登录成功。
任务 4:管理端 keyword 搜索
- 改哪里:ManagerController.users 加
String keyword参数(可空);UserInfoApi加IPage findAll(Integer page, Integer pagesize, String keyword);UserInfoApiImpl 里 keyword 非空时给 selectPage 传QueryWrapper.like("nickname", keyword)。 - 怎么验证:页面用户列表传昵称关键字,只返回匹配记录,total 同步变小;keyword 不传时行为和原来一致。
任务 5:取消好友 / 取消关注
此前留下的缺口:好友和关注「只能加不能删」。现在有了这套骨架,正好补上。
- 改哪里:C 端 Controller 加两个删除接口;
mf-dubbo-interface加 FriendApi.delete / FocusApi.delete 声明,对应实现模块里删 MongoDB friendship/focus 记录并回写双方 counts。注意顺手修掉加好友时 frinedId 写死的问题,删除接口要靠真实的好友 id 才能删对人。 - 怎么验证:A 取消关注 B 后,B 的 fans 数减一、A 的 friend 数减一,B 的联系人列表里 A 消失。
任务 6:用户锁定功能
项目 APP 里早就有「用户被冻结」的提示,但系统里没有任何地方能冻结用户,闭环缺口,正好由管理端补齐。
- 改哪里:给 C 端登录逻辑加一个冻结判定( UserInfo 加标志位,或在 Redis 记冻结名单);管理端
ManagerController加POST /manage/users/freeze,经 Dubbo 写入冻结状态。 - 怎么验证:管理端冻结某用户后,该用户 APP 端重新登录收到「用户被冻结」提示;解冻后恢复登录。
常见误解澄清
| 误解 | 实际情况 |
|---|---|
| 「有了网关鉴权,后端拦截器可以删了」 | 网关只验证 token 有效性,不会解析出身份往下传。后端 TokenInterceptor 负责解析 claims 并填充 AdminHolder,删了它 profile 直接 NPE |
| 「Gateway 的 Filter 和 MVC 拦截器是一回事」 | 完全两套:GlobalFilter 跑在 WebFlux 反应式栈(返回 Mono),HandlerInterceptor 跑在 Servlet 栈。API 不同、线程模型不同,只是职责相似 |
| 「管理员 JWT 和用户 JWT 是两套工具」 | 同一个 JwtUtils、同一个签名密钥。区别只在 claims 内容和允许通过的路径前缀。这也意味着密钥泄露时双端同时沦陷,生产上应拆成两个密钥 |
| 「Nacos 配置中心和注册中心是同一个功能」 | 是 Nacos 的两个能力:注册中心管服务发现(网关靠它把 lb://mf-admin 翻译成真实地址),配置中心管配置托管(bootstrap.yml 里只留「去哪拉配置」,路由规则放 Nacos 上热改) |
| 「MongoDB 分页和 MySQL 一样调个方法就行」 | Mongo 没有 selectPage,必须 count + limit + skip 三步手工拼,且 count 要在加 limit 之前执行,否则统计的是当前页条数 |
| 「401 是业务服务返回的」 | 这里的 401 由网关 AuthFilter 写回,请求根本没到 mf-admin。排查时先分清是网关拦的还是后端拦的:网关返回体是 errCode/errMessage 结构 |
后续方向
后续的「数据统计与内容审核」有两条主线:一是给管理端补上数据看板(注册量、活跃度等统计报表);二是接入云端内容审核服务,动态发布时埋的 state=0/1/2 闸门(0 待审核 / 1 通过 / 2 拒绝)一直只有数据结构没有审核动作,后续由机器审核接管它,审核结果直接决定动态是否可见。用户锁定功能也会和审核体系在管理端汇合。
总结
- 这套骨架的价值大于功能价值:网关 + 双端路由 + Dubbo 复用域服务,是所有多端项目的通用底座。
- 五个套路(网关统一鉴权、JWT 双体系、管理端复用域服务、两种分页形态、聚合取舍)建议对照自己的项目逐条找落点,比记住接口签名有用得多。
- 12 个坑里,AdminHolder 残留、getClaims 不校验、验证码无 TTL 这三个是当前代码里实际存在的,其余多为配置类错误,排查时按「网关层 → 路由层 → 服务层」顺序定位。
- 取消好友 / 关注与用户锁定这两项是真实业务缺口,补完之后项目闭环才算真正合上。
455



被折叠的 条评论
为什么被折叠?



