完善部分注释

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

@@ -1,14 +1,37 @@
+/*
+ *  Copyright 2016 http://www.hswebframework.org
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *
+ */
+
 package org.hswebframework.web.authorization;
 
 /**
- * TODO 完成注释
+ * 权限获取器,用于静态方式获取当前登录用户的权限信息
  *
  * @author zhouhao
+ * @see AuthorizationSupplier
+ * @since 3.0
  */
 public final class AuthorizationHolder {
     private static AuthorizationSupplier supplier;
 
     public static Authorization get() {
+        if (null == supplier) {
+            throw new UnsupportedOperationException("AuthorizationSupplier is null!");
+        }
         return supplier.get();
     }
 

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

@@ -20,9 +20,10 @@ package org.hswebframework.web.authorization;
 import java.util.function.Supplier;
 
 /**
- * TODO 完成注释
- *
  * @author zhouhao
+ * @see Supplier
+ * @see Authorization
+ * @see AuthorizationHolder
  */
 public interface AuthorizationSupplier extends Supplier<Authorization> {
 }

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

@@ -20,12 +20,20 @@ package org.hswebframework.web.authorization;
 import java.io.Serializable;
 
 /**
- * TODO 完成注释
+ * 角色信息
  *
  * @author zhouhao
  */
 public interface Role extends Serializable {
+
+    /**
+     * @return 角色ID
+     */
     String getId();
 
+    /**
+     *
+     * @return 角色名
+     */
     String getName();
 }

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

@@ -20,14 +20,24 @@ package org.hswebframework.web.authorization;
 import java.io.Serializable;
 
 /**
- * TODO 完成注释
+ * 用户信息
  *
  * @author zhouhao
+ * @since 3.0
  */
 public interface User extends Serializable {
+    /**
+     * @return 用户ID
+     */
     String getId();
 
+    /**
+     * @return 用户名
+     */
     String getUsername();
 
+    /**
+     * @return 姓名
+     */
     String getName();
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/CustomDataAccess.java

@@ -1,11 +1,13 @@
 package org.hswebframework.web.authorization.access;
 
 /**
- * TODO 完成注释
- *
  * @author zhouhao
  * @see DataAccess.Type#CUSTOM
  */
 public interface CustomDataAccess extends DataAccess {
     DataAccessController getController();
+
+    default String getType() {
+        return Type.CUSTOM.name();
+    }
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccess.java

@@ -1,3 +1,21 @@
+/*
+ *  Copyright 2016 http://www.hswebframework.org
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *
+ */
+
 package org.hswebframework.web.authorization.access;
 
 
@@ -6,7 +24,8 @@ import org.hswebframework.web.authorization.Permission;
 import java.io.Serializable;
 
 /**
- * 数据级的权限控制
+ * 数据级的权限控制,此接口为控制方式配置
+ * 具体的控制逻辑由控制器{@link DataAccessController}实现
  *
  * @author zhouhao
  * @see org.hswebframework.web.authorization.access.CustomDataAccess
@@ -27,6 +46,17 @@ public interface DataAccess extends Serializable {
      */
     String getAction();
 
+    /**
+     * 控制方式标识
+     *
+     * @return 控制方式
+     * @see Type#name()
+     */
+    String getType();
+
+    /**
+     * 内置3中控制方式
+     */
     enum Type {
         OWN_CREATED("自己创建的数据"),
         SCRIPT("脚本"),

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessController.java

@@ -1,10 +1,18 @@
 package org.hswebframework.web.authorization.access;
 
 /**
- * TODO 完成注释
+ * 数据级别权限控制器,通过此控制器对当前登录用户进行的操作进行数据级别的权限控制。
+ * 如：A用户只能查询自己创建的B数据,A用户只能修改自己创建的B数据
  *
  * @author zhouhao
+ * @see 3.0
  */
 public interface DataAccessController {
+    /**
+     * 执行权限控制
+     * @param access 控制方式以及配置
+     * @param params 当前操作的方法的参数上下文
+     * @return
+     */
     boolean doAccess(DataAccess access, ParamContext params);
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/DataAccessHandler.java

@@ -1,13 +1,26 @@
 package org.hswebframework.web.authorization.access;
 
 /**
- * TODO 完成注释
+ * 数据级别权限控制处理器接口,负责处理支持的权限控制配置
  *
  * @author zhouhao
  */
 public interface DataAccessHandler {
 
+    /**
+     * 是否支持处理此配置
+     *
+     * @param access 控制配置
+     * @return 是否支持
+     */
     boolean isSupport(DataAccess access);
 
-    boolean doAccess(DataAccess access, ParamContext context);
+    /**
+     * 执行处理,返回处理结果
+     *
+     * @param access  控制配置
+     * @param context 参数上下文
+     * @return 处理结果
+     */
+    boolean handle(DataAccess access, ParamContext context);
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/OwnCreatedDataAccess.java

@@ -6,4 +6,7 @@ package org.hswebframework.web.authorization.access;
  * @author zhouhao
  */
 public interface OwnCreatedDataAccess extends DataAccess {
+    default String getType() {
+        return Type.OWN_CREATED.name();
+    }
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/ParamContext.java

@@ -2,21 +2,57 @@ package org.hswebframework.web.authorization.access;
 
 import java.io.Serializable;
 import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
 import java.util.Map;
 import java.util.Optional;
 
 /**
- * TODO 完成注释
+ * 参数上下文，用于获取当前进行操作的方法的各种参数信息，如:当前所在类实例，参数集合，注解
  *
  * @author zhouhao
+ * @see 3.0
  */
 public interface ParamContext extends Serializable {
 
+    /**
+     * 获取当前类实例
+     *
+     * @return 类实例对象
+     */
     Object getTarget();
 
+    /**
+     * 当前操作的方法
+     *
+     * @return 方法实例
+     */
+    Method getMethod();
+
+    /**
+     * 根据参数名获取参数值,此参数为方法的参数,而非http参数 <br/>
+     * 如：当前被操作的方法为 query(QueryParam param); 调用getParameter("param"); 则返回QueryParam实例<br/>
+     * 注意:返回值为Optional对象,使用方法见{@link Optional}<br/>
+     *
+     * @param name 参数名称
+     * @param <T>  参数泛型
+     * @return Optional
+     */
     <T> Optional<T> getParameter(String name);
 
-    <T extends Annotation> T getAnnotation();
+    /**
+     * 获取当前操作方法或实例上指定类型的泛型,如果方法上未获取到,则获取实例类上的注解。实例类上未获取到,则返回null
+     *
+     * @param type 注解的类型
+     * @param <T>  注解泛型
+     * @return 注解
+     */
+    <T extends Annotation> T getAnnotation(Class<T> type);
 
+    /**
+     * 获取全部参数
+     *
+     * @return 参数集合
+     * @see this#getParameter(String)
+     */
     Map<String, Object> getParams();
 }

hsweb-authorization/hsweb-authorization-api/src/main/java/org/hswebframework/web/authorization/access/ScriptDataAccess.java

@@ -6,6 +6,9 @@ package org.hswebframework.web.authorization.access;
  * @author zhouhao
  */
 public interface ScriptDataAccess extends DataAccess {
+    default String getType() {
+        return Type.CUSTOM.name();
+    }
 
     /**
      * 脚本语言: javascript(js),groovy

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/DataAccessAnnotationMethodInterceptor.java

@@ -22,6 +22,7 @@ import org.apache.shiro.authz.aop.AuthorizingAnnotationHandler;
 import org.apache.shiro.authz.aop.AuthorizingAnnotationMethodInterceptor;
 import org.hsweb.expands.script.engine.DynamicScriptEngine;
 import org.hsweb.expands.script.engine.DynamicScriptEngineFactory;
+import org.hswebframework.web.ApplicationContextHolder;
 import org.hswebframework.web.BusinessException;
 import org.hswebframework.web.authorization.Authorization;
 import org.hswebframework.web.authorization.AuthorizationHolder;
@@ -45,9 +46,14 @@ import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
 /**
- * TODO 完成注释
+ * 数据级权限控制实现 <br/>
+ * 通过在方法上注解{@link RequiresDataAccess}，标识需要进行数据级权限控制<br/>
+ * 控制的方式和规则由 {@link Permission#getDataAccesses()}实现<br/>
  *
  * @author zhouhao
+ * @see DefaultDataAccessController
+ * @see DataAccessAnnotationHandler#assertAuthorized(Annotation)
+ * @see 3.0
  */
 public class DataAccessAnnotationMethodInterceptor extends AuthorizingAnnotationMethodInterceptor {
 
@@ -75,8 +81,14 @@ public class DataAccessAnnotationMethodInterceptor extends AuthorizingAnnotation
                 logger.warn("MethodInterceptorHolder is null!");
                 return;
             }
+            //无权限信息
+            Authorization authorization = AuthorizationHolder.get();
+            if (authorization == null) {
+                throw new AuthorizationException("{no_authorization}");
+            }
             RequiresDataAccess accessAnn = ((RequiresDataAccess) a);
             DataAccessController accessController = dataAccessController;
+            //在注解上自定义的权限控制器
             if (DataAccessController.class != accessAnn.controllerClass()) {
                 if (null == (accessController = cache.get(accessAnn.controllerClass()))) {
                     synchronized (cache) {
@@ -89,30 +101,29 @@ public class DataAccessAnnotationMethodInterceptor extends AuthorizingAnnotation
                             }
                     }
                 }
-            } else if (StringUtils.isNullOrEmpty(accessAnn.controllerBeanName())) {
-                // TODO: 17-2-8  get controller from spring context
+            } else if (!StringUtils.isNullOrEmpty(accessAnn.controllerBeanName())) {
+                //获取spring上下文中的控制器
+                accessController = ApplicationContextHolder.get().getBean(accessAnn.controllerBeanName(), DataAccessController.class);
             }
             DataAccessController finalAccessController = accessController;
 
-            ParamContext context = holder.createParamContext(accessAnn);
-            Authorization authorization = AuthorizationHolder.get();
-            if (authorization == null) {
-                throw new AuthorizationException("{no_authorization}");
-            }
+            ParamContext context = holder.createParamContext();
             String permission = accessAnn.permission();
             Permission permissionInfo = authorization.getPermission(permission);
             List<String> actionList = Arrays.asList(accessAnn.action());
-
+            //取得当前登录用户持有的控制规则
             Set<DataAccess> accesses = permissionInfo
                     .getDataAccesses()
                     .stream()
                     .filter(access -> actionList.contains(access.getAction()))
                     .collect(Collectors.toSet());
+            //无规则,则代表不进行控制
             if (accesses.isEmpty()) return;
+            //单个规则验证函数
             Function<Predicate<DataAccess>, Boolean> function =
-                    (accessAnn.logical() == Logical.AND) ?
+                    accessAnn.logical() == Logical.AND ?
                             accesses.stream()::allMatch : accesses.stream()::anyMatch;
-
+            //调用控制器进行验证
             boolean isAccess = function.apply(access -> finalAccessController.doAccess(access, context));
             if (!isAccess) {
                 throw new AuthorizationException("{access_deny}");

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/DefaultDataAccessController.java

@@ -39,7 +39,7 @@ public final class DefaultDataAccessController implements DataAccessController {
         if (parent != null) parent.doAccess(access, params);
         return handlers.parallelStream()
                 .filter(handler -> handler.isSupport(access))
-                .anyMatch(handler -> handler.doAccess(access, params));
+                .anyMatch(handler -> handler.handle(access, params));
     }
 
     public DefaultDataAccessController addHandler(DataAccessHandler handler) {

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/FieldAccessAnnotationMethodInterceptor.java

@@ -65,7 +65,7 @@ public class FieldAccessAnnotationMethodInterceptor extends AuthorizingAnnotatio
                 return;
             }
             RequiresFieldAccess accessAnn = ((RequiresFieldAccess) a);
-            ParamContext context = holder.createParamContext(accessAnn);
+            ParamContext context = holder.createParamContext();
             Authorization authorization = AuthorizationHolder.get();
             if (authorization == null) {
                 throw new AuthorizationException("{no_authorization}");

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/MethodInterceptorHolder.java

@@ -20,6 +20,7 @@ package org.hswebframework.web.authorization.shiro.boost;
 import org.apache.shiro.util.Assert;
 import org.hswebframework.web.ThreadLocalUtils;
 import org.hswebframework.web.authorization.access.ParamContext;
+import org.hswebframwork.utils.ClassUtils;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
@@ -84,13 +85,18 @@ public class MethodInterceptorHolder {
         return args;
     }
 
-    public ParamContext createParamContext(final Annotation annotation) {
+    public ParamContext createParamContext() {
         return new ParamContext() {
             @Override
             public Object getTarget() {
                 return target;
             }
 
+            @Override
+            public Method getMethod() {
+                return method;
+            }
+
             @Override
             public <T> Optional<T> getParameter(String name) {
                 if (args == null) return Optional.empty();
@@ -98,8 +104,11 @@ public class MethodInterceptorHolder {
             }
 
             @Override
-            public <T extends Annotation> T getAnnotation() {
-                return (T) annotation;
+            public <T extends Annotation> T getAnnotation(Class<T> type) {
+                T ann = ClassUtils.getAnnotation(method, type);
+                if (ann == null)
+                    ann = ClassUtils.getAnnotation(target.getClass(), type);
+                return ann;
             }
 
             @Override

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/handler/CustomDataAccessHandler.java

@@ -1,20 +1,40 @@
+/*
+ *  Copyright 2016 http://www.hswebframework.org
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *
+ */
+
 package org.hswebframework.web.authorization.shiro.boost.handler;
 
 import org.hswebframework.web.authorization.access.*;
 
 /**
- * TODO 完成注释
+ * 当配置为自定义处理器时(实现{@link CustomDataAccess }接口),此处理器生效
  *
  * @author zhouhao
+ * @see 3.0
  */
 public class CustomDataAccessHandler implements DataAccessHandler {
+
     @Override
     public boolean isSupport(DataAccess access) {
         return access instanceof CustomDataAccess;
     }
 
     @Override
-    public boolean doAccess(DataAccess access, ParamContext context) {
+    public boolean handle(DataAccess access, ParamContext context) {
         CustomDataAccess custom = ((CustomDataAccess) access);
         return custom.getController().doAccess(access, context);
     }

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/handler/OwnCreatedDataAccessHandler.java

@@ -11,7 +11,6 @@ import org.hswebframework.web.authorization.annotation.RequiresDataAccess;
 import org.hswebframework.web.commons.entity.Entity;
 import org.hswebframework.web.commons.entity.RecordCreationEntity;
 import org.hswebframework.web.commons.entity.param.QueryParamEntity;
-import org.hswebframework.web.controller.HswebController;
 import org.hswebframework.web.controller.QueryController;
 import org.hswebframework.web.service.QueryService;
 import org.hswebframwork.utils.ClassUtils;
@@ -35,7 +34,7 @@ public class OwnCreatedDataAccessHandler implements DataAccessHandler {
     }
 
     @Override
-    public boolean doAccess(DataAccess access, ParamContext context) {
+    public boolean handle(DataAccess access, ParamContext context) {
         OwnCreatedDataAccess own = ((OwnCreatedDataAccess) access);
         Object controller = context.getTarget();
         if (controller != null) {
@@ -75,7 +74,7 @@ public class OwnCreatedDataAccessHandler implements DataAccessHandler {
     @SuppressWarnings("unchecked")
     protected boolean doRWAccess(OwnCreatedDataAccess access, ParamContext context, Object controller) {
         //获取注解
-        RequiresDataAccess dataAccess = context.getAnnotation();
+        RequiresDataAccess dataAccess = context.getAnnotation(RequiresDataAccess.class);
         Object id = context.<String>getParameter(dataAccess.idParamName()).orElse(null);
         //通过QueryController获取QueryService
         //然后调用selectByPk 查询旧的数据,进行对比

hsweb-authorization/hsweb-authorization-shiro/src/main/java/org/hswebframework/web/authorization/shiro/boost/handler/ScriptDataAccessHandler.java

@@ -20,7 +20,7 @@ public class ScriptDataAccessHandler implements DataAccessHandler {
     }
 
     @Override
-    public boolean doAccess(DataAccess access, ParamContext context) {
+    public boolean handle(DataAccess access, ParamContext context) {
         ScriptDataAccess dataAccess = ((ScriptDataAccess) access);
         DynamicScriptEngine engine = DynamicScriptEngineFactory.getEngine(dataAccess.getScriptLanguage());
         if (engine == null) throw new UnsupportedOperationException(dataAccess.getScriptLanguage() + " {not_support}");

hsweb-commons/hsweb-commons-controller/pom.xml

@@ -53,9 +53,15 @@
             <artifactId>hsweb-authorization-api</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.hswebframework.web</groupId>
+            <artifactId>hsweb-authorization-shiro</artifactId>
+            <version>${project.version}</version>
+        </dependency>
         <dependency>
             <groupId>org.springframework</groupId>
             <artifactId>spring-webmvc</artifactId>
         </dependency>
+
     </dependencies>
 </project>

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/CreateController.java

@@ -29,11 +29,18 @@ import org.springframework.web.bind.annotation.ResponseStatus;
 import static org.hswebframework.web.controller.message.ResponseMessage.ok;
 
 /**
- * TODO 完成注释
+ * 通用新增控制器<br>
+ * 使用:实现该接口,注解@RestController 以及@RequestMapping("/myController")
+ * 客户端调用: 通过POST请求,contentType为application/json 。参数为E泛型的json格式
+ * <code>
+ * curl -l -H "Content-type: application/json" -X POST -d '{"field1":"value1","field2":"value2"}'
+ * http://domain/contextPath/myController
+ * </code>
  *
  * @author zhouhao
+ * @since 3.0
  */
-public interface CreateController<E, PK> extends HswebController {
+public interface CreateController<E, PK>  {
 
     InsertService<E, PK> getService();
 

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/CrudController.java

@@ -22,9 +22,15 @@ import org.hswebframework.web.commons.entity.Entity;
 import org.hswebframework.web.service.CrudService;
 
 /**
- * TODO 完成注释
+ * 通用增删改查控制器
  *
  * @author zhouhao
+ * @see QueryController
+ * @see CreateController
+ * @see UpdateController
+ * @see DeleteController
+ * @see CrudService
+ * @since 3.0
  */
 public interface CrudController<E, PK, Q extends Entity>
         extends QueryController<E, PK, Q>, UpdateController<E, PK>, CreateController<E, PK>, DeleteController<PK> {

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/DeleteController.java

@@ -27,11 +27,11 @@ import org.springframework.web.bind.annotation.PathVariable;
 import static org.hswebframework.web.controller.message.ResponseMessage.ok;
 
 /**
- * TODO 完成注释
+ * 通用删除控制器
  *
  * @author zhouhao
  */
-public interface DeleteController<PK> extends HswebController {
+public interface DeleteController<PK> {
 
     DeleteService<PK> getService();
 

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/GenericEntityController.java

@@ -28,9 +28,12 @@ import org.springframework.web.bind.annotation.RequestBody;
 import static org.hswebframework.web.controller.message.ResponseMessage.ok;
 
 /**
- * TODO 完成注释
+ * 通用实体的增删改查控制器
  *
  * @author zhouhao
+ * @see GenericEntity
+ * @see CrudController
+ * @see CrudService
  */
 public interface GenericEntityController<E extends GenericEntity<PK>, PK, Q extends Entity>
         extends CrudController<E, PK, Q> {
@@ -39,6 +42,7 @@ public interface GenericEntityController<E extends GenericEntity<PK>, PK, Q exte
 
     @Override
     default ResponseMessage updateByPrimaryKey(@PathVariable PK id, @RequestBody E data) {
+        // 设置id属性
         data.setId(id);
         return ok(getService().updateByPk(data));
     }

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/UpdateEntityController.java

@@ -27,11 +27,13 @@ import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 
 /**
- * TODO 完成注释
+ * 通用实体更新控制器
  *
  * @author zhouhao
+ * @see UpdateService
+ * @since 3.0
  */
-public interface UpdateEntityController<E extends GenericEntity<PK>, PK> extends UpdateController<E, PK> {
+public interface GenericEntityUpdateController<E extends GenericEntity<PK>, PK> extends UpdateController<E, PK> {
 
     UpdateService<E> getService();
 

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/HswebController.java

@@ -1,9 +0,0 @@
-package org.hswebframework.web.controller;
-
-/**
- * TODO 完成注释
- *
- * @author zhouhao
- */
-public interface HswebController {
-}

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/QueryController.java

@@ -19,6 +19,7 @@ package org.hswebframework.web.controller;
 
 import org.hswebframework.web.authorization.annotation.Authorize;
 import org.hswebframework.web.commons.entity.Entity;
+import org.hswebframework.web.commons.entity.param.QueryParamEntity;
 import org.hswebframework.web.controller.message.ResponseMessage;
 import org.hswebframework.web.logging.AccessLogger;
 import org.hswebframework.web.service.QueryByEntityService;
@@ -29,17 +30,38 @@ import org.springframework.web.bind.annotation.PathVariable;
 import static org.hswebframework.web.controller.message.ResponseMessage.ok;
 
 /**
- * TODO 完成注释
+ * 通用查询控制器。
  *
+ * @param <E>  实体类型
+ * @param <PK> 主键类型
+ * @param <Q>  查询条件实体类型,默认提供{@link QueryParamEntity}实现
  * @author zhouhao
+ * @see QueryParamEntity
+ * @see 3.0
  */
-public interface QueryController<E, PK, Q extends Entity> extends HswebController {
+public interface QueryController<E, PK, Q extends Entity>  {
 
+    /**
+     * 获取实现了{@link QueryByEntityService}和{@link QueryService}的服务类
+     *
+     * @param <T> 服务类泛型
+     * @return 服务类实例
+     */
     <T extends QueryByEntityService<E> & QueryService<E, PK>> T getService();
 
+    /**
+     * 根据参数动态查询。<br>
+     * 参数泛型如果为QueryParamEntity,
+     * 客户的参数 ?terms[0].column=name&terms[0].value=小明
+     * 则执行查询条件 where name = '小明'
+     * 具体使用方法参照 {@link QueryParamEntity}
+     *
+     * @param param 参数
+     * @return 查询结果
+     */
     @Authorize(action = "read")
     @GetMapping
-    @AccessLogger("查询")
+    @AccessLogger("根据条件查询")
     default ResponseMessage list(Q param) {
         return ok(getService().selectPager(param));
     }

hsweb-commons/hsweb-commons-controller/src/main/java/org/hswebframework/web/controller/UpdateController.java

@@ -25,11 +25,11 @@ import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 
 /**
- * TODO 完成注释
+ * 通用更新控制器
  *
  * @author zhouhao
  */
-public interface UpdateController<E, PK> extends HswebController {
+public interface UpdateController<E, PK> {
     @Authorize(action = "update")
     @PutMapping(path = "/{id}")
     @AccessLogger("根据主键修改数据")

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

@@ -21,9 +21,14 @@ package org.hswebframework.web.commons.entity;
 import java.io.Serializable;
 
 /**
- * TODO 完成注释
+ * 实体总接口,所有实体需实现此接口
  *
  * @author zhouhao
+ * @see org.hswebframework.web.commons.entity.factory.EntityFactory
+ * @see GenericEntity
+ * @see TreeSupportEntity
+ * @see TreeSortSupportEntity
+ * @since 3.0
  */
-public interface Entity extends Serializable{
+public interface Entity extends Serializable {
 }

hsweb-commons/hsweb-commons-entity/src/main/java/org/hswebframework/web/commons/entity/GenericEntity.java

@@ -22,6 +22,8 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
+ * 通用实体,提供实体常用属性
+ *
  * @author zhouhao
  * @since 3.0
  */

hsweb-commons/hsweb-commons-service/hsweb-commons-service-api/src/main/java/org/hswebframework/web/service/QueryByEntityService.java

@@ -23,12 +23,45 @@ import org.hswebframework.web.commons.entity.PagerResult;
 
 import java.util.List;
 
+/**
+ * 根据实体类参数执行各种查询的通用服务类
+ *
+ * @param <E> 实体类型
+ * @author zhouhao
+ * @see org.hswebframework.web.commons.entity.param.QueryParamEntity
+ * @since 3.0
+ */
 public interface QueryByEntityService<E> extends Service {
+
+    /**
+     * 按分页查询
+     *
+     * @param param 参数
+     * @return 分页查询结果
+     */
     PagerResult<E> selectPager(Entity param);
 
+    /**
+     * 不分页查询
+     *
+     * @param param 查询参数
+     * @return 查询结果
+     */
     List<E> select(Entity param);
 
+    /**
+     * 查询总数
+     *
+     * @param param 查询参数
+     * @return 总数
+     */
     int count(Entity param);
 
+    /**
+     * 查询单条数据,如果存在多条数据,则返回第一条
+     *
+     * @param param 查询参数
+     * @return 查询结果
+     */
     E selectSingle(Entity param);
 }

hsweb-commons/hsweb-commons-service/hsweb-commons-service-simple/src/main/java/org/hswebframework/web/service/DefaultQueryByEntityService.java

@@ -34,6 +34,13 @@ public interface DefaultQueryByEntityService<E>
 
     QueryByBeanDao<E> getDao();
 
+    /**
+     * 分页进行查询数据，查询条件同 {@link DefaultQueryByEntityService#select}
+     *
+     * @param param 查询参数
+     * @return 分页结果
+     * @ 查询异常
+     */
     @Override
     default PagerResult<E> selectPager(Entity param) {
         PagerResult<E> pagerResult = new PagerResult<>();
@@ -50,20 +57,12 @@ public interface DefaultQueryByEntityService<E>
         return pagerResult;
     }
 
-    /**
-     * 分页进行查询数据，查询条件同 {@link DefaultQueryByEntityService#select}
-     *
-     * @param param 查询参数
-     * @return 分页结果
-     * @ 查询异常
-     */
-
     /**
      * 根据查询参数进行查询，参数可使用 {@link Query}进行构建
      *
      * @param param 查询参数
      * @return 查询结果
-     * @see QueryParam
+     * @see QueryParamEntity
      */
     @Override
     @Transactional(readOnly = true)