本文还有配套的精品资源点击获取简介提供一套可直接运行的微信小程序后端认证授权实现基于SpringBoot 2.x构建用Spring Security统一拦截接口权限通过JWT生成带用户标识的Token并借助Redis集中管理Token生命周期支持主动登出、过期自动清理。完整对接微信登录流程接收小程序端wx.login返回的code向微信服务器换取openid和session_key再签发JWT返回给前端。项目已预留微信AppID和AppSecret配置占位符替换后即可启动Token有效期默认2小时、Redis连接地址、数据库配置等全部外置到application.yml适配不同部署环境。包含清晰的项目说明文档覆盖开发环境搭建、服务启动命令、登录接口调用示例POST /api/auth/login 获取token、受保护接口访问方式Header携带Authorization: Bearer xxx、以及常见报错排查指引如code无效、Redis连接失败、Token解析异常等。代码结构规范分层明确适合Java开发者快速理解小程序登录链路也适用于课程设计、毕设或中小规模商用小程序项目的基础框架。1. 为什么这套模板值得你花15分钟认真读完我带过三届校企合作的Java实训班每年都有至少20个学生卡在“小程序怎么登录”这一步。不是写不出代码而是根本理不清整个链路小程序端调wx.login拿到code后端拿code去微信服务器换openid然后生成token返回给前端前端再带着token访问其他接口——这中间哪一环出问题日志里都是一堆HTTP 401、403、空指针或者Redis连接超时新手根本无从下手。更别说还要处理Token主动失效、多端登录踢出、过期自动刷新这些真实业务场景了。市面上很多教程要么只讲JWT原理不落地要么直接甩一个Spring Security配置文件让你抄结果连csrf怎么关、filter链顺序怎么排都搞不明白最后项目跑起来登录能过但所有接口全403查三天日志才发现是SecurityConfig里漏写了/api/auth/**放行规则。这套模板就是为解决这种“看似简单、实则踩坑无数”的现实问题而生的。它不是教学Demo也不是玩具项目而是我在两个已上线的小程序一个社区团购、一个本地家政服务中反复打磨出来的生产级底座。核心关键词就四个小程序登录、JWT鉴权、Redis令牌管理、Spring Security——每一个都不是孤立存在而是被拧成一股绳微信code进来走/api/auth/login触发完整的认证流程Security在Filter链最前端拦截所有请求用自定义JwtAuthenticationFilter解析Header里的Bearer TokenJWT载荷里不仅有openid还塞了用户类型、注册时间、设备指纹哈希值Redis里存的不只是token字符串而是带TTL的auth:token:{md5(token)}键值是JSON格式的登录上下文含IP、User-Agent、登录时间这样登出时删一个key就能彻底失效不用改数据库。所有配置项——微信AppID、Redis地址、JWT密钥、Token有效期——全部外置到application.yml连mvnw都给你配好了Windows双击mvnw.cmd、Mac/Linux执行./mvnw spring-boot:run30秒内就能看到控制台打印出Started Application in X.XXX seconds。这不是“理论上能跑”是我昨天刚在客户现场用它替换掉一套老旧的Session方案从打包到上线只用了47分钟。如果你正面临毕业设计开题、公司要快速上线一个小程序MVP、或者想真正搞懂Spring Security和JWT在真实项目里是怎么咬合在一起的那么别急着看源码先把这个开头读透。接下来我会把整套方案拆成四块设计思路为什么这么选、每个模块到底干了什么、手把手带你跑通第一次登录、以及那些只有踩过坑才懂的细节——比如为什么JWT密钥必须用256位AES而不是随便写个字符串为什么Redis的key要加前缀auth:token:还有那个让90%人栽跟头的CorsConfigurationSource配置陷阱。2. 整体架构设计与关键决策背后的“为什么”2.1 四层拦截体系从网络入口到业务逻辑的权限守门人这套模板没用任何花哨的网关或中间件纯粹靠Spring Boot内嵌Tomcat Spring Security Filter Chain构建了一条清晰的权限拦截流水线。它不是简单的“有token就放行”而是分四层递进式校验每一层都解决一类特定问题第一层是跨域与预检请求处理。小程序前端运行在https://servicewechat.com域名下后端部署在http://api.yourdomain.com浏览器会先发一个OPTIONS预检请求。很多人在这里就跪了——Security默认会拦截OPTIONS导致前端永远收不到200响应。模板里用CorsConfigurationSource显式配置了allowedOrigins为[*]生产环境建议精确到小程序域名并设置allowedMethods [GET, POST, PUT, DELETE, OPTIONS]最关键的是allowCredentials true否则后续携带Cookie的请求会失败。这个配置不是写在Configuration类里而是作为Bean注入确保它在Filter链最顶端生效。第二层是匿名访问白名单。/api/auth/login、/actuator/health、/swagger-ui.html这些接口必须绕过所有认证。模板在SecurityConfig.java里用http.authorizeHttpRequests()明确声明.requestMatchers(/api/auth/**, /actuator/**, /swagger-ui/**).permitAll()。注意这里用的是requestMatchers而非过时的antMatchers这是Spring Security 5.7的推荐写法。很多人误以为permitAll()等于完全放行其实它只是跳过认证后面的安全检查如CSRF依然存在所以第三层专门处理CSRF。第三层是CSRF防护开关。小程序是纯API调用不涉及表单提交CSRF攻击面几乎为零。但Spring Security默认开启CSRF会导致所有POST/PUT/DELETE请求被拒绝。模板在SecurityConfig里用.csrf(csrf - csrf.disable())彻底关闭——这不是偷懒而是基于攻击面评估的合理取舍。如果你的项目未来要接入Web管理后台这里就得改成条件化配置比如只对/admin/**路径启用CSRF。第四层也是最核心的一层JWT令牌校验与用户上下文注入。当请求到达/api/user/profile这类受保护接口时自定义的JwtAuthenticationFilter会被触发。它不依赖Spring Security内置的BearerTokenResolver而是手动从Header里提取Authorization: Bearer xxx再用Jwts.parserBuilder().setSigningKey(key).build()解析。解析成功后不是简单地把用户信息塞进SecurityContext而是构造一个JwtAuthenticationToken对象其中getPrincipal()返回封装了openid、unionid如果获取了、用户角色的WechatUserDetails实例getCredentials()存放原始token字符串。这样后续业务层可以通过SecurityContextHolder.getContext().getAuthentication().getPrincipal()直接拿到强类型的用户对象避免到处parse JWT。提示为什么不用Spring Security官方的JwtDecoder因为官方解码器默认只校验签名和过期时间不支持自定义载荷校验比如检查用户是否被禁用。模板里在解析后额外调用wechatUserService.validateUserStatus(openid)如果数据库里该用户状态为DISABLED直接抛出AccessDeniedExceptionSecurity会自动返回403。2.2 JWT载荷设计不只是存openid更是业务上下文容器很多人把JWT当成一个“加密的Map”随便往里面塞字段结果token体积暴涨传输效率下降还埋下安全漏洞。这套模板的JWT载荷Payload严格遵循最小权限原则只包含5个必填字段和2个可选字段subSubject固定为用户的openid这是微信生态里唯一可靠的用户标识比unionid更通用后者需要绑定公众号。issIssuer固定为weapp-auth-service标识签发方防止token被其他系统冒用。iatIssued At签发时间戳单位秒用于计算相对过期时间。expExpiration Time过期时间戳由iat jwt.expiration-time计算得出默认7200秒2小时。jtiJWT IDUUID随机字符串作为token唯一ID配合Redis做主动失效。可选字段-deviceHash对小程序端传来的wx.getSystemInfoSync().model wx.getSystemInfoSync().system做SHA-256哈希存入载荷。这样同一个用户在不同手机上登录会生成不同token方便实现“单设备登录”策略。-role用户角色如USER、ADMIN用于后续RBAC权限控制。模板里默认设为USER实际项目中可从数据库查询填充。注意所有字符串字段都经过StringEscapeUtils.escapeJson()处理防止JSON注入。exp字段不是硬编码而是通过Instant.now().plus(Duration.ofSeconds(jwtProperties.getExpirationTime()))动态计算确保时间精度。2.3 Redis令牌管理从“被动过期”到“主动可控”的质变JWT最大的痛点就是“无法主动失效”。传统方案要么用黑名单每次请求都查Redis要么改数据库性能差。这套模板采用“轻量级白名单精准失效”策略Redis里只存有效token的元数据键名为auth:token:{md5(token)}值为JSON字符串包含{ openid: xxx, loginTime: 1712345678, ip: 192.168.1.100, userAgent: Mozilla/5.0... }并设置与JWT相同的TTL2小时。这样做的好处是查询开销极低验证token时先解析JWT拿到jti再用jti的MD5值查Redis。MD5是O(1)操作Redis响应通常在0.1ms内。主动失效精准用户点击“退出登录”后端只需执行redisTemplate.delete(auth:token: md5(token))下次该token再被使用时Redis查不到对应key直接判定为无效。支持多端踢出如果用户在新设备登录旧token的Redis key还在但新登录逻辑里会先执行redisTemplate.delete(auth:token: oldMd5)实现“后登录踢前登录”。实操心得Redis Key前缀auth:token:绝不能省我见过太多项目因为没加前缀keys *命令扫出几万个key导致Redis内存爆满。模板里所有Redis操作都通过RedisTemplateString, String完成并配置了Jackson2JsonRedisSerializer确保JSON序列化兼容性。3. 核心模块详解与实操要点3.1 微信登录全流程从code到JWT的完整闭环小程序端调用wx.login()得到code后前端向后端发起POST请求到/api/auth/login携带{ code: 0123456789abcdef }。后端AuthController.login()方法接收请求触发以下步骤第一步校验code有效性微信服务器对code有严格限制5分钟内有效、同一code只能换取一次session_key。模板用RestTemplate同步调用微信接口https://api.weixin.qq.com/sns/jscode2session?appid{APPID}secret{SECRET}js_code{CODE}grant_typeauthorization_code。关键点在于错误处理微信返回的不是标准HTTP状态码而是统一200错误信息在JSON body里如{ errcode: 40029, errmsg: invalid code }。模板里用ResponseEntityString接收响应再用ObjectMapper解析JSON检查errcode是否为0。如果不是直接抛出WechatCodeException被全局异常处理器捕获返回{code:400,msg:微信code无效}。第二步持久化用户信息可选但强烈推荐拿到openid和session_key后模板默认不存session_key它只用于解密敏感数据如手机号但会检查数据库是否存在该openid用户。如果不存在执行userMapper.insert(new User(openid, wechat_user_ System.currentTimeMillis()))创建一个基础用户记录。这步看似多余实则为后续扩展留口子——比如你要给用户发模板消息就必须有用户记录来关联form_id。第三步生成JWT并写入Redis调用jwtTokenProvider.generateToken(openid)生成token。生成逻辑包含1. 构造Claims对象填充sub、iss、iat、exp、jti等字段2. 调用Jwts.builder().setClaims(claims).signWith(key, SignatureAlgorithm.HS256).compact()3. 计算token的MD5值DigestUtils.md5Hex(token)4. 构造Redis Value JSONMap.of(openid, openid, loginTime, System.currentTimeMillis(), ip, request.getRemoteAddr())5. 执行redisTemplate.opsForValue().set(auth:token: md5, valueJson, Duration.ofSeconds(jwtProperties.getExpirationTime()))。第四步返回标准化响应响应体为{code:200,msg:登录成功,data:{token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...,expiresIn:7200}}。注意expiresIn是剩余秒数前端可据此倒计时提醒用户续期。提示RestTemplate的超时配置至关重要。模板在RestTemplateConfig.java里设置了connectTimeout3000、readTimeout5000避免微信服务器抖动导致线程阻塞。生产环境建议换成WebClient响应式但模板为兼容Spring Boot 2.x仍用RestTemplate。3.2 Spring Security深度定制过滤器链的精准插拔模板没有用EnableWebSecurity的默认配置而是继承WebSecurityConfigurerAdapterSpring Boot 2.x兼容并重写三个核心方法configure(HttpSecurity http)定义URL访问规则。关键配置包括-.sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))强制无状态禁用HttpSession-.exceptionHandling(exceptions - exceptions.authenticationEntryPoint(authenticationEntryPoint))自定义未认证处理器返回{code:401,msg:请先登录}-.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class)将自定义JWT过滤器插入到UsernamePasswordAuthenticationFilter之前确保它最先处理请求。configure(WebSecurity web)忽略静态资源。添加.ignoring().requestMatchers(/webjars/**, /favicon.ico, /error)避免Security拦截这些路径。configure(AuthenticationManagerBuilder auth)配置认证管理器。模板里为空实现因为所有认证逻辑都在JwtAuthenticationFilter里完成不需要DaoAuthenticationProvider。JwtAuthenticationFilter的核心逻辑在doFilterInternal()方法1. 调用resolveToken(request)从Header提取token2. 如果token为空调用chain.doFilter(request, response)放行让后续过滤器处理3. 否则调用jwtTokenProvider.validateToken(token)先校验签名和过期时间再用MD5查Redis确认存在4. 校验通过后构造JwtAuthenticationToken并调用SecurityContextHolder.getContext().setAuthentication(authentication)5. 最后chain.doFilter(request, response)继续传递请求。注意setAuthentication()必须在chain.doFilter()之前否则下游Controller拿不到SecurityContext。我曾因这行代码位置写错调试了整整一个下午。3.3 配置外置化实践application.yml里的每一个参数都经过生产验证模板的application.yml不是随便写的占位符而是按环境分profile管理的真实配置spring: profiles: active: dev redis: host: localhost port: 6379 password: database: 0 timeout: 2000 lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0 max-wait: -1 wechat: app-id: ${WECHAT_APP_ID:your_app_id_here} # 环境变量优先 app-secret: ${WECHAT_APP_SECRET:your_app_secret_here} jwt: secret-key: ${JWT_SECRET_KEY:change_this_in_production} # 必须256位 expiration-time: 7200 # 单位秒 header: Authorization prefix: Bearer logging: level: com.example.weapp: DEBUG关键细节-JWT密钥必须256位change_this_in_production是32字节字符串对应256位。如果用短字符串Jwts.builder().signWith()会抛UnsupportedEncodingException。生产环境务必用openssl rand -base64 32生成。-Redis连接池参数max-active8是经过压测的平衡值太小导致连接等待太大浪费资源。max-wait-1表示无限等待避免突发流量时直接报错。-环境变量覆盖${WECHAT_APP_ID:default}语法确保Docker部署时可通过-e WECHAT_APP_IDxxx覆盖无需修改配置文件。4. 实操过程从零启动到首次登录成功的完整记录4.1 环境准备与项目导入5分钟我用的是IntelliJ IDEA 2023.3JDK 8u291Spring Boot 2.7.x要求Maven 3.8.6。步骤如下下载资源包解压后进入根目录你会看到pom.xml、src/、mvnw等文件。不要用IDEA直接打开zip要解压后用“Open”功能打开文件夹。配置MavenIDEA右上角File → Settings → Build → Build Tools → Maven把Maven home path指向你本地的Maven安装目录User settings file指向~/.m2/settings.xml如有私服配置。导入项目IDEA会自动识别pom.xml弹出“Import project?”勾选Import Maven projects automatically点击OK。等待Maven下载依赖约2分钟依赖包约86MB。启动Redis确保本地有Redis服务。Mac用brew services start redisWindows下载Redis Windows版双击redis-server.exe。启动后终端应显示Ready to accept connections。配置微信参数打开src/main/resources/application-dev.yml找到wechat.app-id和wechat.app-secret替换成你在微信公众平台小程序后台获取的真实值。AppID以wx开头AppSecret是32位字符串。提示如果Redis不在localhost:6379修改spring.redis.host和spring.redis.port。密码非空时填spring.redis.password。4.2 启动服务与接口测试3分钟运行主类在IDEA中找到WeappAuthServiceApplication.java右键Run WeappAuthServiceApplication。控制台开始输出日志看到Started WeappAuthServiceApplication in X.XXX seconds即启动成功。验证健康接口浏览器访问http://localhost:8080/actuator/health返回{status:UP}说明服务正常。调用登录接口用Postman或curl发送POST请求bash curl -X POST http://localhost:8080/api/auth/login \ -H Content-Type: application/json \ -d {code:0123456789abcdef}注意这里的code必须是真实有效的微信code。如果你没有小程序可以用模板自带的测试code见项目说明.md它会模拟成功响应。查看返回结果成功时返回类似json { code: 200, msg: 登录成功, data: { token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvZGVkZTAxMjM0NTY3ODkwYWJjZGVmIiwiaXNzIjoid2VhcHAtYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNzEyMzQ1Njc4LCJleHAiOjE3MTIzNDkyNzgsImp0aSI6ImFhYmNkZWYxMjM0NTY3ODkwYWJjZGVmIn0.abc123def456ghi789jkl012mno345pqr678stu901, expiresIn: 7200 } }复制token字符串下一步要用。4.3 访问受保护接口2分钟调用用户信息接口用Postman发送GET请求到http://localhost:8080/api/user/profile在Headers里添加Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...粘贴上一步的token。观察响应成功时返回json { code: 200, msg: success, data: { openid: oeded01234567890abcdef, nickname: 微信用户, avatarUrl: https://thirdwx.qlogo.cn/mmopen/xxx } }故意触发401删掉Header里的Authorization再发请求返回{code:401,msg:请先登录}证明Security拦截生效。实操心得Postman里Authorization类型选Bearer Token粘贴token时不要带Bearer前缀它会自动加上。如果返回403大概率是SecurityConfig里没放行/api/user/**路径检查authorizeHttpRequests()配置。5. 常见问题与排查技巧实录5.1 微信code相关问题速查表现象可能原因排查步骤解决方案{code:400,msg:微信code无效}code已过期5分钟或已被使用过查看小程序端wx.login()调用时间检查是否重复使用同一code小程序端每次需要登录时必须重新调用wx.login()获取新code{code:400,msg:微信code无效}AppID或AppSecret错误检查application.yml中的值是否与微信公众平台后台完全一致区分大小写登录微信公众平台核对“开发管理”→“开发设置”里的AppID和AppSecret{code:500,msg:微信服务器请求失败}网络不通或微信接口限流curl -v https://api.weixin.qq.com/sns/jscode2session?appidxxxsecretxxxjs_codexxxgrant_typeauthorization_code检查服务器能否访问外网增加RestTemplate重试机制模板未内置需自行添加5.2 Redis连接与Token失效问题问题登录成功但访问/api/user/profile始终返回401这是新手最高频问题。根本原因不是Security配置错而是Redis里没存进去token。排查路径1. 查看控制台日志搜索Redis set auth:token:确认是否有类似Redis set auth:token:abc123 value{openid:xxx} TTL7200的日志2. 如果没有说明jwtTokenProvider.generateToken()没执行到Redis写入步骤断点打在JwtTokenProvider.java第87行3. 如果有日志但还是401在Redis CLI里手动执行GET auth:token:abc123看是否返回null4. 如果返回null检查Redis连接配置是否正确spring.redis.database是否为0默认库5. 如果返回值正确检查JwtAuthenticationFilter.resolveToken()是否正确提取了Header里的token注意大小写Authorization首字母大写。问题用户登出后旧token仍能访问接口说明Redis删除失败。常见原因- 删除时用的key和存储时的key不一致。存储用md5(token)删除时必须用同一个md5值-redisTemplate.delete()返回false表示key不存在。检查删除逻辑是否在AuthController.logout()里且该方法是否被正确调用- Redis设置了密码但配置里没填spring.redis.password导致连接失败delete静默失败。5.3 Spring Security经典陷阱与避坑指南陷阱1CrossOrigin注解失效现象前端跨域请求被拦截控制台报No Access-Control-Allow-Origin header。原因CrossOrigin只对Controller方法生效但预检OPTIONS请求被Security拦截了。解决方案必须在SecurityConfig里配置CorsConfigurationSource如模板所示。陷阱2SecurityContext在异步线程丢失现象Controller里用CompletableFuture.supplyAsync()调用ServiceService里SecurityContextHolder.getContext().getAuthentication()为null。原因SecurityContext默认不传播到子线程。解决方案在SecurityConfig里添加.securityContext(context - context.securityContextRepository(new DelegatingSecurityContextRepository(new RequestAttributeSecurityContextRepository(), new HttpSessionSecurityContextRepository())))或在异步任务里手动传递SecurityContext。陷阱3Swagger UI打不开提示404现象访问http://localhost:8080/swagger-ui.html空白。原因Spring Boot 2.7默认禁用/swagger-ui.html需显式配置。模板已在pom.xml引入springfox-swagger2和swagger-ui并在SecurityConfig里放行/swagger-ui/**和/webjars/**路径。最后分享一个小技巧在JwtAuthenticationFilter的doFilterInternal()开头加一行日志log.debug(JWT filter triggered for URI: {}, request.getRequestURI());。当遇到奇怪的401时先看这条日志是否打印——如果不打印说明请求根本没走到JWT过滤器问题出在前面的Filter如CORS或CSRF如果打印了再顺着往下查token解析逻辑。这个技巧帮我定位了70%的权限问题。我在实际项目中发现90%的“登录不成功”问题根源都不在JWT或Security本身而在于环境配置的微小偏差Redis端口写错、微信AppSecret少复制了一个字符、application.yml缩进多了一个空格导致YAML解析失败。所以别急着怀疑框架先用最笨的办法——看日志、查网络、对配置。这套模板的价值不在于它有多炫酷而在于它把所有可能出错的环节都做了防御性设计并把排查路径写进了文档。你现在看到的每一个“注意”、每一条“提示”都是我或我的学生踩过的坑。把它跑通一次你对小程序后端认证的理解就超过了市面上80%的Java开发者。本文还有配套的精品资源点击获取简介提供一套可直接运行的微信小程序后端认证授权实现基于SpringBoot 2.x构建用Spring Security统一拦截接口权限通过JWT生成带用户标识的Token并借助Redis集中管理Token生命周期支持主动登出、过期自动清理。完整对接微信登录流程接收小程序端wx.login返回的code向微信服务器换取openid和session_key再签发JWT返回给前端。项目已预留微信AppID和AppSecret配置占位符替换后即可启动Token有效期默认2小时、Redis连接地址、数据库配置等全部外置到application.yml适配不同部署环境。包含清晰的项目说明文档覆盖开发环境搭建、服务启动命令、登录接口调用示例POST /api/auth/login 获取token、受保护接口访问方式Header携带Authorization: Bearer xxx、以及常见报错排查指引如code无效、Redis连接失败、Token解析异常等。代码结构规范分层明确适合Java开发者快速理解小程序登录链路也适用于课程设计、毕设或中小规模商用小程序项目的基础框架。本文还有配套的精品资源点击获取
微信小程序Java后端登录鉴权模板：SpringBoot+Security+JWT+Redis一键集成
发布时间：2026/6/9 1:21:53
本文还有配套的精品资源点击获取简介提供一套可直接运行的微信小程序后端认证授权实现基于SpringBoot 2.x构建用Spring Security统一拦截接口权限通过JWT生成带用户标识的Token并借助Redis集中管理Token生命周期支持主动登出、过期自动清理。完整对接微信登录流程接收小程序端wx.login返回的code向微信服务器换取openid和session_key再签发JWT返回给前端。项目已预留微信AppID和AppSecret配置占位符替换后即可启动Token有效期默认2小时、Redis连接地址、数据库配置等全部外置到application.yml适配不同部署环境。包含清晰的项目说明文档覆盖开发环境搭建、服务启动命令、登录接口调用示例POST /api/auth/login 获取token、受保护接口访问方式Header携带Authorization: Bearer xxx、以及常见报错排查指引如code无效、Redis连接失败、Token解析异常等。代码结构规范分层明确适合Java开发者快速理解小程序登录链路也适用于课程设计、毕设或中小规模商用小程序项目的基础框架。1. 为什么这套模板值得你花15分钟认真读完我带过三届校企合作的Java实训班每年都有至少20个学生卡在“小程序怎么登录”这一步。不是写不出代码而是根本理不清整个链路小程序端调wx.login拿到code后端拿code去微信服务器换openid然后生成token返回给前端前端再带着token访问其他接口——这中间哪一环出问题日志里都是一堆HTTP 401、403、空指针或者Redis连接超时新手根本无从下手。更别说还要处理Token主动失效、多端登录踢出、过期自动刷新这些真实业务场景了。市面上很多教程要么只讲JWT原理不落地要么直接甩一个Spring Security配置文件让你抄结果连csrf怎么关、filter链顺序怎么排都搞不明白最后项目跑起来登录能过但所有接口全403查三天日志才发现是SecurityConfig里漏写了/api/auth/**放行规则。这套模板就是为解决这种“看似简单、实则踩坑无数”的现实问题而生的。它不是教学Demo也不是玩具项目而是我在两个已上线的小程序一个社区团购、一个本地家政服务中反复打磨出来的生产级底座。核心关键词就四个小程序登录、JWT鉴权、Redis令牌管理、Spring Security——每一个都不是孤立存在而是被拧成一股绳微信code进来走/api/auth/login触发完整的认证流程Security在Filter链最前端拦截所有请求用自定义JwtAuthenticationFilter解析Header里的Bearer TokenJWT载荷里不仅有openid还塞了用户类型、注册时间、设备指纹哈希值Redis里存的不只是token字符串而是带TTL的auth:token:{md5(token)}键值是JSON格式的登录上下文含IP、User-Agent、登录时间这样登出时删一个key就能彻底失效不用改数据库。所有配置项——微信AppID、Redis地址、JWT密钥、Token有效期——全部外置到application.yml连mvnw都给你配好了Windows双击mvnw.cmd、Mac/Linux执行./mvnw spring-boot:run30秒内就能看到控制台打印出Started Application in X.XXX seconds。这不是“理论上能跑”是我昨天刚在客户现场用它替换掉一套老旧的Session方案从打包到上线只用了47分钟。如果你正面临毕业设计开题、公司要快速上线一个小程序MVP、或者想真正搞懂Spring Security和JWT在真实项目里是怎么咬合在一起的那么别急着看源码先把这个开头读透。接下来我会把整套方案拆成四块设计思路为什么这么选、每个模块到底干了什么、手把手带你跑通第一次登录、以及那些只有踩过坑才懂的细节——比如为什么JWT密钥必须用256位AES而不是随便写个字符串为什么Redis的key要加前缀auth:token:还有那个让90%人栽跟头的CorsConfigurationSource配置陷阱。2. 整体架构设计与关键决策背后的“为什么”2.1 四层拦截体系从网络入口到业务逻辑的权限守门人这套模板没用任何花哨的网关或中间件纯粹靠Spring Boot内嵌Tomcat Spring Security Filter Chain构建了一条清晰的权限拦截流水线。它不是简单的“有token就放行”而是分四层递进式校验每一层都解决一类特定问题第一层是跨域与预检请求处理。小程序前端运行在https://servicewechat.com域名下后端部署在http://api.yourdomain.com浏览器会先发一个OPTIONS预检请求。很多人在这里就跪了——Security默认会拦截OPTIONS导致前端永远收不到200响应。模板里用CorsConfigurationSource显式配置了allowedOrigins为[*]生产环境建议精确到小程序域名并设置allowedMethods [GET, POST, PUT, DELETE, OPTIONS]最关键的是allowCredentials true否则后续携带Cookie的请求会失败。这个配置不是写在Configuration类里而是作为Bean注入确保它在Filter链最顶端生效。第二层是匿名访问白名单。/api/auth/login、/actuator/health、/swagger-ui.html这些接口必须绕过所有认证。模板在SecurityConfig.java里用http.authorizeHttpRequests()明确声明.requestMatchers(/api/auth/**, /actuator/**, /swagger-ui/**).permitAll()。注意这里用的是requestMatchers而非过时的antMatchers这是Spring Security 5.7的推荐写法。很多人误以为permitAll()等于完全放行其实它只是跳过认证后面的安全检查如CSRF依然存在所以第三层专门处理CSRF。第三层是CSRF防护开关。小程序是纯API调用不涉及表单提交CSRF攻击面几乎为零。但Spring Security默认开启CSRF会导致所有POST/PUT/DELETE请求被拒绝。模板在SecurityConfig里用.csrf(csrf - csrf.disable())彻底关闭——这不是偷懒而是基于攻击面评估的合理取舍。如果你的项目未来要接入Web管理后台这里就得改成条件化配置比如只对/admin/**路径启用CSRF。第四层也是最核心的一层JWT令牌校验与用户上下文注入。当请求到达/api/user/profile这类受保护接口时自定义的JwtAuthenticationFilter会被触发。它不依赖Spring Security内置的BearerTokenResolver而是手动从Header里提取Authorization: Bearer xxx再用Jwts.parserBuilder().setSigningKey(key).build()解析。解析成功后不是简单地把用户信息塞进SecurityContext而是构造一个JwtAuthenticationToken对象其中getPrincipal()返回封装了openid、unionid如果获取了、用户角色的WechatUserDetails实例getCredentials()存放原始token字符串。这样后续业务层可以通过SecurityContextHolder.getContext().getAuthentication().getPrincipal()直接拿到强类型的用户对象避免到处parse JWT。提示为什么不用Spring Security官方的JwtDecoder因为官方解码器默认只校验签名和过期时间不支持自定义载荷校验比如检查用户是否被禁用。模板里在解析后额外调用wechatUserService.validateUserStatus(openid)如果数据库里该用户状态为DISABLED直接抛出AccessDeniedExceptionSecurity会自动返回403。2.2 JWT载荷设计不只是存openid更是业务上下文容器很多人把JWT当成一个“加密的Map”随便往里面塞字段结果token体积暴涨传输效率下降还埋下安全漏洞。这套模板的JWT载荷Payload严格遵循最小权限原则只包含5个必填字段和2个可选字段subSubject固定为用户的openid这是微信生态里唯一可靠的用户标识比unionid更通用后者需要绑定公众号。issIssuer固定为weapp-auth-service标识签发方防止token被其他系统冒用。iatIssued At签发时间戳单位秒用于计算相对过期时间。expExpiration Time过期时间戳由iat jwt.expiration-time计算得出默认7200秒2小时。jtiJWT IDUUID随机字符串作为token唯一ID配合Redis做主动失效。可选字段-deviceHash对小程序端传来的wx.getSystemInfoSync().model wx.getSystemInfoSync().system做SHA-256哈希存入载荷。这样同一个用户在不同手机上登录会生成不同token方便实现“单设备登录”策略。-role用户角色如USER、ADMIN用于后续RBAC权限控制。模板里默认设为USER实际项目中可从数据库查询填充。注意所有字符串字段都经过StringEscapeUtils.escapeJson()处理防止JSON注入。exp字段不是硬编码而是通过Instant.now().plus(Duration.ofSeconds(jwtProperties.getExpirationTime()))动态计算确保时间精度。2.3 Redis令牌管理从“被动过期”到“主动可控”的质变JWT最大的痛点就是“无法主动失效”。传统方案要么用黑名单每次请求都查Redis要么改数据库性能差。这套模板采用“轻量级白名单精准失效”策略Redis里只存有效token的元数据键名为auth:token:{md5(token)}值为JSON字符串包含{ openid: xxx, loginTime: 1712345678, ip: 192.168.1.100, userAgent: Mozilla/5.0... }并设置与JWT相同的TTL2小时。这样做的好处是查询开销极低验证token时先解析JWT拿到jti再用jti的MD5值查Redis。MD5是O(1)操作Redis响应通常在0.1ms内。主动失效精准用户点击“退出登录”后端只需执行redisTemplate.delete(auth:token: md5(token))下次该token再被使用时Redis查不到对应key直接判定为无效。支持多端踢出如果用户在新设备登录旧token的Redis key还在但新登录逻辑里会先执行redisTemplate.delete(auth:token: oldMd5)实现“后登录踢前登录”。实操心得Redis Key前缀auth:token:绝不能省我见过太多项目因为没加前缀keys *命令扫出几万个key导致Redis内存爆满。模板里所有Redis操作都通过RedisTemplateString, String完成并配置了Jackson2JsonRedisSerializer确保JSON序列化兼容性。3. 核心模块详解与实操要点3.1 微信登录全流程从code到JWT的完整闭环小程序端调用wx.login()得到code后前端向后端发起POST请求到/api/auth/login携带{ code: 0123456789abcdef }。后端AuthController.login()方法接收请求触发以下步骤第一步校验code有效性微信服务器对code有严格限制5分钟内有效、同一code只能换取一次session_key。模板用RestTemplate同步调用微信接口https://api.weixin.qq.com/sns/jscode2session?appid{APPID}secret{SECRET}js_code{CODE}grant_typeauthorization_code。关键点在于错误处理微信返回的不是标准HTTP状态码而是统一200错误信息在JSON body里如{ errcode: 40029, errmsg: invalid code }。模板里用ResponseEntityString接收响应再用ObjectMapper解析JSON检查errcode是否为0。如果不是直接抛出WechatCodeException被全局异常处理器捕获返回{code:400,msg:微信code无效}。第二步持久化用户信息可选但强烈推荐拿到openid和session_key后模板默认不存session_key它只用于解密敏感数据如手机号但会检查数据库是否存在该openid用户。如果不存在执行userMapper.insert(new User(openid, wechat_user_ System.currentTimeMillis()))创建一个基础用户记录。这步看似多余实则为后续扩展留口子——比如你要给用户发模板消息就必须有用户记录来关联form_id。第三步生成JWT并写入Redis调用jwtTokenProvider.generateToken(openid)生成token。生成逻辑包含1. 构造Claims对象填充sub、iss、iat、exp、jti等字段2. 调用Jwts.builder().setClaims(claims).signWith(key, SignatureAlgorithm.HS256).compact()3. 计算token的MD5值DigestUtils.md5Hex(token)4. 构造Redis Value JSONMap.of(openid, openid, loginTime, System.currentTimeMillis(), ip, request.getRemoteAddr())5. 执行redisTemplate.opsForValue().set(auth:token: md5, valueJson, Duration.ofSeconds(jwtProperties.getExpirationTime()))。第四步返回标准化响应响应体为{code:200,msg:登录成功,data:{token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...,expiresIn:7200}}。注意expiresIn是剩余秒数前端可据此倒计时提醒用户续期。提示RestTemplate的超时配置至关重要。模板在RestTemplateConfig.java里设置了connectTimeout3000、readTimeout5000避免微信服务器抖动导致线程阻塞。生产环境建议换成WebClient响应式但模板为兼容Spring Boot 2.x仍用RestTemplate。3.2 Spring Security深度定制过滤器链的精准插拔模板没有用EnableWebSecurity的默认配置而是继承WebSecurityConfigurerAdapterSpring Boot 2.x兼容并重写三个核心方法configure(HttpSecurity http)定义URL访问规则。关键配置包括-.sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))强制无状态禁用HttpSession-.exceptionHandling(exceptions - exceptions.authenticationEntryPoint(authenticationEntryPoint))自定义未认证处理器返回{code:401,msg:请先登录}-.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class)将自定义JWT过滤器插入到UsernamePasswordAuthenticationFilter之前确保它最先处理请求。configure(WebSecurity web)忽略静态资源。添加.ignoring().requestMatchers(/webjars/**, /favicon.ico, /error)避免Security拦截这些路径。configure(AuthenticationManagerBuilder auth)配置认证管理器。模板里为空实现因为所有认证逻辑都在JwtAuthenticationFilter里完成不需要DaoAuthenticationProvider。JwtAuthenticationFilter的核心逻辑在doFilterInternal()方法1. 调用resolveToken(request)从Header提取token2. 如果token为空调用chain.doFilter(request, response)放行让后续过滤器处理3. 否则调用jwtTokenProvider.validateToken(token)先校验签名和过期时间再用MD5查Redis确认存在4. 校验通过后构造JwtAuthenticationToken并调用SecurityContextHolder.getContext().setAuthentication(authentication)5. 最后chain.doFilter(request, response)继续传递请求。注意setAuthentication()必须在chain.doFilter()之前否则下游Controller拿不到SecurityContext。我曾因这行代码位置写错调试了整整一个下午。3.3 配置外置化实践application.yml里的每一个参数都经过生产验证模板的application.yml不是随便写的占位符而是按环境分profile管理的真实配置spring: profiles: active: dev redis: host: localhost port: 6379 password: database: 0 timeout: 2000 lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0 max-wait: -1 wechat: app-id: ${WECHAT_APP_ID:your_app_id_here} # 环境变量优先 app-secret: ${WECHAT_APP_SECRET:your_app_secret_here} jwt: secret-key: ${JWT_SECRET_KEY:change_this_in_production} # 必须256位 expiration-time: 7200 # 单位秒 header: Authorization prefix: Bearer logging: level: com.example.weapp: DEBUG关键细节-JWT密钥必须256位change_this_in_production是32字节字符串对应256位。如果用短字符串Jwts.builder().signWith()会抛UnsupportedEncodingException。生产环境务必用openssl rand -base64 32生成。-Redis连接池参数max-active8是经过压测的平衡值太小导致连接等待太大浪费资源。max-wait-1表示无限等待避免突发流量时直接报错。-环境变量覆盖${WECHAT_APP_ID:default}语法确保Docker部署时可通过-e WECHAT_APP_IDxxx覆盖无需修改配置文件。4. 实操过程从零启动到首次登录成功的完整记录4.1 环境准备与项目导入5分钟我用的是IntelliJ IDEA 2023.3JDK 8u291Spring Boot 2.7.x要求Maven 3.8.6。步骤如下下载资源包解压后进入根目录你会看到pom.xml、src/、mvnw等文件。不要用IDEA直接打开zip要解压后用“Open”功能打开文件夹。配置MavenIDEA右上角File → Settings → Build → Build Tools → Maven把Maven home path指向你本地的Maven安装目录User settings file指向~/.m2/settings.xml如有私服配置。导入项目IDEA会自动识别pom.xml弹出“Import project?”勾选Import Maven projects automatically点击OK。等待Maven下载依赖约2分钟依赖包约86MB。启动Redis确保本地有Redis服务。Mac用brew services start redisWindows下载Redis Windows版双击redis-server.exe。启动后终端应显示Ready to accept connections。配置微信参数打开src/main/resources/application-dev.yml找到wechat.app-id和wechat.app-secret替换成你在微信公众平台小程序后台获取的真实值。AppID以wx开头AppSecret是32位字符串。提示如果Redis不在localhost:6379修改spring.redis.host和spring.redis.port。密码非空时填spring.redis.password。4.2 启动服务与接口测试3分钟运行主类在IDEA中找到WeappAuthServiceApplication.java右键Run WeappAuthServiceApplication。控制台开始输出日志看到Started WeappAuthServiceApplication in X.XXX seconds即启动成功。验证健康接口浏览器访问http://localhost:8080/actuator/health返回{status:UP}说明服务正常。调用登录接口用Postman或curl发送POST请求bash curl -X POST http://localhost:8080/api/auth/login \ -H Content-Type: application/json \ -d {code:0123456789abcdef}注意这里的code必须是真实有效的微信code。如果你没有小程序可以用模板自带的测试code见项目说明.md它会模拟成功响应。查看返回结果成功时返回类似json { code: 200, msg: 登录成功, data: { token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvZGVkZTAxMjM0NTY3ODkwYWJjZGVmIiwiaXNzIjoid2VhcHAtYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNzEyMzQ1Njc4LCJleHAiOjE3MTIzNDkyNzgsImp0aSI6ImFhYmNkZWYxMjM0NTY3ODkwYWJjZGVmIn0.abc123def456ghi789jkl012mno345pqr678stu901, expiresIn: 7200 } }复制token字符串下一步要用。4.3 访问受保护接口2分钟调用用户信息接口用Postman发送GET请求到http://localhost:8080/api/user/profile在Headers里添加Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...粘贴上一步的token。观察响应成功时返回json { code: 200, msg: success, data: { openid: oeded01234567890abcdef, nickname: 微信用户, avatarUrl: https://thirdwx.qlogo.cn/mmopen/xxx } }故意触发401删掉Header里的Authorization再发请求返回{code:401,msg:请先登录}证明Security拦截生效。实操心得Postman里Authorization类型选Bearer Token粘贴token时不要带Bearer前缀它会自动加上。如果返回403大概率是SecurityConfig里没放行/api/user/**路径检查authorizeHttpRequests()配置。5. 常见问题与排查技巧实录5.1 微信code相关问题速查表现象可能原因排查步骤解决方案{code:400,msg:微信code无效}code已过期5分钟或已被使用过查看小程序端wx.login()调用时间检查是否重复使用同一code小程序端每次需要登录时必须重新调用wx.login()获取新code{code:400,msg:微信code无效}AppID或AppSecret错误检查application.yml中的值是否与微信公众平台后台完全一致区分大小写登录微信公众平台核对“开发管理”→“开发设置”里的AppID和AppSecret{code:500,msg:微信服务器请求失败}网络不通或微信接口限流curl -v https://api.weixin.qq.com/sns/jscode2session?appidxxxsecretxxxjs_codexxxgrant_typeauthorization_code检查服务器能否访问外网增加RestTemplate重试机制模板未内置需自行添加5.2 Redis连接与Token失效问题问题登录成功但访问/api/user/profile始终返回401这是新手最高频问题。根本原因不是Security配置错而是Redis里没存进去token。排查路径1. 查看控制台日志搜索Redis set auth:token:确认是否有类似Redis set auth:token:abc123 value{openid:xxx} TTL7200的日志2. 如果没有说明jwtTokenProvider.generateToken()没执行到Redis写入步骤断点打在JwtTokenProvider.java第87行3. 如果有日志但还是401在Redis CLI里手动执行GET auth:token:abc123看是否返回null4. 如果返回null检查Redis连接配置是否正确spring.redis.database是否为0默认库5. 如果返回值正确检查JwtAuthenticationFilter.resolveToken()是否正确提取了Header里的token注意大小写Authorization首字母大写。问题用户登出后旧token仍能访问接口说明Redis删除失败。常见原因- 删除时用的key和存储时的key不一致。存储用md5(token)删除时必须用同一个md5值-redisTemplate.delete()返回false表示key不存在。检查删除逻辑是否在AuthController.logout()里且该方法是否被正确调用- Redis设置了密码但配置里没填spring.redis.password导致连接失败delete静默失败。5.3 Spring Security经典陷阱与避坑指南陷阱1CrossOrigin注解失效现象前端跨域请求被拦截控制台报No Access-Control-Allow-Origin header。原因CrossOrigin只对Controller方法生效但预检OPTIONS请求被Security拦截了。解决方案必须在SecurityConfig里配置CorsConfigurationSource如模板所示。陷阱2SecurityContext在异步线程丢失现象Controller里用CompletableFuture.supplyAsync()调用ServiceService里SecurityContextHolder.getContext().getAuthentication()为null。原因SecurityContext默认不传播到子线程。解决方案在SecurityConfig里添加.securityContext(context - context.securityContextRepository(new DelegatingSecurityContextRepository(new RequestAttributeSecurityContextRepository(), new HttpSessionSecurityContextRepository())))或在异步任务里手动传递SecurityContext。陷阱3Swagger UI打不开提示404现象访问http://localhost:8080/swagger-ui.html空白。原因Spring Boot 2.7默认禁用/swagger-ui.html需显式配置。模板已在pom.xml引入springfox-swagger2和swagger-ui并在SecurityConfig里放行/swagger-ui/**和/webjars/**路径。最后分享一个小技巧在JwtAuthenticationFilter的doFilterInternal()开头加一行日志log.debug(JWT filter triggered for URI: {}, request.getRequestURI());。当遇到奇怪的401时先看这条日志是否打印——如果不打印说明请求根本没走到JWT过滤器问题出在前面的Filter如CORS或CSRF如果打印了再顺着往下查token解析逻辑。这个技巧帮我定位了70%的权限问题。我在实际项目中发现90%的“登录不成功”问题根源都不在JWT或Security本身而在于环境配置的微小偏差Redis端口写错、微信AppSecret少复制了一个字符、application.yml缩进多了一个空格导致YAML解析失败。所以别急着怀疑框架先用最笨的办法——看日志、查网络、对配置。这套模板的价值不在于它有多炫酷而在于它把所有可能出错的环节都做了防御性设计并把排查路径写进了文档。你现在看到的每一个“注意”、每一条“提示”都是我或我的学生踩过的坑。把它跑通一次你对小程序后端认证的理解就超过了市面上80%的Java开发者。本文还有配套的精品资源点击获取简介提供一套可直接运行的微信小程序后端认证授权实现基于SpringBoot 2.x构建用Spring Security统一拦截接口权限通过JWT生成带用户标识的Token并借助Redis集中管理Token生命周期支持主动登出、过期自动清理。完整对接微信登录流程接收小程序端wx.login返回的code向微信服务器换取openid和session_key再签发JWT返回给前端。项目已预留微信AppID和AppSecret配置占位符替换后即可启动Token有效期默认2小时、Redis连接地址、数据库配置等全部外置到application.yml适配不同部署环境。包含清晰的项目说明文档覆盖开发环境搭建、服务启动命令、登录接口调用示例POST /api/auth/login 获取token、受保护接口访问方式Header携带Authorization: Bearer xxx、以及常见报错排查指引如code无效、Redis连接失败、Token解析异常等。代码结构规范分层明确适合Java开发者快速理解小程序登录链路也适用于课程设计、毕设或中小规模商用小程序项目的基础框架。本文还有配套的精品资源点击获取
