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

背景

目前我负责的一个公司内部Java应用，其Web层几乎没有进行水平鉴权，存在着一定的风险，比如A可以看到不属于他的B公司的数据。最近公司进行渗透测试，将这个风险暴露出来，并将修复提上了议程。

由于Web层的接口很多，我希望能用一种较为通用易于接入的方式来完成这个工作。很容易就想到了通过注解方式进行水平鉴权。说来惭愧，我工作了十年多还没有从0到1写一个稍微复杂点的注解，正好利用这个机会进行学习和实践。

我结合了一些现有代码以及DeepSeek（元宝版）的建议，实现了相关功能。为了便于理解，本文在保留适用场景通用性的前提下，删减无关的代码。

鉴权场景

一个公司可以给一个或多个用户授权，一个用户可以被一个或多个公司授权。

用户只能查看被授权公司的数据。

架构

实现

注解定义

/* by 01130.hk - online tools website : 01130.hk/zh/quchong.html */ @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; }

两个枚举的取值范围是

/* by 01130.hk - online tools website : 01130.hk/zh/quchong.html */ /** * 授权对象类型 * */ @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<A> 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>，取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; } }

设计思路

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

1. 最常见的场景，使用方式最简单。最常见的场景是鉴权所需参数（本例是公司id即companyId）直接出现在方法的形参表里。这种情况只需要直接给方法打@UserPermission注解。

2. 尽量减少重复配置。如果一个Controller类的大部分入参形式是一样的，那么直接在Controller类上打注解。

3. 预处理重复参数。多个comanyId鉴权时，在调用外部服务前，先做去重，可能可以减少服务提供方的系统开销。当然，这里的系统提供方的代码也是我写的，我会在提供方代码里也做一次去重。

4. 直接放行的场景处理。如admin用户，不需要做任何权限配置就可以访问，这块逻辑可以放在切面，也可以放在UserPermissionManger

5. 对象取值优先使用getter。Web层的Controller，入参对象一般都是pojo，直接调用getter效率更好。如果没有pojo，那就需要使用反射方法来直接读取属性值。

使用示例

不同场景下，注解属性字段的配置方式如下表：

边界场景处理

看起来这个注解已经非常全面，可以能处理绝大多数场景了，是吗？

话不能说绝对，在一个运行多年的系统中，你会看到这种入参：Task queryTask(Long taskId)，companyId字段是Task的属性，现在注解是不是束手无策了？

有两个选择：

1. 进一步扩展注解的适用场景，或者为这种场景编写专属的注解

2. 直接编码，先查Task，取companyId，手动调用userPermissionManger

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

编译期校验

根据注解的使用实例，可以看到objectType和valueType是有一定的对应关系的，valueType=COLLECTION_FIELD或OBJECT_COLLECTION_FIELD时，objectType必然是COMPANIES。如果写错了，也没测试出来，上线以后还要重新改，可不是什么好事。

此外，index显然是大于等于0的。如何将这些限制的检查放到编译期，从根源上防止配置错误呢？

方法是有的，而且有好几种。但是有些方法需要增加三方库依赖及对应的配置，我选择了一个最简单的方案，利用JDK8的原生能力就能完成，不过缺点是需要把注解相关代码移到业务代码之外的module，并且确保这个module比业务module先编译。步骤如下：

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

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

/** * UserPermission注解处理器，在编译期校验注解是否配置正确 * * 如果和业务代码在同一模块，需要做很多额外的编译配置，或引入二方包并配置。简单起见单独抽一个模块 * */ @SupportedAnnotationTypes("com.yourcompany.xxproject.annotation.UserPermission") @SupportedSourceVersion(SourceVersion.RELEASE_8) public class UserPermissionProcessor extends AbstractProcessor { @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { for (TypeElement annotation : annotations) { Set<? extends Element> annotatedElements = roundEnv.getElementsAnnotatedWith(annotation); for (Element element : annotatedElements) { checkUserPermissionUsage(element); } } return true; } private void checkUserPermissionUsage(Element element) { AnnotationMirror userPermissionMirror = getAnnotationMirror(element, "com.yourcompany.xxproject.annotation.UserPermission"); if (userPermissionMirror == null) { return; } Map<? extends ExecutableElement, ? extends AnnotationValue> elementValues = processingEnv.getElementUtils().getElementValuesWithDefaults(userPermissionMirror); checkValueTypeObjectTypeConstraint(element, userPermissionMirror, elementValues); checkIndexConstraint(element, userPermissionMirror, elementValues); } private void checkValueTypeObjectTypeConstraint( Element element, AnnotationMirror annotationMirror, Map<? extends ExecutableElement, ? extends AnnotationValue> values) { AuthObjectTypeEnum objectType = extractEnumValue(values, "objectType", element, annotationMirror); if (objectType == null) { processingEnv .getMessager() .printMessage(Diagnostic.Kind.ERROR, "objectType为空", element, annotationMirror); return; } AuthObjectValueEnum valueType = extractEnumValue(values, "valueType", element, annotationMirror); if (valueType == null) { processingEnv .getMessager() .printMessage(Diagnostic.Kind.ERROR, "valueType为空", element, annotationMirror); return; } if ((valueType.getValue() == AuthObjectValueEnum.COLLECTION_FIELD.getValue() || valueType.getValue() == AuthObjectValueEnum.OBJECT_COLLECTION_FIELD.getValue()) && objectType.getValue() != AuthObjectTypeEnum.COMPANIES.getValue()) { processingEnv .getMessager() .printMessage( Diagnostic.Kind.ERROR, "当valueType为AuthObjectValueEnum.COLLECTION_FIELD或AuthObjectValueEnum.OBJECT_COLLECTION_FIELD时， objectType必须是AuthObjectTypeEnum.COMPANIES", element, annotationMirror); } } private void checkIndexConstraint( Element element, AnnotationMirror annotationMirror, Map<? extends ExecutableElement, ? extends AnnotationValue> values) { AnnotationValue indexValue = getAnnotationValue(values, "index"); if (indexValue != null) { int indexVal = (Integer) indexValue.getValue(); if (indexVal < 0) { processingEnv .getMessager() .printMessage( Diagnostic.Kind.ERROR, "index必须大于等于0，当前值: " + indexVal, element, annotationMirror); } } } private AnnotationMirror getAnnotationMirror(Element element, String annotationClassName) { for (AnnotationMirror mirror : element.getAnnotationMirrors()) { if (mirror.getAnnotationType().toString().equals(annotationClassName)) { return mirror; } } return null; } private <T> T extractEnumValue( Map<? extends ExecutableElement, ? extends AnnotationValue> values, String valueKey, Element element, AnnotationMirror annotationMirror) { AnnotationValue value = getAnnotationValue(values, valueKey); if (value == null) { return null; } String valueStr = value.toString(); try { // 1. 剔除前缀 "java: "，trim去空格 String enumFullStr = valueStr.replace("java: ", "").trim(); // 2. 按最后一个"."拆分枚举类名和常量名 int lastDotIndex = enumFullStr.lastIndexOf("."); if (lastDotIndex == -1) { throw new IllegalArgumentException("枚举字符串格式异常：" + valueStr); } // 枚举类全限定名（如com.yourcompany.xxproject.api.annotation.enums.AuthObjectTypeEnum） String enumClassName = enumFullStr.substring(0, lastDotIndex); // 枚举常量名（如COMPANIES） String enumConstantName = enumFullStr.substring(lastDotIndex + 1); // 步骤3：反射还原枚举实例 Class<?> enumClass = Class.forName(enumClassName); if (enumClass.isEnum()) { return (T) Enum.valueOf((Class<? extends Enum>) enumClass, enumConstantName); } else { processingEnv .getMessager() .printMessage(Diagnostic.Kind.ERROR, valueKey + "的值不是枚举", element, annotationMirror); } } catch (Exception e) { processingEnv .getMessager() .printMessage( Diagnostic.Kind.ERROR, valueKey + "解析枚举失败，原始值:" + valueStr, element, annotationMirror); } return null; } private AnnotationValue getAnnotationValue( Map<? extends ExecutableElement, ? extends AnnotationValue> values, String key) { for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : values.entrySet()) { if (entry.getKey().getSimpleName().toString().equals(key)) { return entry.getValue(); } } return null; } }

3. 在切面所在的module的src/main/resources/META-INF/services路径下，增加一个文件javax.annotation.processing.Processor，内容注解处理器的完整类路径：

com.yourcompany.xxproject.annotation.processor.UserPermissionProcessor

如图

验证，写一段违反规则的代码，IDE build时提示：

继续迭代...

1. COMPANY和COMPANIES拼写接近，如果用代码自动补全，有可能写错。你可以将后者字面值改为MULTI_COMPANIES。

2. 可以将对象鉴权和角色鉴权结合起来，判断用户是否有某个角色的权限，也即在水平鉴权的基础上增加垂直鉴权。当然你也可以用另一个注解来完成。

3. 如果这个注解足够通用，你可以将它们（包括UserPermissionManger）打成一个二方包，供其他应用使用。这时你需要研究下如何封装远程调用相关的代码，这和你所用的微服务框架有关。实际上，我前司的鉴权平台就有这样一个鉴权二方包。当你把它打成了二方包，就意味着使用者会日趋变多，调用量也会随着业务不断增长，不同的应用可能使用了这个包的不同版本，一定要在早期开始优化性能！