优化API

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/README.md

@@ -0,0 +1,59 @@
+# OAuth2客户端API
+本模块只提供接口,未提供实现,使用时请自行引入相关实现模块
+
+## 处理OAuth2授权码方式的回调
+方式一、创建一个类并实现 `OAuth2Listener` 使用`OAuth2CodeAuthBeforeEvent`作为泛型,例如
+```java
+ public class MyOAuth2Listener
+         implements OAuth2Listener<OAuth2CodeAuthBeforeEvent> {
+     @Override
+     public void on(OAuth2CodeAuthBeforeEvent event) {
+          String authCode= event.getCode();
+     }
+ }
+```
+
+注册到对应的oauth2服务配置,例如:
+```java
+@Autowired
+OAuth2RequestService requestService;
+public void demo(){
+      requestService.registerListener("oauth2_server",new MyOAuth2Listener());
+}
+```
+
+方式二、使用`AutoRegisterOAuth2Listener`
+```java
+ @Component
+ public class MyOAuth2Listener
+         implements AutoRegisterOAuth2Listener<OAuth2CodeAuthBeforeEvent> {
+    @Override
+    public String getServerId(){
+        return "oauth2_server";
+    }
+    @Override
+    public void on(OAuth2CodeAuthBeforeEvent event) {
+        String authCode= event.getCode();
+    }
+ }
+```
+
+## 发起OAuth2请求
+```java
+@Autowired
+OAuth2RequestService requestService;
+
+public void demo(){
+   //第一步
+   OAuth2Session session = requestService
+                .create(oatuh2ServerId)
+                .byAuthorizationCode(authorizationCode); //使用授权码方式,将自动获取access_token信息并存入会话
+  
+    //第二步
+    String oauth2ApiUri = "oauth2/user-auth-info";
+    Authentication authentication = session
+                   .request(oauth2ApiUri)       // 创建api请求,将自动使用第一步获得的token
+                   .get().ifSuccess()           // http GET请求
+                   .as(Authentication.class);   // 响应结果转为Class
+}
+```

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/OAuth2RequestService.java

@@ -18,47 +18,48 @@
 
 package org.hswebframework.web.authorization.oauth2.client;
 
-import org.hswebframework.web.authorization.Authentication;
 import org.hswebframework.web.authorization.oauth2.client.listener.OAuth2Event;
 import org.hswebframework.web.authorization.oauth2.client.listener.OAuth2Listener;
-import org.hswebframework.web.authorization.oauth2.client.request.OAuth2Session;
-import org.hswebframework.web.authorization.oauth2.client.response.OAuth2Response;
-
-import java.util.List;
-import java.util.function.Function;
 
 /**
+ * OAuth2请求服务接口,用于创建OAuth2请求,注册监听器等操作
+ *
  * @author zhouhao
+ * @@since 3.0
  */
 public interface OAuth2RequestService {
+
+    /**
+     * 创建一个OAuth2服务的会话创建器
+     *
+     * @param serverId 服务ID,serverId是由接口的实现模块自行定义的
+     * @return OAuth2会话创建器
+     * @see OAuth2ServerConfig
+     * @see OAuth2SessionBuilder
+     */
     OAuth2SessionBuilder create(String serverId);
 
+    /**
+     * 注册一个监听器到指定的OAuth2服务
+     *
+     * @param serverId 服务ID
+     * @param listener 监听器
+     */
     void registerListener(String serverId, OAuth2Listener<? extends OAuth2Event> listener);
 
+    /**
+     * 触发一个监听事件
+     *
+     * @param serverId 服务ID
+     * @param event    事件实例
+     */
     void doEvent(String serverId, OAuth2Event event);
 
+    /**
+     * 触发一个指定类型的事件
+     * @param serverId
+     * @param event
+     * @param eventType
+     */
     void doEvent(String serverId, OAuth2Event event, Class<? extends OAuth2Event> eventType);
-
-
-    static void main(String[] args) {
-        OAuth2RequestService requestService = null;
-        Function<OAuth2Response, Authentication> authExchanger = null;
-        String authorizationCode = "";
-
-        OAuth2Session session = requestService
-                .create("hsweb-user-center")
-                .byAuthorizationCode(authorizationCode);
-
-        Authentication authentication = session
-                .request("oauth2/user-auth-info")
-                .get()
-                .as(Authentication.class);
-
-        session.request("menu")
-                .param("paging", "0")
-                .get().as(List.class);
-
-        authentication.getUser().getId();
-
-    }
 }

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/OAuth2SessionBuilder.java

@@ -21,19 +21,53 @@ package org.hswebframework.web.authorization.oauth2.client;
 import org.hswebframework.web.authorization.oauth2.client.request.OAuth2Session;
 
 /**
+ * OAuth2会话创建器,根据各种方式创建 OAuth2会话
+ *
  * @author zhouhao
+ * @see OAuth2Session
+ * @since 3.0
  */
 public interface OAuth2SessionBuilder {
+
+    /**
+     * 根据授权码方式创建会话
+     *
+     * @param code 授权码
+     * @return 会话
+     * @see "grant_type=authorization_code"
+     */
     OAuth2Session byAuthorizationCode(String code);
 
+    /**
+     * 根据密钥方式创建会话
+     *
+     * @return 会话
+     * @see "grant_type=client_credentials"
+     */
     OAuth2Session byClientCredentials();
 
+    /**
+     * 根据密码方式创建会话
+     *
+     * @return 会话
+     * @see "grant_type=password"
+     */
     OAuth2Session byPassword(String username, String password);
 
+    /**
+     * 根据简化模式创建会话
+     *
+     * @return 会话
+     * @see "grant_type=implicit"
+     */
     OAuth2Session byImplicit();
 
-    OAuth2Session refreshToken(String refreshToken);
-
+    /**
+     * 直接指定accessToken创建会话
+     *
+     * @param accessToken
+     * @return 会话
+     */
     OAuth2Session byAccessToken(String accessToken);
 
 }

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/listener/AutoRegisterOAuth2Listener.java

@@ -0,0 +1,27 @@
+/*
+ *  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.oauth2.client.listener;
+
+/**
+ *
+ * @author zhouhao
+ */
+public interface AutoRegisterOAuth2Listener<T extends OAuth2Event> extends OAuth2Listener<T> {
+    String getServerId();
+}

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/listener/OAuth2CodeAuthBeforeEvent.java

@@ -23,7 +23,6 @@ import java.util.Optional;
 import java.util.function.Function;
 
 /**
- * TODO 完成注释
  *
  * @author zhouhao
  */

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/request/OAuth2Session.java

@@ -21,16 +21,45 @@ package org.hswebframework.web.authorization.oauth2.client.request;
 import java.io.Serializable;
 
 /**
+ * OAuth2会话,此会话保存的是 OAuth2授权成功后得到的access_token等相关信息.
+ * 通过会话发起的OAuth2请求将自动带上access_token信息.
+ *
  * @author zhouhao
+ * @see OAuth2Request
+ * @since 3.0
  */
 public interface OAuth2Session extends Serializable {
+    /**
+     * 连接会话
+     *
+     * @return 会话自身
+     */
     OAuth2Session connect();
 
+    /**
+     * 发起一个OAuth2请求,参数为接口地址
+     *
+     * @param uriOrUrl 请求地址,可以为URI或者URL
+     * @return 请求接口
+     */
     OAuth2Request request(String uriOrUrl);
 
+    /**
+     * 设置在请求OAuth2 授权的时候的参数(除了必要之外的参数),client_id,client_secret等信息不需要调用此方法设置
+     *
+     * @param name  参数名称
+     * @param value 参数值
+     * @return 会话自身
+     */
     OAuth2Session param(String name, Object value);
 
+    /**
+     * 关闭会话,将清空
+     */
     void close();
 
+    /**
+     * @return 是否已关闭
+     */
     boolean isClosed();
 }

hsweb-authorization/hsweb-authorization-oauth2/hsweb-authorization-oauth2-client/src/main/java/org/hswebframework/web/authorization/oauth2/client/response/OAuth2Response.java

@@ -22,18 +22,58 @@ import java.util.List;
 import java.util.function.Function;
 
 /**
+ * OAuth2 请求结果
+ *
  * @author zhouhao
  */
 public interface OAuth2Response {
+
+    /**
+     * @return 结果转为字符串
+     */
     String asString();
 
+    /**
+     * @return 结果转为byte数组
+     */
     byte[] asBytes();
 
+    /**
+     * 自定义转换方式
+     *
+     * @param exchangeFunction 转换函数
+     * @param <T>              转换结果类型
+     * @return 转换结果
+     */
     <T> T as(Function<OAuth2Response, T> exchangeFunction);
 
+    /**
+     * 转换为指定的类型
+     *
+     * @param type 类型Class
+     * @param <T>  结果类型
+     * @return 结果
+     */
     <T> T as(Class<T> type);
 
+    /**
+     * 转换为指定类型的结果集
+     *
+     * @param type 类型Class
+     * @param <T>  结果类型
+     * @return 结果集合
+     */
     <T> List<T> asList(Class<T> type);
 
+    /**
+     * @return 响应状态码
+     */
     int status();
+
+    /**
+     * 判断是否成功,如果不成功,则抛出异常
+     *
+     * @return 响应结果本身
+     */
+    OAuth2Response ifSuccess();
 }