【JEECG技术文档】JEECG平台对外接口JWT应用文档V3.7.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	删除成功