全部产品
云市场

iOS接入

更新时间:2019-12-05 15:16:00

一、MTOPSDK初始化

  • 指定仓库:
  1. source 'git@gitlab-ce.emas-poc.com:EMAS-iOS/emas-specs.git'
  • 添加依赖:
  1. pod 'MtopSDK', '10.1.3'
  2. pod 'mtopext/MtopCore', '10.1.2'

作为基础中间件请使用方尽量早的初始化MtopSDK,建议在程序启动后AppDelegate中的didFinishLaunchingWithOptions回调中就完成初始化的工作;

MTOPSDK以全局单例’TBSDKConfiguration’配置来进行初始化;初始化代码如下:

  1. #import "AppDelegate.h"
  2. #import "TBSDKConfiguration.h"
  3. #import "TBSDKLogUtil.h"
  4. @interface AppDelegate ()
  5. @end
  6. @implementation AppDelegate
  7. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  8. // 步骤一、获取配置单例 在MTOP初始化时禁用获取deviceID和获取服务端时间接口
  9. TBSDKConfiguration *mtopconfig = [TBSDKConfiguration shareInstanceDisableDeviceID:YES andSwitchOffServerTime:YES];
  10. // 步骤二、设置mtop环境,iOS SDK设置为release环境
  11. config.environment = TBSDKEnvironmentRelease;
  12. // 步骤三、选择是否使用安全保镖,外部版本一律设置为NO
  13. config.safeSecret = NO;// EMAS版本的MTOP不依赖安全保镖,这里设为NO
  14. // 步骤四、对于没有使用安全保镖的情况下,用户需要设置应用的appkey、appSecert
  15. config.appKey = @"4272";
  16. config.appSecret = @"xxxx";
  17. // 步骤五、 全局定制MTOP网关域名
  18. config.wapAPIURL = @"xxxx" //设置全局自定义域名
  19. // 步骤六、全局设置MTOP请求通道,使用HTTPS or HTTP(默认使用HTTPS)
  20. config.enableHttps = yes; // 是否开启HTTPS,默认yes
  21. // 步骤七、设置APP渠道ID
  22. config.wapTTID = @"xxxx" // 渠道ID格式:渠道号@应用名_平台名_应用版本号
  23. // 步骤八、设置MTOP协议版本
  24. // config.protocolType = MtopProtocolTypeEmas;// 设置EMAS MTOP协议版本(全局协议版本控制),全局暂时不要设置,在请求中设置。
  25. // 步骤九(可选)、控制开关MTOPSDK日志 (默认关闭状态)
  26. openSDKSwitchLog(yes);
  27. return YES;
  28. }

二、MTOPSDK接口调用

2.1 构造MtopExtRequest请求对象

  • 构造对象
  1. /*!
  2. * 初始化一个API请求对象
  3. * @param apiName API名称
  4. * @param apiVersion API版本
  5. * @return MtopExtRequest请求
  6. */
  7. - (MtopExtRequest*) initWithApiName: (NSString*) apiName apiVersion: (NSString*) apiVersion;
  • 添加自定义请求头
  1. /*!
  2. * 添加一个http请求头
  3. * @param value HTTP头value, 请不要做urlencode, 底层会统一做的
  4. * @param key HTTP头key
  5. * @return MtopExtRequest 以便可以链式操作
  6. */
  7. - (MtopExtRequest*) addHttpHeader: (NSString*) value forKey: (NSString*) key;
  • 添加请求业务参数
  1. /*!
  2. * 添加一个业务参数(业务级别参数)
  3. * @param value 参数值
  4. * @param key 参数名
  5. * @return MtopExtRequest 以便可以链式操作
  6. */
  7. - (MtopExtRequest*) addBizParameter: (id) value forKey: (NSString*) key;
  • 设置MTOP请求类型(默认请求为GET模式)
  1. /*!
  2. * 使用post请求
  3. * @return MtopExtRequest 以便可以链式操作
  4. */
  5. - (MtopExtRequest*) useHttpPost;
  • 指定MTOP请求级别域名
  1. @property (nonatomic, strong) NSString* customHost; // 设置该属性可指定请求级别自定义域名
  • 指定MTOP请求级别的协议类型
  1. @property (nonatomic, assign) MtopProtocolType protocolType;// mtop协议版本

2.2 调用全局MtopService服务发送Mtop请求

  • 获取MtopService单例
  1. /*!
  2. * 获取单例
  3. */
  4. + (MtopService*) getInstance;
  • 同步发送MTOP请求API
  1. /**
  2. * 同步调用API
  3. *
  4. * @param request
  5. * @return MtopExtResponse API响应
  6. */
  7. - (MtopExtResponse*) sync_call: (MtopExtRequest*) request;
  • 异步发送MTOP请求API
  1. /**
  2. * 异步调用API
  3. *
  4. * @param request
  5. * @param delegate (请求回调代理)
  6. *
  7. */
  8. - (void) async_call: (MtopExtRequest*) request delegate: (id<MtopExtRequestDelegate>) delegate;
  • MTOP请求结果回调(提供代理回调和Block回调两种方式)
  1. 代理协议回调
  2. @protocol MtopExtRequestDelegate<NSObject>
  3. /*!
  4. * 请求开始执行时回调 (开始发送网络请求)
  5. */
  6. @optional
  7. -(void) started: (MtopExtRequest*) request;
  8. /*!
  9. * 失败回调, 注意: 我们用的是主线程回调
  10. * @param response response.error 是错误信息
  11. */
  12. -(void) failed: (MtopExtResponse*) response;
  13. /*!
  14. * 成功回调, 注意: 我们用的是主线程回调
  15. * @param response response.error 是错误信息
  16. */
  17. -(void) succeed: (MtopExtResponse*) response;
  18. Block回调 (Block回调请在构造 MtopextRequest请求对象时设置相应的成功失败回调)
  19. =================================================================
  20. /*!
  21. * 请求开始, 回调block
  22. * @param request
  23. */
  24. typedef void (^MtopExtRequestStarted)(MtopExtRequest* request);
  25. /*!
  26. * 请求失败, 回调block
  27. * @param request
  28. */
  29. typedef void (^MtopExtRequestFailed)(MtopExtResponse* response);
  30. /*!
  31. * 请求成功, 回调block
  32. * @param request
  33. */
  34. typedef void (^MtopExtRequestSucceed)(MtopExtResponse* response);

2.3 JSON 透传控制功能

  • 背景说明:

    默认mtop请求中业务参数,无论是GET请求URL中query, 还是POST请求body中kv, 都需要业务在mtop 网关做参数映射,如果业务某个api需要新增参数,且不希望新增mtop网关映射参数,则可以通过“透传”的方式,当 mtop 网关遇到开启“透传”功能API, 请求body中的数据直接透传给业务。

  • 注意事项:

    • 透传功能必须使用 POST 方式
    • 参数格式需要JSON格式,其合法性由业务保证
  • 使用说明:
  1. MtopExtRequest* request = [[MtopExtRequest alloc] initWithApiName: apiName apiVersion: apiVersion];
  2. // 设置协议类型,只有该类型支持透传,必须设置
  3. request.protocolType = MtopProtocolTypeEmas;
  4. // 赋值透传参数,需要json格式,合法性由业务保证
  5. request.jsonBody = @"{\"k1\":\"v1\", \"k2\":\"v2\"}";
  6. .....

2.4 请求响应MtopExtResponse

  1. MtopExtResponse类属性
  2. @interface MtopExtResponse : NSObject
  3. @property(assign, nonatomic) int httpResponseCode; // http 响应码
  4. @property(strong, nonatomic) Error* error; // 错误信息
  5. @property(strong, nonatomic) NSMutableDictionary* headers; // http响应头
  6. @property(strong, nonatomic) NSData* rawbody; // 原始的http响应body
  7. @property(strong, nonatomic) NSString* body; // 原始的http响应body
  8. @property(strong, nonatomic) NSDictionary* json; // json响应,从http body 解析
  9. @property(assign, nonatomic) BOOL isFromCache; // 响应是否来至cache
  10. @property(assign, nonatomic) BOOL isCacheExpired; // cache是否失效了
  11. @property(strong, nonatomic) MtopExtRequest* request; // 响应对应的API Request
  12. ===================================================================
  13. 1.同步请求直接获取错误码或响应, 异步请求在回调中获取错误码或响应数据
  14. 2.通过MtopExtResponse获取响应数据或错误码
  15. ===================================================================
  16. 判断响应是否成功 (调用 ErrorisSucceed方法)
  17. YES: 服务端返回 SUCCESS
  18. NO: 任何错误: 客户端错误 + mtop服务端错误 + 后端业务错误
  19. BOOL isSucceed = [response isSucceed];
  20. // 获取错误码
  21. Error* error = response.error;
  22. // error.httpResponseCode http响应码
  23. // error.code 错误码
  24. // error.msg 错误提示信息
  25. // error.subCode 子错误码
  26. // error.subMsg 子错误提示信息
  27. // 获取服务端响应json
  28. NSDictionary* json = response.json;
  29. // 获取服务端响应头
  30. NSDictionary* headers = response.headers;
  31. // 获取服务端返回http body(JOSN字符串)
  32. NSString* body = response.body;
  33. // 获取服务端端返回的原始的http body(二进制数据)
  34. NSData* raw = response.rawbody;

三、MTOP接口调用示例

下面提供一个使用MTOPSDK发送请求示例:

  1. - (void)sendMtopRequest {
  2. // 构造MTOP请求
  3. MtopExtRequest *request = [[MtopExtRequest alloc] initWithApiName:@"mtop.mediaplatform.live.livedetail" apiVersion:@"3.0"];
  4. // 设置请求级别的MTOP请求协议
  5. request.protocolType = MtopProtocolTypeEmas; // 设置EMAS MTOP协议版本(请求级别版本控制)
  6. // 默认请求为GET (MTOPSDK目前支持POST、GET两种请求方式),发送POST请求
  7. [request useHttpPost];
  8. // 给请求设置业务参数
  9. [request addBizParameter:[NSNumber numberWithBool:true] forKey:@"testBool"];
  10. [request addBizParameter:[NSNumber numberWithInteger:2] forKey:@"testInteger"];
  11. [request addBizParameter:[NSNumber numberWithBool:false] forKey:@"testBoolean"];
  12. [request addBizParameter:@"test" forKey:@"testStr"];
  13. [request addBizParameter:[NSNumber numberWithInt:1] forKey:@"testInt"];
  14. // 特别注意,在业务参数为doule类型时请使用NSDecimalNumber类进行包装,切勿使用NSNumber类,使用NSNumber类会导致请求的double参数精度丢失
  15. [request addBizParameter:[NSDecimalNumber numberWithDouble:1.1] forKey:@"testDoub"];
  16. [request addBizParameter:[NSDecimalNumber numberWithDouble:1.2] forKey:@"testDouble"];
  17. // 添加自定义请求头
  18. [request addHttpHeaders:headers];
  19. // Block形式回调
  20. request.startedBlock = ^(MtopExtRequest *request) {
  21. NSLog(@"start mtop request..");
  22. };
  23. request.failedBlock = ^(MtopExtResponse *response) {
  24. NSLog(@"mtop request failed..");
  25. // 获取响应错误ERROR
  26. Error *error = respnse.error;
  27. // 获取错误码 & 错误信息 & 错误码映射信息
  28. NSString *errorCode = error.code;
  29. NSString *errorMsg = error.msg ;
  30. NSString *errorMappingCode = error.mappingCode;
  31. ...........
  32. };
  33. request.succeedBlock = ^(MtopExtResponse *response) {
  34. NSLog(@"mtop request success..");
  35. NSDictionary *responseDict = response.json;
  36. // 获取响应的业务data
  37. NSDictionary *bizResponseData = [respnse.json objectForKey:@"data"];
  38. /* 业务Data解析时需要特别注意服务端返回JSON数据存在有字段可能为‘null’空的情况,使用MTOP返回的字典转模型时候需要注意对‘NSNull’的兼容
  39. * 假设下面数据为服务端返回的json数据
  40. * {
  41. * "api":"mtop.bizmock.test.simpleparam",
  42. * "ret":"SUCCESS::接口调用成功",
  43. * "v":"1.0",
  44. * "data":{"price":null}
  45. * }
  46. *
  47. * 在得到业务参数做字典转模型的时候判断下解析参数的类型是否与模型定义的属性一致,防止因类型不一致导致的'unrecognized selector sent to instance' crashdata
  48. * if ([bizResponseData isKindOfClass:[NSString Class]]){
  49. * price = [bizbizResponseData obejctValueForKey:@"price"];
  50. * }
  51. */
  52. ............
  53. };
  54. // 异步接口调用MTOP请求,设置回调代理
  55. [[MtopService getInstance] async_call:request delegate:self];
  56. }
  57. /**
  58. mtop开始请求回调
  59. @param request mtop请求对象
  60. */
  61. - (void)started:(MtopExtRequest *)request {
  62. NSLog(@"start mtop request..");
  63. }
  64. /**
  65. mtop请求成功回调
  66. @param response mtop响应对象
  67. */
  68. - (void)succeed:(MtopExtResponse *)response {
  69. NSDictionary *responseDict = response.json;
  70. // 获取响应的业务data
  71. NSDictionary *bizResponseData = [respnse.json objectForKey:@"data"];
  72. .........
  73. }
  74. /**
  75. mtop请求失败回调
  76. @param response mtop响应对象
  77. */
  78. - (void)failed:(MtopExtResponse *)response {
  79. // 获取响应错误ERROR
  80. Error *error = respnse.error;
  81. // 获取错误码 & 错误信息
  82. NSString *errorCode = error.code;
  83. NSString *errorMsg = error.msg ;
  84. NSString *errorMappingCode = error.mappingCode;
  85. ...........
  86. }

四、特别注意事项

1.调用 - (MtopExtRequest*) addBizParameter: (id) value forKey: (NSString*) key方法添加业务参数当业务参数为doule类型时请使用NSDecimalNumber类进行包装,切勿使用NSNumber类,使用NSNumber类会导致请求的double参数精度丢失

2.特别注意服务端返回JSON数据存在有字段可能为‘null’空的情况,业务在使用MTOP返回的字典转模型时候需要注意对‘NSNull’的兼容; (如果您的APP已对NSNULL做过保护请忽略)

五、iOS端错误码说明

1.iOS端MTOPSDK错误对象(Error类)属性定义

httpResponseCode: 请求响应码

code: 服务端返回的错误编码(为更好的用户体验不建议业务直接对外输出)

msg: 服务端返回错误信息(对于非业务错误:网关错误统一文案’服务竟然出错了’,网络错误统一文案’网络竟然崩溃了’,网关防刷限流统一文案‘前方拥堵,亲稍候再试’)

mappingCode: 错误映射编码,方便及时准确定位具体错误(建议业务对外透出该错误编码)格式: 网络库状态码StatusCode + 客户端标识(I代码IOS,A代表Android)+错误分类E + 错误数字编码5位(XXXXX)错误分类E 说明

  • ES 代表 Mtop服务端错误 FAIL_SYS前缀
  • EC 代表 MtopSDK客户端错误
  • 错误数字编码根据具体的错误分类定义

网络状态码列表

  • iOS端底层网路库长连状态码
  1. {-1900, EC_NONE_NETWORK/*network unreachable*/},
  2. {-3860, EC_CONNECT_FAILED/*HTTP2 error: receive 'goaway' frame, server close connection*/},
  3. {-3861, EC_CONNECT_FAILED/*HTTP2 error: PROTOCOL_ERROR (0x1)*/},
  4. {-3862, EC_CONNECT_FAILED/*HTTP2 error: INTERNAL_ERROR (0x2)*/},
  5. {-3863, EC_CONNECT_FAILED/*HTTP2 error: FLOW_CONTROL_ERROR (0x3)*/},
  6. {-3864, EC_CONNECT_FAILED/*HTTP2 error: SETTINGS_TIMEOUT (0x4)*/},
  7. {-3865, EC_CONNECT_FAILED/*HTTP2 error: STREAM_CLOSED (0x5)*/},
  8. {-3866, EC_CONNECT_FAILED/*HTTP2 error: FRAME_SIZE_ERROR (0x6)*/},
  9. {-3867, EC_CONNECT_FAILED/*HTTP2 error: REFUSED_STREAM (0x7)*/},
  10. {-3868, EC_CONNECT_FAILED/*HTTP2 error: CANCEL (0x8)*/},
  11. {-3869, EC_CONNECT_FAILED/*HTTP2 error: COMPRESSION_ERROR (0x9)*/},
  12. {-3870, EC_CONNECT_FAILED/*HTTP2 error: CONNECT_ERROR (0xA)*/},
  13. {-3871, EC_CONNECT_FAILED/*HTTP2 error: ENHANCE_YOUR_CALM (0xB)*/},
  14. {-3872, EC_CONNECT_FAILED/*HTTP2 error: INADEQUATE_SECURITY (0xC)*/},
  15. {-3873, EC_CONNECT_FAILED/*HTTP2 error: HTTP_1_1_REQUIRED (0xD)*/},
  16. {-3900, EC_CONNECT_FAILED/*L7 encryption parsing error*/},
  17. {-2001, EC_CONNECT_FAILED/*no connection*/},
  18. {-2002, EC_CONNECT_FAILED/*close connection actively*/},
  19. {-2003, EC_CONNECT_TIMEOUT/*connecting timeout*/},
  20. {-2004, EC_CONNECT_TIMEOUT/*request timeout*/},
  21. {-2005, EC_CONNECT_FAILED/*spdy stream reset by peer*/},
  22. {-2010, EC_CONNECT_FAILED/*parse spdy protocol error*/},
  23. {-2011, EC_CONNECT_FAILED/*invalid stream*/},
  24. {-2015, EC_CONNECT_FAILED/*spdy internal error*/},
  25. {-2017, EC_CONNECT_FAILED/*duplicated stream id*/},
  26. {-2018, EC_CONNECT_FAILED/*spdy error*/},
  27. {-2030, EC_CONNECT_FAILED/*call tnet stop*/},
  28. {-2031, EC_CONNECT_FAILED/*allocate memory failed*/},
  29. {-2032, EC_CONNECT_FAILED/*connection closed by server*/},
  30. {-2035, EC_CONNECT_FAILED/*slight ssl error*/},
  31. {-2036, EC_CONNECT_FAILED/*initialize connection failed*/},
  32. {-2037, EC_CONNECT_FAILED/*send data error*/},
  33. {-2042, EC_CONNECT_FAILED/*parse package error*/},
  34. {-2045, EC_CONNECT_FAILED/*process callback error*/},
  35. {-2046, EC_CONNECT_FAILED/*readidle callback error*/},
  36. {-2047, EC_CONNECT_FAILED/*spdy ping callback error*/},
  37. {-2048, EC_CONNECT_FAILED/*on idle callback error*/},
  38. {-2050, EC_CONNECT_FAILED/*unknown error*/},
  39. {-2108, EC_CONNECT_FAILED/*read socket error: ENOEXEC 8*/},
  40. {-2109, EC_CONNECT_FAILED/*read socket error: EBADF 9*/},
  41. {-2154, EC_CONNECT_FAILED/*read socket error: ECONNRESET 54*/},
  42. {-2157, EC_CONNECT_FAILED/*read socket error: ENOTCONN 57*/},
  43. {-2160, EC_CONNECT_FAILED/*read socket error: ETIMEDOUT 110*/},
  44. {-2222, EC_CONNECT_FAILED/*send detection ping fail*/},
  45. {-2332, EC_CONNECT_FAILED/*write socket error: EPIPE 32*/},
  46. {-2349, EC_CONNECT_FAILED/*write socket error: EADDRNOTAVAIL 49*/},
  47. {-2354, EC_CONNECT_FAILED/*write socket error: ECONNRESET*/},
  48. {-2360, EC_CONNECT_FAILED/*write socket error: ETIMEDOUT 110*/},
  49. {-2361, EC_CONNECT_FAILED/*write socket error: ECONNREFUSED 111*/},
  50. {-2365, EC_CONNECT_FAILED/*write socket error: EHOSTUNREACH 65*/},
  51. {-2499, EC_CONNECT_FAILED/*connect error: call getsockopt failed*/},
  52. {-2500, EC_CONNECT_FAILED/*connect error: set socket unblock failed*/},
  53. {-2504, EC_CONNECT_FAILED/*connect error: EINTR 4*/},
  54. {-2506, EC_CONNECT_FAILED/*connect error: ENXIO 6*/},
  55. {-2509, EC_CONNECT_FAILED/*connect error: EBADF 9*/},
  56. {-2512, EC_CONNECT_FAILED/*"connect error: ENOMEM 12*/},
  57. {-2513, EC_CONNECT_FAILED/*connect error: EACCES 13*/},
  58. {-2522, EC_CONNECT_FAILED/*connect error: EINVAL 22*/},
  59. {-2524, EC_CONNECT_FAILED/*connect error: EMFILE 24*/},
  60. {-2532, EC_CONNECT_FAILED/*connect error: EPIPE 32*/},
  61. {-2538, EC_CONNECT_FAILED/*connect error: ENOTSOCK 88*/},
  62. {-2549, EC_CONNECT_FAILED/*connect error: EADDRNOTAVAIL 99*/},
  63. {-2551, EC_CONNECT_FAILED/*connect error: ENETUNREACH 101*/},
  64. {-2553, EC_CONNECT_FAILED/*connect error: ECONNABORTED 103*/},
  65. {-2554, EC_CONNECT_FAILED/*connect error: ECONNRESET 104*/},
  66. {-2550, EC_CONNECT_FAILED/*connect error: ENOBUFS 105*/},
  67. {-2560, EC_CONNECT_TIMEOUT/*connect error: ETIMEDOUT 60*/},
  68. {-2561, EC_CONNECT_FAILED/*connect error: ECONNREFUSED 111*/},
  69. {-2565, EC_CONNECT_FAILED/*connect error: EHOSTUNREACH 113*/},
  70. {-2602, EC_CONNECT_FAILED/*connect error: EOPNOTSUPP 102*/},
  71. {-3500, EC_CONNECT_FAILED/*slight ssl error*/},
  72. {-3501, EC_CONNECT_FAILED/*slight ssl error: call read/write failed*/},
  73. {-3502, EC_CONNECT_FAILED/*slight ssl error: allocate memroy failed*/},
  74. {-3503, EC_CONNECT_FAILED/*slight ssl error*/},
  75. {-3504, EC_CONNECT_FAILED/*slight ssl error: ERR_ECDH_FAILED*/},
  76. {-3505, EC_CONNECT_FAILED/*slight ssl error: ERR_STATE_ERROR*/},
  77. {-3506, EC_CONNECT_FAILED/*slight ssl error: ERR_NOT_SUPPORT*/},
  78. {-3509, EC_CONNECT_FAILED/*slight ssl error: ERR_READ_END*/},
  79. {-3510, EC_CONNECT_FAILED/*slight ssl error*/},
  80. {-3511, EC_CONNECT_FAILED/*slight ssl error*/},
  81. {-3512, EC_CONNECT_FAILED/*slight ssl error*/},
  82. {-3513, EC_CONNECT_FAILED/*slight ssl error*/},
  83. {-3514, EC_CONNECT_FAILED/*slight ssl error: ERR_CERT_TOO_LARGE*/},
  84. {-3515, EC_CONNECT_FAILED/*slight ssl error*/},
  85. {-3516, EC_CONNECT_FAILED/*slight ssl error*/},
  86. {-3517, EC_CONNECT_FAILED/*slight ssl error*/},
  87. {-3528, EC_CONNECT_FAILED/*slight ssl error: ERR_HANDSHAKE_ERROR*/},
  88. {-3529, EC_CONNECT_FAILED/*slight ssl error*/},
  89. {-3530, EC_CONNECT_FAILED/*slight ssl error: ERR_GET_PUBKEY*/},
  90. {-3800, EC_CONNECT_FAILED/*unknown error*/},
  91. {-5001, EC_CONNECT_FAILED/*authentication error*/},
  92. {-5002, EC_SESSION_EXPIRED/*no exists spdy session*/},
  93. {-5003, EC_CONNECT_FAILED/*no avaliable policy*/}
  94. {-5004, EC_CONNECT_FAILE/*NETERR_REQUEST_WAITING_TNET_SESSION_TIMEOUT*/}
  • iOS System NetworkErrorCode
  1. * CFNetworkErrors
  2. *
  3. * Discussion:
  4. * The list of all public error codes returned under the error domain
  5. * kCFErrorDomainCFNetwork
  6. */
  7. typedef CF_ENUM(int, CFNetworkErrors) {
  8. kCFHostErrorHostNotFound = 1,
  9. kCFHostErrorUnknown = 2, // Query the kCFGetAddrInfoFailureKey to get the value returned from getaddrinfo; lookup in netdb.h
  10. // SOCKS errors; in all cases you may query kCFSOCKSStatusCodeKey to recover the status code returned by the server
  11. kCFSOCKSErrorUnknownClientVersion = 100,
  12. kCFSOCKSErrorUnsupportedServerVersion = 101, // Query the kCFSOCKSVersionKey to find the version requested by the server
  13. // SOCKS4-specific errors
  14. kCFSOCKS4ErrorRequestFailed = 110, // request rejected or failed by the server
  15. kCFSOCKS4ErrorIdentdFailed = 111, // request rejected because SOCKS server cannot connect to identd on the client
  16. kCFSOCKS4ErrorIdConflict = 112, // request rejected because the client program and identd report different user-ids
  17. kCFSOCKS4ErrorUnknownStatusCode = 113,
  18. // SOCKS5-specific errors
  19. kCFSOCKS5ErrorBadState = 120,
  20. kCFSOCKS5ErrorBadResponseAddr = 121,
  21. kCFSOCKS5ErrorBadCredentials = 122,
  22. kCFSOCKS5ErrorUnsupportedNegotiationMethod = 123, // query kCFSOCKSNegotiationMethodKey to find the method requested
  23. kCFSOCKS5ErrorNoAcceptableMethod = 124,
  24. // FTP errors; query the kCFFTPStatusCodeKey to get the status code returned by the server
  25. kCFFTPErrorUnexpectedStatusCode = 200,
  26. // HTTP errors
  27. kCFErrorHTTPAuthenticationTypeUnsupported = 300,
  28. kCFErrorHTTPBadCredentials = 301,
  29. kCFErrorHTTPConnectionLost = 302,
  30. kCFErrorHTTPParseFailure = 303,
  31. kCFErrorHTTPRedirectionLoopDetected = 304,
  32. kCFErrorHTTPBadURL = 305,
  33. kCFErrorHTTPProxyConnectionFailure = 306,
  34. kCFErrorHTTPBadProxyCredentials = 307,
  35. kCFErrorPACFileError = 308,
  36. kCFErrorPACFileAuth = 309,
  37. kCFErrorHTTPSProxyConnectionFailure = 310,
  38. kCFStreamErrorHTTPSProxyFailureUnexpectedResponseToCONNECTMethod = 311,
  39. // Error codes for CFURLConnection and CFURLProtocol
  40. kCFURLErrorBackgroundSessionInUseByAnotherProcess = -996,
  41. kCFURLErrorBackgroundSessionWasDisconnected = -997,
  42. kCFURLErrorUnknown = -998,
  43. kCFURLErrorCancelled = -999,
  44. kCFURLErrorBadURL = -1000,
  45. kCFURLErrorTimedOut = -1001,
  46. kCFURLErrorUnsupportedURL = -1002,
  47. kCFURLErrorCannotFindHost = -1003,
  48. kCFURLErrorCannotConnectToHost = -1004,
  49. kCFURLErrorNetworkConnectionLost = -1005,
  50. kCFURLErrorDNSLookupFailed = -1006,
  51. kCFURLErrorHTTPTooManyRedirects = -1007,
  52. kCFURLErrorResourceUnavailable = -1008,
  53. kCFURLErrorNotConnectedToInternet = -1009,
  54. kCFURLErrorRedirectToNonExistentLocation = -1010,
  55. kCFURLErrorBadServerResponse = -1011,
  56. kCFURLErrorUserCancelledAuthentication = -1012,
  57. kCFURLErrorUserAuthenticationRequired = -1013,
  58. kCFURLErrorZeroByteResource = -1014,
  59. kCFURLErrorCannotDecodeRawData = -1015,
  60. kCFURLErrorCannotDecodeContentData = -1016,
  61. kCFURLErrorCannotParseResponse = -1017,
  62. kCFURLErrorInternationalRoamingOff = -1018,
  63. kCFURLErrorCallIsActive = -1019,
  64. kCFURLErrorDataNotAllowed = -1020,
  65. kCFURLErrorRequestBodyStreamExhausted = -1021,
  66. kCFURLErrorAppTransportSecurityRequiresSecureConnection = -1022,
  67. kCFURLErrorFileDoesNotExist = -1100,
  68. kCFURLErrorFileIsDirectory = -1101,
  69. kCFURLErrorNoPermissionsToReadFile = -1102,
  70. kCFURLErrorDataLengthExceedsMaximum = -1103,
  71. kCFURLErrorFileOutsideSafeArea = -1104,
  72. // SSL errors
  73. kCFURLErrorSecureConnectionFailed = -1200,
  74. kCFURLErrorServerCertificateHasBadDate = -1201,
  75. kCFURLErrorServerCertificateUntrusted = -1202,
  76. kCFURLErrorServerCertificateHasUnknownRoot = -1203,
  77. kCFURLErrorServerCertificateNotYetValid = -1204,
  78. kCFURLErrorClientCertificateRejected = -1205,
  79. kCFURLErrorClientCertificateRequired = -1206,
  80. kCFURLErrorCannotLoadFromNetwork = -2000,
  81. // Download and file I/O errors
  82. kCFURLErrorCannotCreateFile = -3000,
  83. kCFURLErrorCannotOpenFile = -3001,
  84. kCFURLErrorCannotCloseFile = -3002,
  85. kCFURLErrorCannotWriteToFile = -3003,
  86. kCFURLErrorCannotRemoveFile = -3004,
  87. kCFURLErrorCannotMoveFile = -3005,
  88. kCFURLErrorDownloadDecodingFailedMidStream = -3006,
  89. kCFURLErrorDownloadDecodingFailedToComplete = -3007,
  90. // Cookie errors
  91. kCFHTTPCookieCannotParseCookieFile = -4000,
  92. // Errors originating from CFNetServices
  93. kCFNetServiceErrorUnknown = -72000L,
  94. kCFNetServiceErrorCollision = -72001L,
  95. kCFNetServiceErrorNotFound = -72002L,
  96. kCFNetServiceErrorInProgress = -72003L,
  97. kCFNetServiceErrorBadArgument = -72004L,
  98. kCFNetServiceErrorCancel = -72005L,
  99. kCFNetServiceErrorInvalid = -72006L,
  100. kCFNetServiceErrorTimeout = -72007L,
  101. kCFNetServiceErrorDNSServiceFailure = -73000L // An error from DNS discovery; look at kCFDNSServiceFailureKey to get the error number and interpret using dns_sd.h
  102. };

2.iOS错误对象获取方式

错误字段名称 iOS端获取方法
错误码code mtopextResponse.error.code
错误信息msg mtopextResponse.error.msg
错误映射码mappingCode mtopextResponse.error.mappingCode
网络请求状态码httpResponseCode mtopextResponse.error.httpResponseCode

3.错误分类

1. “FAIL_SYS” 为前缀的网关系统错误,映射码后缀ESXXXXX(1).网关服务端系统错误映射码后缀错误映射码格式为:”ES+5位数字”。(ES:Error server),mtop通过header x-mapping-code输出映射错误码。

    1. ES1xxxx:表示mtop内部执行session检查,sm,mtee,签名校验,限流,授权等等逻辑时出错。
    1. ES2xxxx:表示后端业务方以HSF接入,mtop调用业务方HSF接口出错。
    1. ES3xxxx:表示后端业务方以HTTP接入,mtop调用业务方HTTP接口出错。
    1. ES4xxxx: 表示已经调用到后端业务接口,但是后端业务接口处理出错或返回结果格式非法。
mtop错误码 映射错误码 描述说明
FAIL_SYS_API_STOP_SERVICE ES10000 应用访问的api暂停服务
FAIL_SYS_SM_ODD_REQUEST ES10001 请求被sm或者mtee识别为恶意请求,被拦截
FAIL_SYS_API_NOT_FOUNDED ES10002 api+v指定的api不存在
FAIL_SYS_SESSION_EXPIRED ES10003 session失效
FAIL_SYS_SYSTEM_BUSY_ERROR ES10004 mtop查询session失败
FAIL_SYS_SERVLET_ASYNC_START_FAIL ES10005 mtop请求处理SERVLET异步启动失败
FAIL_SYS_FLOWLIMIT ES10006 触发mtop单机并发数限流
FAIL_SYS_API_UNAUTHORIZED ES10007 请求API未授权
FAIL_SYS_PROTOPARAM_MISSED ES10008 缺少请求的mtop协议参数
FAIL_SYS_PROTOVER_MISSED ES10009 缺少mtop协议版本
FAIL_SYS_REQUEST_EXPIRED ES10010 防重放攻击,请求失效
FAIL_SYS_ILEGEL_SIGN ES10011 非法请求签名
FAIL_SYS_INVALID_HTTP_METHOD ES10012 HttpMethod验证错误
FAIL_SYS_BADARGUMENT_T ES10013 请求参数t非法
FAIL_SYS_UNKNOWN_APP ES10014 未知APP应用,根据appkey查找不到应用数据
FAIL_SYS_INTERNAL_FAULT ES10015 mtop内部生成签名计算过程中出错
FAIL_SYS_TRAFFIC_LIMIT ES10016 触发mtop单机限流
FAIL_SYS_BIZPARAM_TYPE_ERROR ES10017 请求业务参数类型错误
FAIL_SYS_BIZPARAM_MISSED ES10018 缺少业务参数
FAIL_SYS_AUTH_PARAM_MISSED ES10019 缺少验证鉴权参数
FAIL_SYS_AUTH_FAILED ES10020 验证鉴权失败
FAIL_SYS_AUTH_ACCESS_TOKEN_EXPIRED_ERROR ES10021 鉴权token失效
FAIL_SYS_TOPAUTH_TRAFFICLIMIT_ERROR ES10022 TOP 流量限制
FAIL_SYS_UNAUTH_API_ERROR ES10023 业务鉴权不通过
FAIL_SYS_AUTH_FAULT ES10024 鉴权配置错误
FAIL_SYS_RETMISSED_ERROR ES10025 缺少请求响应码
FAIL_SYS_PARAMINVALID_ERROR ES10026 检查请求参数非法
SYSTEM_ERROR ES10027 调用后端业务http,hsf接口出错
FAIL_SYS_UNAUTHORIZED_ENTRANCE ES10028 API访问入口未授权
FAIL_SYS_SESSION_ERROR ES10029 session查询失败在pandora插件中
FAIL_SYS_MT_ODD_REQUEST ES10030 被mtee安全拦截
FAIL_SYS_EXPIRED_REQUEST ES10031 防重放攻击,请求失效
FAIL_SYS_PORTOCOLPARAM_INVALID ES10032 请求协议参数非法
FAIL_SYS_INVALID_PROTOCOLVERSION ES10033 非法协议版本
FAIL_SYS_ILLEGAL_ARGUMENT_TTID ES10034 请求参数ttid非法
FAIL_SYS_PARAM_MISSING ES10035 缺少必填的参数
FAIL_SYS_PARAM_FORMAT_ERROR ES10036 参数格式不正确
FAIL_SYS_ILLEGAL_ACCESS_TOKEN ES10037 ACCESS_TOKEN无效
FAIL_SYS_ACCESS_TOKEN_STOP_SERVICE ES10038 ACCESS_TOKEN禁止授权
FAIL_SYS_ACCESS_TOKEN_INTERNAL_FAULT ES10039 ACCESS_TOKEN鉴权发生异常
FAIL_SYS_ACCESS_TOKEN_TRAFFIC_LIMIT ES10040 ACCESS_TOKEN校验流量限制
FAIL_SYS_ACCESS_TOKEN_EXPIRED ES10041 ACCESS_TOKEN已过期
FAIL_SYS_ACCESS_TOKEN_PARAM_INVALID ES10042 ACCESS_TOKEN_PARAM_INVALID
FAIL_SYS_ACCESS_TOKEN_UNKNOWN_ERROR ES10043 ACCESS_TOKEN_UNKNOWN_ERROR
FAIL_SYS_REQUEST_QUEUED ES10044 请求被限流排队
FAIL_SYS_SERVICE_NOT_EXIST ES20000 服务端hsf不存在
FAIL_SYS_SERVICE_TIMEOUT ES20001 服务端hsf超时
FAIL_SYS_SERVICE_FAULT ES20002 请求服务故障
FAIL_SYS_HTTP_QUERYIP_ERROR ES30000 后端业务方http接入指定域名无法查询到ip
FAIL_SYS_HTTP_REQUESTSUBMIT_FAILED ES30001 异步http请求提交执行失败
FAIL_SYS_HTTP_INVOKE_ERROR ES30002 后端业务以http接入,调用后台http服务错误
FAIL_SYS_HTTP_RESPONSE_TIMEOUT ES30003 后端业务以http接入,http调用响应超时
FAIL_SYS_HTTP_CONNECT_TIMEOUT ES30004 后端业务以http接入,http调用连接超时
UNKNOWN_FAIL_CODE ES40000 业务方未返回错误码
FAIL_SYS_HSF_THROWN_EXCEPTION ES40001 HSF方法内部抛出了未捕获的异常
FAIL_SYS_SERVICE_INNER_FAULT ES40002 系统服务内部错误
FAIL_SYS_HTTP_RESULT_FIELDMISSED ES40003 后端业务以http接入,http响应结果缺少必传参数

(2).不在客户端已知列表的服务端运行时错误码

MTOP服务端错误码 说明 用户友好提示msg mappingcode后缀
不在客户端已知列表的FAIL_SYS_XXX 未知MTOP服务端错误 服务竟然出错了 ES00000

2 . MTOPSDK错误,映射码后缀ECXXXXX

(1).网络相关

错误场景 msg友好提示 iOS code iOS mappingCode suffix
无网络 网络竟然奔溃了 tbsdk request not network IEC10000
网络请求超时错误 网络竟然奔溃了 tbsdk request timeout IEC10001
ACCS连接失败 网络竟然奔溃了 FAIL_ACCS IEC10002

(2).防刷限流

错误场景 msg友好提示 iOS code iOS mappingCode suffix
420 限流响应 前方拥挤,亲稍等再试试 FAIL_LOCAL_ERROR_FANG_XUE_FENG IEC20000
419 防刷验证响应 前方拥挤,亲稍等再试试 FAIL_LOCAL_ERROR_FANG_SHUO IEC20001

(3).服务端返回4XX/5XX错误和服务端返回数据格式异常

错误场景 msg友好提示 iOS code iOS mappingCode suffix
数据格式不对,如返回html页面 服务竟然出错了 Wrong_Server_Response IEC30001

3.业务系统错误

  • 服务端返回的以“FAIL_BIZ”为前缀错误码
  • 服务端返回的其他业务自定义错误码
  • 业务系统错误,MTOPSDK不提供具体MappingCode映射,需要业务方按实际情况处理code和msg