Web层接口通用鉴权注解实践（基于JDK8）

酝垓 · 1 小时前

背景

目前我负责的一个公司内部Java应用，其Web层几乎没有进行水平鉴权，存在着一定的风险，比如A可以看到不属于他的B公司的数据。最近公司进行渗透测试，将这个风险暴露出来，并将修复提上了议程。
由于Web层的接口很多，我希望能用一种较为通用易于接入的方式来完成这个工作。很容易就想到了通过注解方式进行水平鉴权。说来惭愧，我工作了十年多还没有从0到1写一个稍微复杂点的注解，正好利用这个机会进行学习和实践。
我结合了一些现有代码以及DeepSeek（元宝版）的建议，实现了相关功能。为了便于理解，本文在保留适用场景通用性的前提下，删减无关的代码。
鉴权场景

一个公司可以给一个或多个用户授权，一个用户可以被一个或多个公司授权。
用户只能查看被授权公司的数据。
架构

实现

注解定义

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface UserPermission {
/** 鉴权对象类型，如果是List，应使用COMPANIES */
AuthObjectTypeEnum objectType() default AuthObjectTypeEnum.COMPANY;
/** 鉴权对象值类型，定义如何取得用来鉴权的对象 */
AuthObjectValueEnum valueType() default AuthObjectValueEnum.RARE;
/** 鉴权参数序号. 0~n表示第x个参数对象的内部成员变量，仅当 valueType不为RARE时有效 */
int index() default 0;
/** 鉴权参数名称, 如果是多级的，使用'.'分割，比如companyInfo.companyId */
String paramName() default "companyId";
/** 是否忽略鉴权，用于覆盖类上有默认注解的场景，此时接口不需要鉴权 */
boolean isIgnore() default false;
}

复制代码

两个枚举的取值范围是

/**
* 授权对象类型
*
*/
@Getter
public enum AuthObjectTypeEnum {
COMPANY(1, "单个企业"),
COMPANIES(2, "多个企业");
private final int value;
private final String des;
AuthObjectTypeEnum(int value, String des) {
this.value = value;
this.des = des;
}
}

复制代码

/**
* 授权对象参数类型，即该参数是以何种形式出现在形参表的
*
*/
@Getter
public enum AuthObjectValueEnum {
/** 参数直接按原始值出现 */
RARE(1, "原始参数"),
/** eg1. 入参是A,取A.companyId, eg2. 入参是B，取B.companyIds */
OBJECT_FIELD(2, "对象的属性"),
/** eg. 入参是List objects,取A.companyId */
COLLECTION_FIELD(3, "集合元素的属性"),
/** eg. 入参是A，取A.companyInfo.companyId, A.B.companyIds */
OBJECT_SUB_FIELD(4, "对象的属性的属性"),
/** eg. 入参是A，取A.companyList中的companyId */
OBJECT_COLLECTION_FIELD(5, "对象的属性中集合元素的属性"),
;
private final int value;
private final String des;
AuthObjectValueEnum(int value, String des) {
this.value = value;
this.des = des;
}
}

复制代码

鉴权辅助类

调用外部服务（本例是公司-用户关系管理平台），获取一个用户是否有单个或多个公司的权限。

/**
* 公司-用户关系管理平台用户鉴权服务封装
*
*/
@Component
public class UserPermissionManager {
@Resource private UserPermissionFeignService userPermissionFeignService;
/**
* 检测用户是否对公司的数据拥有访问权限
*
* @param userName
* @param companyId
* @return
*/
public boolean checkCompany(String userName, long companyId) {
return checkResult(userPermissionFeignService.checkCompany(userName, companyId));
}
/**
* 批量检测用户是否对所有指定的公司的数据都拥有访问权限
*
* @param userName
* @param companyIds
* @return
*/
public boolean checkCompanies(String userName, List<Long> companyIds) {
if (CollectionUtils.isEmpty(companyIds)) {
throw new BizException("鉴权公司id列表不能为空");
}
// 去重
companyIds = companyIds.stream().distinct().collect(Collectors.toList());
return companyIds.size() == 1
? checkResult(userPermissionFeignService.checkCompany(userName, companyIds.get(0)))
: checkResult(userPermissionFeignService.checkCompanies(userName, companyIds));
}
private boolean checkResult(ResultVO<Boolean> result) {
if (result == null
|| result.getCode() != HttpCodeConstants.SUCCESS_CODE
|| result.getData() == null) {
throw new BizException("调用平台进行用户企业数据权限鉴权失败");
}
return BooleanUtils.isTrue(result.getData());
}
}

复制代码

AOP切面

鉴权功能的核心，注解只有在定义了对应的处理切面后，才能发挥作用。

@Aspect
@Component
public class UserPermissionAspect {
@Resource UserPermissionManager userPermissionManager;
/** 定义切点 */
@Pointcut("execution(public * com.yourcompany.xxproject.web.controller..*.*(..))")
public void privilege() {}
@Around("privilege()")
public Object isAccessMethod(ProceedingJoinPoint joinPoint) throws Throwable {
// 获取方法签名和注解信息
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
Class targetClass = signature.getDeclaringType();
UserPermission permissionOnClass =
(UserPermission) targetClass.getAnnotation(UserPermission.class);
UserPermission permissionOnMethod = method.getAnnotation(UserPermission.class);
// 优先取方法上的注解
UserPermission permissionAnnotation =
permissionOnClass != null ? permissionOnClass : permissionOnMethod;
if (permissionAnnotation == null || permissionAnnotation.isIgnore()) {
// 如果没有注解，或注解的策略是忽略，直接放行
return joinPoint.proceed();
}
ServletRequestAttributes servletRequestAttributes =
(ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
if (servletRequestAttributes == null) {
throw new BizException("请求中缺少属性信息");
}
UserInfoVO userVo = (UserInfoVO) servletRequestAttributes.getRequest().getAttribute("userVo");
if (userVo == null || StringUtils.isBlank(userVo.getUserName())) {
throw new BizException("请求中缺少用户信息或不完整");
}
String userName = userVo.getUserName();
// admin直接放行
if (UserUtil.isAdminOrSystem(userVo.getUserName())) {
return joinPoint.proceed();
}
try {
Object authValue = extractAuthValue(joinPoint, permissionAnnotation);
boolean hasPermission =
checkUserPermission(userName, authValue, permissionAnnotation.objectType());
if (!hasPermission) {
LoggerUtils.error(
String.format(
"用户%s没有%s类型对象%s的访问权限, 拒绝访问",
userName, permissionAnnotation.objectType().getDes(), authValue));
throw new BizException("权限不足，无法访问对应的数据。请确认当前用户是待访问数据所属的企业/企业组的成员。");
}
} catch (BizException e) {
throw e;
} catch (Exception e) {
LoggerUtils.error("权限校验失败，发生异常", e);
throw new BizException("权限校验失败，发生异常", e);
}
return joinPoint.proceed();
}
/**
* 从方法参数中提取鉴权对象的值
*
* @param joinPoint
* @param annotation
* @return
*/
private Object extractAuthValue(ProceedingJoinPoint joinPoint, UserPermission annotation) {
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
String[] parameterNames = signature.getParameterNames();
Object[] args = joinPoint.getArgs();
if (parameterNames == null || parameterNames.length == 0 || args == null || args.length == 0) {
throw new BizException("用户数据鉴权解析参数时，调用方法参数表为空");
}
if (annotation.valueType().getValue() == AuthObjectValueEnum.RARE.getValue()) {
// 直接按名称获取
for (int i = 0; i < parameterNames.length; i++) {
if (StringUtils.equals(parameterNames[i], annotation.paramName())) {
return args[i];
}
}
throw new BizException("用户数据鉴权解析参数时，未在形参表找到指定的鉴权参数");
}
// 参数所在的参数表的位置
int index = annotation.index();
// 其他情况，从入参对象获取
if (index < 0 || index >= args.length) {
throw new BizException("用户数据鉴权解析参数时索引越界: " + index + "，参数总数: " + args.length);
}
Object targetParam = args[index];
if (targetParam == null) {
throw new BizException("用户数据鉴权解析参数时第" + index + "个参数为null");
}
if (annotation.valueType().getValue() == AuthObjectValueEnum.OBJECT_FIELD.getValue()) {
// 从对象属性中获取, 比如A.companyId、A.companyIds
return extractFieldValue(targetParam, annotation.paramName());
} else if (annotation.valueType().getValue()
== AuthObjectValueEnum.COLLECTION_FIELD.getValue()) {
// 从集合对象的属性中获取，比如List，取A.companyId
// 此时必然是一个List（不考虑去重）
return extractListFieldValue(targetParam, annotation.paramName());
} else if (annotation.valueType().getValue()
== AuthObjectValueEnum.OBJECT_SUB_FIELD.getValue()) {
// 从对象的属性的属性获取，比如A.companyInfo.companyId
String[] fieldNames = annotation.paramName().split("\\.");
Object subTargetParam = extractFieldValue(targetParam, fieldNames[0]);
return extractFieldValue(subTargetParam, fieldNames[1]);
} else if (annotation.valueType().getValue()
== AuthObjectValueEnum.OBJECT_COLLECTION_FIELD.getValue()) {
// 从对象的集合属性中获取，比如A.companyList, 取companyList.companyId
String[] fieldNames = annotation.paramName().split("\\.");
Object subTargetParam = extractFieldValue(targetParam, fieldNames[0]);
return extractListFieldValue(subTargetParam, fieldNames[1]);
} else {
throw new BizException("用户数据鉴权解析参数, 参数值类型配置错误");
}
}
/**
* 实际的鉴权
*
* @param authValue
* @param authObjectTypeEnum
* @return
*/
private boolean checkUserPermission(
String userName, Object authValue, AuthObjectTypeEnum authObjectTypeEnum) {
if (authObjectTypeEnum.getValue() == AuthObjectTypeEnum.COMPANY.getValue()) {
return userPermissionManager.checkCompany(userName, getLongValue(authValue));
} else if (authObjectTypeEnum.getValue() == AuthObjectTypeEnum.COMPANIES.getValue()) {
return userPermissionManager.checkCompanies(userName, getLongListValue(authValue));
} else {
throw new BizException("按用户维度鉴权，该接口的鉴权对象类型非法");
}
}
private static long getLongValue(Object authValue) {
if (authValue instanceof Long) {
return (long) authValue;
} else if (authValue instanceof Integer) {
return (int) authValue;
} else if (authValue instanceof String) {
return Long.parseLong((String) authValue);
} else {
throw new BizException("按用户维度鉴权，企业id不是可处理的类型");
}
}
private static List<Long> getLongListValue(Object authValue) {
if (!(authValue instanceof Collection)) {
throw new BizException("按用户维度鉴权，企业id列表不是Collection类型");
}
Collection<?> col = (Collection<?>) authValue;
return col.stream().map(UserPermissionAspect::getLongValue).collect(Collectors.toList());
}
/**
* 通过反射从对象中提取字段值
*
* @param targetObject
* @param fieldName
*/
private Object extractFieldValue(Object targetObject, String fieldName) {
if (targetObject == null || fieldName == null || fieldName.isEmpty()) {
throw new IllegalArgumentException("目标对象和字段名不能为空");
}
try {
PropertyDescriptor pd = new PropertyDescriptor(fieldName, targetObject.getClass());
Method getter = pd.getReadMethod();
if (getter == null) {
throw new BizException("字段 '" + fieldName + "' 没有对应的getter方法");
}
return getter.invoke(targetObject);
} catch (IntrospectionException e) {
// 如果找不到标准Getter，不尝试直接访问字段即field.setAccessible(true); field.get(targetObject);
// 此注解处理的都是Controller入参，不太可能没有Getter/Setter，没必要写冗余的处理逻辑
throw new BizException("调用字段 '" + fieldName + "' 没有找到标准getter方法时发生错误", e);
} catch (IllegalAccessException | InvocationTargetException e) {
throw new BizException("调用字段 '" + fieldName + "' 的getter方法时发生错误", e);
}
}
private List<Long> extractListFieldValue(Object targetParam, String fieldName) {
if (!(targetParam instanceof Collection)) {
throw new BizException("按用户维度鉴权，待处理对象列表不是Collection类型");
}
Collection<?> col = (Collection<?>) targetParam;
List<Long> result = Lists.newArrayList();
for (Object obj : col) {
if (obj == null) {
throw new BizException("按用户维度鉴权，集合中包含null元素，无法访问其字段。");
}
result.add(getLongValue(extractFieldValue(obj, fieldName)));
}
return result;
}
}

复制代码

设计思路

目前的处理逻辑并不是第一版，和其他功能一样也是从最基础的功能开始，一点一点往上加的。简述一下设计思路：

最常见的场景，使用方式最简单。最常见的场景是鉴权所需参数（本例是公司id即companyId）直接出现在方法的形参表里。这种情况只需要直接给方法打@UserPermission注解。
尽量减少重复配置。如果一个Controller类的大部分入参形式是一样的，那么直接在Controller类上打注解。
预处理重复参数。多个comanyId鉴权时，在调用外部服务前，先做去重，可能可以减少服务提供方的系统开销。当然，这里的系统提供方的代码也是我写的，我会在提供方代码里也做一次去重。
直接放行的场景处理。如admin用户，不需要做任何权限配置就可以访问，这块逻辑可以放在切面，也可以放在UserPermissionManger
对象取值优先使用getter。Web层的Controller，入参对象一般都是pojo，直接调用getter效率更好。如果没有pojo，那就需要使用反射方法来直接读取属性值。

使用示例

不同场景下，注解属性字段的配置方式如下表：
场景名称和实例objectTypevalueTypeindexparamNameisIgnore首个参数，且参数名称为默认名称

func(long companyId)默认(COMPANY)默认(RARE)默认(0)默认(companyId)默认

(false)首个参数，id列表

func(List companyIds)COMPANIESRARE默认(0)companyIds默认

(false)首个参数的属性

func(TaBO bo)

bo.companyId默认(COMPANY)OBJECT_FIELD默认(0)默认(companyId)默认

(false)首个参数的属性

func(TbBO bo)

bo.companyIdsCOMPANIESOBJECT_FIELD默认(0)companyIds默认

(false)第二个参数的属性

func(TaBO abo, TbBO bbo)

bbo.companyId默认(COMPANY)OBJECT_FIELD1默认(companyId)默认

(false)首个集合参数的属性

func(List list)

abo.companyIdCOMPANIESCOLLECTION_FIELD默认(0)默认(companyId)默认

(false)首个参数属性的属性

func(TaBO abo)

abo.companyInfo.companyId默认(COMPANY)OBJECT_SUB_FIELD默认(0)companyInfo.companyId默认

(false)首个参数的属性是一个集合，这个集合元素的属性

func(TaBO abo)

abo.companyInfoList

companyInfo.companyIdCOMPANIESOBJECT_COLLECTION_FIELD默认(0)companyInfoList.companyId默认

(false)Controller类本身有鉴权注解，但是当前方法不需要鉴权任意值任意值任意值任意值true边界场景处理

看起来这个注解已经非常全面，可以能处理绝大多数场景了，是吗？
话不能说绝对，在一个运行多年的系统中，你会看到这种入参：Task queryTask(Long taskId)，companyId字段是Task的属性，现在注解是不是束手无策了？
有两个选择：

进一步扩展注解的适用场景，或者为这种场景编写专属的注解
直接编码，先查Task，取companyId，手动调用userPermissionManger

我选用了方案二。方案一固然可以将更多的接口接入转化为注解，但是也要根据实际情况，如果适用的接口并不多，新增的注解相关代码也意味着额外的维护成本。
编译期校验

根据注解的使用实例，可以看到objectType和valueType是有一定的对应关系的，valueType=COLLECTION_FIELD或OBJECT_COLLECTION_FIELD时，objectType必然是COMPANIES。如果写错了，也没测试出来，上线以后还要重新改，可不是什么好事。
此外，index显然是大于等于0的。如何将这些限制的检查放到编译期，从根源上防止配置错误呢？
方法是有的，而且有好几种。但是有些方法需要增加三方库依赖及对应的配置，我选择了一个最简单的方案，利用JDK8的原生能力就能完成，不过缺点是需要把注解相关代码移到业务代码之外的module，并且确保这个module比业务module先编译。步骤如下：

首先，将你的注解相关代码（切面代码除外）移到业务层之外的module。不推荐放到对外打包的module，因此我选择新建了一个。注意处理各个module的依赖，确保业务层依赖了这个module

编写注解处理器代码，对注解的配置值进行校验

[code]/** * UserPermission注解处理器，在编译期校验注解是否配置正确 * * 如果和业务代码在同一模块，需要做很多额外的编译配置，或引入二方包并配置。简单起见单独抽一个模块 * */@SupportedAnnotationTypes("com.yourcompany.xxproject.annotation.UserPermission")@SupportedSourceVersion(SourceVersion.RELEASE_8)public class UserPermissionProcessor extends AbstractProcessor { @Override public boolean process(Set

账号		自动登录	找回密码
密码			立即注册

Web层接口通用鉴权注解实践（基于JDK8）

相关帖子

签约作者

Web层接口通用鉴权注解实践（基于JDK8）

相关帖子

相关推荐

签约作者