MicroZeroApi规范

API规范

1. 调用方式

Http restful

2. Http Method

GET/POST

3. 参数

采用小驼峰命名规则，文字编码为UTF8,支持内容

传参方式

尽量使用 Url参数 \ Form \Json中的一种方式传递

Json应通过Http协议中的Context写入

系统内部接收规则

• 如果存在Json，则Form与Url参数作为扩展参数（参见GlobalContext说明）处理
• Form与Url参数
  系统先接收Url参数再接收Form参数,所以如果在两处都存在的同名参数,以Form提交的为准
  如Url为:

http://www.microzero.club/Demo/api/v1/test?name=agebull&nike=niu

Form为

name=ab&title=hutian

解析结果为

{
	"name" : "ab",
	"nike" : "niu",
	"title": "hutian"
}

固定参数:

• sign：验签（HTTP不需要）
• token：令牌即用户标识,可能是登录用户的交易标识,也可能是未登录用户的设备标识
• timestamp：UNIX时间戳

4. 返回值

C#	JSON	类型	说明
RequestId	requestId	string	API请求标识
OperatorId	operatorId	string	API操作标识
Success	success	bool	成功或失败标记
ResultData	data	object	API请求返回的个性数据，可以是一个单值，也可以是一个对象
Status	status	OperatorStatus	API状态返回接口实现

说明:

1. success（必有） 标明操作是否成功
2. data是否出现有两个前提，首先要API接口定义有返回值，其次在success为true时返回数据。如需要在success为false也返回数据时，请在API接口文档中着重说明。
3. status在success为false时必须有值，为true时需要状态的话，请在API接口文档中着重说明

Status

C#	JSON	类型	标题	说明	示例
GuideCode	guide	string	指导码	内部使用:指示下一步应如何处理的代码	retry
Describe	describe	string	内部错误说明	详细说明错误内容	系统未就绪
Point	point	string	错误点	系统在哪一个服务节点发生错误	gateway
ErrorCode	code	int	错误码	参见 ErrorCode 说明	-1
HttpCode	http	string	HTTP错误码	参考性使用	404
ClientMessage	msg	string	提示信息	给用户显示的消息内容	你的数据不正确

ErrorCode

标题	名称	数值
正确	Success	0
发生异常	LocalException	-1
逻辑错误	LogicalError	-2
远端错误	RemoteError	-3
本地错误	LocalError	-4
网络错误	NetworkError	-5
系统未就绪	NoReady	-10
客户端应中止请求	Ignore	-11
客户端应重新请求	ReTry	-12
拒绝访问	DenyAccess	-13
方法不存在	NoFind	404
服务不可用	Unavailable	503
未知的RefreshToken	Auth_RefreshToken_Unknow	40083
未知的ServiceKey	Auth_ServiceKey_Unknow	40082
未知的AccessToken	Auth_AccessToken_Unknow	40081
未知的用户	Auth_User_Unknow	40421
未知的设备识别码	Auth_Device_Unknow	40022
令牌过期	Auth_AccessToken_TimeOut	40036

5. 示例:

请求

var url = 'http://www.microzero.club/Demo/api/v1/test?timestamp=1258525445';
$.ajax({
        url: url ,
        type: 'post',
        dataType: 'json',
        timeout: 30,
        headers: {
            "Authorization": "Bearer #AEDGEFDSFSE"
        },
        data: {
			"name" : "agebull",
			"nike" : "老牛"
		},
        /**
         * 成功回调
         * @param {string} jsonStr 文本
         * @returns {void} 
         */
        success: function (jsonStr) {
        	console.log(`success: ${url} => ${jsonStr}`);
            try {
            	var res = eval(`(${jsonStr})`);
            	if(res.success){
            		onSucceed(res);
            	}else if(res.status){
            		switch (result.status.code) {
				        case 40036:
				            refreshAt();
				            return;
				        case 40022:
				        case 40001:
				        case 40083:
				        case 40082:
				        case 40081:
				        case 40421:
				            showLogout();
				            return;
				    }
				    onFailed(res);
            	}
            } catch (ex) {
                console.exception(ex);
            }
        },
        /**
         * 异常回调
         * @param {object} xhr  xhr
         * @param {object} type type
         * @param {object} errorThrown errorThrown
         * @returns {void}  
         */
        error: function (xhr, type, errorThrown) {        	
        	console.log(`error: ${url} => ${type}`);
            showServerNoFind(title);
            onFailed({
            	success:false,
            	status :{
            		code = -999,
            		msg :type
           		}
        	});
        },
        complete: function () {
            hideBusy();
        }
    });

返回值

{
	'success' : false,
	'requestId' : 'API请求标识' ,
	'operatorId' : 'API操作标识' ,
	'status' : {
	'guide' : 'retry' ,
	'describe' : '系统未就绪' ,
	'point' : '1' ,
	'code' : -1 ,
	'http' : '404' ,
	'msg' : '你的数据不正确' 
	} 
}