从零开始设计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 >          < avatar >http://assets.taobaocdn.com/app/sns/img/default/avatar-120.png</ avatar >      </ 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 >