背景
目前我负责的一个公司内部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<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.companyIdsreturn 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.companyIdString[] 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.companyIdString[] 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，那就需要使用反射方法来直接读取属性值。
使用示例
不同场景下，注解属性字段的配置方式如下表：
| 场景名称和实例 | objectType | valueType | index | paramName | isIgnore |
|---|---|---|---|---|---|
| 首个参数，且参数名称为默认名称 func(long companyId) |
默认(COMPANY) | 默认(RARE) | 默认(0) | 默认(companyId) | 默认 (false) |
| 首个参数，id列表 func(List |
COMPANIES | RARE | 默认(0) | companyIds | 默认 (false) |
| 首个参数的属性 func(TaBO bo) bo.companyId |
默认(COMPANY) | OBJECT_FIELD | 默认(0) | 默认(companyId) | 默认 (false) |
| 首个参数的属性 func(TbBO bo) bo.companyIds |
COMPANIES | OBJECT_FIELD | 默认(0) | companyIds | 默认 (false) |
| 第二个参数的属性 func(TaBO abo, TbBO bbo) bbo.companyId |
默认(COMPANY) | OBJECT_FIELD | 1 | 默认(companyId) | 默认 (false) |
| 首个集合参数的属性 func(List abo.companyId |
COMPANIES | COLLECTION_FIELD | 默认(0) | 默认(companyId) | 默认 (false) |
| 首个参数属性的属性 func(TaBO abo) abo.companyInfo.companyId |
默认(COMPANY) | OBJECT_SUB_FIELD | 默认(0) | companyInfo.companyId | 默认 (false) |
| 首个参数的属性是一个集合，这个集合元素的属性 func(TaBO abo) abo.companyInfoList companyInfo.companyId |
COMPANIES | OBJECT_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
- 编写注解处理器代码，对注解的配置值进行校验
/*** UserPermission注解处理器，在编译期校验注解是否配置正确** 如果和业务代码在同一模块，需要做很多额外的编译配置，或引入二方包并配置。简单起见单独抽一个模块**/
@SupportedAnnotationTypes("com.yourcompany.xxproject.annotation.UserPermission")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class UserPermissionProcessor extends AbstractProcessor {@Overridepublic 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;}
}
- 在切面所在的module的src/main/resources/META-INF/services路径下，增加一个文件
javax.annotation.processing.Processor，内容注解处理器的完整类路径：
com.yourcompany.xxproject.annotation.processor.UserPermissionProcessor
如图
验证，写一段违反规则的代码，IDE build时提示：
继续迭代...
-
COMPANY和COMPANIES拼写接近，如果用代码自动补全，有可能写错。你可以将后者字面值改为MULTI_COMPANIES。
-
可以将对象鉴权和角色鉴权结合起来，判断用户是否有某个角色的权限，也即在水平鉴权的基础上增加垂直鉴权。当然你也可以用另一个注解来完成。
-
如果这个注解足够通用，你可以将它们（包括UserPermissionManger）打成一个二方包，供其他应用使用。这时你需要研究下如何封装远程调用相关的代码，这和你所用的微服务框架有关。实际上，我前司的鉴权平台就有这样一个鉴权二方包。当你把它打成了二方包，就意味着使用者会日趋变多，调用量也会随着业务不断增长，不同的应用可能使用了这个包的不同版本，一定要在早期开始优化性能！