Spring Boot集成JWT Token实现认证授权完整实践

在前后端分离架构中，认证授权是保障系统安全的核心环节。JWT（JSON Web Token）凭借其无状态、轻量级、可跨域等优势，成为当前前后端分离项目中主流的认证方案。本文将基于完整的Spring Boot项目代码，详细拆解如何集成JWT Token实现用户认证、接口权限控制、全局异常处理等核心功能，带你从零理解Token认证的实现逻辑与最佳实践。

本文配套代码可直接运行，涵盖学生信息CRUD、JWT登录认证、拦截器权限校验、全局异常捕获等完整功能模块，适合Spring Boot初学者快速上手Token认证开发。

一、项目核心架构与技术栈说明

本项目是一个基于Spring Boot的学生信息管理系统，核心目标是通过JWT Token实现接口的认证授权，确保未登录用户无法访问受保护接口。项目整体采用"Controller层-DAO层-模型层-拦截器-全局异常处理"的分层架构，各模块职责清晰，符合Spring Boot项目的最佳实践规范。

1.1 核心技术栈

• 核心框架：Spring Boot（依赖注入、Web开发支持）

• 认证方案：JWT（JSON Web Token）

• 数据访问：DAO层接口（对接数据库操作，此处可适配MyBatis/MyBatis-Plus等持久层框架）

• 接口规范：RESTful风格（统一响应格式、HTTP请求方法语义）

• 异常处理：@ControllerAdvice全局异常捕获

• 权限控制：Spring MVC拦截器（HandlerInterceptor）

1.2 项目核心模块

项目通过5个核心包实现完整功能，各包职责如下：

• com.xxx.springbootdemotest.controller：控制层，提供学生信息CRUD接口与登录接口

• com.xxx.springbootdemotest.exception：全局异常处理模块，统一异常响应格式

• com.xxx.springbootdemotest.config：配置层，注册拦截器并配置拦截规则

• com.xxx.springbootdemotest.interceptor：拦截器模块，实现Token校验逻辑

• com.qxxx.springbootdemotest.model：模型层，定义实体类与统一响应结果类

• com.xxx.springbootdemotest.util：工具类包，封装JWT生成与解析工具方法

二、核心功能实现原理深度解析

本项目的核心亮点是基于JWT的认证授权机制，整体流程为：用户登录成功后获取Token → 后续请求携带Token → 拦截器校验Token合法性 → 合法则放行访问接口，非法则返回认证失败。下面将按模块拆解实现逻辑。

2.1 统一响应结果封装：ResponseResult

在前后端分离项目中，统一的接口响应格式是降低前后端协作成本的关键。本项目通过泛型类ResponseResult封装所有接口的响应数据，包含响应状态码（code）、提示信息（message）、响应数据（data）三个核心字段。

核心设计思路：

• 采用泛型设计（<T>），支持不同类型的响应数据（如学生列表、Token信息等），提升通用性

• 提供多构造方法，适配"仅状态码+提示信息"（如操作失败）、"状态码+数据"、"状态码+提示信息+数据"（如查询成功返回列表）三种常见场景

• 重写toString方法，便于开发调试时查看响应数据结构

该类的设计确保了所有接口响应格式的一致性，前端可根据固定的code字段判断请求是否成功（如200代表成功，404代表操作失败，999代表异常），降低了前端数据解析的复杂度。

public class ResponseResult<T> {
    private Integer code;
    private String message;
    private T data;

    public ResponseResult(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public ResponseResult(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public ResponseResult(Integer code, T data) {
        this.code = code;
        this.data = data;
    }

    @Override
    public String toString() {
        return "ResponseResult{" +
                "code=" + code +
                ", message='" + message + '\'' +
                ", data=" + data +
                '}';
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

2.2 JWT Token核心工具类：JwtUtil

JWT Token的生成与解析是认证机制的核心，本项目通过JwtUtil工具类封装相关逻辑（代码中虽未展示完整实现，但根据调用逻辑可明确核心功能）。

核心方法解析：

• createJWT(String id, String subject, Map<String, Object> claims)：生成JWT Token。参数说明：id为用户唯一标识（此处使用学生ID），subject为用户名，claims为自定义负载（本项目未使用，传null）。生成的Token包含头部（算法类型）、负载（用户信息）、签名（防止篡改）三部分。

• parseJWT(String token)：解析Token。通过密钥验证Token的合法性，若解析成功则返回负载中的Claims对象（包含用户ID、用户名等信息），若解析失败（如Token过期、签名错误）则抛出异常。

注意事项：JWT的安全性依赖于密钥的保密性，实际开发中需将密钥配置在配置文件中（如application.yml），避免硬编码；同时需合理设置Token的过期时间，平衡安全性与用户体验。

/**
 * JWT工具类
 */
public class JwtUtil {
    //有效期为
    public static final Long JWT_TTL = 60 * 60 *1000L;// 60 * 60 *1000  一个小时
    //设置秘钥明文
    public static final String JWT_KEY = "qcby";

    /**
     * 创建token
     * @param id  //用户id
     * @param subject  // 用户名
     * @param ttlMillis // 有效期
     * @return
     */
    public static String createJWT(String id, String subject, Long ttlMillis) {

        SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;
        long nowMillis = System.currentTimeMillis();
        Date now = new Date(nowMillis);
        if(ttlMillis==null){
            ttlMillis=JwtUtil.JWT_TTL;
        }
        //签名时间
        long expMillis = nowMillis + ttlMillis;
        Date expDate = new Date(expMillis);
        SecretKey secretKey = generalKey();

        JwtBuilder builder = Jwts.builder()
                .setId(id)              //唯一的ID
                .setSubject(subject)   // 主题  可以是JSON数据
                .setIssuer("wd")     // 签发者
                .setIssuedAt(now)      // 签发时间
                .signWith(signatureAlgorithm, secretKey) //使用HS256对称加密算法签名, 第二个参数为秘钥
                .setExpiration(expDate);// 设置过期时间
        return builder.compact();
    }

    /**
     * 生成加密后的秘钥 secretKey
     * @return
     */
    public static SecretKey generalKey() {
        byte[] encodedKey = Base64.getDecoder().decode(JwtUtil.JWT_KEY);
        SecretKey key = new SecretKeySpec(encodedKey, 0, encodedKey.length, "AES");
        return key;
    }

    /**
     * 解析
     *
     * @param jwt
     * @return
     * @throws Exception
     */
    public static Claims parseJWT(String jwt) throws Exception {
        SecretKey secretKey = generalKey();
        return Jwts.parser()
                .setSigningKey(secretKey)
                .parseClaimsJws(jwt)
                .getBody();
    }

    public static void main(String[] args) {
        String token = JwtUtil.createJWT(UUID.randomUUID().toString(),"qd",null );
        System.out.println(token);
    }
}

2.3 登录接口实现：生成Token的入口

登录接口是用户获取Token的唯一入口，位于StudentController中的login方法，核心逻辑如下：

1. 前端传递用户名等登录信息（封装在Student对象中），通过@RequestBody接收

2. 调用studentDao.login(student)查询数据库，验证用户信息是否正确

3. 若查询结果仅有1条记录（说明用户存在且信息正确），则通过JwtUtil生成Token，Token中携带学生ID和用户名

4. 将生成的Token封装到Map中，通过ResponseResult返回给前端

5. 若查询结果不为1条（用户不存在或信息错误），则返回404错误提示

关键设计点：登录接口是唯一不需要Token即可访问的接口，后续将通过拦截器配置放行该接口。

@Controller
@RequestMapping("/s")
public class StudentController {
    @Autowired
    private StudentDao studentDao;

    @PostMapping("/login")
    @ResponseBody
    public ResponseResult login(@RequestBody Student student){
        List<Student> students = studentDao.login(student);
        Map<String,Object> map;
        if (students.size() == 1){
            map = new HashMap<>();
            String token = JwtUtil.createJWT(students.get(0).getId().toString(),students.get(0).getName(),null);
            map.put("token",token);
            return new ResponseResult(200,"success",map);
        }
        return new ResponseResult(404,"error");
    }
}

2.4 拦截器实现：Token校验的核心环节

为了确保所有受保护接口都必须携带合法Token才能访问，本项目通过LoginInterceptor实现Token校验，核心逻辑在preHandle方法中（该方法在接口执行前执行）：

1. 从请求头中获取Token（前端需将登录时获取的Token放在请求头的"token"字段中）

2. 判断Token是否为空：若为空则抛出"请登录"的运行时异常

3. 尝试解析Token：调用JwtUtil.parseJWT(token)解析Token，若解析失败（如Token过期、签名错误）则抛出"请登录"的异常

4. 若Token不为空且解析成功，则返回true，放行请求，允许访问接口

拦截器的作用是在接口执行前进行权限校验，将非法请求拦截在控制器之外，确保系统安全。

@Component
public class LoginInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String token = request.getHeader("token");
        if (!StringUtils.hasText(token)){
            throw new RuntimeException("请登录");
        }
        try{
            Claims claims = JwtUtil.parseJWT(token);
        }catch (Exception e){
            e.printStackTrace();
            throw new RuntimeException("请登录");
        }
        return true;
    }
}

2.5 拦截器配置：定义拦截规则

拦截器需要通过配置类注册到Spring容器中，并定义拦截规则，位于LoginConfig类（实现WebMvcConfigurer接口），核心逻辑如下：

1. 通过@Autowired注入LoginInterceptor实例

2. 重写addInterceptors方法，通过InterceptorRegistry注册拦截器

3. 通过addPathPatterns("/**")设置拦截所有请求

4. 通过excludePathPatterns("/s/login")设置放行登录接口，确保用户可以正常获取Token

配置说明：实际开发中可根据需求调整拦截规则，如放行静态资源、注册接口等不需要认证的接口。

@Configuration
public class LoginConfig implements WebMvcConfigurer {
    @Autowired
    private LoginInterceptor loginInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/s/login");
    }
}

2.6 全局异常处理：统一异常响应

拦截器中抛出的异常需要统一处理，避免直接返回默认的错误页面或杂乱的异常信息。本项目通过MyControllerAdvice类实现全局异常处理，核心逻辑如下：

1. 使用@ControllerAdvice注解标识该类为全局异常处理类，可捕获所有控制器抛出的异常

2. 使用@ExceptionHandler(Exception.class)注解标识handleException方法，该方法可处理所有类型的异常

3. 获取异常信息（e.getMessage()），封装成ResponseResult对象，设置状态码为999（自定义异常状态码），将异常信息作为提示信息返回

全局异常处理的优势：统一异常响应格式，前端可根据999状态码快速识别异常场景，同时便于开发人员排查问题。

@ControllerAdvice
public class MyControllerAdvice {
    @ExceptionHandler(Exception.class)
    @ResponseBody
    public ResponseResult handleException(Exception e){
        String message = e.getMessage();
        ResponseResult responseResult = new ResponseResult<>(999,message);
        return responseResult;
    }
}

2.7 学生信息CRUD接口：受保护的业务接口

StudentController中包含findAll（查询所有学生）、findByName（按姓名查询学生）、addStudent（新增学生）、updateStudent（修改学生）、deleteStudent（删除学生）五个业务接口，核心设计点：

• 使用@RequestMapping("/s")统一前缀，便于拦截器按前缀拦截

• 所有业务接口均使用@ResponseBody注解，返回JSON格式的响应数据（封装在ResponseResult中）

• 新增、修改接口使用@PostMapping，通过@RequestBody接收前端传递的学生信息

• 按姓名查询、删除接口使用@PathVariable接收路径参数

• 所有业务接口均需要携带合法Token才能访问（拦截器已配置拦截/s/**路径下的接口，除了/login）

@Controller
@RequestMapping("/s")
public class StudentController {
    @Autowired
    private StudentDao studentDao;

    @RequestMapping("/findAll")
    @ResponseBody
    public ResponseResult findAll(){
        List<Student> list = studentDao.findAll();
        return new ResponseResult(200,"success",list);
    }

    @RequestMapping("/findByName/{name}")
    @ResponseBody
    public ResponseResult findByName(@PathVariable String name){
        List<Student> list = studentDao.findByName(name);
        return new ResponseResult(200,"success",list);
    }

    @PostMapping("/addStudent")
    @ResponseBody
    public ResponseResult addStudent(@RequestBody Student student){
        int count = studentDao.insert(student);
        if (count > 0){
            return new ResponseResult(200,"success");
        }else {
            return new ResponseResult(404,"error");
        }
    }

    @PostMapping("/updateStudent")
    @ResponseBody
    public ResponseResult updateStudent(@RequestBody Student student){
        int count = studentDao.update(student);
        if (count > 0){
            return new ResponseResult(200,"success");
        }else {
            return new ResponseResult(404,"error");
        }
    }

    @PostMapping("/delete/{id}")
    @ResponseBody
    public ResponseResult deleteStudent(@PathVariable Integer id){
        int count = studentDao.delete(id);
        if (count > 0){
            return new ResponseResult(200,"success");
        }else {
            return new ResponseResult(404,"error");
        }
    }

}

三、完整业务流程演示

结合上述模块，我们可以梳理出整个系统的业务流程，从用户登录到访问接口的完整链路：

1. 用户登录：前端调用/s/login接口，传递登录信息 → 后端验证信息正确 → 生成Token并返回给前端

2. 访问受保护接口：前端调用/s/findAll等业务接口，在请求头中携带Token → 拦截器获取Token并校验合法性 → Token合法则放行，接口执行并返回数据；Token非法则抛出异常 → 全局异常处理类捕获异常，返回统一的异常响应

3. Token过期/非法：若Token过期或被篡改，解析时会抛出异常 → 拦截器抛出"请登录"异常 → 前端接收异常响应后，跳转到登录页面，要求用户重新登录获取新Token

四、项目亮点与最佳实践总结

本项目的实现严格遵循Spring Boot的开发规范，同时融入了JWT Token认证的最佳实践，核心亮点如下：

4.1 架构清晰，分层合理

项目采用分层架构，各模块职责单一，便于维护和扩展。例如：Controller层仅负责接收请求和返回响应，业务逻辑（此处简化为直接调用DAO层）与认证逻辑分离，拦截器专注于Token校验，全局异常处理类专注于异常统一响应。

4.2 统一响应格式，降低协作成本

通过ResponseResult泛型类统一所有接口的响应格式，前端可根据固定的状态码判断请求结果，无需针对不同接口处理不同的响应格式，提升了前后端协作效率。

4.3 无状态认证，适配分布式架构

采用JWT Token认证，Token中包含了用户的核心信息，服务器无需存储用户的认证状态，每次请求仅需校验Token即可。这种无状态的特性使得系统便于横向扩展，可部署多个服务节点，无需考虑会话共享问题。

4.4 拦截器精准控制，安全性高

通过拦截器配置，精准拦截所有受保护接口，仅放行登录接口，确保了系统的安全性。同时，Token放在请求头中传递，相比放在URL中更安全（避免Token被缓存或泄露）。

4.5 全局异常处理，提升用户体验

全局异常处理类捕获所有异常，返回统一的JSON格式响应，避免了前端看到杂乱的异常堆栈信息，同时便于开发人员快速定位问题。

五、实际开发中的优化建议

基于本项目的基础实现，在实际开发中还可进行以下优化，进一步提升系统的安全性和可维护性：

• 配置Token过期时间：在JwtUtil中设置Token的过期时间（如2小时），避免Token永久有效导致安全风险

• 刷新Token机制：实现Token刷新接口，当Token快过期时，前端可调用刷新接口获取新Token，避免用户频繁登录

• 密钥配置化：将JWT的密钥放在application.yml配置文件中，通过@Value注解注入，避免硬编码

• 细化异常类型：除了统一处理Exception，可定义自定义异常（如TokenExpiredException、TokenInvalidException），返回更精准的异常提示

• 添加日志记录：在拦截器、全局异常处理类中添加日志（如使用SLF4J），记录Token校验情况、异常信息等，便于问题排查

• 权限细化：基于Token中的用户信息实现角色权限控制，如不同角色可访问的接口不同

• 参数校验：在Controller层添加参数校验（如使用@Valid注解），避免非法参数传递到业务层

六、总结

本文基于完整的Spring Boot项目代码，详细拆解了JWT Token认证授权的实现逻辑，涵盖了统一响应封装、登录接口实现、拦截器Token校验、全局异常处理等核心模块。通过本项目的实践，我们可以快速掌握Spring Boot集成JWT的核心步骤，理解Token认证的无状态优势。

本项目代码可直接运行，适合初学者作为入门案例，在此基础上进行扩展优化，即可应用到实际的前后端分离项目中。希望本文能为你学习Spring Boot Token认证提供有价值的参考！