1. 项目概述为什么我们需要拦截ApiOperation的传参日志在微服务架构和前后端分离成为主流的今天Spring Boot Spring MVC的组合几乎是后端开发的标准答案。随之而来的是大量使用ApiOperation、ApiParam等Swagger注解来生成API文档。这些注解极大地提升了开发效率和文档的可读性。然而一个容易被忽视的细节是当我们在Controller方法上使用ApiOperation注解并且启用了全局的请求/响应日志拦截比如通过Spring的HandlerInterceptor或AOP切面时方法的所有入参信息都会被完整地打印到日志中。这听起来似乎是个好功能便于调试和问题追踪不是吗但实际情况要复杂得多。想象一下你的用户注册接口接收了一个包含密码、手机号、身份证号的DTO对象或者一个支付回调接口包含了用户的银行卡号、交易金额等敏感信息。如果这些信息被原封不动地打印到应用日志里而日志文件又因为某种原因如服务器权限配置不当、日志收集系统漏洞被泄露那将是一场严重的数据安全灾难。这不仅仅是技术问题更关乎合规性如GDPR、网络安全法对个人信息保护的要求。因此“拦截ApiOperation打印传参日志”这个项目的核心诉求并非简单地关闭所有日志而是实现一种精细化的、智能的日志脱敏与过滤机制。它的目标是在保留必要调试信息如请求路径、耗时、状态码的前提下自动识别并屏蔽或脱敏API接口中的敏感参数确保日志既可用又安全。这不仅仅是加几行代码那么简单它涉及到对Spring MVC请求生命周期的理解、对注解的元数据解析以及对数据安全边界的精准把握。2. 核心思路与方案选型从粗放到精细的演进在动手之前我们先梳理一下常见的日志打印方案及其痛点这能帮助我们理解为什么需要新的方案。2.1 常见方案及其局限性使用Spring Boot默认日志或AOP全局打印 这是最简单的做法。通过一个Around切面在方法执行前后打印JoinPoint的所有参数。其代码可能长这样Around(execution(* com.example.controller..*.*(..))) public Object logAround(ProceedingJoinPoint joinPoint) throws Throwable { // 打印所有参数 Object[] args joinPoint.getArgs(); log.info(方法: {} 参数: {}, joinPoint.getSignature().getName(), Arrays.toString(args)); return joinPoint.proceed(); }痛点无差别打印所有参数一览无余安全隐患巨大。在DTO字段上使用JsonIgnore等注解 在需要保密的字段上添加JsonIgnore这样在序列化为JSON日志时该字段会被忽略。public class UserDTO { private String username; JsonIgnore private String password; // 日志中不会出现此字段 }痛点侵入性强污染了模型对象。这个注解的本意是用于HTTP序列化现在却用来控制日志职责不清。而且如果同一个字段在某个接口需要打印如内部管理接口在另一个接口又不需要就无法灵活处理。手动在每个方法里过滤 在Controller方法内部手动构造一个不包含敏感信息的Map用于打印。PostMapping(/register) public Result register(RequestBody UserDTO user) { MapString, Object logMap new HashMap(); logMap.put(username, user.getUsername()); // 故意不放入password log.info(注册请求: {}, logMap); // ...业务逻辑 }痛点重复劳动容易遗漏代码冗余且无法统一管理规则。2.2 我们的目标方案设计基于以上痛点一个理想的方案应该具备以下特点非侵入性尽量不修改现有的业务DTO模型。集中管理敏感字段的规则在一个地方配置和维护。基于注解的灵活控制能否打印、如何脱敏最好能与API文档注解如ApiOperation、ApiParam或自定义注解关联。与框架无缝集成最好利用Spring MVC现有的拦截器或过滤器机制对性能影响最小。因此我们的核心思路是定制化一个Spring MVC的HandlerInterceptor在preHandle或afterCompletion方法中获取到本次请求的处理器方法HandlerMethod及其上的注解信息然后根据注解中定义的规则或一个全局的敏感词列表对即将被日志记录的参数进行动态脱敏处理。这里为什么选择HandlerInterceptor而不是AOP虽然AOP更强大但HandlerInterceptor是Spring MVC原生请求处理链路的一部分对于请求和响应对象的获取更为直接和高效也更符合“拦截”这个语义。我们将结合AOP的思想通过注解定义切点和Interceptor的执行能力。3. 核心组件设计与实现细节整个方案可以拆解为几个核心组件我们逐一实现。3.1 定义脱敏注解与策略首先我们需要一套注解来标记哪些参数或字段需要被脱敏以及如何脱敏。/** * 字段级脱敏注解。可标注在DTO类的字段上。 */ Target(ElementType.FIELD) Retention(RetentionPolicy.RUNTIME) public interface SensitiveField { /** * 脱敏策略类型 */ SensitiveStrategy strategy(); /** * 自定义正则表达式当策略为CUSTOM时使用 */ String customPattern() default ; String customReplacement() default ***; } /** * 参数级脱敏注解。可标注在Controller方法的参数上。 * 优先级高于字段注解。 */ Target(ElementType.PARAMETER) Retention(RetentionPolicy.RUNTIME) public interface SensitiveParam { /** * 是否完全隐藏该参数不打印 */ boolean hide() default false; /** * 指定脱敏策略若hidetrue则此字段无效 */ SensitiveStrategy strategy() default SensitiveStrategy.DEFAULT; } /** * 脱敏策略枚举 */ public enum SensitiveStrategy { /** 默认整个值替换为 ****** */ DEFAULT, /** 用户名只显示第一位和最后一位如张*三 */ USERNAME, /** 身份证号显示前6后4如110105****1234 */ ID_CARD, /** 手机号显示前3后4如138****5678 */ PHONE, /** 邮箱隐藏前面的部分如a****example.com */ EMAIL, /** 银行卡号显示前6后4如622848****1234 */ BANK_CARD, /** 自定义需配合正则使用 */ CUSTOM }同时我们需要一个脱敏工具类来执行具体的脱敏逻辑Component public class DataMasker { public Object maskField(Object fieldValue, SensitiveField annotation) { if (fieldValue null) { return null; } String valueStr String.valueOf(fieldValue); SensitiveStrategy strategy annotation.strategy(); // 根据不同的策略进行脱敏 switch (strategy) { case USERNAME: return maskUsername(valueStr); case ID_CARD: return maskIdCard(valueStr); case PHONE: return maskPhone(valueStr); case EMAIL: return maskEmail(valueStr); case BANK_CARD: return maskBankCard(valueStr); case CUSTOM: return valueStr.replaceAll(annotation.customPattern(), annotation.customReplacement()); case DEFAULT: default: return ******; } } private String maskUsername(String username) { if (username.length() 1) return *; if (username.length() 2) return username.charAt(0) *; return username.charAt(0) *.repeat(Math.max(0, username.length() - 2)) username.charAt(username.length() - 1); } private String maskIdCard(String idCard) { if (idCard.length() 10) return ******; return idCard.substring(0, 6) **** idCard.substring(idCard.length() - 4); } // ... 其他mask方法实现 }3.2 实现核心日志拦截器这是最核心的部分。我们将创建一个SensitiveLogInterceptor它继承自HandlerInterceptorAdapter或实现HandlerInterceptor接口。Component public class SensitiveLogInterceptor implements HandlerInterceptor { Autowired private DataMasker dataMasker; private static final ObjectMapper objectMapper new ObjectMapper(); Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 1. 只处理HandlerMethod排除静态资源等 if (!(handler instanceof HandlerMethod)) { return true; } HandlerMethod handlerMethod (HandlerMethod) handler; Method method handlerMethod.getMethod(); // 2. 获取方法上的ApiOperation注解用于判断是否需要特殊处理例如可以设置一个属性来关闭日志 ApiOperation apiOperation method.getAnnotation(ApiOperation.class); if (apiOperation ! null apiOperation.hidden()) { // 如果ApiOperation标记为hidden可以选择跳过该方法的日志记录 request.setAttribute(SKIP_PARAM_LOG, true); } // 3. 获取请求参数这里主要处理RequestBody的JSON参数 if (isJsonRequest(request)) { // 使用CachingRequestWrapper需自定义用于缓存RequestBody流读取请求体 CachingRequestWrapper wrappedRequest new CachingRequestWrapper(request); String requestBody wrappedRequest.getBodyAsString(); if (StringUtils.isNotBlank(requestBody)) { // 4. 关键步骤解析并脱敏 Object desensitizedBody desensitizeRequestBody(requestBody, method, handlerMethod.getMethodParameters()); // 将脱敏后的对象或JSON字符串存入请求属性供后续日志组件使用 request.setAttribute(DESENSITIZED_BODY, desensitizedBody); // 替换请求对象以便后续RequestBody参数解析器能读到原始数据 // 注意这里需要小心处理通常我们会缓存原始请求体并在后续步骤中恢复。 // 更常见的做法是不修改原始请求而是将脱敏后的数据单独存放用于日志。 } } // 5. 对于表单参数可以从request.getParameterMap()获取并脱敏逻辑类似但更简单 return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception { // 这里是打印日志的最佳时机因为此时业务方法已执行完毕我们可以拿到响应状态和耗时 if (Boolean.TRUE.equals(request.getAttribute(SKIP_PARAM_LOG))) { return; } Object desensitizedBody request.getAttribute(DESENSITIZED_BODY); long startTime (Long) request.getAttribute(REQUEST_START_TIME); long endTime System.currentTimeMillis(); // 构造一个不包含敏感信息的日志对象 LogEntry logEntry new LogEntry(); logEntry.setPath(request.getRequestURI()); logEntry.setMethod(request.getMethod()); logEntry.setClientIp(request.getRemoteAddr()); logEntry.setStatus(response.getStatus()); logEntry.setCostTime(endTime - startTime); logEntry.setParams(desensitizedBody); // 这里存放的是脱敏后的参数 // 可以从请求属性中获取业务返回的简化结果需在ControllerAdvice或AOP中设置 logEntry.setResult(request.getAttribute(SAFE_RESPONSE_BODY)); log.info(API请求日志: {}, objectMapper.writeValueAsString(logEntry)); } /** * 核心脱敏逻辑 */ private Object desensitizeRequestBody(String requestBodyJson, Method method, Parameter[] parameters) throws IOException { // 将JSON解析为JsonNodeJackson便于灵活操作 JsonNode rootNode objectMapper.readTree(requestBodyJson); // 遍历方法参数找到RequestBody参数对应的类型 for (int i 0; i parameters.length; i) { Parameter parameter parameters[i]; if (parameter.isAnnotationPresent(RequestBody.class)) { Class? parameterType parameter.getType(); // 检查参数上是否有SensitiveParam注解 SensitiveParam paramAnnotation parameter.getAnnotation(SensitiveParam.class); if (paramAnnotation ! null paramAnnotation.hide()) { // 如果要求隐藏整个参数直接返回一个标记 return Collections.singletonMap(parameter.getName(), [HIDDEN]); } // 将JSON反序列化为目标对象 Object paramObject objectMapper.readValue(requestBodyJson, parameterType); // 对该对象进行深度脱敏 Object maskedObject deepMask(paramObject, paramAnnotation); // 返回脱敏后的对象可以转回JsonNode或Map return objectMapper.convertValue(maskedObject, Object.class); } } // 如果没有RequestBody或者不是JSON返回原始JsonNode或进行简单脱敏 return simpleMaskJsonNode(rootNode); } /** * 深度遍历对象进行脱敏 */ private Object deepMask(Object obj, SensitiveParam paramAnnotation) throws IllegalAccessException { if (obj null) { return null; } // 如果是集合或数组遍历每个元素 if (obj instanceof Collection) { Collection? collection (Collection?) obj; ListObject result new ArrayList(); for (Object item : collection) { result.add(deepMask(item, paramAnnotation)); } return result; } // 如果是Map遍历每个Entry if (obj instanceof Map) { Map?, ? map (Map?, ?) obj; MapObject, Object result new HashMap(); for (Map.Entry?, ? entry : map.entrySet()) { result.put(entry.getKey(), deepMask(entry.getValue(), paramAnnotation)); } return result; } // 如果是简单类型String, Number等且参数注解有策略则直接脱敏 if (paramAnnotation ! null !paramAnnotation.hide() obj instanceof String) { // 这里简化处理实际应根据paramAnnotation.strategy()调用DataMasker return dataMasker.maskByStrategy((String) obj, paramAnnotation.strategy()); } // 如果是复杂对象反射遍历其字段 Class? clazz obj.getClass(); if (isJavaClass(clazz)) { // 判断是否是JDK自带的类如String, Integer return obj; } Object newInstance null; try { newInstance clazz.newInstance(); } catch (InstantiationException e) { return obj; // 无法实例化可能返回原对象或进行其他处理 } for (Field field : clazz.getDeclaredFields()) { field.setAccessible(true); Object fieldValue field.get(obj); SensitiveField fieldAnnotation field.getAnnotation(SensitiveField.class); if (fieldAnnotation ! null) { // 调用DataMasker进行字段脱敏 fieldValue dataMasker.maskField(fieldValue, fieldAnnotation); } else if (paramAnnotation ! null !paramAnnotation.hide()) { // 如果参数级注解有策略且字段未被单独注解可以应用参数级策略需谨慎 // 通常更推荐字段级精确控制 } // 递归处理嵌套对象 Object maskedValue deepMask(fieldValue, null); // 嵌套对象不继承参数注解 try { Field newField newInstance.getClass().getDeclaredField(field.getName()); newField.setAccessible(true); newField.set(newInstance, maskedValue); } catch (NoSuchFieldException e) { // 忽略理论上不会发生 } } return newInstance; } private boolean isJsonRequest(HttpServletRequest request) { String contentType request.getContentType(); return contentType ! null contentType.toLowerCase().contains(application/json); } }注意上面的deepMask方法是一个简化示例。在生产环境中你需要考虑性能缓存反射结果、循环引用、继承关系等问题。可以使用像Jackson的JsonNode直接进行树形遍历和修改避免反射和对象创建性能会更好。3.3 配置与注册拦截器为了让拦截器生效需要在Spring配置中注册它并指定拦截路径。Configuration public class WebMvcConfig implements WebMvcConfigurer { Autowired private SensitiveLogInterceptor sensitiveLogInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { // 拦截所有API请求排除Swagger、Actuator等端点 registry.addInterceptor(sensitiveLogInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/swagger-resources/**, /webjars/**, /v2/api-docs, /swagger-ui.html/**, /actuator/**); } }3.4 处理ApiParam与表单参数上面的例子主要处理了RequestBody的JSON参数。对于使用RequestParam或PathVariable以及ApiParam注解的参数处理方式有所不同。这些参数通常值比较简单我们可以直接在拦截器中从request.getParameterMap()获取并根据参数名或注解进行脱敏。一种更通用的方法是利用Spring的HandlerMethodArgumentResolver机制在参数解析阶段就进行脱敏但这会改变实际注入到Controller方法中的参数值通常不推荐因为业务代码可能需要原始值。更好的做法仍然是只在日志记录环节进行脱敏。我们可以扩展拦截器在preHandle中获取HandlerMethod的MethodParameter信息检查每个参数上的ApiParam或自定义的SensitiveParam注解然后从请求中获取对应的参数值脱敏后存入一个Map供日志使用。4. 高级特性与优化实践基础功能实现后可以考虑以下增强点让方案更健壮、更易用。4.1 与Logback/SLF4J集成实现零侵入上面的方案需要在代码中显式地调用日志记录。更优雅的方式是集成到日志框架中。例如可以定义一个%mask转换器在Logback的pattern中。创建自定义Logback转换器public class MaskingConverter extends ClassicConverter { Override public String convert(ILoggingEvent event) { // 从MDCMapped Diagnostic Context中获取已经脱敏的参数字符串 String rawMessage event.getFormattedMessage(); MapString, String mdc event.getMDCPropertyMap(); String safeParams mdc.get(SAFE_PARAMS); // 在日志格式中可以用 %mask 来输出脱敏后的参数 // 但这需要我们在拦截器中将脱敏后的参数存入MDC return safeParams ! null ? safeParams : rawMessage; } }在logback-spring.xml中配置conversionRule conversionWordmask converterClasscom.example.logging.MaskingConverter / appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %mask%n/pattern /encoder /appender在拦截器中设置MDCimport org.slf4j.MDC; // 在preHandle或afterCompletion中 MDC.put(SAFE_PARAMS, objectMapper.writeValueAsString(desensitizedBody)); // 注意需要在请求完成后清理MDC可以注册一个ServletRequestListener或在afterCompletion中清除。4.2 基于配置文件的敏感规则管理将敏感字段的匹配规则如字段名正则、路径规则放到外部配置文件如application.yml中实现动态更新无需重启应用。sensitive: rules: - pattern: .*[Pp]assword.* strategy: DEFAULT - pattern: .*[Ii]d[Cc]ard.* strategy: ID_CARD - pattern: phone strategy: PHONE full-match: true # 是否字段名完全匹配在DataMasker中注入这些规则并在deepMask方法中如果字段没有SensitiveField注解则根据字段名匹配配置文件中的规则进行脱敏。4.3 性能考量与缓存优化反射和JSON序列化/反序列化是性能瓶颈。可以采取以下优化措施缓存反射结果使用ConcurrentHashMap缓存Class到其敏感字段ListField的映射。使用Jackson的树模型在desensitizeRequestBody方法中直接操作JsonNode避免将整个JSON反序列化为Java对象再序列化。找到需要脱敏的节点直接修改其值。异步日志将日志记录操作放入一个独立的线程池或使用Logback的异步Appender避免阻塞主请求线程。采样记录对于超高流量的接口可以配置采样率只记录一定比例的请求详情。5. 常见问题排查与实战心得在实际部署和使用过程中你可能会遇到以下问题5.1 问题拦截器对RequestBody读取后后续RequestBody参数绑定为空。原因HttpServletRequest的输入流getInputStream()只能读取一次。拦截器中读取了Controller就读不到了。解决方案使用ContentCachingRequestWrapperSpring提供或自定义的CachingRequestWrapper来包装请求。它在内部缓存请求体数据允许重复读取。public class CachingRequestWrapper extends HttpServletRequestWrapper { private byte[] body; public CachingRequestWrapper(HttpServletRequest request) throws IOException { super(request); this.body StreamUtils.copyToByteArray(request.getInputStream()); } Override public ServletInputStream getInputStream() { return new CachedBodyServletInputStream(this.body); } // 提供一个方法获取缓存的字符串 public String getBodyAsString() { return new String(body, StandardCharsets.UTF_8); } // 静态内部类 CachedBodyServletInputStream ... }在拦截器的preHandle中使用包装器替换原请求if (request instanceof CachingRequestWrapper) { chain.doFilter(request, response); } else { CachingRequestWrapper wrapper new CachingRequestWrapper(request); chain.doFilter(wrapper, response); }5.2 问题脱敏后日志中出现了[HIDDEN]但想保留参数结构。场景一个用户对象{name:张三,password:123456}密码被隐藏后变成了{name:张三,password:[HIDDEN]”}这没问题。但如果想隐藏整个对象返回[HIDDEN]就丢失了结构信息。解决方案修改脱敏逻辑对于需要隐藏的复杂对象可以返回一个具有相同结构但所有值都被替换的对象例如{name:[HIDDEN],password:[HIDDEN]”}。这需要在deepMask方法中做特殊处理。5.3 问题如何对嵌套对象和集合中的元素进行脱敏解决方案我们的deepMask方法已经通过递归处理了这种情况。关键在于正确识别集合类型Collection、Array、Map并进行遍历。使用Jackson的JsonNode处理会更容易因为它能统一处理ArrayNode和ObjectNode。5.4 问题某些第三方组件如Feign Client、RestTemplate的调用日志也需要脱敏。解决方案方案需要扩展。对于Feign可以实现一个Feign.Logger的自定义子类在记录请求和响应日志前进行脱敏。对于RestTemplate可以配置一个ClientHttpRequestInterceptor其原理与我们现在的Servlet拦截器类似。5.5 实操心得平衡安全与可调试性白名单优于黑名单初期可以考虑采用“白名单”模式即默认不记录任何参数内容只为明确标记了Loggable需自定义的接口或参数打印日志。这更安全但开发体验稍差。区分环境在开发、测试环境可以配置更宽松的日志策略如只脱敏核心密码甚至保留原始参数以便调试。在生产环境则执行最严格的脱敏规则。这可以通过Spring的Profile来实现。日志等级控制敏感参数的详情可以放在DEBUG或TRACE级别而常规的请求日志仅路径、方法、状态码放在INFO级别。这样在生产环境默认级别下敏感信息不会被输出。定期审计日志内容安全是一个持续的过程。定期如每季度抽样检查生产环境的日志文件确保没有敏感信息泄露。可以编写简单的脚本用正则表达式扫描日志中是否出现了身份证号、银行卡号等模式。实现一个健壮的API参数日志脱敏系统是对系统安全性和开发者友好性的一次重要平衡。它要求我们对Spring框架、HTTP协议以及数据安全有深入的理解。上面的方案提供了一个可扩展的起点你可以根据自己项目的具体需求比如对性能的极致要求、更复杂的脱敏规则进行调整和优化。记住没有一劳永逸的安全方案持续的代码审查、安全测试和日志审计同样重要。