服务端接入手册

更新时间:2018-09-29 16:21:12

一、概要

API网关为业务移动应用的开发提供端到云整套技术解决方案,基于API网关可以将服务端能力安全、快速透出,同时移动端APP也可通过网关SDK快速接入完成服务消费。

基于API移动网关,业务只需专注于业务功能本身的开发,底层端到云整套技术细节全部由网关搞定。业务开发时,只需按以下流程简单接入即可。

image.png | left | 827x143

二、Dubbo服务接入

通过参数映射配置,mtop api网关可以将客户端请求的参数自动映射到对应的dubbo服务,并完对应的参数类型转换。具体API相关创建、配置流程可参考:API创建相关文档。

1. 请求数据

  • 服务相关信息

    • 服务接口
    • 服务方法
    • 服务版本
    • 服务分组
  • 服务方法参数

    • 方法参数列表,必须严格按dubbo方法参数类型顺序配置。
    • 参数取值,可以映射客户端参数也可映射 MTOP系统参数,具体定义流程请参考 API创建流程 。

2. 响应数据规约

  • dubbo服务方法返回参数支持:java基本类型、List、Map、自定义对象,mtop会将所返回的对象进行json序列化,以标准json格式输出到客户端。

  • 为了API报表监控、问题排查等,dubbo服务方法返回的对象必须包括以下字段

    • success,当前请求是否成功
    • msgCode,当前请求结果码,结果码设计规范参考:[错误设计规范]
    • msgInfo,当前请求结果描述信息
    • model,当前请求业务返回数据

3. 响应数据格式

返回报文格式如下:

  1. {
  2. "api": ${apiName},
  3. "v": " ${apiVersion},
  4. "ret": ${retcode_msg},
  5. "data": ${biz_payload}
  6. }
  • 返回基本类型,由于返回原始类型为单个值,无法构造合法json对象,因此会默认增加一个"data"作为key

    1. {
    2. "api": "auks.mtop.test",
    3. "v": "1.0",
    4. "ret":"SUCCESS::调用成功",
    5. "data":{
    6. "result": "auks_mtop_pref_testauks_mtop_pref_test"
    7. }
    8. }
  • 返回对象、Map、Set、List、数组

    1. {
    2. "api": "auks.mtop.test",
    3. "v": "1.0",
    4. "ret":"SUCCESS::调用成功",
    5. "data":{
    6. "a1": 123,
    7. "a2": "345",
    8. "isXX": false
    9. }
    10. }
    11. //
    12. {
    13. "api": "auks.mtop.test",
    14. "v": "1.0",
    15. "ret":"SUCCESS::调用成功",
    16. "data":[10,20]
    17. }
    18. //
    19. {
    20. "api": "auks.mtop.test",
    21. "v": "1.0",
    22. "ret":"SUCCESS::调用成功",
    23. "data": [{
    24. "a1": 123,
    25. "a2": "345",
    26. "isXX": false
    27. },
    28. {
    29. "a1": 123,
    30. "a2": "345",
    31. "isXX": false
    32. }]
    33. }

三、HTTP服务接入

在创建API时,通信协议选择HTTP并填入相关服务信息,主要包括VIPServer域名、请求PATH、请求方法(GET/POST)等相关信息,网关需要通过这些数据生成http服务请求URL,具体相关操作文档,可以参考:API创建文档

1. 服务规约

  • 请求编码统一使用UTF-8
  • 遵循HTTP协议标准
  • URLEncode转义非标字符,编码采用UTF-8

2. 请求数据

MTOP向后端HTTP服务转发请求主要包括:协议header和业务参数两部分内容,其中协议header主要为MTOP网关协议参数,主要包括以下数据:

  • Request Header列表
Header名称 描述 是否可空 备注
X-Request-From 标识当前请求来源 N 取值mtop
x-api 当前请求API名称 N
x-api-v 当前请求API版本 N
x-timestamp 请求时间戳 N
x-entrance 请求入口 N 取值H5
x-appKey H5请求appkey N
x-platform 移动app平台 Y 取值TTID
x-appName 移动app名称 Y 取值TTID
x-appVersion 移动app版本 Y 取值TTID
x-channel 移动app渠道 Y 取值TTID
x-ua 请求Agent N
x-client-ip 客户端请求ip N
x-client-port 客户端请求port N
  • Request Parameters 列表 定义API请求参数列表,用于接受客户端请求参数,参数取值可以是客户端请求参数或者映射 MTOP系统参数,具体定义流程请参考 API创建流程

3. 响应数据

服务响应结果与请求数据一样,也需要包括header和业务body两部分,其中header由mtop协议参数和业务header组成,body为业务数据。

  • mtop网关协议header(必填)
Header名称 描述 是否必填 备注
Content-type 响应数据类型 Y 必须为:application/json;charset=UTF-8
x-retcode 请求响应结果码 Y 错误码设计,请参考:错误设计规范
x-retmsg 请求响应结果说明 Y 响应错误消息
  • 业务header(选填)

在某些场景下,业务可能需要向客户端透一些header数据,但为了保证数据安全和性能考虑,mtop网关只允许以下header向客户端透出: 在某些场景下,业务可能需要向客户端透一些header数据,但为了保证数据安全和性能考虑,mtop网关只允许以下header向客户端透出

  1. http协议标准header,如:`ETag``Expires``Last-Modified``Cache-Control``Location``Last-Modified``Cache-Control``Location`
  2. `x-mtop-`开头的业务自定义header,注意:必须以x-mtop-开头,否则无法透传
  • 响应Body

业务响应body不能为空, 且必须为标准json格式

四、系统参数映射

参数名称 参数说明 是否可空
API名称 当前请求API名称 N
请求时间戳 当前请求API版本 N
参数字符串 当前请求参数json串 Y
来源IP 客户端请求IP N
来源端口 客户端请求端口 N
ttid 客户端标识,格式:[渠道号]@[appName]_[platform]_[appVersion] Y
utdid 客户端设备唯一标识 Y
appkey 客户端应用唯一KEY N
客户渠道号(取自ttid) 客户端渠道号 Y
客户端应用名称(取自ttid) 客户端应用名称 Y
客户端应用版本(取自ttid) 客户端应用版本 Y
客户端平台(取自ttid) 客户端平台 Y
User-Agent UserAgent,Native取值mtop-sdk定义格式数据,H5为浏览器UA N
经度 客户端位置:经度 Y
纬度 客户端位置:纬度 Y
网关内部请求ID mtop内部请求唯一ID,长度45字符 N

五、错误码设计

在服务的调用过程中有时会出现异常情况,当异常发生时网关会进行统一处理,并将不同的异常情况统换成不同错误。在错误码设计过程,我们会按照业务异常网关系统异常两个维度进行转换,这样做的好处是便于在API监控报表中可以快速定位问题。其中:

  • 业务异常,表示业务层面发生异常或失败,返回错误码必需以FAIL_BIZ_ 开头,否则无法在API监控报表中正常展现,从而影响问题的快速定位,未按规范返回的错误码将统一按UNKNOW_BIZ_CODE
  • 网关系统异常,表示在服务调用过程中在网关层面发生异常或失败,主要有有以下错误码:
错误码 错误描述 异常说明
SUCCESS API请求成功
FAIL_SYS_INVALID_RESULT 响应结果格式错误 后端服务响应结果对象未按规范返回。参考Dubbo服务接入响应结果设计
FAIL_SYS_PROTOPARAM_MISSED 缺少协议参数 API请求缺少必填协议参数
FAIL_SYS_PROTOVER_MISSED 缺少协议版本 API请求缺少mtop协议版本
FAIL_SYS_REQUEST_EXPIRED 请求失效 每个API请求都有一定有效期,防止请求被重话攻击
FAIL_SYS_ILEGEL_SIGN 非法请求签名 每个API请求都有安全签名机制。出现此错误表示网关无法无法验证客户的数据签名,出现此问题通常是由于客户端加签密钥使用错误、或网关接收到请求数据与客户端加签时使用的数据不一致。
FAIL_SYS_INVALID_HTTP_METHOD HttpMethod验证错误 当API调用使用了不允许的HTTP请求方法时,比如API只允许POST访问,客户端使用GET请求时将报此错误
FAIL_SYS_BADARGUMENT_T 请求参数t非法 每个API请求都有一个时间戳(header: x-t),当时间戳x-t格式非法时出现
FAIL_SYS_UNKNOWN_APP 未知APP应用 当API请求参数appkey不存在或获取对应appkey信息失败时
FAIL_SYS_INTERNAL_FAULT 系统内部故障 API网关内部发生未知异常
FAIL_SYS_API_NOT_FOUNDED 请求API不存在或已下线 API已下线或未发布上线
FAIL_SYS_UNAUTHORIZED_ENTRANCE API访问入口未授权 API只允许APP调用,当H5请求时出现
FAIL_SYS_SERVICE_NOT_EXIST 请求服务不存在 API映射的后端服务不存在
FAIL_SYS_SERVICE_TIMEOUT 请求服务超时 调用后端服务发生超时,需要检查API服务超时时间,默认4秒
FAIL_SYS_SERVICE_FAULT 后端服务内部发生异常 后端服务执行Dubbo服务时抛出了异常
FAIL_SYS_BIZPARAM_TYPE_ERROR 业务参数类型错误 客户端请求参数类型与API定义的参数类型不一致
FAIL_SYS_PARAMINVALID_ERROR 请求参数非法 API请求参数有不合法,导致协议解析发生异常
FAIL_SYS_TOKEN_EMPTY 令牌为空 H5请求必填协议参数token为空
FAIL_SYS_TOKEN_ILLEGAL 非法令牌 H5请求必填协议参数token非法
FAIL_SYS_TOKEN_EXOIRED 令牌过期 H5请求必填协议参数token已过期
FAIL_SYS_ILLEGAL_ACCESS 非法请求 H5请求参数难签失败、参数非法
FAIL_SYS_DOMAIN_NOT_ALLOWED 该域名不允许访问 H5请求方式,API只允许指定域名才可访问