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

编程语言 2018-05-09 16:02:38 阅读次数: 2

一、 接口方式

       

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

 

二、 接口安全

 

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

 

    1. 机制说明

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

    2. 基本流程

    流程上是这样的：

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

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

        （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协议

三、 缓存配置

    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  

 

四、 接口说明

   

    注意：访问除【鉴权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. }  

 

五、 客户端测试代码

   

    代码示例

[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

删除成功

猜你喜欢

转载自jeecg.iteye.com/blog/2410431
今日推荐
《美国对全球网络空间安全与发展的威胁和破坏》报告发布
火速冲上 GitHub 热榜 —— 开源编程语言、框架哪有这么可爱？
北京人形机器人创新中心发布全球首个纯电驱拟人奔跑的全尺寸人形机器人“天工”
LFOSSA 源来如此公开课 | 掌握云原生未来：CNCF 认证全面攻略与备考秘籍
国产云输入法——仅华为无云端数据上传安全问题
周排行
Python环境安装与基础语法（1）——计算机基础知识
IMU预积分
ADAS中的LDW、FCW、BSD、LCA、ACC、AEB、APA、DMS代表的含义
B站笔试两道题
skyeye arm 硬件虚拟机环境的搭建
Web前端静态页面示例
数组-合并排序数组 II-简单
springcloud之版本问题启动报错
面向对象-------------匿名对象(六)
输入URL到页面呈现中间发生了什么？
每日归档
更多
2024-04-30(1)
2024-04-29(40)
2024-04-28(0)
2024-04-27(56)
2024-04-26(39)
2024-04-25(22)
2024-04-24(36)
2024-04-23(26)
2024-04-22(39)
2024-04-21(0)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022