从零构建Spring Security + JWT微服务安全模块：穿透技术喧嚣的工程实践

微服务安全Spring SecurityJWT

于 2026-08-02 04:25:27 修改

·本内容遵循CC 4.0 BY-SA版权协议

在实际的技术开发与项目管理中，我们常常会遇到一种现象：一个技术概念或工具在社区中被过度讨论、包装，甚至形成一种“潮流”，但其核心价值、适用场景和落地细节却鲜有人深入剖析。这种现象在快速迭代的互联网技术圈尤为常见，我们可以将其类比为一种“技术圈的现状”。本文将以一个资深开发者的视角，深入探讨这种现状背后的技术本质，并通过一个具体的、可复现的案例——从零构建一个具备基础认证与授权的微服务模块——来揭示如何穿透喧嚣，聚焦于真正解决工程问题的核心实践。我们将遵循“理解问题 -> 准备环境 -> 实现核心 -> 验证与排错 -> 生产级考量”的主线，确保每一步都有明确的技术目标和可操作的检查点。

1. 理解“技术潮流”背后的核心诉求：以微服务安全为例

当我们谈论“机圈现状”或技术潮流时，其背后往往对应着真实的、未被充分解决的工程痛点。以近年来持续火热的“微服务安全”为例，各种框架、概念层出不穷。但回归本质，我们需要解决的核心问题通常非常具体：如何确保服务间的调用是可信的？如何管理不同角色用户的访问权限？如何避免常见的攻击手段？

1.1 核心问题拆解：认证、授权与安全通信

抛开纷繁的营销术语，微服务安全可以拆解为三个基石：

认证：确认“你是谁”。在分布式系统中，这通常意味着验证一个请求携带的令牌（如JWT）是否有效、是否由可信的认证中心签发。
授权：确认“你能做什么”。在认证通过后，判断当前用户或服务是否有权限执行某个操作或访问某个资源。
安全通信：确保信息在传输过程中不被窃听或篡改，这通常通过TLS/HTTPS来实现。

很多讨论停留在“该用OAuth2.0还是JWT”的层面，但更关键的是理解这些技术组件如何在一个具体的服务中协同工作，以及配置错误会导致哪些难以排查的问题。

1.2 技术选型的务实视角：Spring Security + JWT

为了将讨论落地，我们选择Java生态中广泛使用的Spring Security和JWT作为技术栈。这并不是因为它们是“最潮”的，而是因为：

生态成熟：文档丰富，社区活跃，遇到问题容易找到解决方案。
可插拔设计：其过滤器链机制清晰，便于理解请求的安全处理流程。
JWT的无状态特性：适合分布式场景，无需在服务端存储会话。

我们的目标是构建一个最小可行模块：一个提供用户信息查询的API，该API要求调用者携带有效的JWT，并且只允许管理员角色访问。

2. 环境准备与项目初始化：奠定可复现的基础

在开始写代码之前，明确且一致的环境是后续所有步骤不出错的前提。我们将使用Spring Boot 3.x和Java 17作为基准。

2.1 开发环境清单

请确保你的本地开发环境满足以下要求：

组件	要求	验证命令	说明
JDK	17 或更高版本	`java -version`	推荐使用LTS版本，如OpenJDK 17。
Maven	3.6 或更高版本	`mvn -v`	用于依赖管理和项目构建。
IDE	IntelliJ IDEA 或 VS Code	-	需安装 Lombok 插件以支持注解。
网络	可访问 Maven 中央仓库	`ping repo1.maven.org`	用于下载项目依赖。

2.2 初始化Spring Boot项目

使用 Spring Initializr 生成项目骨架，选择以下依赖：

Spring Web：用于构建RESTful API。
Spring Security：提供安全框架核心。
Lombok：减少样板代码。
JJWT：用于JWT的创建和解析。

生成的 pom.xml 关键依赖部分应如下所示：

XML

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-security</artifactId>

</dependency>

<groupId>org.projectlombok</groupId>

<artifactId>lombok</artifactId>

</dependency>

<groupId>io.jsonwebtoken</groupId>

</dependency>

<groupId>io.jsonwebtoken</groupId>

<scope>runtime</scope>

</dependency>

<groupId>io.jsonwebtoken</groupId>

<artifactId>jjwt-jackson</artifactId>

<scope>runtime</scope>

</dependency>

</dependencies>

注意：JJWT的API和Impl版本必须严格一致，否则在运行时会出现 NoClassDefFoundError。

2.3 项目结构规划

清晰的项目结构有助于维护。我们采用以下分层结构：

TEXT

src/main/java/com/example/demo/

├── config/ # 配置类

├── controller/ # 控制器层

├── dto/ # 数据传输对象

├── service/ # 业务逻辑层

├── security/ # 安全相关类（核心）

│ ├── JwtUtil.java # JWT工具类

│ ├── JwtAuthenticationFilter.java # JWT认证过滤器

│ └── SecurityConfig.java # 安全配置

└── DemoApplication.java # 启动类

3. 实现核心安全逻辑：穿透概念，直达代码

这是将安全概念转化为具体代码的关键步骤。我们将自底向上构建。

3.1 定义JWT工具类：密钥、生成与解析

首先，在 security 包下创建 JwtUtil.java。这个类负责JWT的生成和验证，是认证流程的基石。

JAVA

package com.example.demo.security;

import io.jsonwebtoken.Claims;

import io.jsonwebtoken.Jwts;

import io.jsonwebtoken.SignatureAlgorithm;

import io.jsonwebtoken.security.Keys;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;

import java.util.Date;

import java.util.HashMap;

import java.util.Map;

@Component

public class JwtUtil {

// 从配置文件中读取，生产环境务必使用强密码且妥善保管

@Value("${jwt.secret:mySecretKeyWhichIsVeryLongAndSecure123!@#}")

private String secret;

@Value("${jwt.expiration:3600000}") // 默认1小时

private Long expiration;

// 生成安全的密钥

private SecretKey getSigningKey() {

return Keys.hmacShaKeyFor(secret.getBytes());

}

// 生成JWT令牌

public String generateToken(String username, String role) {

Map<String, Object> claims = new HashMap<>();

claims.put("role", role); // 将角色信息放入claims

return Jwts.builder()

.setClaims(claims)

.setSubject(username) // 主题通常放用户名

.setIssuedAt(new Date()) // 签发时间

.setExpiration(new Date(System.currentTimeMillis() + expiration)) // 过期时间

.signWith(getSigningKey(), SignatureAlgorithm.HS256) // 签名算法和密钥

.compact();

}

// 从令牌中解析用户名

public String getUsernameFromToken(String token) {

return getAllClaimsFromToken(token).getSubject();

}

// 从令牌中解析角色

public String getRoleFromToken(String token) {

return getAllClaimsFromToken(token).get("role", String.class);

}

// 验证令牌是否有效（未过期且签名正确）

public boolean validateToken(String token, String username) {

final String tokenUsername = getUsernameFromToken(token);

return (username.equals(tokenUsername) && !isTokenExpired(token));

}

// 解析令牌中的所有声明（Claims）

private Claims getAllClaimsFromToken(String token) {

return Jwts.parserBuilder()

.setSigningKey(getSigningKey())

.build()

.parseClaimsJws(token)

.getBody();

}

// 检查令牌是否过期

private Boolean isTokenExpired(String token) {

final Date expiration = getAllClaimsFromToken(token).getExpiration();

return expiration.before(new Date());

}

关键解释：

@Value 注解用于从 application.properties 读取配置，这是生产环境将密钥外置化的第一步。
Keys.hmacShaKeyFor 是JJWT 0.10.x+推荐的方式，用于从字符串生成安全的密钥，比直接使用字符串更安全。
claims 是JWT的载荷部分，可以存放用户角色、权限等非敏感信息。
签名算法 HS256 使用对称加密，适合单服务或共享密钥的场景。如果是多服务且由独立的认证中心签发，则应考虑非对称加密算法（如RS256）。

3.2 创建JWT认证过滤器：连接Spring Security链

Spring Security的核心是一系列过滤器。我们需要创建一个自定义过滤器，在 UsernamePasswordAuthenticationFilter 之后介入，用于解析请求头中的JWT。

JAVA

package com.example.demo.security;

import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;

import org.springframework.security.core.authority.SimpleGrantedAuthority;

import org.springframework.security.core.context.SecurityContextHolder;

import org.springframework.web.filter.OncePerRequestFilter;

import javax.servlet.FilterChain;

import javax.servlet.ServletException;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import java.io.IOException;

import java.util.Collections;

public class JwtAuthenticationFilter extends OncePerRequestFilter {

private final JwtUtil jwtUtil;

public JwtAuthenticationFilter(JwtUtil jwtUtil) {

this.jwtUtil = jwtUtil;

}

@Override

protected void doFilterInternal(HttpServletRequest request,

HttpServletResponse response,

FilterChain filterChain) throws ServletException, IOException {

// 1. 从请求头中获取Token

String authHeader = request.getHeader("Authorization");

String username = null;

String jwt = null;

String role = null;

if (authHeader != null && authHeader.startsWith("Bearer ")) {

jwt = authHeader.substring(7); // 去掉"Bearer "前缀

try {

username = jwtUtil.getUsernameFromToken(jwt);

role = jwtUtil.getRoleFromToken(jwt);

} catch (Exception e) {

// 令牌无效（过期、签名错误、格式错误等）

logger.error("JWT token validation failed", e);

}

// 2. 如果令牌有效，且当前上下文没有认证信息，则设置认证信息

if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {

if (jwtUtil.validateToken(jwt, username)) {

// 创建Authentication对象

UsernamePasswordAuthenticationToken authenticationToken =

new UsernamePasswordAuthenticationToken(

username, // 主体

null, // 凭证，JWT模式下通常为null

Collections.singletonList(new SimpleGrantedAuthority("ROLE_" + role)) // 权限/角色

);

// 将认证信息设置到Security上下文中，后续过滤器/控制器可直接获取

SecurityContextHolder.getContext().setAuthentication(authenticationToken);

}

// 3. 继续执行过滤器链

filterChain.doFilter(request, response);

}

关键解释：

OncePerRequestFilter 确保该过滤器在一次请求中只执行一次。
标准做法是从 Authorization 请求头中获取令牌，格式为 Bearer <token>。
解析JWT时进行异常捕获至关重要。任何解析失败（过期、签名无效）都应记录日志并视为无效令牌，不能设置认证信息。
将解析出的用户名和角色封装成 UsernamePasswordAuthenticationToken 对象，并放入 SecurityContextHolder。这是Spring Security识别已认证用户的标志。

3.3 配置安全规则：禁用默认登录，启用JWT过滤

现在，我们需要通过配置类将自定义过滤器集成到Spring Security的过滤器链中，并定义URL的访问规则。

JAVA

package com.example.demo.security;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.security.config.annotation.web.builders.HttpSecurity;

import org.springframework.security.config.http.SessionCreationPolicy;

import org.springframework.security.web.SecurityFilterChain;

import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration

public class SecurityConfig {

private final JwtUtil jwtUtil;

public SecurityConfig(JwtUtil jwtUtil) {

this.jwtUtil = jwtUtil;

}

@Bean

public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

// 创建自定义JWT过滤器实例

JwtAuthenticationFilter jwtAuthenticationFilter = new JwtAuthenticationFilter(jwtUtil);

http

// 禁用CSRF（因为使用无状态的JWT，且通常是API服务）

.csrf().disable()

// 设置会话管理为无状态

.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)

.and()

// 配置请求授权规则

.authorizeHttpRequests(authz -> authz

// 公开登录接口，无需认证

.requestMatchers("/api/auth/login").permitAll()

// 管理员接口需要ADMIN角色

.requestMatchers("/api/admin/**").hasRole("ADMIN")

// 用户接口需要USER角色

.requestMatchers("/api/user/**").hasRole("USER")

// 其他所有请求都需要认证（但不一定需要特定角色）

.anyRequest().authenticated()

)

// 在UsernamePasswordAuthenticationFilter之前添加我们的JWT过滤器

.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);

return http.build();

}

关键解释：

csrf().disable()：对于提供REST API的无状态服务，通常可以禁用CSRF防护。如果服务包含浏览器表单提交，则需谨慎。
sessionCreationPolicy(SessionCreationPolicy.STATELESS)：这是实现无状态JWT认证的关键配置，Spring Security将不会创建或使用HttpSession。
requestMatchers()：用于匹配URL路径并定义其访问规则。规则顺序很重要，更具体的规则应放在前面。
addFilterBefore()：将我们的 JwtAuthenticationFilter 插入到 UsernamePasswordAuthenticationFilter 之前。这样，我们的过滤器会先尝试从JWT中提取认证信息，如果失败，才会走到默认的表单登录流程（本例中我们没提供表单登录，所以会返回401）。

4. 构建业务接口与验证：完成最小闭环

安全框架配置好后，我们需要创建业务接口来验证整个流程是否工作。

4.1 创建模拟登录控制器

首先，创建一个公开的登录接口，它接收用户名和密码（此处模拟），并返回一个JWT令牌。

JAVA

package com.example.demo.controller;

import com.example.demo.security.JwtUtil;

import lombok.Data;

import org.springframework.http.ResponseEntity;

import org.springframework.web.bind.annotation.*;

@RestController

@RequestMapping("/api/auth")

public class AuthController {

private final JwtUtil jwtUtil;

public AuthController(JwtUtil jwtUtil) {

this.jwtUtil = jwtUtil;

}

@PostMapping("/login")

public ResponseEntity<LoginResponse> login(@RequestBody LoginRequest request) {

// 注意：这里仅作演示，实际项目必须查询数据库进行密码校验！！！

String username = request.getUsername();

String password = request.getPassword();

// 模拟用户验证

String role = "USER"; // 默认角色

if ("admin".equals(username) && "admin123".equals(password)) {

role = "ADMIN";

} else if (!"user".equals(username) || !"user123".equals(password)) {

return ResponseEntity.status(401).body(new LoginResponse("Authentication failed"));

}

// 生成JWT令牌

String token = jwtUtil.generateToken(username, role);

return ResponseEntity.ok(new LoginResponse(token));

}

// 内部请求/响应类

@Data

static class LoginRequest {

private String username;

private String password;

}

@Data

static class LoginResponse {

private String token;

LoginResponse(String token) {

this.token = token;

}

4.2 创建受保护的管理员和用户接口

然后，创建需要特定角色才能访问的接口。

JAVA

package com.example.demo.controller;

import org.springframework.security.access.prepost.PreAuthorize;

import org.springframework.web.bind.annotation.*;

@RestController

@RequestMapping("/api/admin")

public class AdminController {

@GetMapping("/info")

@PreAuthorize("hasRole('ADMIN')") // 方法级权限控制，与配置类规则冗余但更明确

public String getAdminInfo() {

return "This is admin only information.";

}

JAVA

package com.example.demo.controller;

import org.springframework.web.bind.annotation.*;

@RestController

@RequestMapping("/api/user")

public class UserController {

@GetMapping("/profile")

public String getUserProfile() {

return "This is user profile information.";

}

4.3 配置JWT密钥与端口

在 application.properties 文件中添加配置：

PROPERTIES

# JWT配置

jwt.secret=mySuperSecretKeyThatIsAtLeast32BytesLongForHS256!@#

jwt.expiration=3600000 # 1小时，单位毫秒

# 服务器端口

server.port=8080

5. 运行验证与结果分析：从请求到响应的完整追踪

现在，启动应用 (DemoApplication)，我们将使用 curl 或 Postman 进行测试。

5.1 测试1：获取JWT令牌

BASH

curl -X POST http://localhost:8080/api/auth/login \

-H "Content-Type: application/json" \

-d '{"username":"admin","password":"admin123"}'

预期成功响应：

JSON

{"token":"eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoiQURNSU4iLCJzdWIiOiJhZG1pbiIsImlhdCI6MTcx...（很长一串）"}

5.2 测试2：使用令牌访问管理员接口

复制上一步得到的 token 值，替换到下面的命令中。

BASH

curl -X GET http://localhost:8080/api/admin/info \

-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

预期成功响应：

TEXT

This is admin only information.

5.3 测试3：使用普通用户令牌访问管理员接口（应被拒绝）

首先获取一个普通用户的令牌。

BASH

curl -X POST http://localhost:8080/api/auth/login \

-H "Content-Type: application/json" \

-d '{"username":"user","password":"user123"}'

然后用这个令牌去访问管理员接口。

BASH

curl -X GET http://localhost:8080/api/admin/info \

-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." # 使用user的token

预期失败响应：HTTP状态码 403 Forbidden，响应体为空或包含“Access Denied”信息。这表明我们的角色授权 (hasRole('ADMIN')) 生效了。

5.4 测试4：不携带令牌或使用无效令牌访问

BASH

curl -X GET http://localhost:8080/api/admin/info

预期失败响应：HTTP状态码 401 Unauthorized。

6. 常见问题排查：从现象定位到根因

在实际集成中，你几乎一定会遇到下面这些问题。以下是系统的排查路径。

问题现象	可能原因	检查点与解决方案
启动报错：`NoClassDefFoundError` 或 `ClassNotFoundException` 与JJWT相关	1. JJWT依赖版本不匹配或缺失。 2. Maven依赖未正确下载。	1. 检查 `pom.xml` 中 `jjwt-api`, `jjwt-impl`, `jjwt-jackson` 版本号是否完全一致。 2. 执行 `mvn clean compile` 观察是否有下载错误，或删除本地仓库 (`~/.m2/repository/io/jsonwebtoken`) 重新下载。
访问任何接口都跳转到 `/login` 页面	Spring Security 默认启用了表单登录。	确认 `SecurityConfig` 中已正确配置 `.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)` 并且没有遗漏 `.and()` 连接。检查配置类是否被正确扫描（`@Configuration` 注解）。
返回 `403 Forbidden`，但令牌看起来有效	1. 角色前缀问题。 2. URL匹配规则错误。 3. 方法级注解与配置类规则冲突。	1. 最常见原因：Spring Security 的 `hasRole` 方法默认会在角色名前加 `ROLE_`。确保JWT的 `role` claim 值是 `ADMIN` 而不是 `ROLE_ADMIN`，同时配置中写 `.hasRole("ADMIN")`。或者在配置中使用 `.hasAuthority("ROLE_ADMIN")`。 2. 检查 `requestMatchers("/api/admin/**")` 路径是否正确。 3. 检查控制器方法上的 `@PreAuthorize` 注解。
返回 `401 Unauthorized`	1. 请求头格式错误。 2. JWT过期或签名无效。 3. 过滤器未生效。	1. 确认请求头为 `Authorization: Bearer <token>`，注意 `Bearer` 后有一个空格。 2. 检查服务器时间是否准确。在 `JwtUtil` 的 `validateToken` 方法中增加日志，打印解析异常。 3. 在 `JwtAuthenticationFilter` 的 `doFilterInternal` 方法开始和结束处打日志，确认过滤器被调用。
日志中看到 `SignatureException: JWT signature does not match`	用于签名和验证的密钥不一致。	1. 确保 `JwtUtil` 中 `getSigningKey()` 方法逻辑一致。 2. 确保 `application.properties` 中的 `jwt.secret` 在应用启动后没有动态改变。 3. 如果部署多实例，必须共享同一个密钥。
令牌解析成功，但 `SecurityContextHolder` 中无认证信息	过滤器链顺序问题，认证信息可能在后续被清除。	确保 `JwtAuthenticationFilter` 被添加在 `UsernamePasswordAuthenticationFilter` 之前。检查是否有其他过滤器或拦截器清空了 `SecurityContext`。

7. 从演示到生产：必须考虑的最佳实践

上面的代码是一个清晰的演示，但直接用于生产环境是危险的。以下是必须升级的要点。

7.1 安全加固清单

密钥管理：绝对不要将密钥硬编码在代码或配置文件中。必须使用环境变量、云厂商的密钥管理服务（如AWS KMS, Azure Key Vault）或专门的配置中心来注入。

PROPERTIES

# 错误做法（仅用于开发）

jwt.secret=hardcodedKey

# 正确做法（生产环境）

# 从环境变量读取

jwt.secret=${JWT_SECRET_KEY}

启动命令：JWT_SECRET_KEY=your_super_strong_secret java -jar app.jar
密码校验：登录接口必须与数据库中的用户信息进行比对，并且密码必须使用BCrypt等强哈希算法加密存储，切勿明文存储或使用弱哈希。
令牌存储与吊销：无状态JWT的缺点是难以主动吊销。对于安全性要求高的场景，可以考虑：
- 使用短过期时间 + 刷新令牌机制。
- 维护一个令牌黑名单（需引入Redis等存储，增加了状态）。
- 考虑使用OAuth 2.0 + 授权服务器模式，将令牌管理职责分离。
HTTPS：生产环境必须启用HTTPS，防止令牌在传输过程中被窃取。

7.2 配置与维护建议

配置外置化：所有与环境相关的配置（数据库URL、密钥、第三方服务地址）都应放在 application-{profile}.properties 或通过环境变量、配置中心管理。
详细的日志记录：在 JwtAuthenticationFilter 和 JwtUtil 中增加不同级别的日志（INFO, WARN, ERROR），记录令牌验证成功/失败、过期等信息，这是排查问题最重要的依据。
统一的异常处理：创建 @ControllerAdvice 类，捕获 AccessDeniedException 和 AuthenticationException，返回结构统一的错误响应JSON，而不是Spring Security的默认HTML页面或空响应。
依赖版本锁定：在 pom.xml 中使用 <dependencyManagement> 或 spring-boot-dependencies 来统一管理所有依赖的版本，避免兼容性问题。

7.3 扩展方向

集成数据库：将用户、角色信息存入数据库，并使用 UserDetailsService 接口进行加载。
更细粒度的权限控制：使用 @PreAuthorize(“hasAuthority(‘USER:READ’)”) 实现基于权限字符串的控制，而非简单的角色控制。
API文档集成：使用Swagger/OpenAPI时，如何自动在文档中添加 Authorization 头字段。
多认证方式：同时支持JWT和Session认证（如管理后台使用Session，API使用JWT）。

通过这个从概念到代码，从开发到生产准备的完整流程，我们可以看到，应对“技术潮流”最有效的方式不是追逐新名词，而是深入理解其解决的核心问题，并通过严谨的工程实践将其落地。这个微服务安全模块的构建过程，其价值不在于使用了Spring Security或JWT，而在于清晰地展示了认证、授权如何融入一个真实的请求处理链路，以及每一个配置项、每一行代码背后的考量与陷阱。这才是穿透技术喧嚣，构建可靠系统的关键能力。