1. 接口加密这件事先搞清楚要防的是谁若依RuoYi前后端分离版落地到实际项目里最常被安全评审挑出来的一条就是/system/user/list这类接口打开浏览器 F12 或者挂个抓包工具请求体里的手机号、身份证号、部门名称全是明文响应体里的用户列表也原样躺在那里。接口加密这个词听着玄乎实际上要解决的问题非常具体——让业务数据在浏览器到服务端这一段路上不以可读形式出现同时让请求具备不可篡改、不可重放的属性。我在几个基于 SpringBoot 前后端分离的中后台项目里都做过这块改造包括若依这套脚手架。踩过的坑不算少有些坑甚至不是加密本身的问题而是加密顺带把框架原有机制给打乱了。这篇内容围绕若依前后端分离版讲清楚四件事方案怎么选、后端在过滤器链的哪个位置插入解密、前端 axios 拦截器里怎么组装报文、以及实测中那些让人抓狂的排查过程。适合已经把若依跑起来、想给接口加一层防护的后端同学也适合负责前端请求封装的伙伴对照着改。需要先摆正一个认知前端加密永远不是绝对安全它的价值在于抬高攻击成本、满足合规要求、防止低级的信息泄露。任何声称前端加密后数据绝对安全的说法都不成立因为密钥就在浏览器里。想明白这一点后面的技术选型和投入尺度才不会跑偏。1.1 抓包工具面前明文接口有多透明前后端分离之后浏览器和服务端之间的通信全部走 HTTP 报文只要用户在本地装了抓包工具、配了证书或者干脆就是公司内部做安全测试的同事请求和响应对他而言就是一本书。若依默认的登录接口/login提交的是用户名密码明文虽然有 HTTPS 兜底/system/user/list返回的是完整用户信息/system/dept/list返回组织架构。这些东西一旦被批量抓取配合一个简单的脚本就能拖库。HTTPS 能挡住链路中间的窃听但挡不住客户端本地的抓包也挡不住用户自己就是攻击者这个场景。比如一个内部系统员工账号泄露之后攻击者拿这个账号登录再改一改请求参数就能拉到不属于自己的数据。接口加密在这种场景下的作用是让攻击者无法通过简单地修改明文参数来构造请求——因为参数被加密了改动之后服务端解密直接失败。所以判断一个项目需不需要做接口加密我的经验是看三条一是有没有等保或者行业合规的硬性要求二是接口里有没有身份证、手机号、薪资、病例这类敏感字段三是接口权限模型是不是只靠前端隐藏菜单、后端缺少细粒度校验。三条中两条以上命中就值得做。1.2 加密、签名、防重放是三件不同的事很多人把接口加密理解成把请求体加密一下实际上完整的报文防护包含三个互相独立的能力缺一个都会留下口子。**加密Encrypt**解决的是机密性——数据不以明文出现在报文中。攻击者抓包看到的是一串 Base64读不懂。**签名Sign**解决的是完整性——报文有没有被篡改。只加密不签名的话虽然攻击者看不懂明文但他可以把整个密文原样截下来再发一次或者把 A 接口的密文贴到 B 接口上。签名是拿参数、时间戳、随机数加一个密钥算出来的哈希服务端收到后重新算一遍对不上就拒绝。**防重放Anti-Replay**解决的是时效性——同一个合法报文能不能被无限次使用。做法是请求里带时间戳和一次性随机数nonce服务端校验时间戳在容忍窗口内比如 5 分钟并把 nonce 写进 RedisTTL 覆盖窗口期重复出现直接拒绝。三者组合起来才是完整方案。只做加密攻击者可以重放只做签名攻击者可以读明文只做防重放参数照样裸露。实际项目里我一般按这三个能力一起设计代码量其实比想象中小一个工具类加一个过滤器就能装下。1.3 全站加密的代价与分级策略有人上来就想给所有接口加解密结果上线后发现两件事性能掉了一截前端到处报错。AES 加解密的开销单次几乎可以忽略微秒级但高频接口叠加上 Base64 编解码、JSON 序列化两次、大响应体翻倍吞吐确实会下降。而且像文件下载、图片预览、验证码这些接口加密之后就很难处理了。我的做法是分级按接口的敏感程度分三档等级适用接口处理方式L1 强保护登录、实名认证、手机号/身份证相关、批量导出加密 签名 nonce 防重放L2 中保护常规增删改查、列表查询只做签名 时间戳不加密请求体L3 不处理验证码图片、文件上传下载、静态资源、健康检查白名单直接放行分级的意义在于把有限的复杂度花在刀刃上。L2 只签名不加密很简单前端只是在请求头多带两个字段后端在过滤器里做一次 HMAC 校验几乎无感。L1 才需要动请求体。这里有个细节要说清楚分级判定不能让前端自己说了算否则攻击者绕过前端直接把请求标成 L3 就通过了。正确做法是后端维护一份 URL 白名单放行的和一份强制加密的 URL 清单前端加密属于配合后端校验属于兜底。真正的高危接口后端必须强制要求签名头存在缺失直接返回 401。2. 算法与密钥方案AES-CBC 打底RSA/SM2 只解决密钥分发算法选型这块网上有很多教科书式的方案前端用 RSA 公钥加密后端用私钥解密。听起来很优雅但真跑起来会撞上一个残酷的现实——RSA 只能加密不超过密钥长度减去填充开销的数据2048 位密钥最多加密 245 字节。一个稍微大一点的 JSON 就超了更别说列表接口的响应。所以实际能落地的方案几乎都是对称加密打底非对称加密最多用来传递对称密钥或者干脆不用。若依这类中后台项目我推荐的就是 AES-128/256 CBC 模式 PKCS5Padding再配一个 HMAC-SHA256 签名。国密场景换成 SM4 SM3结构完全一样。2.1 为什么绝大多数项目最后落回对称加密对称加密与非对称加密的性能差距是数量级的。AES 在普通笔记本上单核能做几百 MB/s 的吞吐RSA-2048 单次解密大概在毫秒级而且还有上面说的长度限制。一个列表接口返回 200 条记录、200KB 的 JSON用非对称加密根本走不通。还有一个更现实的问题前端做非对称加密需要引入 JS 库jsencrypt、sm-crypto 之类这些库处理大字符串时性能很差在低端安卓机上能卡出明显的白屏。而对称加密用 crypto-js 里的 AES性能表现可以接受。那么 RSA 在方案里还有没有位置有。如果你们的安全要求里明确每次会话使用不同的对称密钥那就可以用前端随机生成 AES key用 RSA 公钥加密后放在请求头后端用私钥解出 AES key这套混合模式。但代价是每个请求都要做一次 RSA 解密且后端需要维持密钥与会话的关联或者干脆一次一密把加密后的 key 随请求传递。对绝大多数中后台系统来说这个复杂度收益比不划算。我的建议很直接固定密钥的 AES HMAC 签名 nonce 防重放这套方案能覆盖 90% 的场景代码量小排查容易。只有金融、医疗这类强监管场景才考虑混合模式。2.2 密钥写在前端就等于公开这一点必须承认不管你把密钥藏在哪个 JS 文件里做了多少层混淆、拆成几段拼接、在运行时才组装最终它都要在浏览器内存里以明文形式存在。稍微懂行的人打开 DevTools、打个断点、看一眼前端算出来的结果密钥就出来了。那这套方案还有什么意义意义在于它防的是批量脚本化的攻击和随手改参数的好奇心挡不住的是专门针对你的逆向分析。这两类攻击者的成本差了两三个数量级绝大多数系统只需要挡住前一类。因此密钥管理上有几条实际经验前端密钥和后端密钥分环境配置开发、测试、生产的密钥必须不同避免测试环境泄露之后生产直接沦陷。前端密钥至少做一次 Base64 编码或者简单的字符打散不要让const AES_KEY 1234567890abcdef这样赤裸裸地躺在打包产物里。密钥定期轮换后端支持同时接受新旧两把密钥用版本号区分请求头带X-Key-Version轮换时不影响在线用户。后端密钥放配置中心或环境变量不要写死在application.yml里跟着代码一起进 Git。2.3 和现有 JWT 认证体系的职责划分若依前后端分离版的认证走的是 Spring Security JWTToken 放在Authorization请求头里。接口加密加进来之后两者职责要理清楚不然会出现到底谁先校验的混乱。我的分工是这样的JWT 负责你是谁签名负责这个报文是不是你发的且没被改过加密负责报文内容别被人看见。执行顺序上先做解密 验签在过滤器里再做 JWT 认证在 Spring Security 的过滤链里最后进 Controller。为什么这个顺序因为签名里通常会把 Token 的摘要也算进去服务端需要先验证报文完整再去解析 Token 判断身份。如果反过来先认证后验签攻击者可以拿一个合法 Token 构造任意报文的签名请求——虽然他还是进不来因为签名不对但错误码会误导排查方向。还有一个易错点登录接口本身没有 Token但它恰恰是最需要保护的接口密码明文传输。所以登录接口要放进需要加密但不需要 Token 校验的名单在 Spring Security 的permitAll里放行同时加密过滤器照样生效。3. 后端改造在若依的过滤器链上开一道解密口子后端这块是整个改造的核心也是最容易出问题的地方。核心难点只有一个Servlet 的请求体流只能读一次。如果我们在过滤器里把 InputStream 读完解密后面的RequestBody就拿不到数据了会直接报Required request body is missing。解决办法是经典的HttpServletRequestWrapper套路把原始流读出来、解密、塞进一个字节数组然后用一个自定义的 Wrapper 覆盖getInputStream()和getReader()让它每次都返回一个新的流对象。这个套路不新鲜但在若依这种已经叠了好几层过滤器的框架里位置和顺序要格外小心。3.1 解密放在过滤器而不是拦截器的原因Spring MVC 的HandlerInterceptor里读请求体是可以的但问题是拦截器执行时HttpMessageConverter还没有消费流你必须自己读完再包一层然后想办法把包装后的 request 传递下去——而拦截器的preHandle方法签名里根本没有办法替换 request 对象。所以拦截器这条路基本走不通。ControllerAdvice配RequestBodyAdvice倒是一个思路它能在消息转换阶段介入beforeBodyRead里可以替换输入消息。但这种方式只对RequestBody生效对表单提交、文件上传无能为力而且和全局异常处理的配合比较别扭。过滤器Filter是最合适的位置它在 DispatcherServlet 之前执行可以完整地替换 request 对象对所有进入容器的请求统一生效。若依本身就用了不少过滤器XSS 过滤、Repeatable 过滤等我们加一个解密过滤器属于同一种模式风格也统一。3.2 可重复读的 RequestWrapper 写法先看 Wrapper 的实现这是整个方案的地基写错了后面全是坑。public class DecryptRequestWrapper extends HttpServletRequestWrapper { private final byte[] body; public DecryptRequestWrapper(HttpServletRequest request, byte[] body) { super(request); this.body body null ? new byte[0] : body; } Override public BufferedReader getReader() { return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8)); } Override public ServletInputStream getInputStream() { final ByteArrayInputStream bais new ByteArrayInputStream(body); return new ServletInputStream() { Override public boolean isFinished() { return bais.available() 0; } Override public boolean isReady() { return true; } Override public void setReadListener(ReadListener listener) { throw new UnsupportedOperationException(); } Override public int read() { return bais.read(); } }; } Override public int getContentLength() { return body.length; } Override public long getContentLengthLong() { return body.length; } }这段代码里最容易被忽略的是最后两个方法。如果不重写getContentLength()它返回的还是原始密文的长度而解密后的明文长度通常和密文不同Base64 解码后长度变短但 JSON 明文又比原始密文短。Spring 在读取 body 时如果依赖 Content-Length 做长度校验就会出现只读了一半或者读了多余字节的问题表现是 JSON 解析报Unexpected end of JSON input或者末尾多出乱码。这个坑我踩过一次排查了整整一个下午。3.3 过滤器注册顺序与若依 XSS 过滤的先后关系若依默认带了 XSS 过滤器它会对请求参数做转义处理防住脚本注入。我们的解密过滤器必须排在它之前否则 XSS 过滤器看到的是 Base64 密文里面不会有尖括号当然安全但解密之后的明文就绕过了 XSS 检查等于把防护撕开了一个口子。用 Spring Boot 的FilterRegistrationBean显式指定 order比Order注解更可控因为若依内部有些过滤器是通过Bean注册的注解和注册顺序混在一起容易乱。Configuration public class CryptoFilterConfig { Bean public FilterRegistrationBeanDecryptFilter decryptFilterRegistration(DecryptFilter filter) { FilterRegistrationBeanDecryptFilter bean new FilterRegistrationBean(); bean.setFilter(filter); bean.addUrlPatterns(/*); bean.setOrder(Ordered.HIGHEST_PRECEDENCE 10); bean.setName(decryptFilter); return bean; } }Ordered.HIGHEST_PRECEDENCE是Integer.MIN_VALUE加 10 是为了给容器自身的编码过滤器留位置同时保证排在其他业务过滤器前面。数字越小越靠前这一点和拦截器相反别记混了。过滤器主体大致长这样Component public class DecryptFilter extends OncePerRequestFilter { Resource private ApiCryptoProperties props; Resource private RedisCache redisCache; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { String uri request.getRequestURI(); if (!props.isEnabled() || MatchUtils.isWhite(uri, props.getUrlWhitelist())) { chain.doFilter(request, response); return; } String cipherText StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8); if (StringUtils.isEmpty(cipherText)) { // 无报文体的 GET 请求只校验签名 verifySign(request, ); chain.doFilter(request, response); return; } // 1. 先验签对密文验签避免解密后被篡改 verifySign(request, cipherText); // 2. 校验 nonce 是否重复 checkNonce(request.getHeader(X-Nonce)); // 3. 解密 String plain AesUtils.decrypt(cipherText, props.getAesKey()); chain.doFilter(new DecryptRequestWrapper(request, plain.getBytes(StandardCharsets.UTF_8)), response); } }注意第 1 步的顺序对密文做验签。如果先解密再验签攻击者可以构造任意密文让服务端先解一次虽然大概率解密失败抛异常但异常堆栈、错误信息本身就是信息泄露。对密文验签成本一样安全性更好。校验失败时统一抛一个自定义异常交给若依的全局异常处理器GlobalExceptionHandler返回统一格式不要在前端看到javax.crypto.BadPaddingException这种堆栈信息。3.4 配置项与开关设计配置项单独抽一个ConfigurationProperties方便后续调参和按环境覆盖。api-crypto: enabled: true aes-key: S3cr3tKeyForDemo0123456789ABCDEF # 32 位AES-256 sign-secret: SignSecretForHmac0123456789 timestamp-tolerance: 300000 # 5 分钟单位毫秒 nonce-ttl: 300 # Redis 过期时间单位秒 url-whitelist: - /login - /captchaImage - /common/download - /profile/avatarenabled这个开关非常关键。开发阶段前后端联调加密会产生大量噪音加个开关可以让前端在本地把加密关掉VUE_APP_CRYPTO_ENABLEDfalse后端也跟着关联调效率高很多。上线前记得确认两边的开关都打开我曾经遇到过一次测试环境关了忘了开上线后所有的加密请求全被服务端当成缺签名头拒绝了好在灰度及时发现。签名算法本身很简单把需要参与签名的要素按固定顺序拼成一个字符串再用 HMAC-SHA256 算摘要signSource method \n uri \n timestamp \n nonce \n body sign Base64(HmacSHA256(signSource, signSecret))拼接顺序前后端必须完全一致中间的分隔符也别省略否则会出现两边算法一样但结果永远对不上的问题而且这种问题极难排查因为哈希值看起来都是乱的。我的习惯是把这套拼装逻辑写在文档里前后端各自实现联调时先拿同一个固定输入跑一遍对比输出确认一致后再接业务。4. 前端改造axios 拦截器里的加密时序若依前端是 Vue axios所有请求都走src/utils/request.js里统一的实例拦截器已经做了 Token 注入、重复提交判断、错误码统一处理。加密代码要插进去最忌讳的就是直接在最前面加一段把原有的机制打乱。前端有一个绕不开的技术细节要先说清楚crypto-js 不支持 AES-GCM 模式它只实现了 CBC、CFB、OFB、CTR、ECB 这几种。如果后端选了AES/GCM/NoPadding前端用 crypto-js 根本对不上只能改用浏览器原生的 Web Crypto APIcrypto.subtle。但crypto.subtle只在 HTTPS 或者 localhost 下可用内网 HTTP 部署的环境直接报undefined。所以前后端要约定同一个模式。我的选择是 CBC PKCS7虽然 CBC 在密码学上不如 GCM没有内置完整性校验但我们外层已经加了 HMAC 签名完整性由签名保证CBC 的弱点被补上了。4.1 请求拦截器中加密、签名、时间戳的组装顺序axios 的请求拦截器会按注册顺序倒序执行若依默认就有一个拦截器做 Token 注入和重复提交判断。新增的加密拦截器必须加在它之后注册也就是更早执行否则加密完再判断重复提交每次密文都不同重复提交检查永远通过。更稳妥的做法是干脆把加密逻辑写进现有的拦截器里用明确的顺序控制。组装顺序是这样的判断是否需要加密白名单 URL、开关状态。生成 13 位时间戳和 16 位随机 nonce。把config.data序列化成 JSON 字符串。生成 16 字节随机 IVAES-CBC 加密输出Base64(IV 密文)。用method uri timestamp nonce 密文计算 HMAC 签名。把密文替换config.data时间戳、nonce、签名、密钥版本塞进请求头。前端加密的核心代码import CryptoJS from crypto-js const AES_KEY CryptoJS.enc.Utf8.parse(process.env.VUE_APP_AES_KEY) const SIGN_SECRET process.env.VUE_APP_SIGN_SECRET function encryptBody(plain) { const iv CryptoJS.lib.WordArray.random(16) const encrypted CryptoJS.AES.encrypt(plain, AES_KEY, { iv: iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }) // IV 前置拼接到密文后端按前 16 字节取 IV return iv.concat(encrypted.ciphertext).toString(CryptoJS.enc.Base64) } function buildSign(method, uri, timestamp, nonce, body) { const source [method.toUpperCase(), uri, timestamp, nonce, body].join(\n) return CryptoJS.HmacSHA256(source, SIGN_SECRET).toString(CryptoJS.enc.Base64) }有一个细节必须提醒CryptoJS.lib.WordArray.random(16)生成的 IV 是 WordArray 对象iv.concat(ciphertext)返回新对象不会修改原 IV这个行为是正确的。但如果你看到某些老代码里先iv.concat(...)再单独用iv那可能会出问题因为不同版本的 crypto-js 在concat的副作用上表现不一致稳妥起见还是显式 clone 一份。4.2 响应解密与 blob 下载的分流响应这块比请求麻烦因为 axios 的响应可能是 JSON也可能是 blob文件下载还可能是纯文本。如果后端统一做了响应加密前端在响应拦截器里要先判断response.config.responseType是blob或arraybuffer直接放行不解密。是普通 JSON取response.data它是一个 Base64 字符串解密后JSON.parse回来。service.interceptors.response.use(res { if (res.config.responseType blob || res.config.responseType arraybuffer) { return res } if (typeof res.data string res.data.length 0) { try { const plain decryptBody(res.data) res.data JSON.parse(plain) } catch (e) { // 非加密响应保持原样 } } return handleCode(res) }, error { ... })这里用try/catch兜底是必要的。总有一些接口没有走加密比如第三方回调、健康检查如果解密失败就抛异常这些接口就全挂了。用一个宽松的 fallback先把字符串当普通数据处理能大幅降低上线的风险面。还有一个更隐蔽的问题加解密和解密失败的错误处理会互相掩盖。比如后端返回了一个 500 错误响应体是若依统一的{code: 500, msg: xxx}如果这个错误响应没走加密前端解密失败后 fallback 到原样解析看起来是对的。但如果错误响应走了加密而前端在解析之前就抛了SyntaxError用户看到的就是一个空白页面。所以错误响应的处理路径一定要和正常响应走同一套逻辑别用两套代码。5. 真实踩过的六个坑与排查顺序加密这套东西写代码可能只要两天调通要一周排查问题要更久。下面这几个坑都是我实际遇到过的按症状—定位—修复的顺序写出来方便你对照着排查。5.1 请求体读两次变空症状与定位路径症状很典型前端发了加密请求后端日志显示过滤器里解密成功、明文也打印出来了但进到 Controller 里RequestBody参数全是 null或者直接报Required request body is missing。定位路径分三步第一步在过滤器里打印request.getClass().getName()确认包装是否生效。如果打出来还是org.apache.catalina.connector.RequestFacade说明chain.doFilter传的还是原对象包装没起作用。第二步检查是不是有其他过滤器在更前面读了流。若依自带的一些过滤器、日志组件、链路追踪组件都可能在早期读 body。可以用request.getInputStream().available()打印一下如果是 0说明已经被消费了。第三步检查 Content-Length。如果 Wrapper 里没重写getContentLength()Spring 按旧的 Content-Length 读读到一半就停了。修复方案就是前面写的 Wrapper 完整实现加上显式重写长度方法。如果项目里还有别的过滤器要读 body那就统一改用ContentCachingRequestWrapper风格的缓存或者干脆把解密过滤器提到最前面独占读取权。5.2 重复提交拦截失效若依前端request.js里有一段重复提交判断逻辑是把url data作为 key 存进 sessionStorage短时间内相同就拦截。加了加密之后每次请求的 IV 随机、nonce 随机密文完全不一样这个判断就形同虚设了。这个坑的影响不大毕竟后端还有RepeatSubmit注解兜底但如果你的业务里前端拦截是关键防线就得处理。我的做法是在加密之前用明文做重复判断const plainData JSON.stringify(config.data || {}) if (isRepeatSubmit(config.url, plainData)) { return Promise.reject(new Error(数据正在处理请勿重复提交)) } // 再做加密 config.data encryptBody(plainData)后端那边RepeatSubmit的 key 是基于解密后的请求参数算的所以后端拦截是正常工作的。这里要注意若依的RepeatSubmitInterceptor实现它是拿request.getParameterMap()和 body 一起算 key 的我们包装后的 request 里getParameterMap返回的是原始参数加密请求通常不用 query 参数body 是解密后的明文算出来的 key 是对的。这一点我专门验证过没问题。5.3 Base64 里的加号在 URL 中变成空格Base64 字符集里有、/、三个特殊字符其中在 URL 的 query string 里会被解码成空格。如果密文放在 URL 参数里传输有些老接口这么干后端收到之后解密必然失败报Illegal base64 character或者解出来是乱码。处理方式有两种一是传输前做一次encodeURIComponent后端先URLDecoder.decode再解密二是换成 URL 安全的 Base64 变体把换成-、/换成_去掉末尾的。Java 里用Base64.getUrlEncoder().withoutPadding()前端用CryptoJS.enc.Base64.stringify(...).replace(/\/g, -).replace(/\//g, _).replace(/$/, )。两边必须严格一致少做一步就对不上。我现在的项目里密文一律放请求体不放 URL从源头上避开这个问题。但还是建议把 URL 安全的编码函数提前准备好表单提交、重定向带参数这些场景迟早会用上。5.4 大文件上传整体加密导致内存溢出有人图省事在 axios 拦截器里对所有请求统一加密包括multipart/form-data的文件上传。结果用户传一个 200MB 的视频浏览器直接把内存吃满页面崩溃。原因很直白config.data如果是 FormData你不能简单JSON.stringify而如果强行把文件读成 ArrayBuffer 再加密等于把一个 200MB 的 buffer 在内存里复制三份原始、密文、Base64现代浏览器也扛不住。正确的处理是文件上传接口加入白名单不做整体加密。如果业务上确实需要保护上传内容那也不应该走前端加密而是走 HTTPS 服务端存储加密 短时效的上传凭证。前端加密在这个场景没有收益只有风险。顺带说一句文件下载同理。若依的/common/download返回的是二进制流如果被响应拦截器当成 Base64 字符串去解密要么报错要么把文件搞坏。必须用responseType做分流这个前面已经说过了。5.5 时间戳与服务器时钟偏差防重放的时间戳校验最怕的就是用户设备的时钟不准。我遇到过一台测试机的时间比服务器慢了 8 分钟所有请求都被判时间戳过期但设备上显示的时间看起来完全正常。TP 容忍窗口设多大合适太小容易误伤太大会削弱防重放效果。我的经验值是 5 分钟300000 毫秒能覆盖绝大多数时钟偏差同时把重放窗口控制在可接受范围内。还有一个进阶处理如果服务端发现时间戳偏差在 5 到 30 分钟之间不要直接拒绝而是在响应头里返回服务器的当前时间戳前端拿到之后自动校准本地时钟记录一个 offset后续请求都用本地时间 offset。这个机制我在一个跨时区部署的项目里用过效果不错。要注意的是时区并不是问题——时间戳统一用 UTC 毫秒数前后端的Date.now()和System.currentTimeMillis()都是 UTC 基准跟时区没关系。真正的问题只有设备时钟本身的偏差。5.6 签名对不上时的排查顺序签名不匹配是最让人头大的问题因为哈希值看起来就是一堆乱码没有任何可读信息。我总结了一个固定的排查顺序按这个走基本十分钟内能定位排查项检查方法常见原因拼接顺序前后端各打印 signSource 原文字段顺序不一致、少拼接或多拼接换行符大小写对比 method 是否统一大写前端用了post后端用了POST空值处理空 body 时是否拼了空字符串一方拼接了null字符串另一方拼了空字符编码确认都是 UTF-8中文参数在拼接时编码不一致密钥对比前后端密钥字符串长度前端多了一个空格、环境变量没读到变成 undefined密钥版本检查请求头 X-Key-Version轮换密钥期间新旧版本混用最有效的手段是让前后端在开发环境把signSource完整打印出来直接肉眼看差异。比看哈希值靠谱一百倍。生产环境记得把这个日志关掉因为signSource里包含密文和密钥相关的中间值泄露了等于降低了攻击门槛。6. 一份上线前的自检清单改造做完、联调通了别急着上线。下面这几条是我每次都会过一遍的检查项每一条背后都有一次教训。开关与配置。确认api-crypto.enabled在生产环境是true前端的VUE_APP_CRYPTO_ENABLED也是true两边的 AES 密钥、签名密钥完全一致。我习惯在应用启动时打一行日志API Crypto enabled: true, keyVersion: v2上线后看日志就知道配置对不对。白名单完整性。逐条验证白名单里的接口登录、验证码、文件上传、文件下载、头像访问、第三方回调、健康检查、Swagger如果生产要开的话。漏掉一个用户就会看到一个莫名其妙的解密失败错误。验证方法是上线前用 Postman 把所有白名单接口裸调一遍确认都能正常返回。异常兜底的友好性。解密失败、签名失败、时间戳过期、nonce 重复这四类异常都要有独立错误码和清晰提示。不要把BadPaddingException的堆栈直接抛给用户。同时后端日志要记录完整的请求 URI、时间戳、客户端 IP方便事后追溯。与现有日志组件的兼容。若依默认有操作日志Log注解它会把请求参数序列化存库。加密改造之后Log拿到的是解密后的明文这是好事日志有意义但要注意敏感字段脱敏。若依有Sensitive注解配合SensitiveJsonSerializer把手机号、身份证加上脱敏别让加密做完了、日志里全是明文。压测数据对比。改造前后各压一轮核心接口看 QPS 下降多少。我的实测数据是AES-128 CBC 加解密 HMAC 签名在普通 4 核机器上单次开销大约 0.1 到 0.3 毫秒QPS 下降 3% 到 8%属于可接受范围。如果下降超过 20%多半是哪里重复加解密了或者 Base64 转换做了好几遍值得查一查。降级预案。万一上线后加密导致大面积不可用能不能快速回滚答案是能——api-crypto.enabled改成false重启即可但有个前提后端关闭加密之后前端如果还在加密就会全部失败。所以要有平滑降级的设计后端在关闭开关时让解密过滤器尝试解密失败则按明文处理这样前后端任何一边先切都不影响。这个逻辑加个 try-catch 成本很低但关键时刻能救命。最后分享一个我自己的习惯这套加密改造我会在项目里单独留一个docs/crypto.md写明算法、密钥长度、拼接顺序、错误码定义、白名单维护规则。因为经验告诉我这套东西一旦过了半年连当初写它的人都要重新读一遍代码才能想起来签名是怎么拼的。文档写得糙一点没关系关键是把那些看起来理所当然但不能改的约定写死后面接手的人才不会随手一改就把线上搞挂。
1. 接口加密这件事先搞清楚要防的是谁若依RuoYi前后端分离版落地到实际项目里最常被安全评审挑出来的一条就是/system/user/list这类接口打开浏览器 F12 或者挂个抓包工具请求体里的手机号、身份证号、部门名称全是明文响应体里的用户列表也原样躺在那里。接口加密这个词听着玄乎实际上要解决的问题非常具体——让业务数据在浏览器到服务端这一段路上不以可读形式出现同时让请求具备不可篡改、不可重放的属性。我在几个基于 SpringBoot 前后端分离的中后台项目里都做过这块改造包括若依这套脚手架。踩过的坑不算少有些坑甚至不是加密本身的问题而是加密顺带把框架原有机制给打乱了。这篇内容围绕若依前后端分离版讲清楚四件事方案怎么选、后端在过滤器链的哪个位置插入解密、前端 axios 拦截器里怎么组装报文、以及实测中那些让人抓狂的排查过程。适合已经把若依跑起来、想给接口加一层防护的后端同学也适合负责前端请求封装的伙伴对照着改。需要先摆正一个认知前端加密永远不是绝对安全它的价值在于抬高攻击成本、满足合规要求、防止低级的信息泄露。任何声称前端加密后数据绝对安全的说法都不成立因为密钥就在浏览器里。想明白这一点后面的技术选型和投入尺度才不会跑偏。1.1 抓包工具面前明文接口有多透明前后端分离之后浏览器和服务端之间的通信全部走 HTTP 报文只要用户在本地装了抓包工具、配了证书或者干脆就是公司内部做安全测试的同事请求和响应对他而言就是一本书。若依默认的登录接口/login提交的是用户名密码明文虽然有 HTTPS 兜底/system/user/list返回的是完整用户信息/system/dept/list返回组织架构。这些东西一旦被批量抓取配合一个简单的脚本就能拖库。HTTPS 能挡住链路中间的窃听但挡不住客户端本地的抓包也挡不住用户自己就是攻击者这个场景。比如一个内部系统员工账号泄露之后攻击者拿这个账号登录再改一改请求参数就能拉到不属于自己的数据。接口加密在这种场景下的作用是让攻击者无法通过简单地修改明文参数来构造请求——因为参数被加密了改动之后服务端解密直接失败。所以判断一个项目需不需要做接口加密我的经验是看三条一是有没有等保或者行业合规的硬性要求二是接口里有没有身份证、手机号、薪资、病例这类敏感字段三是接口权限模型是不是只靠前端隐藏菜单、后端缺少细粒度校验。三条中两条以上命中就值得做。1.2 加密、签名、防重放是三件不同的事很多人把接口加密理解成把请求体加密一下实际上完整的报文防护包含三个互相独立的能力缺一个都会留下口子。**加密Encrypt**解决的是机密性——数据不以明文出现在报文中。攻击者抓包看到的是一串 Base64读不懂。**签名Sign**解决的是完整性——报文有没有被篡改。只加密不签名的话虽然攻击者看不懂明文但他可以把整个密文原样截下来再发一次或者把 A 接口的密文贴到 B 接口上。签名是拿参数、时间戳、随机数加一个密钥算出来的哈希服务端收到后重新算一遍对不上就拒绝。**防重放Anti-Replay**解决的是时效性——同一个合法报文能不能被无限次使用。做法是请求里带时间戳和一次性随机数nonce服务端校验时间戳在容忍窗口内比如 5 分钟并把 nonce 写进 RedisTTL 覆盖窗口期重复出现直接拒绝。三者组合起来才是完整方案。只做加密攻击者可以重放只做签名攻击者可以读明文只做防重放参数照样裸露。实际项目里我一般按这三个能力一起设计代码量其实比想象中小一个工具类加一个过滤器就能装下。1.3 全站加密的代价与分级策略有人上来就想给所有接口加解密结果上线后发现两件事性能掉了一截前端到处报错。AES 加解密的开销单次几乎可以忽略微秒级但高频接口叠加上 Base64 编解码、JSON 序列化两次、大响应体翻倍吞吐确实会下降。而且像文件下载、图片预览、验证码这些接口加密之后就很难处理了。我的做法是分级按接口的敏感程度分三档等级适用接口处理方式L1 强保护登录、实名认证、手机号/身份证相关、批量导出加密 签名 nonce 防重放L2 中保护常规增删改查、列表查询只做签名 时间戳不加密请求体L3 不处理验证码图片、文件上传下载、静态资源、健康检查白名单直接放行分级的意义在于把有限的复杂度花在刀刃上。L2 只签名不加密很简单前端只是在请求头多带两个字段后端在过滤器里做一次 HMAC 校验几乎无感。L1 才需要动请求体。这里有个细节要说清楚分级判定不能让前端自己说了算否则攻击者绕过前端直接把请求标成 L3 就通过了。正确做法是后端维护一份 URL 白名单放行的和一份强制加密的 URL 清单前端加密属于配合后端校验属于兜底。真正的高危接口后端必须强制要求签名头存在缺失直接返回 401。2. 算法与密钥方案AES-CBC 打底RSA/SM2 只解决密钥分发算法选型这块网上有很多教科书式的方案前端用 RSA 公钥加密后端用私钥解密。听起来很优雅但真跑起来会撞上一个残酷的现实——RSA 只能加密不超过密钥长度减去填充开销的数据2048 位密钥最多加密 245 字节。一个稍微大一点的 JSON 就超了更别说列表接口的响应。所以实际能落地的方案几乎都是对称加密打底非对称加密最多用来传递对称密钥或者干脆不用。若依这类中后台项目我推荐的就是 AES-128/256 CBC 模式 PKCS5Padding再配一个 HMAC-SHA256 签名。国密场景换成 SM4 SM3结构完全一样。2.1 为什么绝大多数项目最后落回对称加密对称加密与非对称加密的性能差距是数量级的。AES 在普通笔记本上单核能做几百 MB/s 的吞吐RSA-2048 单次解密大概在毫秒级而且还有上面说的长度限制。一个列表接口返回 200 条记录、200KB 的 JSON用非对称加密根本走不通。还有一个更现实的问题前端做非对称加密需要引入 JS 库jsencrypt、sm-crypto 之类这些库处理大字符串时性能很差在低端安卓机上能卡出明显的白屏。而对称加密用 crypto-js 里的 AES性能表现可以接受。那么 RSA 在方案里还有没有位置有。如果你们的安全要求里明确每次会话使用不同的对称密钥那就可以用前端随机生成 AES key用 RSA 公钥加密后放在请求头后端用私钥解出 AES key这套混合模式。但代价是每个请求都要做一次 RSA 解密且后端需要维持密钥与会话的关联或者干脆一次一密把加密后的 key 随请求传递。对绝大多数中后台系统来说这个复杂度收益比不划算。我的建议很直接固定密钥的 AES HMAC 签名 nonce 防重放这套方案能覆盖 90% 的场景代码量小排查容易。只有金融、医疗这类强监管场景才考虑混合模式。2.2 密钥写在前端就等于公开这一点必须承认不管你把密钥藏在哪个 JS 文件里做了多少层混淆、拆成几段拼接、在运行时才组装最终它都要在浏览器内存里以明文形式存在。稍微懂行的人打开 DevTools、打个断点、看一眼前端算出来的结果密钥就出来了。那这套方案还有什么意义意义在于它防的是批量脚本化的攻击和随手改参数的好奇心挡不住的是专门针对你的逆向分析。这两类攻击者的成本差了两三个数量级绝大多数系统只需要挡住前一类。因此密钥管理上有几条实际经验前端密钥和后端密钥分环境配置开发、测试、生产的密钥必须不同避免测试环境泄露之后生产直接沦陷。前端密钥至少做一次 Base64 编码或者简单的字符打散不要让const AES_KEY 1234567890abcdef这样赤裸裸地躺在打包产物里。密钥定期轮换后端支持同时接受新旧两把密钥用版本号区分请求头带X-Key-Version轮换时不影响在线用户。后端密钥放配置中心或环境变量不要写死在application.yml里跟着代码一起进 Git。2.3 和现有 JWT 认证体系的职责划分若依前后端分离版的认证走的是 Spring Security JWTToken 放在Authorization请求头里。接口加密加进来之后两者职责要理清楚不然会出现到底谁先校验的混乱。我的分工是这样的JWT 负责你是谁签名负责这个报文是不是你发的且没被改过加密负责报文内容别被人看见。执行顺序上先做解密 验签在过滤器里再做 JWT 认证在 Spring Security 的过滤链里最后进 Controller。为什么这个顺序因为签名里通常会把 Token 的摘要也算进去服务端需要先验证报文完整再去解析 Token 判断身份。如果反过来先认证后验签攻击者可以拿一个合法 Token 构造任意报文的签名请求——虽然他还是进不来因为签名不对但错误码会误导排查方向。还有一个易错点登录接口本身没有 Token但它恰恰是最需要保护的接口密码明文传输。所以登录接口要放进需要加密但不需要 Token 校验的名单在 Spring Security 的permitAll里放行同时加密过滤器照样生效。3. 后端改造在若依的过滤器链上开一道解密口子后端这块是整个改造的核心也是最容易出问题的地方。核心难点只有一个Servlet 的请求体流只能读一次。如果我们在过滤器里把 InputStream 读完解密后面的RequestBody就拿不到数据了会直接报Required request body is missing。解决办法是经典的HttpServletRequestWrapper套路把原始流读出来、解密、塞进一个字节数组然后用一个自定义的 Wrapper 覆盖getInputStream()和getReader()让它每次都返回一个新的流对象。这个套路不新鲜但在若依这种已经叠了好几层过滤器的框架里位置和顺序要格外小心。3.1 解密放在过滤器而不是拦截器的原因Spring MVC 的HandlerInterceptor里读请求体是可以的但问题是拦截器执行时HttpMessageConverter还没有消费流你必须自己读完再包一层然后想办法把包装后的 request 传递下去——而拦截器的preHandle方法签名里根本没有办法替换 request 对象。所以拦截器这条路基本走不通。ControllerAdvice配RequestBodyAdvice倒是一个思路它能在消息转换阶段介入beforeBodyRead里可以替换输入消息。但这种方式只对RequestBody生效对表单提交、文件上传无能为力而且和全局异常处理的配合比较别扭。过滤器Filter是最合适的位置它在 DispatcherServlet 之前执行可以完整地替换 request 对象对所有进入容器的请求统一生效。若依本身就用了不少过滤器XSS 过滤、Repeatable 过滤等我们加一个解密过滤器属于同一种模式风格也统一。3.2 可重复读的 RequestWrapper 写法先看 Wrapper 的实现这是整个方案的地基写错了后面全是坑。public class DecryptRequestWrapper extends HttpServletRequestWrapper { private final byte[] body; public DecryptRequestWrapper(HttpServletRequest request, byte[] body) { super(request); this.body body null ? new byte[0] : body; } Override public BufferedReader getReader() { return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8)); } Override public ServletInputStream getInputStream() { final ByteArrayInputStream bais new ByteArrayInputStream(body); return new ServletInputStream() { Override public boolean isFinished() { return bais.available() 0; } Override public boolean isReady() { return true; } Override public void setReadListener(ReadListener listener) { throw new UnsupportedOperationException(); } Override public int read() { return bais.read(); } }; } Override public int getContentLength() { return body.length; } Override public long getContentLengthLong() { return body.length; } }这段代码里最容易被忽略的是最后两个方法。如果不重写getContentLength()它返回的还是原始密文的长度而解密后的明文长度通常和密文不同Base64 解码后长度变短但 JSON 明文又比原始密文短。Spring 在读取 body 时如果依赖 Content-Length 做长度校验就会出现只读了一半或者读了多余字节的问题表现是 JSON 解析报Unexpected end of JSON input或者末尾多出乱码。这个坑我踩过一次排查了整整一个下午。3.3 过滤器注册顺序与若依 XSS 过滤的先后关系若依默认带了 XSS 过滤器它会对请求参数做转义处理防住脚本注入。我们的解密过滤器必须排在它之前否则 XSS 过滤器看到的是 Base64 密文里面不会有尖括号当然安全但解密之后的明文就绕过了 XSS 检查等于把防护撕开了一个口子。用 Spring Boot 的FilterRegistrationBean显式指定 order比Order注解更可控因为若依内部有些过滤器是通过Bean注册的注解和注册顺序混在一起容易乱。Configuration public class CryptoFilterConfig { Bean public FilterRegistrationBeanDecryptFilter decryptFilterRegistration(DecryptFilter filter) { FilterRegistrationBeanDecryptFilter bean new FilterRegistrationBean(); bean.setFilter(filter); bean.addUrlPatterns(/*); bean.setOrder(Ordered.HIGHEST_PRECEDENCE 10); bean.setName(decryptFilter); return bean; } }Ordered.HIGHEST_PRECEDENCE是Integer.MIN_VALUE加 10 是为了给容器自身的编码过滤器留位置同时保证排在其他业务过滤器前面。数字越小越靠前这一点和拦截器相反别记混了。过滤器主体大致长这样Component public class DecryptFilter extends OncePerRequestFilter { Resource private ApiCryptoProperties props; Resource private RedisCache redisCache; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { String uri request.getRequestURI(); if (!props.isEnabled() || MatchUtils.isWhite(uri, props.getUrlWhitelist())) { chain.doFilter(request, response); return; } String cipherText StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8); if (StringUtils.isEmpty(cipherText)) { // 无报文体的 GET 请求只校验签名 verifySign(request, ); chain.doFilter(request, response); return; } // 1. 先验签对密文验签避免解密后被篡改 verifySign(request, cipherText); // 2. 校验 nonce 是否重复 checkNonce(request.getHeader(X-Nonce)); // 3. 解密 String plain AesUtils.decrypt(cipherText, props.getAesKey()); chain.doFilter(new DecryptRequestWrapper(request, plain.getBytes(StandardCharsets.UTF_8)), response); } }注意第 1 步的顺序对密文做验签。如果先解密再验签攻击者可以构造任意密文让服务端先解一次虽然大概率解密失败抛异常但异常堆栈、错误信息本身就是信息泄露。对密文验签成本一样安全性更好。校验失败时统一抛一个自定义异常交给若依的全局异常处理器GlobalExceptionHandler返回统一格式不要在前端看到javax.crypto.BadPaddingException这种堆栈信息。3.4 配置项与开关设计配置项单独抽一个ConfigurationProperties方便后续调参和按环境覆盖。api-crypto: enabled: true aes-key: S3cr3tKeyForDemo0123456789ABCDEF # 32 位AES-256 sign-secret: SignSecretForHmac0123456789 timestamp-tolerance: 300000 # 5 分钟单位毫秒 nonce-ttl: 300 # Redis 过期时间单位秒 url-whitelist: - /login - /captchaImage - /common/download - /profile/avatarenabled这个开关非常关键。开发阶段前后端联调加密会产生大量噪音加个开关可以让前端在本地把加密关掉VUE_APP_CRYPTO_ENABLEDfalse后端也跟着关联调效率高很多。上线前记得确认两边的开关都打开我曾经遇到过一次测试环境关了忘了开上线后所有的加密请求全被服务端当成缺签名头拒绝了好在灰度及时发现。签名算法本身很简单把需要参与签名的要素按固定顺序拼成一个字符串再用 HMAC-SHA256 算摘要signSource method \n uri \n timestamp \n nonce \n body sign Base64(HmacSHA256(signSource, signSecret))拼接顺序前后端必须完全一致中间的分隔符也别省略否则会出现两边算法一样但结果永远对不上的问题而且这种问题极难排查因为哈希值看起来都是乱的。我的习惯是把这套拼装逻辑写在文档里前后端各自实现联调时先拿同一个固定输入跑一遍对比输出确认一致后再接业务。4. 前端改造axios 拦截器里的加密时序若依前端是 Vue axios所有请求都走src/utils/request.js里统一的实例拦截器已经做了 Token 注入、重复提交判断、错误码统一处理。加密代码要插进去最忌讳的就是直接在最前面加一段把原有的机制打乱。前端有一个绕不开的技术细节要先说清楚crypto-js 不支持 AES-GCM 模式它只实现了 CBC、CFB、OFB、CTR、ECB 这几种。如果后端选了AES/GCM/NoPadding前端用 crypto-js 根本对不上只能改用浏览器原生的 Web Crypto APIcrypto.subtle。但crypto.subtle只在 HTTPS 或者 localhost 下可用内网 HTTP 部署的环境直接报undefined。所以前后端要约定同一个模式。我的选择是 CBC PKCS7虽然 CBC 在密码学上不如 GCM没有内置完整性校验但我们外层已经加了 HMAC 签名完整性由签名保证CBC 的弱点被补上了。4.1 请求拦截器中加密、签名、时间戳的组装顺序axios 的请求拦截器会按注册顺序倒序执行若依默认就有一个拦截器做 Token 注入和重复提交判断。新增的加密拦截器必须加在它之后注册也就是更早执行否则加密完再判断重复提交每次密文都不同重复提交检查永远通过。更稳妥的做法是干脆把加密逻辑写进现有的拦截器里用明确的顺序控制。组装顺序是这样的判断是否需要加密白名单 URL、开关状态。生成 13 位时间戳和 16 位随机 nonce。把config.data序列化成 JSON 字符串。生成 16 字节随机 IVAES-CBC 加密输出Base64(IV 密文)。用method uri timestamp nonce 密文计算 HMAC 签名。把密文替换config.data时间戳、nonce、签名、密钥版本塞进请求头。前端加密的核心代码import CryptoJS from crypto-js const AES_KEY CryptoJS.enc.Utf8.parse(process.env.VUE_APP_AES_KEY) const SIGN_SECRET process.env.VUE_APP_SIGN_SECRET function encryptBody(plain) { const iv CryptoJS.lib.WordArray.random(16) const encrypted CryptoJS.AES.encrypt(plain, AES_KEY, { iv: iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }) // IV 前置拼接到密文后端按前 16 字节取 IV return iv.concat(encrypted.ciphertext).toString(CryptoJS.enc.Base64) } function buildSign(method, uri, timestamp, nonce, body) { const source [method.toUpperCase(), uri, timestamp, nonce, body].join(\n) return CryptoJS.HmacSHA256(source, SIGN_SECRET).toString(CryptoJS.enc.Base64) }有一个细节必须提醒CryptoJS.lib.WordArray.random(16)生成的 IV 是 WordArray 对象iv.concat(ciphertext)返回新对象不会修改原 IV这个行为是正确的。但如果你看到某些老代码里先iv.concat(...)再单独用iv那可能会出问题因为不同版本的 crypto-js 在concat的副作用上表现不一致稳妥起见还是显式 clone 一份。4.2 响应解密与 blob 下载的分流响应这块比请求麻烦因为 axios 的响应可能是 JSON也可能是 blob文件下载还可能是纯文本。如果后端统一做了响应加密前端在响应拦截器里要先判断response.config.responseType是blob或arraybuffer直接放行不解密。是普通 JSON取response.data它是一个 Base64 字符串解密后JSON.parse回来。service.interceptors.response.use(res { if (res.config.responseType blob || res.config.responseType arraybuffer) { return res } if (typeof res.data string res.data.length 0) { try { const plain decryptBody(res.data) res.data JSON.parse(plain) } catch (e) { // 非加密响应保持原样 } } return handleCode(res) }, error { ... })这里用try/catch兜底是必要的。总有一些接口没有走加密比如第三方回调、健康检查如果解密失败就抛异常这些接口就全挂了。用一个宽松的 fallback先把字符串当普通数据处理能大幅降低上线的风险面。还有一个更隐蔽的问题加解密和解密失败的错误处理会互相掩盖。比如后端返回了一个 500 错误响应体是若依统一的{code: 500, msg: xxx}如果这个错误响应没走加密前端解密失败后 fallback 到原样解析看起来是对的。但如果错误响应走了加密而前端在解析之前就抛了SyntaxError用户看到的就是一个空白页面。所以错误响应的处理路径一定要和正常响应走同一套逻辑别用两套代码。5. 真实踩过的六个坑与排查顺序加密这套东西写代码可能只要两天调通要一周排查问题要更久。下面这几个坑都是我实际遇到过的按症状—定位—修复的顺序写出来方便你对照着排查。5.1 请求体读两次变空症状与定位路径症状很典型前端发了加密请求后端日志显示过滤器里解密成功、明文也打印出来了但进到 Controller 里RequestBody参数全是 null或者直接报Required request body is missing。定位路径分三步第一步在过滤器里打印request.getClass().getName()确认包装是否生效。如果打出来还是org.apache.catalina.connector.RequestFacade说明chain.doFilter传的还是原对象包装没起作用。第二步检查是不是有其他过滤器在更前面读了流。若依自带的一些过滤器、日志组件、链路追踪组件都可能在早期读 body。可以用request.getInputStream().available()打印一下如果是 0说明已经被消费了。第三步检查 Content-Length。如果 Wrapper 里没重写getContentLength()Spring 按旧的 Content-Length 读读到一半就停了。修复方案就是前面写的 Wrapper 完整实现加上显式重写长度方法。如果项目里还有别的过滤器要读 body那就统一改用ContentCachingRequestWrapper风格的缓存或者干脆把解密过滤器提到最前面独占读取权。5.2 重复提交拦截失效若依前端request.js里有一段重复提交判断逻辑是把url data作为 key 存进 sessionStorage短时间内相同就拦截。加了加密之后每次请求的 IV 随机、nonce 随机密文完全不一样这个判断就形同虚设了。这个坑的影响不大毕竟后端还有RepeatSubmit注解兜底但如果你的业务里前端拦截是关键防线就得处理。我的做法是在加密之前用明文做重复判断const plainData JSON.stringify(config.data || {}) if (isRepeatSubmit(config.url, plainData)) { return Promise.reject(new Error(数据正在处理请勿重复提交)) } // 再做加密 config.data encryptBody(plainData)后端那边RepeatSubmit的 key 是基于解密后的请求参数算的所以后端拦截是正常工作的。这里要注意若依的RepeatSubmitInterceptor实现它是拿request.getParameterMap()和 body 一起算 key 的我们包装后的 request 里getParameterMap返回的是原始参数加密请求通常不用 query 参数body 是解密后的明文算出来的 key 是对的。这一点我专门验证过没问题。5.3 Base64 里的加号在 URL 中变成空格Base64 字符集里有、/、三个特殊字符其中在 URL 的 query string 里会被解码成空格。如果密文放在 URL 参数里传输有些老接口这么干后端收到之后解密必然失败报Illegal base64 character或者解出来是乱码。处理方式有两种一是传输前做一次encodeURIComponent后端先URLDecoder.decode再解密二是换成 URL 安全的 Base64 变体把换成-、/换成_去掉末尾的。Java 里用Base64.getUrlEncoder().withoutPadding()前端用CryptoJS.enc.Base64.stringify(...).replace(/\/g, -).replace(/\//g, _).replace(/$/, )。两边必须严格一致少做一步就对不上。我现在的项目里密文一律放请求体不放 URL从源头上避开这个问题。但还是建议把 URL 安全的编码函数提前准备好表单提交、重定向带参数这些场景迟早会用上。5.4 大文件上传整体加密导致内存溢出有人图省事在 axios 拦截器里对所有请求统一加密包括multipart/form-data的文件上传。结果用户传一个 200MB 的视频浏览器直接把内存吃满页面崩溃。原因很直白config.data如果是 FormData你不能简单JSON.stringify而如果强行把文件读成 ArrayBuffer 再加密等于把一个 200MB 的 buffer 在内存里复制三份原始、密文、Base64现代浏览器也扛不住。正确的处理是文件上传接口加入白名单不做整体加密。如果业务上确实需要保护上传内容那也不应该走前端加密而是走 HTTPS 服务端存储加密 短时效的上传凭证。前端加密在这个场景没有收益只有风险。顺带说一句文件下载同理。若依的/common/download返回的是二进制流如果被响应拦截器当成 Base64 字符串去解密要么报错要么把文件搞坏。必须用responseType做分流这个前面已经说过了。5.5 时间戳与服务器时钟偏差防重放的时间戳校验最怕的就是用户设备的时钟不准。我遇到过一台测试机的时间比服务器慢了 8 分钟所有请求都被判时间戳过期但设备上显示的时间看起来完全正常。TP 容忍窗口设多大合适太小容易误伤太大会削弱防重放效果。我的经验值是 5 分钟300000 毫秒能覆盖绝大多数时钟偏差同时把重放窗口控制在可接受范围内。还有一个进阶处理如果服务端发现时间戳偏差在 5 到 30 分钟之间不要直接拒绝而是在响应头里返回服务器的当前时间戳前端拿到之后自动校准本地时钟记录一个 offset后续请求都用本地时间 offset。这个机制我在一个跨时区部署的项目里用过效果不错。要注意的是时区并不是问题——时间戳统一用 UTC 毫秒数前后端的Date.now()和System.currentTimeMillis()都是 UTC 基准跟时区没关系。真正的问题只有设备时钟本身的偏差。5.6 签名对不上时的排查顺序签名不匹配是最让人头大的问题因为哈希值看起来就是一堆乱码没有任何可读信息。我总结了一个固定的排查顺序按这个走基本十分钟内能定位排查项检查方法常见原因拼接顺序前后端各打印 signSource 原文字段顺序不一致、少拼接或多拼接换行符大小写对比 method 是否统一大写前端用了post后端用了POST空值处理空 body 时是否拼了空字符串一方拼接了null字符串另一方拼了空字符编码确认都是 UTF-8中文参数在拼接时编码不一致密钥对比前后端密钥字符串长度前端多了一个空格、环境变量没读到变成 undefined密钥版本检查请求头 X-Key-Version轮换密钥期间新旧版本混用最有效的手段是让前后端在开发环境把signSource完整打印出来直接肉眼看差异。比看哈希值靠谱一百倍。生产环境记得把这个日志关掉因为signSource里包含密文和密钥相关的中间值泄露了等于降低了攻击门槛。6. 一份上线前的自检清单改造做完、联调通了别急着上线。下面这几条是我每次都会过一遍的检查项每一条背后都有一次教训。开关与配置。确认api-crypto.enabled在生产环境是true前端的VUE_APP_CRYPTO_ENABLED也是true两边的 AES 密钥、签名密钥完全一致。我习惯在应用启动时打一行日志API Crypto enabled: true, keyVersion: v2上线后看日志就知道配置对不对。白名单完整性。逐条验证白名单里的接口登录、验证码、文件上传、文件下载、头像访问、第三方回调、健康检查、Swagger如果生产要开的话。漏掉一个用户就会看到一个莫名其妙的解密失败错误。验证方法是上线前用 Postman 把所有白名单接口裸调一遍确认都能正常返回。异常兜底的友好性。解密失败、签名失败、时间戳过期、nonce 重复这四类异常都要有独立错误码和清晰提示。不要把BadPaddingException的堆栈直接抛给用户。同时后端日志要记录完整的请求 URI、时间戳、客户端 IP方便事后追溯。与现有日志组件的兼容。若依默认有操作日志Log注解它会把请求参数序列化存库。加密改造之后Log拿到的是解密后的明文这是好事日志有意义但要注意敏感字段脱敏。若依有Sensitive注解配合SensitiveJsonSerializer把手机号、身份证加上脱敏别让加密做完了、日志里全是明文。压测数据对比。改造前后各压一轮核心接口看 QPS 下降多少。我的实测数据是AES-128 CBC 加解密 HMAC 签名在普通 4 核机器上单次开销大约 0.1 到 0.3 毫秒QPS 下降 3% 到 8%属于可接受范围。如果下降超过 20%多半是哪里重复加解密了或者 Base64 转换做了好几遍值得查一查。降级预案。万一上线后加密导致大面积不可用能不能快速回滚答案是能——api-crypto.enabled改成false重启即可但有个前提后端关闭加密之后前端如果还在加密就会全部失败。所以要有平滑降级的设计后端在关闭开关时让解密过滤器尝试解密失败则按明文处理这样前后端任何一边先切都不影响。这个逻辑加个 try-catch 成本很低但关键时刻能救命。最后分享一个我自己的习惯这套加密改造我会在项目里单独留一个docs/crypto.md写明算法、密钥长度、拼接顺序、错误码定义、白名单维护规则。因为经验告诉我这套东西一旦过了半年连当初写它的人都要重新读一遍代码才能想起来签名是怎么拼的。文档写得糙一点没关系关键是把那些看起来理所当然但不能改的约定写死后面接手的人才不会随手一改就把线上搞挂。
