从零开始设计SOA框架（二）：请求/响应参数的设计
每个接口都有请求参数、响应参数。其中请求参数分为公共参数和业务参数、响应参数分为两类：正常的响应参数、统一的错误参数
一、请求参数
1、公共参数：每个接口都有的参数，主要包含appkey、时间戳、版本、响应格式、session
参考淘宝开放平台如下：
公共请求参数：a) session：有些接口需要登陆后才能调用，所以需要传递session参数b) timestamp：用于验证相同一组参数值不能重复使用，如其它参数都一样，timestamp也一样可考虑是否参数被他人截获并反复调用，服务端遇到这种情况可拒绝服务c) sign：是所有参数+app_secret加密后的字符串，则无法伪造sign串
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| method | String | 是 | API接口名称。 |
| app_key | String | 是 | TOP分配给应用的AppKey。 |
| session | String | 否 | 用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。 |
| timestamp | String | 是 | 时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。 |
| format | String | 否 | 响应格式。默认为xml格式，可选值：xml，json。 |
| v | String | 是 | API协议版本，可选值：2.0。 |
| partner_id | String | 否 | 合作伙伴身份标识。 |
| target_app_key | String | 否 | 被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。 |
| simplify | Boolean | 否 | 是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。 |
| sign_method | String | 是 | 签名的摘要算法，可选值为：hmac，md5。 |
| sign | String | 是 | API输入参数签名结果，签名算法介绍请点击这里。 |
2、业务参数
每个接口特定的参数
1、如根据商品编号获取商品信息接口，则参数为product_id
2、如登录接口，则参数为login_name,login_pwd等
二、响应参数
响应参数分为两大类，如果接口调用成功则返回业务参数，如果调用失败则统一返回错误信息
1、正常返回
a) 获取用户信息返回参数
|
1
2
3
4
5
6
7
|
<user_buyer_get_response> <user> <nick>hz0799</nick> <sex>m</sex> </user></user_buyer_get_response> |
2、错误返回
错误参数包括错误主信息，错误子信息，如请求参数验证失败，则主信息提示参数错误，子信息包含具体哪个参数错误
a) solution：可选，给出解决错误的建议
b) code： 主错误信息，定义全局的错误编码
c) msg：错误原因
|
1
2
3
4
5
6
7
8
9
10
|
<error_response> <code>50</code> <msg>参数错误</msg> <solution></solution> <sub_errors> <sub_code>isv.invalid-parameter</sub_code> <sub_msg>用户名不能为空</sub_msg> <sub_solution>请填写用户名</sub_solution> </sub_errors></error_response> |
