add doc - default-datasource, exception, path-match

e116211e · sinat_25235033 · 5c40d7f8 · e116211e · e116211e · e116211e
5 changed file
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
 - 入门  
  - [介绍](README.md "introduce")
  - [快速开始](quickstart.md "quick start greatest")  
+  - [url路径匹配](path-match.md)  
+  - [sureness异常](exception.md)  
+  - [默认数据源](default-datasource.md)  

 - 进阶扩展
  - [扩展点](extend-point.md)

--- a/docs/default-datasource.md
+++ b/docs/default-datasource.md
+# 默认数据源   
+
+`sureness`认证鉴权当然也需要我们自己的配置数据:账户数据，角色权限数据等  
+这些配置数据可能来自文本，关系数据库，非关系数据库  
+我们提供了配置数据接口`SurenessAccountProvider`, `PathTreeProvider`, 用户可以实现此接口实现自定义配置数据源  
+
+当然我们也提供默认文本形式的配置数据实现 `DocumentResourceDefaultProvider`  
+用户可以创建文件`sureness.yml`来配置数据,配置样例如下：  
+
+```
+## -- sureness.yml文本数据源 -- ##
+
+# 加载到匹配字典的资源,也就是需要被保护的,设置了所支持角色访问的资源
+# 没有配置的资源也默认被认证保护,但不鉴权
+# eg: /api/v2/host===post===[role2,role3,role4] 表示 /api/v2/host===post 这条资源支持 role2,role3,role4这三种角色访问
+# eg: /api/v1/getSource3===get===[] 表示 /api/v1/getSource3===get 这条资源支持所有角色或无角色访问
+resourceRole:
+  - /api/v2/host===post===[role2,role3,role4]
+  - /api/v2/host===get===[role2,role3,role4]
+  - /api/v2/host===delete===[role2,role3,role4]
+  - /api/v2/host===put===[role2,role3,role4]
+  - /api/mi/**===put===[role2,role3,role4]
+  - /api/v1/getSource1===get===[role1,role2]
+  - /api/v2/getSource2/*/*===get===[role2]
+  - /api/v1/source1===get===[role2]
+  - /api/v1/source1===post===[role1]
+  - /api/v1/source1===delete===[role3]
+  - /api/v1/source1===put===[role1,role2]
+  - /api/v1/source2===get===[]
+
+# 需要被过滤保护的资源,不认证鉴权直接访问
+excludedResource:
+  - /api/v3/host===get
+  - /api/v3/book===get
+  - /api/v1/account/auth===post
+
+# 用户账户信息
+# 下面有 admin root tom三个账户
+# eg: admin 拥有[role1,role2]角色,加盐密码为0192023A7BBD73250516F069DF18B500
+# eg: root 没有角色,密码为明文23456
+account:
+  - appId: admin
+    # 如果填写了加密盐--salt,则credential为MD5(password+salt)的32位结果
+    # 没有盐认为不加密,credential为明文
+    credential: 0192023A7BBD73250516F069DF18B500
+    salt: 123
+    role: [role1,role2]
+  - appId: root
+    credential: 23456
+    role: [role1]
+  - appId: tom
+    credential: 32113
+    role: [role2]
+
+```
+
+我们提供了默认文本数据源使用`DEMO`，默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
--- a/docs/exception.md
+++ b/docs/exception.md
+## sureness 异常  
+
+`sureness`异常                              | 异常描述
+---                                       | ---
+SurenessAuthenticationException           | 基础认证异常,认证相关的子异常应该继承此异常 
+SurenessAuthorizationException            | 基础鉴权异常,鉴权相关的子异常应该继承此异常
+ProcessorNotFoundException                | 认证异常,未找到支持此subject的processor
+UnknownAccountException                   | 认证异常,不存在此账户
+UnSupportedSubjectException               | 认证异常,不支持的请求,未创建出subject
+DisabledAccountException                  | 认证异常,账户禁用
+ExcessiveAttemptsException                | 认证异常,账户尝试认证次数过多
+IncrrectCredentialsException             | 认证异常,密钥错误
+ExpiredCredentialsException               | 认证异常,密钥认证过期
+UnauthorizedException                     | 鉴权异常,没有权限访问此资源
+
+自定义异常需要继承`SurenessAuthenticationException`或`SurenessAuthorizationException`才能被最外层捕获  
--- a/docs/path-match.md
+++ b/docs/path-match.md
+## url路径匹配  
+
+我们配置的资源格式为：`requestUri===httpMethod`, 即请求的路径加上其请求方式(`post,get,put,delete...`)作为一个整体被视作一个资源   
+`eg: /api/v2/book===get` `get`方式请求`/api/v2/book`接口数据  
+这里的`requestUri`支持url路径匹配:  *, **  
+
+通配符                      | 描述              
+---                        | ---               
+*                          | 匹配0个或1个目录   
+**                         | 匹配0个或多个目录  
+
+
+ 样例                      | 说明  
+ ---                       | ---
+ /api/*/book               | 可以匹配 /api/user/book 或 /api/book等  
+ /**                       | 可以匹配任何路径  
+ /**/foo                   | 可以匹配 /api/user/book/foo 等  
+ 
+匹配优先级: 原始字符串 大于 * 大于 **
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -8,11 +8,12 @@
  `eg: /api/v2/book===get` `get`方式请求`/api/v2/book`接口数据     
 - 角色资源映射: 用户所属角色--角色拥有资源--用户拥有资源(用户就能访问此`api`)   

+资源路径匹配详见 [url路径匹配](path-match.md)  
+
 ### 项目中加入sureness  

 1. 项目使用`maven`构建,加入`maven`坐标  
 ```
-<!-- https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core -->
 <dependency>
    <groupId>com.usthe.sureness</groupId>
    <artifactId>sureness-core</artifactId>
@@ -62,21 +63,7 @@ SurenessSecurityManager.getInstance().checkIn(servletRequest)
            // 其他自定义异常
        }
 ```
-
-`sureness`异常                              | 异常描述
---                                       | ---
-SurenessAuthenticationException           | 基础认证异常,认证相关的子异常应该继承此异常 
-SurenessAuthorizationException            | 基础鉴权异常,鉴权相关的子异常应该继承此异常
-ProcessorNotFoundException                | 认证异常,未找到支持此subject的processor
-UnknownAccountException                   | 认证异常,不存在此账户
-UnSupportedSubjectException               | 认证异常,不支持的请求,未创建出subject
-DisabledAccountException                  | 认证异常,账户禁用
-ExcessiveAttemptsException                | 认证异常,账户尝试认证次数过多
-IncrrectCredentialsException             | 认证异常,密钥错误
-ExpiredCredentialsException               | 认证异常,密钥认证过期
-UnauthorizedException                     | 鉴权异常,没有权限访问此资源
-
-自定义异常需要继承`SurenessAuthenticationException`或`SurenessAuthorizationException`才能被最外层捕获  
+异常详见 [sureness 异常](exception.md)

 ### 加载配置数据  

@@ -84,54 +71,10 @@ UnauthorizedException                     | 鉴权异常,没有权限访问此
 这些配置数据可能来自文本，关系数据库，非关系数据库  
 我们提供了配置数据接口`SurenessAccountProvider`, `PathTreeProvider`, 用户可以实现此接口实现自定义配置数据源  
 当前我们也提供默认文本形式的配置数据实现 `DocumentResourceDefaultProvider`, 用户可以配置`sureness.yml`来配置数据  
-```
-## -- sureness.yml文本数据源 -- ##
-
-# 加载到匹配字典的资源,也就是需要被保护的,设置了所支持角色访问的资源
-# 没有配置的资源也默认被认证保护,但不鉴权
-# eg: /api/v2/host===post===[role2,role3,role4] 表示 /api/v2/host===post 这条资源支持 role2,role3,role4这三种角色访问
-# eg: /api/v1/getSource3===get===[] 表示 /api/v1/getSource3===get 这条资源支持所有角色或无角色访问
-resourceRole:
-  - /api/v2/host===post===[role2,role3,role4]
-  - /api/v2/host===get===[role2,role3,role4]
-  - /api/v2/host===delete===[role2,role3,role4]
-  - /api/v2/host===put===[role2,role3,role4]
-  - /api/mi/**===put===[role2,role3,role4]
-  - /api/v1/getSource1===get===[role1,role2]
-  - /api/v2/getSource2/*/*===get===[role2]
-  - /api/v1/source1===get===[role2]
-  - /api/v1/source1===post===[role1]
-  - /api/v1/source1===delete===[role3]
-  - /api/v1/source1===put===[role1,role2]
-  - /api/v1/source2===get===[]
-
-# 需要被过滤保护的资源,不认证鉴权直接访问
-excludedResource:
-  - /api/v3/host===get
-  - /api/v3/book===get
-  - /api/v1/account/auth===post
-
-# 用户账户信息
-# 下面有 admin root tom三个账户
-# eg: admin 拥有[role1,role2]角色,加盐密码为0192023A7BBD73250516F069DF18B500
-# eg: root 没有角色,密码为明文23456
-account:
-  - appId: admin
-    # 如果填写了加密盐--salt,则credential为MD5(password+salt)的32位结果
-    # 没有盐认为不加密,credential为明文
-    credential: 0192023A7BBD73250516F069DF18B500
-    salt: 123
-    role: [role1,role2]
-  - appId: root
-    credential: 23456
-    role: [role1]
-  - appId: tom
-    credential: 32113
-    role: [role2]

-```
+默认文本数据源配置详见 [默认数据源](default-datasource.md)  

-我们提供了使用`DEMO`，默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
+我们提供了默认文本数据源使用`DEMO`，默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
 若权限配置数据来自数据库,请参考[使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)  

 **HAVE FUN**  
\ No newline at end of file