Skip to content

Commit 8b1f928

Browse files
zhou-haozhou-hao
committed
完善部分注释
1 parent 20b0a8f commit 8b1f928

File tree

33 files changed

+273
-128
lines changed

33 files changed

+273
-128
lines changed

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

Lines changed: 73 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,51 @@
2121
import java.util.List;
2222
import java.util.Map;
2323
import java.util.Objects;
24+
import java.util.Optional;
2425
import java.util.function.Supplier;
2526

2627
/**
27-
* TODO 完成注释
28+
* 用户授权信息,当前登录用户的权限信息,包括用户的基本信息,角色,权限集合等常用信息<br>
29+
* 如何获取:
30+
* <ul>
31+
* <li>springmvc 入参方式: ResponseMessage myTest(@AuthInfo Authorization auth){}</li>
32+
* <li>静态方法方式:AuthorizationHolder.get();</li>
33+
* </ul>
2834
*
2935
* @author zhouhao
36+
* @see AuthorizationHolder
37+
* @see org.hswebframework.web.authorization.annotation.AuthInfo
38+
* @since 3.0
3039
*/
3140
public interface Authorization extends Serializable {
41+
42+
/**
43+
* 获取用户基本信息
44+
*
45+
* @return 用户信息
46+
*/
3247
User getUser();
3348

49+
/**
50+
* 获取持有的角色集合
51+
*
52+
* @return 角色集合
53+
*/
3454
List<Role> getRoles();
3555

56+
/**
57+
* 获取持有的权限集合
58+
*
59+
* @return 权限集合
60+
*/
3661
List<Permission> getPermissions();
3762

63+
/**
64+
* 根据id获取角色,角色不存在则返回null
65+
*
66+
* @param id 角色id
67+
* @return 角色信息
68+
*/
3869
default Role getRole(String id) {
3970
if (null == id) return null;
4071
return getRoles().stream()
@@ -43,6 +74,12 @@ default Role getRole(String id) {
4374
.orElse(null);
4475
}
4576

77+
/**
78+
* 根据权限id获取权限信息,权限不存在则返回null
79+
*
80+
* @param id 权限id
81+
* @return 权限信息
82+
*/
4683
default Permission getPermission(String id) {
4784
if (null == id) return null;
4885
return getPermissions().parallelStream()
@@ -51,17 +88,46 @@ default Permission getPermission(String id) {
5188
.orElse(null);
5289
}
5390

91+
/**
92+
* 根据属性名获取属性值,返回一个{@link Optional}对象。<br>
93+
* 此方法可用于获取自定义的属性信息
94+
*
95+
* @param name 属性名
96+
* @param <T> 属性值类型
97+
* @return Optional属性值
98+
*/
99+
<T extends Serializable> Optional<T> getAttribute(String name);
54100

55-
<T extends Serializable> T getAttribute(String name);
56-
57-
<T extends Serializable> T getAttribute(String name, T defaultValue);
58-
59-
<T extends Serializable> T getAttribute(String name, Supplier<T> supplier);
60-
101+
/**
102+
* 设置一个属性值,如果属性名称已经存在,则将其覆盖。<br>
103+
* 注意:由于权限信息可能会被序列化,属性值必须实现{@link Serializable}接口
104+
*
105+
* @param name 属性名称
106+
* @param object 属性值
107+
*/
61108
void setAttribute(String name, Serializable object);
62109

110+
/**
111+
* 设置多个属性值,参数为map类型,key为属性名称,value为属性值
112+
*
113+
* @param attributes 属性值map
114+
*/
63115
void setAttributes(Map<String, Serializable> attributes);
64116

117+
/**
118+
* 删除属性,并返回被删除的值
119+
*
120+
* @param name 属性名
121+
* @param <T> 被删除的值类型
122+
* @return 被删除的值
123+
*/
124+
<T extends Serializable> T removeAttributes(String name);
125+
126+
/**
127+
* 获取全部属性,此属性为通过{@link this#setAttribute(String, Serializable)}或{@link this#setAttributes(Map)}设置的属性。
128+
*
129+
* @return 全部属性集合
130+
*/
65131
Map<String, Serializable> getAttributes();
66132

67133
}

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

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,15 @@
1919
package org.hswebframework.web.authorization;
2020

2121
/**
22-
* 权限获取器,用于静态方式获取当前登录用户的权限信息
22+
* 权限获取器,用于静态方式获取当前登录用户的权限信息.
23+
* 例如:
24+
* <pre>
25+
* &#064;RequestMapping("/example")
26+
* public ResponseMessage example(){
27+
* Authorization auth = AuthorizationHolder.get();
28+
* return ResponseMessage.ok();
29+
* }
30+
* </pre>
2331
*
2432
* @author zhouhao
2533
* @see AuthorizationSupplier
@@ -28,6 +36,9 @@
2836
public final class AuthorizationHolder {
2937
private static AuthorizationSupplier supplier;
3038

39+
/**
40+
* @return 当前登录用户信息
41+
*/
3142
public static Authorization get() {
3243
if (null == supplier) {
3344
throw new UnsupportedOperationException("AuthorizationSupplier is null!");

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727
* 用户持有的权限信息
2828
*
2929
* @author zhouhao
30+
* @see Authorization
31+
* @since 3.0
3032
*/
3133
public interface Permission extends Serializable {
3234

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
* 角色信息
2424
*
2525
* @author zhouhao
26+
* @since 3.0
2627
*/
2728
public interface Role extends Serializable {
2829

@@ -32,7 +33,6 @@ public interface Role extends Serializable {
3233
String getId();
3334

3435
/**
35-
*
3636
* @return 角色名
3737
*/
3838
String getName();

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,16 @@
11
package org.hswebframework.web.authorization.access;
22

33
/**
4+
* 自定义控制器的数据级权限控制器
5+
*
46
* @author zhouhao
57
* @see DataAccess.Type#CUSTOM
68
*/
79
public interface CustomDataAccess extends DataAccess {
10+
11+
/**
12+
* @return 自定义的控制器
13+
*/
814
DataAccessController getController();
915

1016
default String getType() {

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
* 如：A用户只能查询自己创建的B数据,A用户只能修改自己创建的B数据
66
*
77
* @author zhouhao
8-
* @see 3.0
8+
* @since 3.0
99
*/
1010
public interface DataAccessController {
1111
/**
1212
* 执行权限控制
1313
* @param access 控制方式以及配置
1414
* @param params 当前操作的方法的参数上下文
15-
* @return
15+
* @return 授权是否通过
1616
*/
1717
boolean doAccess(DataAccess access, ParamContext params);
1818
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import java.util.Set;
55

66
/**
7-
* 字段级别权限控制
7+
* 字段级别权限控制配置,表示此用户不能对字段{@link this#getField()} 执行 {@link this#getActions()}操作
88
*
99
* @author zhouhao
1010
* @see FieldAccessController

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

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,23 @@
11
package org.hswebframework.web.authorization.access;
22

3+
import org.hswebframework.web.authorization.Permission;
4+
35
import java.util.Set;
46

57
/**
6-
* TODO 完成注释
8+
* 字段级权限控制器,用于控制对字段的操作权限。如:不同角色,可操作的字段不同等
79
*
810
* @author zhouhao
911
*/
1012
public interface FieldAccessController {
13+
14+
/**
15+
* 执行权限验证。根据当前被拦截的操作类型,以及此类型可操作的字段集合进行权限验证
16+
*
17+
* @param action 当前操作的类型 {@link Permission#getActions()}
18+
* @param accesses 不可操作的字段
19+
* @param params 参数上下文
20+
* @return 验证是否通过
21+
*/
1122
boolean doAccess(String action, Set<FieldAccess> accesses, ParamContext params);
1223
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package org.hswebframework.web.authorization.access;
22

33
/**
4-
* TODO 完成注释
4+
* 只能操作由自己创建的数据
55
*
66
* @author zhouhao
77
*/

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ public interface ParamContext extends Serializable {
2929
Method getMethod();
3030

3131
/**
32-
* 根据参数名获取参数值,此参数为方法的参数,而非http参数 <br/>
33-
* 如：当前被操作的方法为 query(QueryParam param); 调用getParameter("param"); 则返回QueryParam实例<br/>
34-
* 注意:返回值为Optional对象,使用方法见{@link Optional}<br/>
32+
* 根据参数名获取参数值,此参数为方法的参数,而非http参数 <br>
33+
* 如：当前被操作的方法为 query(QueryParam param); 调用getParameter("param"); 则返回QueryParam实例<br>
34+
* 注意:返回值为Optional对象,使用方法见{@link Optional}<br>
3535
*
3636
* @param name 参数名称
3737
* @param <T> 参数泛型

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package org.hswebframework.web.authorization.access;
22

33
/**
4-
* 动态脚本数据权限控制
4+
* 通过脚本来控制数据操作权限.脚本可以在前端设置角色的时候进行编辑
55
*
66
* @author zhouhao
77
*/

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

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,19 @@
2020
import java.lang.annotation.*;
2121

2222
/**
23-
* TODO 完成注释
23+
* 用于springmvc中,将授权信息自动注入到参数中.
24+
* 例如:
25+
* <pre>
26+
* &#064;ReuqestMapping("/example")
27+
* public ResponseMessage(&#064;AuthInfo Authorization auth){
28+
* User user = auth.getUser();
29+
* return ok();
30+
* }
31+
* </pre>
2432
*
2533
* @author zhouhao
34+
* @see org.hswebframework.web.authorization.Authorization
35+
* @since 3.0
2636
*/
2737
@Target(ElementType.PARAMETER)
2838
@Retention(RetentionPolicy.RUNTIME)

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

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,17 @@
1818

1919
package org.hswebframework.web.authorization.annotation;
2020

21+
import org.hswebframework.web.authorization.Permission;
22+
import org.hswebframework.web.authorization.Role;
23+
import org.hswebframework.web.authorization.User;
24+
2125
import java.lang.annotation.*;
2226

2327
/**
24-
* 权限注解
28+
* 基础权限控制注解,提供基本的控制配置
29+
*
30+
* @author zhouhao
31+
* @since 3.0
2532
*/
2633
@Target({ElementType.TYPE, ElementType.METHOD})
2734
@Retention(RetentionPolicy.RUNTIME)
@@ -32,67 +39,58 @@
3239
/**
3340
* 对角色授权,当使用按角色授权时，对模块以及操作级别授权方式失效
3441
*
35-
* @return 进行授权的角色数组
42+
* @return 进 role id array
43+
* @see Role#getId()
3644
*/
3745
String[] role() default {};
3846

3947
/**
4048
* 对模块授权
4149
*
42-
* @return 进行授权的模块
50+
* @return permission id array
51+
* @see Permission#getId()
4352
*/
4453
String[] permission() default {};
4554

4655
/**
4756
* 如增删改查等
4857
*
49-
* @return
58+
* @return action array
59+
* @see Permission#getActions()
5060
*/
5161
String[] action() default {};
5262

53-
5463
/**
5564
* 验证是否为指定user
5665
*
57-
* @return
66+
* @return user id array
67+
* @see User#getId()
5868
*/
5969
String[] user() default {};
6070

6171
/**
6272
* 验证失败时返回的消息
6373
*
64-
* @return
74+
* @return 验证失败提示的消息
6575
*/
6676
String message() default "{unauthorized}";
6777

6878
/**
6979
* 表达式验证
7080
*
71-
* @return
81+
* @return 表达式
82+
* @see RequiresExpression#value()
7283
*/
7384
String expression() default "";
7485

7586
/**
7687
* 表达式语言，默认spring表达式
7788
*
7889
* @return 表达式语言
90+
* @see RequiresExpression#language()
7991
*/
8092
String expressionLanguage() default "spel";
8193

82-
/**
83-
* 是否为api接口，为true时，可使用api方式请求。
84-
*
85-
* @return
86-
*/
87-
boolean api() default false;
88-
89-
/**
90-
* 可匿名访问
91-
*
92-
* @return 是否可匿名访问, 匿名访问将不用登录
93-
*/
94-
boolean anonymous() default false;
95-
9694
/**
9795
* 是否合并类上的注解
9896
*
@@ -103,7 +101,7 @@
103101
/**
104102
* 验证模式，在使用多个验证条件时有效
105103
*
106-
* @return
104+
* @return logical
107105
*/
108106
Logical logical() default Logical.OR;
109107

0 commit comments

Comments
 (0)