一、背景
在给第三方提供接口时,我们需要对接口进行验签。具体来说,当外部系统调用我们的接口时,请求中需要携带一个签名,我们接收到请求后,会解析数据并校验签名是否正确,以确保请求的合法性和安全性。
为了在不同项目中方便地使用这一功能,我们将签名校验规则封装成一个工具包。使用方只需通过简单的注解即可轻松集成验签功能,无需重复编写验签逻辑,从而提高开发效率并确保一致性。
二、实现原理
- 使用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[i]) {
if (anno instanceof SignatureParam) {
signatureParam = (SignatureParam) anno;
Object paramValue = args[i];
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[i]) {
if (anno instanceof SignatureParam) {
SignatureParam signatureParam = (SignatureParam) anno;
Class<?> aClass = parameterTypes[i];
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.SignatureAutoConfiguration
4.2.13 pom.xml
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>2.1.3.RELEASE</version>
<optional>true</optional>
</dependency>
<dependency>
<groupId>com.alibaba.fastjson2</groupId>
<artifactId>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)
- 请求接口
行业拓展
分享一个面向研发人群使用的前后端分离的低代码软件——JNPF。
基于 Java Boot/.Net Core双引擎,它适配国产化,支持主流数据库和操作系统,提供五十几种高频预制组件,内置了常用的后台管理系统使用场景和实用模版,通过简单的拖拉拽操作,开发者能够高效完成软件开发,提高开发效率,减少代码编写工作。
JNPF基于SpringBoot+Vue.js,提供了一个适合所有水平用户的低代码学习平台,无论是有经验的开发者还是编程新手,都可以在这里找到适合自己的学习路径。
此外,JNPF支持全源码交付,完全支持根据公司、项目需求、业务需求进行二次改造开发或内网部署,具备多角色门户、登录认证、组织管理、角色授权、表单设计、流程设计、页面配置、报表设计、门户配置、代码生成工具等开箱即用的在线服务。