Ajax 接口约定

KMS 所支持的网络请求类型如下列表，每种支持格式都有一些约定，遵守这些约定将会简化很多额外的配置：

jsonp

jsonp 是通过 script 标签请求的一段特殊的 JavaScript 代码，通过请求参数传递回调函数的函数名。有以下约定：

传递回调函数名的参数名为 callback 并仅仅支持字符和数字
请求不支持 KMS 签名

提示

在 KMS 网络配置中，支持更换回调函数名的参数名，也支持静态的回调函数名，不过那些都需要额外配置而不是默认值状态。

script

script 方式跟 jsonp 有点相似，也是通过 script 加载一段 JavaScript 代码，只不过不是执行一个回调函数，而是写入一个 window 全局变量。有以下约定：

传递全局变量名的参数名为 var 并仅仅支持字符和数字
请求不支持 KMS 签名

提示

在 KMS 网络配置中，支持更换全局变量名的参数名，也支持静态的变量名。通常 script 方式比 jsonp 更灵活一些，可以在页面 head 区域提前加载一些必要配置，在业务代码加载完毕时直接从全局变量中读取即可。

ajax

KMS 对于前后端 ajax 请求，有如下的格式约定：

请求和响应都基于 json 即 application/json

默认解析策略

系统默认的 ajax 返回内容解析策略如下：

HTTP 状态码错误时 statusCode <200 或者 statusCode >= 400
将 response.body 解析为 json，并依次从 message desc msg 字段中读取错误信息
HTTP 状态码成功时 statusCode >=200 并且 statusCode < 400
将 response.body 解析为 json，并尝试读取 data 字段作为返回数据，如果字段没有值（undefined, null, NaN）则将整个 json 作为数据内容；
从 json 中依次读取 message desc msg 作为成功提示消息，如果没有值，则不提示；如果消息为 ok success done successed 则忽略消息也不提示

自定义解析策略

当上述默认策略不能满足要求时，可以自定义响应处理策略。功能路径如下：

系统设置 - 项目配置 - 功能配置 - ajax内容解析

错误信息字段和提示字段，都支持设置多个值，以半角逗号分割

讨论

对于多数页面功能来说，只需要 { data, message } 两个字段即可，一个用来承载具体的业务数据，一个用来指示要提示的消息。在 KMS 内部所有的 ajax 请求响应内容，都会被强制转成 { data, message } 格式以保持格式统一以及扩展能力（比如增加数据分页信息 pagination 字段）。

但 message 缺少类型信息，不考虑消息的样式，这已经足够了。但通常需要区分两个消息样式：错误消息和成功消息。KMS 默认策略中，以 HTTP 状态码作为识别消息类型的参考，而在自定义策略中，可以通过额外的 json 字段，比如 code 或者 err 来指示更细化场景下的提示消息类型；

upload

上传类型的网络请求，在普通 ajax 的约定之外，额外增加以下约定：

请求类型固定为 mulipart/form-data 类型，所有参数均通过 Post Body 发送
文件二进制的字段名固定为 file，不支持修改

download

下载请求是一个特殊的表单提交，而非 ajax。有如下约定：

请求不支持 KMS 签名
请求需要自行处理 Content-Type 以触发浏览器下载

Ajax 接口约定 ​

jsonp ​

script ​

ajax ​

默认解析策略 ​

自定义解析策略 ​

upload ​

download ​