Spring Boot 如何整合 Passport.js 实现 Node 风格认证？

Passport.js 在 Node 生态里的流行，很大程度上来自它把认证拆成了策略注册和策略触发两个极其简单的动作。passport.use 用于注册认证方式，passport.authenticate 用于在路由中触发认证，回调函数通过 done 返回用户、错误或提示信息。这种表达方式不需要开发者记住复杂的过滤器继承体系，也不需要在 XML 或配置类之间来回跳转。Spring Boot 本身并不排斥这种设计，只是 Spring Security 默认暴露出来的接口偏底层，导致很多开发者误以为无法在 Java 项目里实现类似体验。实际上，只要把 Passport.js 的策略模型拆开，再用 Spring Security 的 AuthenticationProvider、OncePerRequestFilter 和自定义注册表承接，就能在 Spring Boot 中复刻出非常接近 Node 风格的认证写法。

Passport.js 的策略抽象到底强在哪里

Passport.js 的核心概念只有三个：策略、调用、结果回调。策略是一个可插拔的认证实现，例如本地账号密码策略用一个验证函数判断用户名和密码是否匹配，JWT 策略则从请求头中提取令牌并解析用户信息。调用发生在路由层，passport.authenticate('local') 的意思是使用名为 local 的策略处理当前请求。结果回调则由 done 函数承担，开发者可以返回错误、失败状态或成功用户对象。这个模型最大的好处是新增认证方式几乎不会影响已有代码，每个策略只关心自己的输入和输出。

下面是一段典型的 Passport.js 本地策略代码。它不需要了解 Express 的请求对象内部结构，只通过参数接收用户名和密码，然后通过 done 返回结果。这种隔离让策略逻辑可以独立测试，也可以被多个路由复用。

const passport = require('passport');
const LocalStrategy = require('passport-local').Strategy;

passport.use(new LocalStrategy(
  function(username, password, done) {
    User.findOne({ username: username }, function(err, user) {
      if (err) return done(err);
      if (!user) return done(null, false, { message: '用户名不存在' });
      if (!user.verifyPassword(password)) return done(null, false, { message: '密码错误' });
      return done(null, user);
    });
  }
));

app.post('/login',
  passport.authenticate('local', { session: false }),
  function(req, res) {
    res.json({ token: req.user.token });
  }
);

从代码可以看出来，认证策略并不绑定具体的 Web 框架。它只要拿到必要的凭据，就可以完成校验并返回结果。这一点正是我们能把它移植到 Spring Boot 中的前提。Passport.js 与 Express 的衔接靠中间件，而 Spring Boot 中与之对应的就是过滤器。

另外，Passport.js 的策略注册表非常灵活。同一个应用可以同时注册 local、jwt、oauth2 等多个策略，路由触发时只通过字符串名称选择。这个注册表结构也可以直接用 Java 的 Map 来模拟，甚至可以通过 Spring 的依赖注入自动发现所有策略实现。

Spring Security 如何对应 Passport 的三大要素

Spring Security 表面上提供了 UserDetailsService、AuthenticationManager、SecurityFilterChain 等一堆概念，看起来比 Passport.js 复杂得多，但本质上它们覆盖的是同一个问题域。AuthenticationProvider 可以理解为 Passport 的策略接口，AuthenticationManager 则相当于策略注册表和调度器的结合体，而过滤器负责从 HTTP 请求中提取认证信息并触发管理器。只要把这些组件重新组织一下，就可以得到类似 Passport 的调用节奏。

以本地账号密码认证为例，先创建一个 AuthenticationProvider，它的职责和 Passport 的 LocalStrategy 基本一致：接收用户名和密码，返回认证成功或失败的结果。Spring Security 中通常传入 UsernamePasswordAuthenticationToken 作为待认证对象，校验通过后返回带有权限信息的同类型对象。

@Component
public class LocalAuthProvider implements AuthenticationProvider {
    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        String username = authentication.getName();
        String password = authentication.getCredentials().toString();

        // 这里用伪代码表示用户查询与密码校验
        User user = userService.findByUsername(username);
        if (user == null || !passwordEncoder.matches(password, user.getPassword())) {
            throw new BadCredentialsException("用户名或密码错误");
        }

        return new UsernamePasswordAuthenticationToken(user, null, user.getAuthorities());
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return UsernamePasswordAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

这个 Provider 就相当于一个 Passport 策略。它不关心请求从哪里来，也不关心响应该如何写，只处理凭据校验。Spring Security 的 AuthenticationManager 会遍历所有 Provider，找到第一个支持当前认证对象的实现并执行。我们可以把它看成简化版的 Passport 注册表。

不过默认的过滤器和认证管理器在触发方式上还是偏重配置驱动，没有 Passport 那种“指定策略名称即可”的直观感。接下来可以把这层抽象再往上提一层，让控制器或过滤器通过字符串选择策略，真正获得 Node 风格的调用体验。

封装一套 Passport 风格策略 API

要让 Spring Boot 中的认证代码看起来像 Passport.js，核心思路是定义一个 Java 接口，把所有认证策略统一成相同的方法签名。这个接口只需要三个能力：策略名称、是否支持当前请求、执行认证。策略名称对应 passport.use 的第一个参数，执行认证对应策略函数本身。

可以设计如下结构：AuthStrategy 是策略接口，AuthRequest 保存策略名称和参数，AuthResult 表示成功或失败结果。然后利用 Spring 的构造器注入把所有 AuthStrategy 实现收集到 StrategyRegistry，形成一个按名称查找的注册表。

public interface AuthStrategy {
    String name();
    boolean supports(AuthRequest request);
    AuthResult authenticate(AuthRequest request);
}

public class AuthRequest {
    private final String strategy;
    private final Map<String, String> params = new HashMap<>();

    public AuthRequest(String strategy) {
        this.strategy = strategy;
    }

    public String getStrategy() {
        return strategy;
    }

    public Map<String, String> getParams() {
        return params;
    }
}

@Component
public class StrategyRegistry {
    private final Map<String, AuthStrategy> strategies = new HashMap<>();

    public StrategyRegistry(List<AuthStrategy> strategyList) {
        strategyList.forEach(s -> strategies.put(s.name(), s));
    }

    public Optional<AuthStrategy> find(String name) {
        return Optional.ofNullable(strategies.get(name));
    }
}

这种设计把策略注册从 Spring Security 的配置类中解放出来。新增一个认证方式时，只需实现 AuthStrategy 接口并添加 @Component 注解，注册表就会自动把它加入。与 Passport.js 一样，策略之间互不干扰。

实现 AuthResult 时需要注意，失败结果要带出消息，成功结果要带出用户主体和权限集合。这样在过滤器里就能根据结果决定是继续放行还是直接返回 401。

public class AuthResult {
    private final boolean success;
    private final Object principal;
    private final String message;
    private final List<GrantedAuthority> authorities;

    public AuthResult(boolean success, Object principal, String message, List<GrantedAuthority> authorities) {
        this.success = success;
        this.principal = principal;
        this.message = message;
        this.authorities = authorities;
    }

    public boolean isSuccess() {
        return success;
    }

    public Object getPrincipal() {
        return principal;
    }

    public String getMessage() {
        return message;
    }

    public List<GrantedAuthority> getAuthorities() {
        return authorities;
    }
}

有了这套轻量 API，过滤器就可以按照 Passport 的调用方式工作：从请求中读取策略名称，从注册表中查找策略，然后执行认证，最后根据结果显示错误或写入 Spring Security 上下文。

完整实战：本地策略与 JWT 策略协作

下面展示如何在一个 Spring Boot 项目中同时注册本地密码策略和 JWT 策略。调用方只需要在请求参数中传入 strategy=local 或 strategy=jwt，认证过滤器就会自动选择对应策略。这种形式已经非常接近 Passport.js 的参数化调用。

本地策略负责用户名密码校验，代码与前面的 LocalAuthProvider 类似，只是实现的是自定义的 AuthStrategy 接口。JWT 策略则从请求头中读取 Bearer Token，解析出用户身份并返回成功结果。

@Service
public class LocalAuthStrategy implements AuthStrategy {
    private final UserService userService;
    private final PasswordEncoder passwordEncoder;

    public LocalAuthStrategy(UserService userService, PasswordEncoder passwordEncoder) {
        this.userService = userService;
        this.passwordEncoder = passwordEncoder;
    }

    @Override
    public String name() {
        return "local";
    }

    @Override
    public boolean supports(AuthRequest request) {
        return "local".equals(request.getStrategy());
    }

    @Override
    public AuthResult authenticate(AuthRequest request) {
        String username = request.getParams().get("username");
        String password = request.getParams().get("password");
        User user = userService.findByUsername(username);
        if (user == null || !passwordEncoder.matches(password, user.getPassword())) {
            return new AuthResult(false, null, "用户名或密码错误", List.of());
        }
        return new AuthResult(true, user, "ok", user.getAuthorities());
    }
}

@Service
public class JwtAuthStrategy implements AuthStrategy {
    private final JwtTokenService jwtTokenService;

    public JwtAuthStrategy(JwtTokenService jwtTokenService) {
        this.jwtTokenService = jwtTokenService;
    }

    @Override
    public String name() {
        return "jwt";
    }

    @Override
    public boolean supports(AuthRequest request) {
        return "jwt".equals(request.getStrategy());
    }

    @Override
    public AuthResult authenticate(AuthRequest request) {
        String token = request.getParams().get("token");
        if (token == null || token.isBlank()) {
            return new AuthResult(false, null, "缺少令牌", List.of());
        }
        User user = jwtTokenService.parseAndValidate(token);
        if (user == null) {
            return new AuthResult(false, null, "令牌无效或已过期", List.of());
        }
        return new AuthResult(true, user, "ok", user.getAuthorities());
    }
}

过滤器的作用是把 HTTP 请求转换成 AuthRequest，然后调用注册表。认证成功后，过滤器会构造一个 Spring Security 的 UsernamePasswordAuthenticationToken 放入 SecurityContextHolder，后续的授权判断就能正常使用用户信息和权限。

@Component
public class PassportStyleAuthFilter extends OncePerRequestFilter {
    private final StrategyRegistry strategyRegistry;

    public PassportStyleAuthFilter(StrategyRegistry strategyRegistry) {
        this.strategyRegistry = strategyRegistry;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String strategyName = request.getParameter("strategy");
        if (strategyName == null) {
            strategyName = "local";
        }

        Optional<AuthStrategy> strategyOpt = strategyRegistry.find(strategyName);
        if (strategyOpt.isEmpty()) {
            response.setStatus(400);
            response.getWriter().write("unsupported strategy");
            return;
        }

        AuthRequest authRequest = new AuthRequest(strategyName);
        authRequest.getParams().put("username", request.getParameter("username"));
        authRequest.getParams().put("password", request.getParameter("password"));
        authRequest.getParams().put("token", request.getHeader("Authorization"));

        AuthResult result = strategyOpt.get().authenticate(authRequest);
        if (result.isSuccess()) {
            UsernamePasswordAuthenticationToken authentication =
                new UsernamePasswordAuthenticationToken(result.getPrincipal(), null, result.getAuthorities());
            SecurityContextHolder.getContext().setAuthentication(authentication);
        } else {
            response.setStatus(401);
            response.getWriter().write(result.getMessage());
            return;
        }

        chain.doFilter(request, response);
    }
}

这段过滤器的设计让控制器可以完全忽略认证细节。控制器只负责业务处理，认证策略的选择由请求参数决定。这种分工和 Express 中 passport.authenticate('local') 放在路由前面是一样的效果。引入 JWT 策略也只是在注册表中多了一个实现，没有改动控制器代码。

在安全配置类中，需要把这个过滤器放到 Spring Security 默认的用户名密码过滤器之前，并放行公开接口。由于过滤器自身已经完成认证，不需要再配置复杂的 UserDetailsService 或表单登录逻辑。

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    private final PassportStyleAuthFilter passportStyleAuthFilter;

    public SecurityConfig(PassportStyleAuthFilter passportStyleAuthFilter) {
        this.passportStyleAuthFilter = passportStyleAuthFilter;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .addFilterBefore(passportStyleAuthFilter, UsernamePasswordAuthenticationFilter.class)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/login", "/api/public/**").permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

这里使用了 authorizeHttpRequests，它是 Spring Security 6 及之后版本推荐的写法。如果你的项目还在 Spring Boot 2.x 时期，可以改用 authorizeRequests，但整体结构不变。核心是把自定义过滤器前移到默认认证逻辑之前，避免表单登录机制干扰。

拆成独立 Node 认证服务还是继续在 JVM 内实现

虽然可以在 Spring Boot 内部复刻 Passport.js 风格，但有些人会问：直接把 Passport.js 跑在 Node 服务里，再让 Spring Boot 通过 HTTP 调用认证接口，是否更合理？这种方案适合团队同时维护 Node 和 Java 服务，并且已经有网关统一处理认证的情况。Node 认证服务的优势是能直接使用 Passport.js 及其丰富插件，例如 OAuth2、SAML、LDAP 等，不需要在 Java 侧重复造轮子。

如果选择独立 Node 认证服务，Spring Boot 可以只负责业务 API，认证令牌由 Node 服务签发，业务服务通过公钥或共享密钥校验 JWT。这种架构下，Passport.js 原封不动运行在 Node 环境中，Spring Boot 反而只需要一个简单的 JWT 校验过滤器。不过代价是系统多了一个服务，部署、监控和链路追踪都更复杂。

如果团队以 Java 为主，仅仅因为喜欢 Passport.js 的调用风格就引入一个 Node 服务，成本往往高于收益。此时更适合采用本文的方式，在 Spring Boot 中抽象出 AuthStrategy，保留 Passport 的设计思想，同时继续使用 Java 生态的稳定性和 Spring Security 的上下文体系。无论选择哪条路，目的都是让认证代码更好维护，而不是执着于某一种语言运行时。

最终判断标准其实很简单：如果现有认证插件生态大多来自 npm，且团队有 Node 工程化能力，拆成独立认证服务更合理；如果只是想把认证模块写得像 Passport 一样清晰，在 Spring Boot 内封装策略 API 已经足够。

Spring BootPassport.js认证策略修改时间：2026-10-07 01:00:17