使用AOP技术实现Java通用接口验签工具
一、背景在给第三方提供接口时，我们需要对接口进行验签。具体来说，当外部系统调用我们的接口时，请求中需要携带一个签名，我们接收到请求后，会解析数据并校验签名是否正确，以确保请求的合法性和安全性。
为了在不同项目中方便地使用这一功能，我们将签名校验规则封装成一个工具包。使用方只需通过简单的注解即可轻松集成验签功能，无需重复编写验签逻辑，从而提高开发效率并确保一致性。
二、实现原理
[*]使用AOP来拦截方法
[*]获取参数值进行组装、校验签名是否一致
三、设计思路
通过俩个注解进行标记所需要进行验签的方法
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SignatureChecker {
// 服务Code
String serviceCode() default SignatureConst.EMPTY_STR;
// 签名生成密钥
String secretKey() default SignatureConst.EMPTY_STR;
// 签名过期时间，单位为分钟
int expireMinutes() default -1;
// 默认为true，表示需要验证签名
boolean required() default true;
// 返回值类型
String returnType() default SignatureConst.DEFAULT_RETURN_TYPE;
}serviceCode：服务编码，进行区分不同的服务/业务
secretKey：双方约定好的密钥，进行生成签名，可以写在配置文件中。
expireMinutes：标识签名有效时长，默认5分钟，可以配置文件中进行全局修改。
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface SignatureParam {
// 0:标识serviceCode 1:标识请求参数
SignatureParamTypeEnum type() default SignatureParamTypeEnum.PARAMS;
String requestIdField() default SignatureConst.EMPTY_STR;
String timestampField() default SignatureConst.EMPTY_STR;
String signatureField() default SignatureConst.EMPTY_STR;
}对于不同的请求实体，可能对应的字段名不相同，所以我们需要使用一个注解进行标注当前实体验签字段的名称。
当签名字段发生变化时，可以使用requestIdField、timestampField、signatureField 字段进行指定。
四、代码
4.1 代码结构
4.2 详细代码
4.2.1 SignatureChecker.class
import org.tao.consts.SignatureConst;import java.lang.annotation.ElementType;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SignatureChecker {
// 服务Code
String serviceCode() default SignatureConst.EMPTY_STR;
// 签名生成密钥
String secretKey() default SignatureConst.EMPTY_STR;
// 签名过期时间，单位为分钟
int expireMinutes() default -1;
// 默认为true，表示需要验证签名
boolean required() default true;
// 返回值类型
String returnType() default SignatureConst.DEFAULT_RETURN_TYPE;
}4.2.2 SignatureParam.class
import org.tao.consts.SignatureConst;import org.tao.enums.SignatureParamTypeEnum;import java.lang.annotation.ElementType;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface SignatureParam {
// 0:标识serviceCode 1:标识请求参数
SignatureParamTypeEnum type() default SignatureParamTypeEnum.PARAMS;
String requestIdField() default SignatureConst.EMPTY_STR;
String timestampField() default SignatureConst.EMPTY_STR;
String signatureField() default SignatureConst.EMPTY_STR;
}4.2.3 SignatureAspect.class
import com.alibaba.fastjson2.JSON;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.tao.anno.SignatureChecker;
import org.tao.anno.SignatureParam;
import org.tao.config.SignatureProperties;
import org.tao.consts.SignatureConst;
import org.tao.enums.SignatureParamTypeEnum;
import org.tao.exception.SignatureValidationException;
import org.tao.utils.SignatureUtil;
import javax.annotation.Resource;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.util.Map;
@Aspect
@Component
public class SignatureAspect {
private static final Logger logger = LoggerFactory.getLogger(SignatureAspect.class);
@Resource
private SignatureProperties signatureProperties;
@Around("@annotation(org.tao.anno.SignatureChecker) " +
"&& (@annotation(org.springframework.web.bind.annotation.PostMapping) || @annotation(org.springframework.web.bind.annotation.RequestMapping))")
public Object validateSignature(ProceedingJoinPoint joinPoint) throws Throwable {
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
Map<String, Object> paramMap = null;
String serviceCode = null;
Object[] args = joinPoint.getArgs();
Annotation[][] parameterAnnotations = method.getParameterAnnotations();
SignatureChecker signatureChecker = method.getAnnotation(SignatureChecker.class);
if (signatureChecker != null && signatureChecker.required()) {
SignatureParam signatureParam = null;
// 遍历参数注解，找到被 @SignatureParam 注解修饰的参数
for (int i = 0; i < parameterAnnotations.length; i++) {
for (Annotation anno : parameterAnnotations) {
if (anno instanceof SignatureParam) {
signatureParam = (SignatureParam) anno;
Object paramValue = args;
if (signatureParam.type() == SignatureParamTypeEnum.PARAMS) {
try {
paramMap = JSON.parseObject(JSON.toJSONString(paramValue), Map.class);
} catch (Exception e) {
logger.error("[签名校验] 失败，请检查 params 参数是否正确, paramsValue => {}, message => {}", JSON.toJSONString(paramValue), e.getMessage());
}
} else if (signatureParam.type() == SignatureParamTypeEnum.SERVICE_CODE) {
if (paramValue instanceof String) {
serviceCode = paramValue.toString();
} else {
logger.error("[签名校验] 失败，请检查 serviceCode 参数是否正确, serviceCode => {}", JSON.toJSONString(paramValue));
}
} else {
throw new SignatureValidationException(SignatureConst.DEFAULT_RETURN_TYPE, "参数类型错误，请检查！");
}
}
}
}
try {
validateSignature(signatureChecker, signatureParam, paramMap, serviceCode);
} catch (SignatureValidationException e) {
logger.warn("[签名校验] 校验失败，paramMap => {}, message => {}", JSON.toJSONString(paramMap), e.getMessage());
throw e;
} catch (Exception e){
logger.error("[签名校验] 校验失败，paramMap => {}, message => {}", JSON.toJSONString(paramMap), e.getMessage());
throw new SignatureValidationException(SignatureConst.DEFAULT_RETURN_TYPE, "系统异常，请稍后重试！");
}
}
// 继续执行原方法
return joinPoint.proceed();
}
private void validateSignature(SignatureChecker checker, SignatureParam signatureParam, Map<String, Object> paramMap, String serviceCode) throws SignatureValidationException {
// 获取服务编码，如果 SignatureChecker 指定，选择 SignatureChecker 的值，否则选择 signatureParam 标记的值
String servicedCodeNew = StringUtils.isEmpty(checker.serviceCode()) ? serviceCode : checker.serviceCode();
if (StringUtils.isEmpty(servicedCodeNew)) {
throw new SignatureValidationException(checker.returnType(), "[验签失败] 缺失 serviceCode，请配置！");
}
// 获取密钥 如果 SignatureChecker 指定，选择 SignatureChecker 的值，否则选择 signatureProperties 配置的值
String secretKey = StringUtils.isEmpty(checker.secretKey()) ? signatureProperties.getSecretKeys().get(servicedCodeNew) : checker.secretKey();
if (StringUtils.isEmpty(secretKey)) {
throw new SignatureValidationException(checker.returnType(), "[验签失败] 缺失 secretKey，请配置！");
}
// 获取参数字段 如果 signatureParam 指定，选择 signatureParam 的值，否则选择 signatureProperties 配置的值
String signatureField = StringUtils.isEmpty(signatureParam.signatureField()) ? signatureProperties.getSignatureField() : signatureParam.signatureField();
String requestIdField = StringUtils.isEmpty(signatureParam.requestIdField()) ? signatureProperties.getRequestIdField() : signatureParam.requestIdField();
String timestampField = StringUtils.isEmpty(signatureParam.timestampField()) ? signatureProperties.getTimestampField() : signatureParam.timestampField();
// 获取实际请求参数数据
String requestId = paramMap.get(requestIdField) == null ? null : paramMap.get(requestIdField).toString();
Long timestamp = paramMap.get(timestampField) == null ? null : Long.parseLong(paramMap.get(timestampField).toString());
String signature = paramMap.get(signatureField) == null ? null : paramMap.get(signatureField).toString();
if (StringUtils.isEmpty(requestId) || StringUtils.isEmpty(signature) || StringUtils.isEmpty(timestamp)) {
logger.warn("[验签失败] 缺失鉴权参数，请检查！requestId => {}, signature => {}, timestamp => {}", requestId, signature, timestamp);
throw new SignatureValidationException(checker.returnType(), "[验签失败] 缺失鉴权参数，请检查！");
}
// 校验时间戳
validateTimestamp(checker, timestamp);
// 校验签名
if (!SignatureUtil.verifySignature(requestId + timestamp, secretKey, signature)) {
throw new SignatureValidationException(checker.returnType(), "签名校验不通过！");
}
}
private void validateTimestamp(SignatureChecker checker, long timestamp) throws SignatureValidationException {
// 如果是-1，则使用配置文件中的默认值
long expireMinutes = checker.expireMinutes() == -1 ? signatureProperties.getExpireMinutes() : checker.expireMinutes();
// 如果是0，则代表永久有效，不进行时间判断
if (expireMinutes == 0) {
return;
} else if (expireMinutes <= 0) {
throw new SignatureValidationException(checker.returnType(), "[验签失败] 过期时间配置无效，请检查！");
}
long currentTime = System.currentTimeMillis();
if (timestamp > currentTime + 5 * 60 * 1000) {
throw new SignatureValidationException(checker.returnType(), "[验签失败] 调用端时间与服务器时间未同步，请检查！");
} else if (currentTime - timestamp > (long) expireMinutes * 60 * 1000) {
throw new SignatureValidationException(checker.returnType(), "[验签失败] 请求已过期，请重新请求！");
}
}
}4.2.4 SignatureAutoConfiguration.class
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.tao.aspect.SignatureAspect;
/**
* @author: handsometaoa
* @description
* @date: 2025/3/29 11:00
*/
@Configuration
@EnableConfigurationProperties(SignatureProperties.class)
@ComponentScan(basePackages = {"org.tao"})
public class SignatureAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public SignatureAspect signatureAspect() {
return new SignatureAspect();
}
}4.2.5 SignatureProperties.class
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.HashMap;
import java.util.Map;
@ConfigurationProperties(prefix = "signature")
public class SignatureProperties {
private String requestIdField = "requestId";
private String timestampField = "timestamp";
private String signatureField = "signature";
private Integer expireMinutes = 5;
private Map<String, String> secretKeys = new HashMap<>();
private Map<String, String> returnJsons = new HashMap<>();
public Map<String, String> getSecretKeys() {
return secretKeys;
}
public void setSecretKeys(Map<String, String> secretKeys) {
this.secretKeys = secretKeys;
}
public Integer getExpireMinutes() {
return expireMinutes;
}
public void setExpireMinutes(Integer expireMinutes) {
this.expireMinutes = expireMinutes;
}
public String getRequestIdField() {
return requestIdField;
}
public void setRequestIdField(String requestIdField) {
this.requestIdField = requestIdField;
}
public String getSignatureField() {
return signatureField;
}
public void setSignatureField(String signatureField) {
this.signatureField = signatureField;
}
public String getTimestampField() {
return timestampField;
}
public void setTimestampField(String timestampField) {
this.timestampField = timestampField;
}
public Map<String, String> getReturnJsons() {
return returnJsons;
}
public void setReturnJsons(Map<String, String> returnJsons) {
this.returnJsons = returnJsons;
}
}4.2.6 SignatureConst.class
public class SignatureConst {
public static final String DEFAULT_RETURN_TYPE = "default";
public static final String EMPTY_STR = "";
}4.2.7 SignatureParamTypeEnum.class
public enum SignatureParamTypeEnum {
SERVICE_CODE(1, "服务编码"),
PARAMS(2, "参数");
private Integer code;
private String desc;
SignatureParamTypeEnum(Integer code, String desc) {
this.code = code;
this.desc = desc;
}
public Integer getCode() {
return code;
}
}4.2.8 GlobalExceptionHandler
import com.alibaba.fastjson2.JSON;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.tao.config.SignatureProperties;
import org.tao.consts.SignatureConst;
import javax.annotation.Resource;
import java.util.HashMap;
import java.util.Map;
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
@Resource
private SignatureProperties signatureProperties;
@ExceptionHandler(SignatureValidationException.class)
public ResponseEntity<Map<String, Object>> handleSignatureValidationException(SignatureValidationException ex) {
Map<String, Object> map = new HashMap<>();
map.put("code", 500);
map.put("message", ex.getMessage());
if (ex.getReturnType() != null && !ex.getReturnType().equals(SignatureConst.DEFAULT_RETURN_TYPE)) {
String responseStr = signatureProperties.getReturnJsons().get(ex.getReturnType());
if (StringUtils.isEmpty(responseStr)) {
log.error("[全局异常处理] 返回json配置错误，请检查配置！");
} else {
responseStr = responseStr.replace("${message}", ex.getMessage());
}
map = JSON.parseObject(responseStr, Map.class);
}
return new ResponseEntity<>(map, HttpStatus.INTERNAL_SERVER_ERROR);
}
}4.2.9 SignatureValidationException.class
import org.tao.consts.SignatureConst;
public class SignatureValidationException extends RuntimeException {
private String returnType = SignatureConst.DEFAULT_RETURN_TYPE;
public SignatureValidationException(String returnType, String message) {
super(message);
this.returnType = returnType;
}
public String getReturnType() {
return returnType;
}
}4.2.10 AnnotationValidationProcessor.class
import com.alibaba.fastjson2.JSON;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.tao.anno.SignatureChecker;
import org.tao.anno.SignatureParam;
import org.tao.config.SignatureProperties;
import org.tao.consts.SignatureConst;
import org.tao.enums.SignatureParamTypeEnum;
import org.tao.exception.GlobalExceptionHandler;
import javax.annotation.PostConstruct;
import javax.annotation.Resource;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.util.Map;
@Component
public class AnnotationValidationProcessor implements BeanPostProcessor {
private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
@Resource
private SignatureProperties signatureProperties;
@PostConstruct
public void preCheck() {
Map<String, String> returnJsons = signatureProperties.getReturnJsons();
if (returnJsons != null && !returnJsons.isEmpty()) {
returnJsons.forEach((key, value) -> {
if (!JSON.isValidObject(value)) {
log.warn("[验签配置校验] 返回类型 json 字符串配置错误，value => {}", value);
throw new IllegalStateException("[验签配置校验] 返回类型 json 字符串配置错误，请检查配置！");
}
});
}
}
@Override
public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
Class<?> clazz = bean.getClass();
for (Method method : clazz.getDeclaredMethods()) {
// 检查方法是否带有 @SignatureChecker
if (method.isAnnotationPresent(SignatureChecker.class)) {
SignatureChecker annotation = method.getAnnotation(SignatureChecker.class);
if (!StringUtils.isEmpty(annotation.serviceCode()) && StringUtils.isEmpty(annotation.secretKey())) {
if (!signatureProperties.getSecretKeys().containsKey(annotation.serviceCode())) {
log.warn("[验签配置校验] 配置缺失服务编码对应的密钥，serviceCode => {}", annotation.serviceCode());
throw new IllegalStateException("[验签配置校验] 配置缺失服务编码对应的密钥，请检查配置！");
}
}
if (!annotation.returnType().equals(SignatureConst.DEFAULT_RETURN_TYPE)) {
if (!signatureProperties.getReturnJsons().containsKey(annotation.returnType())) {
log.warn("[验签配置校验] 配置缺失返回类型 JSON 字符串，returnType => {}", annotation.returnType());
throw new IllegalStateException("[验签配置校验] 配置缺失返回类型 JSON 字符串，请检查配置！");
}
}
// 检查是否同时带有 @PostMapping 或 @RequestMapping
if (!method.isAnnotationPresent(PostMapping.class) && !method.isAnnotationPresent(RequestMapping.class)) {
throw new IllegalStateException("方法 " + method.getName() + " 必须同时带有 @PostMapping 或 @RequestMapping 注解");
}
// 检查方法参数
validateMethodParameters(method);
}
}
return bean;
}
private void validateMethodParameters(Method method) {
// 这里可以根据业务需求检查方法的参数
Class<?>[] parameterTypes = method.getParameterTypes();
if (parameterTypes.length == 0) {
throw new IllegalStateException("[验签配置校验] 方法 " + method.getClass().getName() + "." + method.getName() + " 必须至少有一个参数");
}
// 其他校验逻辑
Annotation[][] parameterAnnotations = method.getParameterAnnotations();
for (int i = 0; i < parameterAnnotations.length; i++) {
for (Annotation anno : parameterAnnotations) {
if (anno instanceof SignatureParam) {
SignatureParam signatureParam = (SignatureParam) anno;
Class<?> aClass = parameterTypes;
if (signatureParam.type() == SignatureParamTypeEnum.PARAMS) {
if (isPrimitiveType(aClass)) {
throw new IllegalStateException("[验签配置校验] " + method.getName() + " 方法 params 参数" + " 必须是对象类型");
}
} else if (signatureParam.type() == SignatureParamTypeEnum.SERVICE_CODE) {
if (aClass != String.class) {
throw new IllegalStateException("[验签配置校验] " + method.getName() + " 方法 serviceCode 参数" + " 必须是String类型");
}
} else {
throw new IllegalStateException("[验签配置校验] " + method.getName() + " 暂未适配类型");
}
}
}
}
}
private boolean isPrimitiveType(Class<?> clazz) {
return clazz.isPrimitive() || clazz == Integer.class || clazz == Boolean.class ||
clazz == Character.class || clazz == Byte.class || clazz == Short.class ||
clazz == Long.class || clazz == Float.class || clazz == Double.class;
}
}4.2.11 SignatureUtil.class
import org.springframework.util.DigestUtils;
/**
* @author: handsometaoa
* @description
* @date: 2025/3/29 11:00
*/
public class SignatureUtil {
/**
* 校验签名是否正确
*
* @param params 请求参数
* @param sign 客户端传递的签名
* @param secretKey 密钥
* @return 是否校验通过
*/
public static boolean verifySignature(String params, String secretKey, String sign) {
String serverSign = generateSignature(params, secretKey);
return serverSign.equals(sign);
}
/**
* 生成签名
*
* @param requestId 请求id
* @param timestamp 时间戳
* @param secretKey 密钥
* @return 生成的签名
*/
public static String generateSignature(String requestId, String timestamp, String secretKey) {
String rawData = requestId + timestamp + secretKey;
return DigestUtils.md5DigestAsHex(rawData.getBytes());
}
private static String generateSignature(String params, String secretKey) {
String rawData = params + secretKey;
return DigestUtils.md5DigestAsHex(rawData.getBytes());
}
}4.2.12 spring.factories.class
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
org.tao.config.SignatureAutoConfiguration4.2.13 pom.xml
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
spring-boot-starter-aop</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
spring-boot-autoconfigure</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
spring-boot-starter-web</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>com.alibaba.fastjson2</groupId>
fastjson2</artifactId>
<version>2.0.31</version>
<optional>true</optional>
</dependency>
</dependencies>五、使用方式
5.1 集成方式 （俩种方式）
[*]打成 jar 包引入依赖
[*]直接将代码拷进自己项目
5.2 使用说明
[*]在方法上添加 @SignatureChecker 注解，包含密钥的参数前添加 @SignatureParam 注解；举例：假设需要给XX业务进行验签，约定密钥为XXX，请求参数分别为 request_id、timeStamp、signature
@PostMapping("test")
@SignatureChecker(serviceserCode = "XX", secretKey = "XXX")
public String test(@RequestBody @SignatureParam(requestIdField = "request_id", timestampField = "timeStamp") Request request) {
return "test";
}
[*]基于 注解值 > 配置值 > 默认值（约定大于配置）
[*]serviceCode ： SignatureChecker 指定 serviceserCode【此方式只能固定一个serviceCode】> SignatureParam(type = 0) 标注【此方式可标注到 String 字段上，更加通用】
[*]密钥 secretKey : 注解(secretKey) > 配置值 （signature.secretKeys 中定义的）
[*]有效期 expireMinutes：注解（expireMinutes）> 配置值 （signature.expireMinutes）> 默认值（5）
[*]验签字段：注解（requestIdField、timestampField、signatureField）> 配置值 （signature.requestIdField) > 默认值（requestId、timestamp、signature）
[*]请求接口
六、最后
当然代码还是有很多不足的地方，仅供学习参考。
源码：https://github.com/handsometaoa/signutare-kit
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！
页:
[1]