JeeSite 快速开发平台

API 接口开发、手机端接口、前后分离接口、Swagger

本文介绍如何使用 JeeSite 作为服务端 API，提供手机端、前后分离应用、第三方服务接口调用。如实现接口登录、登出、权限认证、基础数据、业务办理等。 如何自己来开发API接口提供服务。

JeeSite 手机端项目地址：https://gitee.com/thinkgem/jeesite-uniapp (opens new window)

# 系统登录接口

JeeSite 的系统默认登录，设置了 Base64 或 DES 加密，如果不想加密，可将 secretKey 设置为 ~ (空) 即可，或更改密钥，配置如下application.yml（v4.0.x：jeesite.yml）：

shiro:
  # 登录提交信息加密（如果不需要加密，设置为空即可）
  loginSubmit:
    # 加密用户名、密码、验证码，后再提交（key设置为3个，用逗号分隔）加密方式：DES（4.1.9及之前版本默认设置）
    # v4.2.0+ 开始支持 Base64 加密方式，方便移动端及第三方系统处理认证，可直接设置 Key 为 Base64（4.2.0+默认设置）
    #secretKey: thinkgem,jeesite,com
    secretKey: Base64
    #secretKey: ~

  # 如果是JS请求可能会有跨域访问问题，可将如下参数设置为，允许的域名，全部域名设置*号，否则设置为空
  accessControlAllowOrigin: '*'
1
2
3
4
5
6
7
8
9
10
11

如果开启了加密，您就需要先将DES加密工具引入：

JS：<script src="${ctxStatic}/common/des.js?${_version}"></script>

Java: com.jeesite.common.codec.DesUtils

引入完成之后就可以通过如下方法进行调用加密了：

JS：

<script>
var secretKey = '${@Global.getConfig("shiro.loginSubmit.secretKey")}';
var username = DesUtils.encode('system', secretKey);
var password = DesUtils.encode('admin', secretKey);
console.log('&username=' + username + '&password=' + password);
</script>
1
2
3
4
5
6

Java：

String secretKey = Global.getConfig("shiro.loginSubmit.secretKey");
String username = DesUtils.encode("system", secretKey);
String password = DesUtils.encode("admin", secretKey);
System.out.println("&username=" + username + "&password=" + password);
1
2
3
4

以上两种语言，输出结果相同如下：

  • shiro.loginSubmit.secretKey 为 Base64 时返回（默认）：
&username=c3lzdGVt&password=YWRtaW4
1
  • shiro.loginSubmit.secretKey 为 thinkgem,jeesite,com 时返回：
&username=F3EDC7D2C193E0B8DCF554C726719ED2&password=235880C505ACCDA5C581A4F4CDB81DA0
1

下面我们就可以拿着这个用户名密码进行测试登录了。

通过 Api 工具 或 HttpClient 进行 POST 或 GET 请求如下地址，即可进行登录验证：

  • shiro.loginSubmit.secretKey 为 Base64 时（默认）：
http://127.0.0.1:8980/js/a/login?__login=true&__ajax=json&username=c3lzdGVt&password=YWRtaW4=&validCode=&__sid=
1
  • shiro.loginSubmit.secretKey 为 thinkgem,jeesite,com 时：
http://127.0.0.1:8980/js/a/login?__login=true&__ajax=json&username=F3EDC7D2C193E0B8DCF554C726719ED2&password=235880C505ACCDA5C581A4F4CDB81DA0&validCode=&__sid=
1
  • shiro.loginSubmit.secretKey 为 ~ (空) 时：
http://127.0.0.1:8980/js/a/login?__login=true&__ajax=json&username=system&password=admin&validCode=&__sid=
1

另外，您也可以添加登录附加参数如下：（格式：param_参数名）

1、指定登录设备类型（在线用户列表区分、登录验证码按设备区分，可根据设备指定session超时时间，默认PC）：
   param_deviceType=mobileApp
2、指定登录的系统（区分不同的菜单，默认default）
   param_sysCode=mobileApp
3、指定登录页面和主框架页的视图（默认：employee）
   param_userType=member
4、自定义参数，后台获取方式：formToken.getParam("custom")
   param_custom=123
1
2
3
4
5
6
7
8

若登录信息不正确，则返回如下失败JSON数据：

{
	"username": "F3EDC7D2C193E110B8DCF554C726719ED2",
	"rememberMe": false,
	"rememberUserCode": false,
	"shiroLoginFailure": "org.apache.shiro.authc.UnknownAccountException",
	"message": "账号或密码错误, 请重试.",
	"isValidCodeLogin": false,
	"result": "false",
	"sessionid":"2a6669501bf24afebcf4ff63eb048a56"
}
1
2
3
4
5
6
7
8
9
10

# 访问业务接口

如果失败，第二次登录或访问业务接口，您需要附加一个 __sid 参数，或将 x-token（v4.2.2 及之前版本使用 __sid） 放到 Header 里面，用来指明是同一个会话，如：

http://127.0.0.1:8980/js/a/login?__login=true&__ajax=json&username=c3lzdGVt&password=YWRtaW4=&validCode=&__sid=2a6669501bf24afebcf4ff63eb048a56
1

注意：若参数配置的密码失败次数超过了预警值，则返回的结果信息中的 isValidCodeLogin 会变为 true，这时您需要调用 http://127.0.0.1:8980/js/validCode?__sid=2a6669501bf24afebcf4ff63eb048a56 地址来获取验证码图片，并在登录参数里加 validCode 表示用户输入的验证码。另外请注意，移动端一般调用是无cookie的，您需要在请求参数中包含 __sid 参数与获取验证码的 __sid 一致，否则获取到的验证码值将无法与您登录请求会话匹配。

若登录信息正确，则返回如下登录成功JSON数据：

{
	"user": {
		"id": "system",
		"status": "0",
		"remarks": "",
		"userCode": "system",
		"loginCode": "system",
		"userName": "超级管理员",
		"userType": "none",
		"mgrType": "0",
		"lastLoginIp": "127.0.0.1",
		"lastLoginDate": "2018-03-14 22:34:44",
		"userWeight": 0,
		"oldLastLoginIp": "127.0.0.1",
		"corpName_": "JeeSite",
		"corpCode_": "0",
		"oldLoginDate": "2018-03-14 22:34:44",
		"avatarUrl": "/ctxPath/static/images/user1.jpg"
	},
	"result": "true",
	"message": "登录成功！",
	"sessionid": "5fe9c7c45ded4425b03eff8f78179637"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

授权 __sid 与 x-token 可通过 yml 进行更改名称：

session:
  # 设置接收 SessionId 请求参数和请求头的名称
  sessionIdParamName: __sid
  sessionIdHeaderName: x-token
1
2
3
4

# 系统退出接口

通过 Ajax 或 HttpClient 进行 POST 或 GET 请求如下地址，即可进行退出账号：

http://127.0.0.1:8980/js/a/logout?__ajax=json&__sid=5fe9c7c45ded4425b03eff8f78179637
1

注意：无 cookie 环境下，必须要指定要退出的 sessionid

返回JSON数据：

{ "result": "true", "message": "退出成功！" }
1

# 统一包装结果

支持对数据统一包装，满足提供给第三方接口要求，如格式如下：

{ "code": 200, "msg": "", "data": [] | {} }
1

以下方法支持 v5.8.1+ 版本，其它版本可联系售后技术获取方案。

方案一：按需进行包装

请求参数添加 __data=true，或请求头添加 x-data=true 进行开启，如下：

http://127.0.0.1:8980/js/a/index?__data=true&__ajax=json&__sid=5fe9c7c45ded4425b03eff8f78179637
1

参数名和请求头名可根据业务需求进行修改：

# Web 相关
web:
  # 开启对接口结果数据进行包装的请求参数名和请求头名（v5.8.1）
  resultParamName: __data
  resultHeaderName: x-header
1
2
3
4
5

方案二：全局开启

# Web 相关
web:
  # 是否默认对结果进行统一包装为：{ code: 200, msg: "", data: {} | [] }（v5.8.1）
  # 注意：如果设置为 true 会对页面访问产生影响，暂时只为系统纯接口提供开启使用。
  isDefaultResult: false
1
2
3
4
5

# 会话失效，刷新 Token

token 就是 __sid，当会话失效后，系统会返回 "result":"login" 则代表 __sid 已失效，需要重新登录。

v4.2.3 及之后版本，已经实现手机端的记住我功能，原理步骤如下：（ jeesite-uniapp 已实现）

  1. 登录增加 param_remember=true 参数。
  2. 登录成功后，响应头里会包含 x-remember 记住我数据，自行进行存储到手机内存卡。
  3. 在需要自动登录的 url 里增加 x-remember 请求头，设置上次存储的记住我数据。
  4. JeeSite 服务端接口，收到请求头里的 x-remember 数据，则会自动检测登录。

注意：记住我数据的加密秘钥，通过下面的参数设置，若不设置每次重启服务后记住我数据将失效：

shiro:
  # 记住我密钥设置，您可以通过 com.jeesite.test.RememberMeKeyGen 类快速生成一个秘钥。
  # 若不设置，则每次启动系统后自动生成一个新秘钥，这样会导致每次重启后，客户端记录的用户信息将失效。
  rememberMe:
    secretKey: ~
1
2
3
4
5

v4.2.2 及之前版本，您需要写一个通用的 post 或 get 方法，逻辑如下：

  1. 正常调用业务地址，若返回 "result":"login" 则代表 __sid 会话已失效，需要重新登录，否则正常处理；
  2. 若会话已失效，则重新调用 login 登录方法重新获取新的 __sid；
  3. 根据新的 __sid 再调用业务地址，返回正确数据。

伪代码如下：

var __sid = ''; // 当前 sid
function post(url, data, callback){
	$.post('http://host/'+url, {__sid: __sid}, function(data){
		// 如果 sid 失效，则刷新 sid 并重试
		if (Object.prototype.toString.call(res) === '[object Object]'
				&& data.result == 'login'){
			refreshSid(function(data){
				if (data.result == 'true'){
					$.post('http://host/'+url, {__sid: __sid}, function(data){
						callback(data);
					});
				}else{
					// 身份认证失败
					callback(data);
				}
			});
		}else{
			callback(data);
		}
	});
}
function refreshSid(callback){
	// 注意：此处手机登录后可以生成一个当前手机设备的 uuid，将此 uuid 存储到，用户表的 mobileImei 字段
	//       下面请求的这个 /mobile/login 地址为开发者自己实现，通过存储的 uuid 无条件登录系统。
	//       uuid 的时效性可以自己控制，解绑设备，清理该 uuid 即可。
	$.post('http://host/a/mobile/login', {uuid: '', __sid: __sid}, function(data){
		if (data.result == 'true'){
			__sid = data.sessionid;
		}
		callback(data);
	});
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 快速单点登录接口

详见：简单登录接口

# OAuth2 第三方登录

详见：oauth2-第三方登录

# 无条件登录接口

详见：无条件登录接口

# 更多登录方式

比如您的业务上可能会有根据设备码登录、根据手机号登录、根据加密狗或UKey登录等等。这时您可以找到 AuthorizingRealm 类的 getUserInfo 方法，修改为您需要根据什么条件查询，对应用户信息返回即可实现。

# 其它常用接口

在登录成功的信息里，也有个 sessionid 属性，该属性值将作为您以后访问系统的凭证，相当于token令牌，举例如下：

1、获取用户权限信息：
  http://127.0.0.1:8980/js/a/authInfo?__sid=5fe9c7c45ded4425b03eff8f78179637
2、获取用户菜单信息：
  http://127.0.0.1:8980/js/a/menuTree?__sid=5fe9c7c45ded4425b03eff8f78179637
3、重新获取登录信息：
  http://127.0.0.1:8980/js/a/index?__ajax=json&__sid=5fe9c7c45ded4425b03eff8f78179637
4、获取当前用户信息：
  http://127.0.0.1:8980/js/a/sys/user/info?__ajax=json&__sid=5fe9c7c45ded4425b03eff8f78179637
5、获取数据字典列表：
  http://127.0.0.1:8980/js/a/sys/dictData/treeData?dictType=sys_status&__sid=5fe9c7c45ded4425b03eff8f781...
1
2
3
4
5
6
7
8
9
10

# 更多接口发现

教给大家一个接口发现的方法。

v4.2.0+ 版本，链接增加 __ajax=json 参数，或增加 __ajax=xml 参数，或增加 __ajax 的 Header 请求头。

举例：用户列表的访问地址是 /a/sys/empUser/list，如果直接访问，则返回页面的视图界面，如果加 __ajax=json 参数，则返回视图所需要的json 数据，如：/a/sys/empUser/list?__ajax=json，这样返回的数据，就可以在您的前端分离应用中使用了。

v4.1.9 及之前版本，链接地址增加 .json 或 .xml 后缀。如：/a/sys/empUser/list.json，即可返回视图数据。

在 v4.2.0 版本中默认关闭了 .json、.xml 后缀匹配视图，您可以通过以下参数设置为 true 启用：

# Web 相关
web:
  # MVC 视图相关
  view:
    # 使用 .json、.xml 后缀匹配视图（不推荐使用，推荐使用 favorParameter） v4.2.0
    favorPathExtension: false
    # 使用 __ajax=json、__ajax=xml 参数名匹配视图  v4.2.0
    favorParameter: true
1
2
3
4
5
6
7
8

所有列表加载的数据均使用 listData 为后缀获取数据，如用户列表的数据地址为 /a/sys/empUser/listData，则直接返回表格所需的 JSON 数据。

listData 只是一个命名规则，如果您发现了不遵循规范的地址，怎么办？您可以通过Chrome浏览器的开发者界面(F12)，打开 Network，Filter 中选择 XHR，好了，准备就绪，这是您点击列表里的查询按钮，即可监控到访问的数据的地址是什么

# 开发一个API接口

在您的 Controller 映射方法上增加 @ResponseBody 即可返回 JSON 数据，而不返回视图

或者替换 @Controller 为 @RestController，则应用所有映射方法均返回JSON数据。

如果您想两用，就如 接口发现 章节所述，增加 .json 后缀即可。

另外，对于移动端或高并发的应用对于流量是非常珍贵的，通用方法可能会返回一些很多无用的数据，这时，您可以使用 @JsonView 注解进行配置，返回需要的数据即可。

# Swagger 在线文档

当外部系统调用 JeeSite 或者前后端分离开发的过程中的 API 接口对接交互时，就需要一个 API 规范文档，来方便数据参数对接。

但 API 文档不能根据代码的变化发生实时动态的改变，这样服务端修改了接口，调用端不能及时获取最新的接口，导致调用出错。这时需要手动维护 API 文档，加大了开发的工作量和困难，而 Swagger 的出现就是为了解决这一系列的问题。并且还提供了接口的在线测试功能。

JeeSite 对此进行封装，简化简单接口调用，实现自动扫描指定包下的 Controller 和 @Table 注解获取字段备注信息，更适合中国用户的习惯，提供更方便接口生成维护。实现分布式微服务情况下的 API 分模块管理。

新增模块方法：

@Configuration
@ConditionalOnProperty(name="web.swagger.enabled", havingValue="true", matchIfMissing=false)
public class CustomApiConfig {

	@Bean
	@ConditionalOnProperty(name="web.swagger.custom.enabled", havingValue="true", matchIfMissing=true)
	public Docket customApi() {
		String moduleCode = "custom";
		String moduleName = "自定义模块";
		String basePackage = "com.jeesite.modules.custom.web";
		return SwaggerConfig.docket(moduleCode, moduleName, basePackage)
				.select()
				.apis(
//						Predicates.and(Predicates.and(
//						RequestHandlerSelectors.withClassAnnotation(Api.class),
//						RequestHandlerSelectors.withMethodAnnotation(ResponseBody.class)),
//						RequestHandlerSelectors.basePackage(basePackage))
						RequestHandlerSelectors.basePackage(basePackage)
					).build();
	}
	
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

注解：

// 写在 Controller 类上
@Api(tags = "类的说明")

// 写在 Controller 类的方法上
@ApiOperation(value = "方法的说明")
@ApiImplicitParams({
	@ApiImplicitParam(name = "参数名", value = "参数说明", required = 是否必填, paramType="参数类型", type="String"),
})
// 请求参数属性：
// 	paramType 指参数的类型
// 		* header：请求头的获取：@RequestHeader
// 		* query：请求参数的获取：@RequestParam
// 		* path：请求路径变量的获取：@PathVariable
// 		* body：请求数据包：@RequestBody
// 	type：参数类型，默认 String，数值：dataType="Integer"
// 	defaultValue：参数的默认值

// 写在 Entity 类上
@ApiModel("实体类的说明")

// 写在 Entity 的属性或get方法上
@ApiModelProperty("实体类属性或请求参数的说明")

// 忽略属性，写在 get 方法上
@ApiIgnore
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

当设置 ApiImplicitParams 的时候，ApiModelProperty 设置自动忽略

例子：

https://gitee.com/thinkgem/jeesite5/blob/v5.7/modules/core/src/main/java/com/jeesite/modules/sys/web/AccountController.java (opens new window)

单机版：

访问地址：http://127.0.0.1:8980/js/swagger-ui.html (opens new window)

微服务版：

地址模板：http://127.0.0.1:8980/js/{spring.application.name}/swagger/swagger-ui.html

例如：http://127.0.0.1:8980/js/jeesite-cloud-module-test1/swagger/swagger-ui.html (opens new window)

访问权限：

默认需要 perms[swagger]权限（即有在线文档菜单的用户）才可以访问，如果想不用授权即可访问，可修改如下配置：

shiro:
  filterChainDefinitions: |
    ${adminPath}/${spring.application.name}/swagger/** = anon
    ${adminPath}/** = user
1
2
3
4

提示：在原有配置上添加 swagger 的地址权限，必须放到 ${adminPath}/** = user 权限上面。

# 安全参数配置

一些安全配置，解决：请求方法限定、一个账号多地登录、是否允许刷新主页、是否允许嵌入iframe、 是否允许跨域及跨域访问的域名设置、跨域访问允许的方法和标头、允许来源地址等。

# Shiro 相关配置
shiro:

  # 指定获取客户端IP的Header名称，防止IP伪造。指定为空，则使用原生方法获取IP。
  remoteAddrHeaderName: X-Forwarded-For

  # 允许的请求方法设定，解决安全审计问题（BPM设计器用到了PUT或DELETE方法）
  allowRequestMethods: GET, POST, OPTIONS, PUT, DELETE
  
  # 是否允许账号多地登录，如果设置为false，同一个设备类型的其它地点登录的相同账号被踢下线
  isAllowMultiAddrLogin: true
  
  # 是否允许多账号多设备登录，如果设置为false，其它地点登录的相同账号全部登录设备将被踢下线
  isAllowMultiDeviceLogin: true
  
  # 是否允许刷新主框架页，如果设置为false，刷新主页将导致重新登录。如安全性比较高的，如银行个人首页不允许刷新。
  isAllowRefreshIndex: true
  
  # 是否允许嵌入到外部网站iframe中（true：不限制，false：不允许）
  isAllowExternalSiteIframe: true
  
  # 设定允许获取的资源列表（v4.2.3）
  contentSecurityPolicy: "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; img-src 'self' 'unsafe-inline' 'unsafe-eval' data:"
  
  # 是否允许跨域访问 CORS，如果允许，设置允许的域名。v4.2.3 开始支持多个域名和模糊匹配，例如：http://*.jeesite.com,http://*.jeesite.net
  accessControlAllowOrigin: '*'
  
  # 允许跨域访问时 CORS，可以获取和返回的方法和请求头
  accessControlAllowMethods: GET, POST, OPTIONS
  accessControlAllowHeaders: content-type, x-requested-with, x-ajax, x-token, x-remember
  accessControlExposeHeaders: x-remember
  
  # 是否允许接收跨域的Cookie凭证数据 CORS
  accessControlAllowCredentials: false
  
  # 允许的网站来源地址，不设置为全部地址（避免一些跨站点请求伪造 CSRF、防盗链）
  allowReferers: http://127.0.0.1,http://localhost
  
  # 是否在登录后生成新的Session（默认false）
  isGenerateNewSessionAfterLogin: false
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
进入 JeeSite 源码仓库页面，点击右上角 ⭐ Star 加星关注。

← ★ 常见问题 ★→

联系我们：s.jeesite.com  |  微信号：jeesitex  |  邮箱：jeesite@163.com
© 2013-2024 济南卓源软件有限公司 版权所有 | Theme Vdoing

请关注 JeeSite 微信公众号，了解最新动态