【JEECG技术文档】JEECG平台对外接口JWT应用文档V3.7.2

时间  2019-11-20
标签 JEECG技术文档 jeecg 平台 对外 接口 jwt 应用 文档 v3.7.2 繁體版
原文   原文链接

1、 接口方式

    接口调用采用http协议，rest请求方式；java

2、 接口安全

    接口安全采用Json web token (JWT)机制，基于token的鉴权机制.web

1. 机制说明redis

    基于token的鉴权机制相似于http协议也是无状态的，它不须要在服务端去保留用户的认证信息或者会话信息。这就意味着基于token认证机制的应用不须要去考虑用户在哪一台服务器登陆了，这就为应用的扩展提供了便利。json

2. 基本流程缓存

    流程上是这样的：安全

        （1） 用户使用用户名密码来请求服务器服务器

        （2） 服务器进行验证用户的信息app

        （3） 服务器经过验证发送给用户一个token测试

        （4） 客户端存储token，并在每次请求时附送上这个token值（存在head里的参数X-AUTH-TOKEN）编码

        （5） 服务端验证token值，并返回数据

 

 

3. 优势

  •   由于json的通用性，因此JWT是能够进行跨语言支持的，像JAVA,JavaScript,NodeJS,PHP等不少语言均可以使用。
  •   由于有了payload部分，因此JWT能够在自身存储一些其余业务逻辑所必要的非敏感信息。
  •   便于传输，jwt的构成很是简单，字节占用很小，因此它是很是便于传输的。
  •   它不须要在服务端保存会话信息, 因此它易于应用的扩展

4. 安全相关

  •   不该该在jwt的payload部分存放敏感信息，由于该部分是客户端可解密的部分。
  •   保护好secret私钥，该私钥很是重要。
  •   若是能够，请使用https协议

3、 缓存配置

    JWT 验证token采用redis进行缓存，

    redis配置文件：src/main/resources/redis.properties

    修改redis对应的IP和端口。

[java]  view plain  copy
  1. #redis  
  2. redis.host=124.206.91.99  
  3. redis.port=6379  
  4. redis.pass=  
  5. redis.adapter.maxIdle=100  
  6. redis.adapter.minIdle=10  
  7. redis.adapter.testOnBorrow=true  
  8. redis.adapter.testOnReturn=true  
  9. redis.adapter.testWhileIdle=true  
  10. redis.adapter.numTestsPerEvictionRun=10  
  11. redis.adapter.timeBetweenEvictionRunsMillis=60000  

4、 接口说明

    注意：访问除【鉴权TOKEN接口】之外的接口时，都须要访问用户拥有对接口的访问权限，如无权限，将直接返回以下信息：

[java]  view plain  copy
  1. {"message":"您没有该接口的权限！","data":null,"ok":false,"respCode":"-1"}  

1. 鉴权TOKEN接口

    ■描述

        根据用户名和密码获取TOKEN。

    ■访问地址

        http://域名/rest/tokens

    ■访问方式

        GET

    ■参数

参数名

数据类型

是否必须

示例值

默认值

描述

username

String

Y

“admin”

 

用户名

password

String

Y

“123456”

 

密码

 

    ■返回值

        成功时，直接返回token字符串。

        失败时，直接返回用户帐号密码错误!

    ■校验规则

        无

    ■请求示例

        请求地址：http://域名/rest/tokens

[java]  view plain  copy
  1. {  
  2.     "username":"admin",  
  3.     "password":"123456"  
  4. }  

    ■返回示例

        成功案例：

[java]  view plain  copy
  1. eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI4YThhYjBiMjQ2ZGM4MTEyMDE0NmRjODE4MTk1MDA1MiIsInN1YiI6ImFkbWluIiwiaWF0IjoxNTExODU0NDE4fQ.tnILZEivS-6YOX9uqsnCHygh7-XrG_-Sj8vLslNGkdQ  
  2.   
  3. 失败案例：  
  4.   
  5. 用户帐号密码错误!  

2. 建立黑名单信息接口

    ■描述

        建立黑名单信息接口，黑名单为单表。

    ■访问地址

        http://域名/rest/tsBlackListController

    ■访问方式

        POST

    ■参数（详见excel）

参数名

数据类型

是否必须

示例值

默认值

描述

ip

String

Y

“192.168.1.1”

 

 

......

 

 

……省略信息其余字段……


    ■返回值

参数名

描述

respCode

返回码（见附录1接口返回信息列表）

respMsg

返回信息（见附录1接口返回信息列表）

data

返回结果（NULL）

ok

状态

    ■校验规则

        1. 接口中涉及日期时间的字段，要求格式化为字符串传递，日期格式为“YYYY-MM-dd”，时间格式为“YYYY-MM-dd HH:mm:ss”。

    ■请求示例

        请求地址：http://域名/rest/tsBlackListController

    参数以下：

     注意：建立企业无需传id，子表无需传id和企业id，这些都会在后台生成，必须要传入的是来源id和来源表。

[java]  view plain  copy
 
  1. {  
  2.   "ip": "192.1.1.1",  
  3. ……(省略信息其余字段)  
  4. }  

    ■返回示例

[java]  view plain  copy
 
  1. 成功案例：  
  2. {  
  3.     "respCode":"0",  
  4.     " respMsg":"成功"  
  5. }  
  6. 失败案例：  
  7. {  
  8.     "respCode":"-1",  
  9.     "respMsg":"黑名单建立失败"  
  10. }  

3. 查询黑名单信息接口

    ■描述

        根据id查询或查询黑名单信息接口。

    ■访问地址

根据id查询

http://域名/rest/tsBlackListController/get/{id}

    ■访问方式

        GET

    ■参数

        无

    ■返回值

参数名

描述

respCode

返回码（见附录1接口返回信息列表）

respMsg

返回信息（见附录1接口返回信息列表）

data

返回结果（结构参照建立企业接口的参数，具体字段参照excel）

ok

状态

    ■校验规则

    ■请求示例

        请求地址：http://域名

[java]  view plain  copy
  1. /rest/tsBlackListController/get/297e7ae15f7f7f7e015f7fb0f57e0040  

    ■返回示例

[java]  view plain  copy
  1. 成功案例:  
  2.   
  3. {  
  4.   
  5.     "message": "成功",  
  6.   
  7.     "data": {  
  8.   
  9.         "id": "402881f15e751d2a015e75212c570005",  
  10.   
  11.         "createBy": "admin",  
  12.   
  13.         "updateBy": "",  
  14.   
  15.         "bpmStatus": "1",  
  16.   
  17.         "ip": "111.193.210.4",  
  18.   
  19.         "createName": "管理员",  
  20.   
  21.         "createDate": "2017-09-12 16:07:41",  
  22.   
  23.         "updateName": "",  
  24.   
  25.         "updateDate": null,  
  26.   
  27.         "sysOrgCode": "A03",  
  28.   
  29.         "sysCompanyCode": "A03"  
  30.   
  31.     },  
  32.   
  33.     "respCode": "0",  
  34.   
  35.     "ok": true  
  36.   
  37. }  
[java]  view plain  copy
  1. 失败案例：  
  2. {"data":null,"respCode":"-1","respMsg":"根据所传id查询无结果"}  

4. 修改黑名单信息接口

    ■描述

        根据id修改

    ■访问地址

        http://域名/rest/tsBlackListController/update/{id}

    ■访问方式

        PUT

    ■参数

参数名

数据类型

是否必须

示例值

默认值

描述

id

String

Y

“402881f15f811877015f8124ca1c0002”

 

 

ip

String

Y

“192.168.1.1”

 

 

 

 

 

……省略信息其余字段……

    ■返回值

参数名

描述

respCode

返回码（见附录1接口返回信息列表）

respMsg

返回信息（见附录1接口返回信息列表）

data

返回结果（NULL）

ok

状态

    ■校验规则

        经过校验主表的字段：来源id和来源表验证数据惟一性。

    ■请求示例

       请求地址：http://域名/rest/tsBlackListController/update/402881f15f811877015f8124ca1c0002

       参数以下：

[java]  view plain  copy
  1. {  
  2.   "id": "402881e75f94878e015f94896bb80002",  
  3.   "ip": "1.1.1.1"  
  4.   
  5. }  

    ■返回示例

[java]  view plain  copy
 
  1. 成功案例：  
  2. {  
  3.     "respCode":"0",  
  4.     "respMsg":"成功"  
  5. }  
  6.   
  7. 失败案例：  
  8. {  
  9.     "respCode":"-1",  
  10.     "respMsg":"输入ID无效,重复输入"  
  11. }  

5. 删除黑名单接口

    ■描述

        根据id删除

    ■访问地址

        http://域名/rest/tsBlackListController/delete/{id}

    ■访问方式

        DELETE

    ■参数

       无

    ■返回值

参数名

描述

respCode

返回码（见附录1接口返回信息列表）

respMsg

返回信息（见附录1接口返回信息列表）

data

返回结果（NULL）

ok

状态

    ■校验规则

        无

    ■请求示例

        请求地址：http://域名/rest/tsBlackListController/delete/297e7ae15f7f7f7e015f7fb0f57e0040

    ■返回示例

[java]  view plain  copy
 
  1. 成功案例：  
  2. {  
  3.     "respCode":"0",  
  4.     "respMsg":"成功"  
  5. }  
  6. 失败案例：  
  7. {  
  8.     "respCode":"-1",  
  9.     "respMsg":"输入ID无效,重复输入"  
  10. }  

5、 客户端测试代码

    代码示例

[java]  view plain  copy
  1. public static String getToken(String userName,String password){  
  2.         String url = "http://localhost:8080/jeecg/rest/tokens?username="+userName+"&password="+password;  
  3.         String token= JwtHttpUtil.httpRequest(url, "POST", null);  
  4.         return token;  
  5.     }  
  6.         //获取黑名单列表  
  7.     public static JSONObject getBlackList(String token){  
  8.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  9.         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  10.         return resp;  
  11.     }  
  12.     //建立黑名单  
  13.     public static JSONObject createBlackList(String token,String json){  
  14.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  15.         JSONObject resp= JwtHttpUtil.httpRequest(url, "POST", json,token);  
  16.         return resp;  
  17.     }  
  18.     //更新黑名单  
  19.     public static JSONObject updateBlackList(String token,String json){  
  20.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  21.         JSONObject resp= JwtHttpUtil.httpRequest(url, "PUT", json,token);  
  22.         return resp;  
  23.     }  
  24.     //删除黑名单  
  25.     public static JSONObject deleteBlackList(String token,String id){  
  26.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  27.         JSONObject resp= JwtHttpUtil.httpRequest(url, "DELETE", null,token);  
  28.         return resp;  
  29.     }  
  30.     //查询黑名单  
  31.     public static JSONObject getBlackList(String token,String id){  
  32.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  33.         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  34.         return resp;  
  35.     }  
  • 参考源码：
[java]  view plain  copy
 
  1. package org.jeecgframework.test.demo;  
  2.   
  3. import org.jeecgframework.jwt.util.JwtHttpUtil;  
  4.   
  5. import com.alibaba.fastjson.JSONObject;  
  6.   
  7. /** 
  8.  * jeecg jwt 
  9.  * 接口客户端调用demo 
  10.  * @author qinfeng 
  11.  * 
  12.  */  
  13. public class JwtRestfulClientDemo {  
  14.       
  15.     public static String getToken(String userName,String password){  
  16.         String url = "http://localhost:8080/jeecg/rest/tokens?username="+userName+"&password="+password;  
  17.         String token= JwtHttpUtil.httpRequest(url, "POST", null);  
  18.         return token;  
  19.     }  
  20.       
  21.       
  22.     //获取黑名单列表  
  23.     public static JSONObject getBlackList(String token){  
  24.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  25.         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  26.         return resp;  
  27.     }  
  28.       
  29.     //建立黑名单  
  30.     public static JSONObject createBlackList(String token,String json){  
  31.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  32.         JSONObject resp= JwtHttpUtil.httpRequest(url, "POST", json,token);  
  33.         return resp;  
  34.     }  
  35.       
  36.       
  37.     //更新黑名单  
  38.     public static JSONObject updateBlackList(String token,String json){  
  39.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  40.         JSONObject resp= JwtHttpUtil.httpRequest(url, "PUT", json,token);  
  41.         return resp;  
  42.     }  
  43.       
  44.       
  45.     //删除黑名单  
  46.     public static JSONObject deleteBlackList(String token,String id){  
  47.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  48.         JSONObject resp= JwtHttpUtil.httpRequest(url, "DELETE", null,token);  
  49.         return resp;  
  50.     }  
  51.       
  52.     //查询黑名单  
  53.     public static JSONObject getBlackList(String token,String id){  
  54.         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  55.         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  56.         return resp;  
  57.     }  
  58.       
  59.       
  60.     public static void main(String[] args) {  
  61.         String token = getToken("interfaceuser","123456");  
  62. //      String token = "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZG1pbiIsInN1YiI6ImFkbWluIiwiaWF0IjoxNTExODU5NjM2fQ.Emfe8VZKA_L33jaW8ZUtVFVDEin83Np_d3gKlPIZryE";  
  63. //      System.out.println(token);  
  64.           
  65.         //添加黑名单  
  66. //      JSONObject jsonObject=new JSONObject();  
  67. //      jsonObject.put("ip","192.168.1.2");  
  68. //      System.out.println("======添加黑名单======="+createBlackList(token,jsonObject.toJSONString()));  
  69.         //更新黑名单  
  70. //      JSONObject jsonObject=new JSONObject();  
  71. //      jsonObject.put("id","402881ee6001da57016001dc13110001");  
  72. //      jsonObject.put("ip","192.168.0.111");  
  73. //      System.out.println("======更新黑名单======="+updateBlackList(token,jsonObject.toJSONString()));  
  74.         //删除黑名单  
  75. //      System.out.println("======删除黑名单======="+deleteBlackList(token,"402881ee6001da57016001dc13110001"));  
  76.         //查询黑名单  
  77. //      System.out.println("======查询黑名单======="+getBlackList(token,"402881ee6001e873016001f369f40008"));  
  78.         //获取黑名单列表  
  79.         System.out.println("======获取黑名单列表======="+getBlackList(token));  
  80.     }  
  81.   
  82. }  
[java]  view plain  copy
  1. package org.jeecgframework.jwt.util;  
  2.   
  3. import java.io.BufferedReader;  
  4. import java.io.InputStream;  
  5. import java.io.InputStreamReader;  
  6. import java.io.OutputStream;  
  7. import java.net.ConnectException;  
  8. import java.net.HttpURLConnection;  
  9. import java.net.URL;  
  10. import org.jeecgframework.core.util.LogUtil;  
  11. import com.alibaba.fastjson.JSONObject;  
  12.   
  13. /** 
  14.  * JWT 客户端 
  15.  * @author qinfeng 
  16.  * 
  17.  */  
  18. public class JwtHttpUtil {  
  19.   
  20.     /** 
  21.      * 发起https请求并获取结果 
  22.      *  
  23.      * @param requestUrl 
  24.      *            请求地址 
  25.      * @param requestMethod 
  26.      *            请求方式（GET、POST） 
  27.      * @param outputStr 
  28.      *            提交的数据 
  29.      * @return JSONObject(经过JSONObject.get(key)的方式获取json对象的属性值) 
  30.      */  
  31.     public static JSONObject httpRequest(String requestUrl, String requestMethod, String outputStr, String sign) {  
  32.         JSONObject jsonObject = null;  
  33.         StringBuffer buffer = new StringBuffer();  
  34.         HttpURLConnection httpUrlConn = null;  
  35.         try {  
  36.             // 建立SSLContext对象，并使用咱们指定的信任管理器初始化  
  37.             URL url = new URL(requestUrl);  
  38.             httpUrlConn = (HttpURLConnection) url.openConnection();  
  39.             httpUrlConn.setDoOutput(true);  
  40.             httpUrlConn.setDoInput(true);  
  41.             httpUrlConn.setUseCaches(false);  
  42.             httpUrlConn.setRequestProperty("X-AUTH-TOKEN", sign);  
  43.             httpUrlConn.setRequestProperty("Accept", "*/*");  
  44.             httpUrlConn.setRequestProperty("Content-Type", "application/json");  
  45.             // 设置请求方式（GET/POST）  
  46.             httpUrlConn.setRequestMethod(requestMethod);  
  47.             if ("GET".equalsIgnoreCase(requestMethod))  
  48.                 httpUrlConn.connect();  
  49.   
  50.             // 当有数据须要提交时  
  51.             if (null != outputStr) {  
  52.                 OutputStream outputStream = httpUrlConn.getOutputStream();  
  53.                 // 注意编码格式，防止中文乱码  
  54.                 outputStream.write(outputStr.getBytes("UTF-8"));  
  55.                 outputStream.close();  
  56.             }  
  57.   
  58.             // 将返回的输入流转换成字符串  
  59.             InputStream inputStream = httpUrlConn.getInputStream();  
  60.             InputStreamReader inputStreamReader = new InputStreamReader(inputStream, "utf-8");  
  61.             BufferedReader bufferedReader = new BufferedReader(inputStreamReader);  
  62.   
  63.             String str = null;  
  64.             while ((str = bufferedReader.readLine()) != null) {  
  65.                 buffer.append(str);  
  66.             }  
  67.             bufferedReader.close();  
  68.             inputStreamReader.close();  
  69.             // 释放资源  
  70.             inputStream.close();  
  71.             inputStream = null;  
  72.             httpUrlConn.disconnect();  
  73.             System.out.println(buffer.toString());  
  74.             jsonObject = JSONObject.parseObject(buffer.toString());  
  75.             // jsonObject = JSONObject.fromObject(buffer.toString());  
  76.         } catch (ConnectException ce) {  
  77.             LogUtil.info("Weixin server connection timed out.");  
  78.         } catch (Exception e) {  
  79.             e.printStackTrace();  
  80.             org.jeecgframework.core.util.LogUtil.info("https request error:{}" + e.getMessage());  
  81.         } finally {  
  82.             try {  
  83.                 httpUrlConn.disconnect();  
  84.             } catch (Exception e) {  
  85.                 e.printStackTrace();  
  86.                 org.jeecgframework.core.util.LogUtil.info("http close error:{}" + e.getMessage());  
  87.             }  
  88.         }  
  89.         return jsonObject;  
  90.     }  
  91.       
  92.       
  93.     /**  
  94.      * 发起https请求并获取结果  
  95.      *   
  96.      * @param requestUrl  
  97.      *            请求地址  
  98.      * @param requestMethod  
  99.      *            请求方式（GET、POST）  
  100.      * @param outputStr  
  101.      *            提交的数据  
  102.      * @return JSONObject(经过JSONObject.get(key)的方式获取json对象的属性值)  
  103.      */  
  104.     public static String httpRequest(String requestUrl, String requestMethod, String outputStr) {  
  105.         String res = "";  
  106.         StringBuffer buffer = new StringBuffer();  
  107.         HttpURLConnection httpUrlConn = null;  
  108.         try {  
  109.             // 建立SSLContext对象，并使用咱们指定的信任管理器初始化  
  110.             URL url = new URL(requestUrl);  
  111.             httpUrlConn = (HttpURLConnection) url.openConnection();  
  112.             httpUrlConn.setDoOutput(true);  
  113.             httpUrlConn.setDoInput(true);  
  114.             httpUrlConn.setUseCaches(false);  
  115.             httpUrlConn.setRequestProperty("Accept", "text/plain");  
  116.              httpUrlConn.setRequestProperty("Content-Type", "application/json");  
  117.             // 设置请求方式（GET/POST）  
  118.             httpUrlConn.setRequestMethod(requestMethod);  
  119.             if ("GET".equalsIgnoreCase(requestMethod))  
  120.                 httpUrlConn.connect();  
  121.   
  122.             // 当有数据须要提交时  
  123.             if (null != outputStr) {  
  124.                 OutputStream outputStream = httpUrlConn.getOutputStream();  
  125.                 // 注意编码格式，防止中文乱码  
  126.                 outputStream.write(outputStr.getBytes("UTF-8"));  
  127.                 outputStream.close();  
  128.             }  
  129.   
  130.             // 将返回的输入流转换成字符串  
  131.             InputStream inputStream = httpUrlConn.getInputStream();  
  132.             InputStreamReader inputStreamReader = new InputStreamReader(inputStream, "utf-8");  
  133.             BufferedReader bufferedReader = new BufferedReader(inputStreamReader);  
  134.   
  135.             String str = null;  
  136.             while ((str = bufferedReader.readLine()) != null) {  
  137.                 buffer.append(str);  
  138.             }  
  139.             bufferedReader.close();  
  140.             inputStreamReader.close();  
  141.             // 释放资源  
  142.             inputStream.close();  
  143.             inputStream = null;  
  144.             httpUrlConn.disconnect();  
  145.             res = buffer.toString();  
  146.             System.out.println(res);  
  147. //          jsonObject = JSONObject.parseObject(buffer.toString());  
  148.             // jsonObject = JSONObject.fromObject(buffer.toString());  
  149.         } catch (ConnectException ce) {  
  150.             LogUtil.info("Weixin server connection timed out.");  
  151.         } catch (Exception e) {  
  152.             e.printStackTrace();  
  153.             org.jeecgframework.core.util.LogUtil.info("https request error:{}" + e.getMessage());  
  154.         } finally {  
  155.             try {  
  156.                 httpUrlConn.disconnect();  
  157.             } catch (Exception e) {  
  158.                 e.printStackTrace();  
  159.                 org.jeecgframework.core.util.LogUtil.info("http close error:{}" + e.getMessage());  
  160.             }  
  161.         }  
  162.         return res;  
  163.     }  
  164.   
  165. }  
  • 附录1：接口返回CODE

code

msg

说明

解决方案

0

SUCCESS

成功

 

-1

ERROR

无接口访问权限

 

1000

VALID_ERROR

验证失败

 

r0001

SAVE_SUCCESS

写入成功

 

r0002

UPDATE_SUCCESS

更新成功

 

r0003

REMOVE_SUCCESS

删除成功
相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程