大家好，我是小韦

每次用 RuoYi-Cloud 做微服务项目，你是不是也会想：

"微服务之间调来调去，Token 验证了又验证，响应慢得要死？""管理后台和 APP 的 API 混在一起，路径乱成一锅粥？"

答案是：RuoYi-Cloud 内置了一整套路由+认证的精华设计，只是很多人没发现。

今天这期，我把 RuoYi-Cloud 源码里关于 API 路由自动映射 和 内部 Feign 调用免 Token 透传 的机制拆开来讲透。

本期关键词：RuoYi-Cloud 源码解析 | 难度：⭐⭐⭐

一、场景痛点

先说说典型的多端项目会遇到什么：

痛点 1：API 路径混乱

同一个系统同时有管理后台、移动 APP 两个端，路径各写各的：

/admin/user/list/app-api/user/info/api/v1/system/user/profile

没人管得清哪些接口是给 APP 的，哪些是给后台的。新人来了更懵。

痛点 2：微服务间调用认证重复

RuoYi-Cloud 默认的认证链路：

外部请求 → Gateway 验证 Token(查 Redis, 30ms)         → 业务服务 A 验证 Token(查 Redis, 30ms)         → Feign → 业务服务 B 验证 Token(查 Redis, 30ms)

一个请求，Token 验证 3 次。 服务链路越长，浪费越多。

二、RuoYi-Cloud 原有方案

2.1 路由方案

RuoYi-Cloud 的 Controller 用的是传统 @RequestMapping 手动写路径前缀：

// ruoyi-modules/ruoyi-system/src/main/java/com/ruoyi/system/controller/@RestController@RequestMapping("/system/user")public class SysUserController { }

每个模块的路径靠人为约定，没有统一的端侧隔离机制。

2.2 认证方案

RuoYi-Cloud 使用 Spring Security + JWT Token，每个服务都配置了 TokenAuthenticationFilter：

// ruoyi-common/ruoyi-common-security/src/main/java/com/ruoyi/common/security/filter/public class JwtAuthenticationTokenFilter extends OncePerRequestFilter {    @Override    protected void doFilterInternal(HttpServletRequest request, ...) {        // 每次请求都解析 Token        LoginUser loginUser = tokenService.getLoginUser(request);        SecurityContextHolder.getContext().setAuthentication(/* ... */);        chain.doFilter(request, response);    }}

问题：Feign 调用时，每个服务都要重新解析一次 Token，重复查 Redis。

三、改造方案

不改 RuoYi-Cloud 框架代码，只做两处扩展：

1. 1. 基于包名的 API 路由自动映射 — 不再手写 /admin-api 前缀
2. 2. Feign 调用 Header 透传用户信息 — 网关验证一次，下游直接复用

四、完整代码

改造 1：基于包名的 API 路由自动映射

思路：利用 Spring MVC 的 PathMatchConfigurer，根据包名自动注入路径前缀。

第 1 步：定义配置类

// ruoyi-common/ruoyi-common-web/src/main/java/com/ruoyi/common/web/config/@Data@ConfigurationProperties(prefix = "ruoyi.web")public class WebProperties {    private Api adminApi = new Api("/admin-api", "**.controller.admin.**");    private Api appApi = new Api("/app-api", "**.controller.app.**");    @Data    @NoArgsConstructor    @AllArgsConstructor    public static class Api {        private String prefix;        private String controller;    }}

第 2 步：自动注入路径前缀

// ruoyi-common/ruoyi-common-web/src/main/java/com/ruoyi/common/web/config/@Configurationpublic class WebAutoConfiguration implements WebMvcConfigurer {    @Autowired    private WebProperties webProperties;    @Override    public void configurePathMatch(PathMatchConfigurer configurer) {        AntPathMatcher matcher = new AntPathMatcher(".");        for (WebProperties.Api api : webProperties.getApis()) {            configurer.addPathPrefix(api.getPrefix(), clazz ->                clazz.isAnnotationPresent(RestController.class)                    && matcher.match(api.getController(), clazz.getPackage().getName())            );        }    }}

效果：

// Controller 只需写业务路径package com.ruoyi.system.controller.admin.user;@RestController@RequestMapping("/user")public class SysUserController { }// 实际访问：/admin-api/system/userpackage com.ruoyi.system.controller.app.user;@RestController@RequestMapping("/user")public class AppUserController { }// 实际访问：/app-api/system/user

目录结构一目了然：

controller/├── admin/          # 管理后台 → 自动加 /admin-api│   ├── user/│   ├── role/│   └── menu/└── app/            # 移动端 → 自动加 /app-api    ├── auth/    ├── profile/    └── home/

改造 2：Feign 调用 Header 透传

核心思路：Gateway 验证一次 Token，通过 Header 传递用户信息，下游直接解析，不再重复查 Redis。

第 1 步：Feign 请求拦截器

// ruoyi-common/ruoyi-common-security/src/main/java/com/ruoyi/common/security/feign/@Slf4jpublic class LoginUserRequestInterceptor implements RequestInterceptor {    @Override    public void apply(RequestTemplate requestTemplate) {        LoginUser user = SecurityFrameworkUtils.getLoginUser();        if (user == null) {            return;        }        String userStr = JsonUtils.toJsonString(user);        userStr = URLEncoder.encode(userStr, StandardCharsets.UTF_8);        requestTemplate.header("nf-login-user", userStr);    }}

第 2 步：网关注入 Header

// ruoyi-gateway/src/main/java/com/ruoyi/gateway/filter/@Componentpublic class TokenAuthenticationFilter implements GlobalFilter {    @Override    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {        // 先移除客户端伪造的 Header        ServerHttpRequest request = exchange.getRequest().mutate()            .headers(h -> h.remove("nf-login-user"))            .build();        String token = getToken(request);        if (StrUtil.isEmpty(token)) {            return chain.filter(exchange);        }        // 验证 Token 获取用户        LoginUser user = tokenService.getLoginUser(token);        // 注入 Header 透传给下游        request = request.mutate()            .header("nf-login-user", URLEncoder.encode(JsonUtils.toJsonString(user), "UTF-8"))            .build();        return chain.filter(exchange.mutate().request(request).build());    }}

第 3 步：后端服务优先解析 Header

// ruoyi-common/ruoyi-common-security/src/main/java/com/ruoyi/common/security/filter/public class LoginUserFilter extends OncePerRequestFilter {    @Override    protected void doFilterInternal(HttpServletRequest request, ...) {        // 模式1：从 Header 获取（Feign 透传）        LoginUser user = parseLoginUserFromHeader(request);        // 模式2：从 Token 获取（外部直接访问）        if (user == null) {            String token = getToken(request);            if (StrUtil.isNotEmpty(token)) {                user = tokenService.getLoginUser(token);            }        }        if (user != null) {            SecurityFrameworkUtils.setLoginUser(user, request);        }        chain.doFilter(request, response);    }}

五、效果对比

测试环境：RuoYi-Cloud v3.8.5，JDK 17，Gateway + 2 个业务服务

六、适用场景

• • 多端项目：管理后台 + APP + 小程序，需要统一 API 管理
• • 服务链路长：3 个以上微服务链式调用
• • 高并发：QPS > 2000，Redis 查询成为瓶颈
• • 团队协作：需要代码规范约束，减少 Code Review 成本

七、注意事项

1. 1. Gateway 必须移除客户端 Header：防止用户伪造身份，第一件事就是 headers.remove("nf-login-user")
2. 2. 异步线程丢失用户：使用 TransmittableThreadLocal 或手动传递 Header
3. 3. 敏感操作二次校验：如删除/转账，走 Token 重新验证
4. 4. 包名规范必须强制：IDE 模板 + CI 检查，放错包名的 Controller 直接报错
5. 5. 兼容性：直接访问业务服务（跳过 Gateway）时降级为 Token 验证模式

📌 本期小结

💡 觉得有用？「点赞」让更多人看到「在看」支持继续更新「转发」给需要的同事

下期预告：RuoYi-Cloud 分布式事务 Seata 接入实战 | 记得关注哦～

我是小韦，专注若依生态