优化说明

Author: zhou-hao

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/FieldDataAccess.java

@@ -4,10 +4,14 @@
 
 import java.lang.annotation.*;
 
+/**
+ * @deprecated 已弃用
+ */
 @DataAccessType(id = "FIELD_DENY", name = "字段权限")
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
+@Deprecated
 public @interface FieldDataAccess {
 
     @AliasFor(annotation = DataAccessType.class)

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/Resource.java

@@ -1,28 +1,101 @@
 package org.hswebframework.web.authorization.annotation;
 
 
+import org.hswebframework.web.authorization.Permission;
 import org.hswebframework.web.authorization.define.Phased;
 
 import java.lang.annotation.*;
 
+/**
+ * 接口资源声明注解,声明Controller的资源相关信息,用于进行权限控制。
+ * <br>
+ * 在Controller进行注解,表示此接口需要有对应的权限{@link Permission#getId()}才能进行访问.
+ * 具体的操作权限控制,需要在方法上注解{@link ResourceAction}.
+ * <br>
+ *
+ *
+ * <pre>{@code
+ * @RestController
+ * //声明资源
+ * @Resource(id = "test", name = "测试功能")
+ * public class TestController implements ReactiveCrudController<TestEntity, String> {
+ *
+ *     //声明操作,需要有 test:query 权限才能访问此接口
+ *     @QueryAction
+ *     public Mono<User> getUser() {
+ *         return Authentication.currentReactive()
+ *                 .switchIfEmpty(Mono.error(new UnAuthorizedException()))
+ *                 .map(Authentication::getUser);
+ *     }
+ *
+ * }
+ * }
+ * </pre>
+ * 如果接口不需要进行权限控制,可注解{@link Authorize#ignore()}来标识此接口不需要权限控制.
+ * 或者通过监听 {@link org.hswebframework.web.authorization.events.AuthorizingHandleBeforeEvent}来进行自定义处理
+ * <pre>{@code
+ *   @EventListener
+ *   public void handleAuthEvent(AuthorizingHandleBeforeEvent e) {
+ *      //admin用户可以访问全部操作
+ *      if ("admin".equals(e.getContext().getAuthentication().getUser().getUsername())) {
+ *         e.setAllow(true);
+ *       }
+ *    }
+ * }</pre>
+ *
+ * @author zhouhao
+ * @see ResourceAction
+ * @see Authorize
+ * @see org.hswebframework.web.authorization.events.AuthorizingHandleBeforeEvent
+ * @since 4.0
+ */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
 public @interface Resource {
+
+    /**
+     * 资源ID
+     *
+     * @return 资源ID
+     */
     String id();
 
+    /**
+     * @return 资源名称
+     */
     String name();
 
+    /**
+     * @return 资源操作定义
+     */
     ResourceAction[] actions() default {};
 
+    /**
+     * @return 多个操作控制逻辑
+     */
     Logical logical() default Logical.DEFAULT;
 
+    /**
+     * @return 权限控制阶段
+     */
     Phased phased() default Phased.before;
 
+    /**
+     * @return 资源描述
+     */
     String[] description() default {};
 
+    /**
+     * @return 资源分组
+     */
     String[] group() default {};
 
+    /**
+     * 如果在方法上设置此属性，表示是否合并类上注解的属性
+     *
+     * @return 是否合并
+     */
     boolean merge() default true;
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/ResourceAction.java

@@ -1,24 +1,65 @@
 package org.hswebframework.web.authorization.annotation;
 
-import org.hswebframework.web.authorization.define.Phased;
+
+import org.hswebframework.web.authorization.Permission;
 
 import java.lang.annotation.*;
 
 /**
+ * 对资源操作的描述,通常用来进行权限控制.
+ * <p>
+ * 在Controller方法上添加此注解,来声明根据权限操作{@link Permission#getActions()}进行权限控制.
+ * <p>
+ * 可以使用注解继承的方式来统一定义操作:
+ * <pre>{@code
+ * @Target(ElementType.METHOD)
+ * @Retention(RetentionPolicy.RUNTIME)
+ * @Inherited
+ * @Documented
+ * @ResourceAction(id = "create", name = "新增")
+ * public @interface CreateAction {
+ *
+ * }
+ * }
+ * </pre>
+ *
  * @see CreateAction
+ * @see DeleteAction
+ * @see SaveAction
+ * @see org.hswebframework.web.authorization.Authentication
+ * @see Permission#getActions()
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
 public @interface ResourceAction {
+    /**
+     * 操作标识
+     *
+     * @return 操作标识
+     * @see Permission#getActions()
+     */
     String id();
 
+    /**
+     * @return 操作名称
+     */
     String name();
 
+    /**
+     * @return 操作说明
+     */
     String[] description() default {};
 
+    /**
+     * @return 多个操作时的判断逻辑
+     */
     Logical logical() default Logical.DEFAULT;
 
+    /**
+     * @deprecated 已弃用, 4.1中移除
+     */
+    @Deprecated
     DataAccess[] dataAccess() default @DataAccess(ignore = true);
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/SaveAction.java

@@ -5,13 +5,20 @@
 
 import java.lang.annotation.*;
 
+/**
+ * 继承{@link ResourceAction},提供统一的id定义
+ *
+ * @author zhouhao
+ * @since 4.0
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
 @ResourceAction(id = Permission.ACTION_SAVE, name = "保存")
 public @interface SaveAction {
 
-    @AliasFor(annotation = ResourceAction.class,attribute = "dataAccess")
+    @Deprecated
+    @AliasFor(annotation = ResourceAction.class, attribute = "dataAccess")
     DataAccess dataAccess() default @DataAccess(ignore = true);
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/annotation/UserOwnData.java

@@ -4,12 +4,15 @@
 
 /**
  * 声明某个操作支持用户查看自己的数据
+ *
+ * @deprecated 已弃用
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
 @DataAccessType(id = "user_own_data", name = "用户自己的数据")
+@Deprecated
 public @interface UserOwnData {
 
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/events/AuthorizingHandleBeforeEvent.java

@@ -4,6 +4,22 @@
 import org.hswebframework.web.authorization.define.HandleType;
 import org.springframework.context.ApplicationEvent;
 
+/**
+ * 权限控制事件,在进行权限控制之前会推送此事件，用于自定义权限控制结果:
+ * <pre>{@code
+ *   @EventListener
+ *   public void handleAuthEvent(AuthorizingHandleBeforeEvent e) {
+ *      //admin用户可以访问全部操作
+ *      if ("admin".equals(e.getContext().getAuthentication().getUser().getUsername())) {
+ *         e.setAllow(true);
+ *       }
+ *    }
+ * }</pre>
+ *
+ * @author zhouhao
+ * @since 4.0
+ */
+// TODO: 2021/12/21 Reactive支持
 public class AuthorizingHandleBeforeEvent extends ApplicationEvent implements AuthorizationEvent {
 
     private static final long serialVersionUID = -1095765748533721998L;
@@ -14,7 +30,7 @@ public class AuthorizingHandleBeforeEvent extends ApplicationEvent implements Au
 
     private String message;
 
-    private HandleType handleType;
+    private final HandleType handleType;
 
     public AuthorizingHandleBeforeEvent(AuthorizingContext context, HandleType handleType) {
         super(context);
@@ -33,6 +49,11 @@ public boolean isAllow() {
         return allow;
     }
 
+    /**
+     * 设置通过当前请求
+     *
+     * @param allow allow
+     */
     public void setAllow(boolean allow) {
         execute = false;
         this.allow = allow;
@@ -42,11 +63,18 @@ public String getMessage() {
         return message;
     }
 
+    /**
+     * 设置错误提示消息
+     *
+     * @param message 消息
+     */
     public void setMessage(String message) {
         this.message = message;
     }
 
-
+    /**
+     * @return 权限控制类型
+     */
     public HandleType getHandleType() {
         return handleType;
     }

hsweb-commons/hsweb-commons-api/src/main/java/org/hswebframework/web/api/crud/entity/Entity.java

@@ -32,18 +32,48 @@
  */
 public interface Entity extends Serializable {
 
+    /**
+     * 使用jsr303对当前实体类进行验证，如果未通过验证则会抛出{@link org.hswebframework.web.exception.ValidationException}异常
+     *
+     * @param groups 分组
+     * @see org.hswebframework.web.exception.ValidationException
+     */
     default void tryValidate(Class<?>... groups) {
         ValidatorUtils.tryValidate(this, groups);
     }
 
+    /**
+     * 将当前实体类复制到指定其他类型中,类型将会被自动实例化,在类型明确时,建议使用{@link Entity#copyFrom(Object, String...)}.
+     *
+     * @param target           目标类型
+     * @param ignoreProperties 忽略复制的属性
+     * @param <T>类型
+     * @return 复制结果
+     */
     default <T> T copyTo(Class<T> target, String... ignoreProperties) {
         return FastBeanCopier.copy(this, target, ignoreProperties);
     }
 
+    /**
+     * 将当前实体类复制到其他对象中
+     *
+     * @param target           目标实体
+     * @param ignoreProperties 忽略复制的属性
+     * @param <T>类型
+     * @return 复制结果
+     */
     default <T> T copyTo(T target, String... ignoreProperties) {
         return FastBeanCopier.copy(this, target, ignoreProperties);
     }
 
+    /**
+     * 从其他对象复制属性到当前对象
+     *
+     * @param target           其他对象
+     * @param ignoreProperties 忽略复制的属性
+     * @param <T>              类型
+     * @return 当前对象
+     */
     @SuppressWarnings("all")
     default <T> T copyFrom(Object target, String... ignoreProperties) {
         return (T) FastBeanCopier.copy(target, this, ignoreProperties);

hsweb-commons/hsweb-commons-api/src/main/java/org/hswebframework/web/api/crud/entity/PagerResult.java

@@ -28,15 +28,42 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * 分页查询结果,用于在分页查询时,定义查询结果.如果需要拓展此类,例如自定义json序列化,请使用spi方式定义拓展实现类型:
+ * <pre>
+ * ---resources
+ * -----|--META-INF
+ * -----|----services
+ * -----|------org.hswebframework.web.api.crud.entity.PagerResult
+ * </pre>
+ *
+ * @param <E> 结果类型
+ * @author zhouhao
+ * @since 4.0.0
+ */
 @Getter
 @Setter
 public class PagerResult<E> {
     private static final long serialVersionUID = -6171751136953308027L;
 
+    /**
+     * 创建一个空结果
+     *
+     * @param <E> 结果类型
+     * @return PagerResult
+     */
     public static <E> PagerResult<E> empty() {
         return of(0, new ArrayList<>());
     }
 
+    /**
+     * 创建一个分页结果
+     *
+     * @param total 总数据量
+     * @param list  当前页数据列表
+     * @param <E>   结果类型
+     * @return PagerResult
+     */
     @SuppressWarnings("all")
     public static <E> PagerResult<E> of(int total, List<E> list) {
         PagerResult<E> result;
@@ -46,6 +73,15 @@ public static <E> PagerResult<E> of(int total, List<E> list) {
         return result;
     }
 
+    /**
+     * 创建一个分页结果,并将查询参数中的分页索引等信息填充到分页结果中
+     *
+     * @param total  总数据量
+     * @param list   当前页数据列表
+     * @param entity 查询参数
+     * @param <E>    结果类型
+     * @return PagerResult
+     */
     public static <E> PagerResult<E> of(int total, List<E> list, QueryParam entity) {
         PagerResult<E> pagerResult = of(total, list);
         pagerResult.setPageIndex(entity.getThinkPageIndex());