## 一、概述 wbase uniframework平台提供了一套独立运行的开放服务子平台。它是基于oauth2的开放接口平台；  >[danger] 开放接口平台，实质上，就是wbase提供的微服务内核，它不仅可用于对外充当API网关的作用，对于基于平台的应用来说，无论是外部业务、内部应用，还是APP，也都可以通过开放服务体系，获取授权资源； ## 二、接入流程 对于系统厂商来说，流程如下： 1、创建微服务账号，也就是创建一个用户，该用户必须拥有微服务角色，这将自动的为该账户创建一个未启用的开放服务应用，包含对应的appId及appSecret（在应用设置中可以看到这两个参数） ；  >[danger] 微服务角色是平台内置的专用于定义微服务客户的角色； > 2、在应用设置中，设置该账户访微服务的服务器ip地址，可以有多个，设置完毕，就可以启用该账户开放服务应用了；  3、设置该客户可以使用的api，默认的，刚开通的用户除了正式测试用的API之外，没有任何api授权，需要根据实际业务，给客户授权它应用拥有的api；  4，将该appId及appSecret提供给客户，就完成了微服务开户完整流程； 对于微服务客户来说，流程如下： 1）、申请接口，提供调用ip地址给厂商，获取自己的appId和appSecret； 2）、阅读接口文档（定义具体api及其语义的），编写测试代码，提交测试ip； 3）、测试完毕，上线； ## 三、开通服务 api服务地址：http://ip:port/oauth/service， >[danger] > 1、api服务地址+api的url组合，构成了客户端api请求的完整地址； > 2、比如平台内置提供了一个用于测试验证的api，其url是/test/validation，那么实际完整的请求地址应当为：http://ip:port/oauth/service/test/validation ## 四、技术要求 1.所有接口的请求，采用httpPost方式提交，发出http请求的时候，请求content-type需设定为：application/x-www-form-urlencoded;charset=UTF-8 ，参数按照普通表单参数传值，不必包裹成一个json字符串； 2.所有接口的响应，采用json格式，编码为UTF-8，响应的content-type为：application/json;charset=UTF-8； 3.提供ip白名单功能，仅供授权的ip调用； 4.每个对外提供服务的api，都必须包含的参数为appId及timeStamp； 5.每个对外提供服务的api，都必须包含一个sign参数，该参数是通过算法计算出来的值； 6.考虑服务器承载量，目前限制每个ip访问接口频率，程序中不得做高频率轮询； 7.接口服务自身的设计与开发是基于BASE理论。因此，也强烈建议代码编写者遵循该理论；程序开发者必需考虑接口服务器因机房网络故障、域名解析故障、例行检修、程序升级、依赖服务中断等因素导致当前服务不可用。因此，业务逻辑的编写必须严格的核对响应码，并且必须编写消费接口服务的异常分支逻辑； >[danger] 只有responseCode为1，才说明您的api执行成功，其他的任何数字都是失败的，只是失败的原因不同； ## 五、时间戳格式 1.获取从1970, 00:00:00开始到当前的毫秒数(13位) 2.每个api请求的有效时间为3分钟,所以,务必确保当前服务请求的时间是准确的； ## 六、签名算法 假设：paramstrings = 当前api的所有参数(除sign自身外)，根据参数名升序排序，以“参数名=值&”的方式连接起来； 结果：sign = md5(md5(paramstrings)+appSecret) >[danger] 注意： > 1、是双层md5加密，中间那个"+"仅表示两段字符相连,组合的结果并不包括该符号本身； > 2、签名计算放到参数传值的最后，因为要用到接口所有参数（除sign自身外）参与加密计算； ## 七、接口限流 对外服务的每个API接口当访问频率或者并发量超过其承受范围时候,我们就必须考虑限流来保证接口的可用性或者降级可用性.以防止非预期的请求对系统压力过大而引起的系统瘫痪； ### (1) 算法 平台采用令牌桶算法进行限流，针对每个appId（客户端），都限制其每秒钟可以接收的请求数，确保整个对外服务正常有序； 令牌桶算法的原理是系统会以一个恒定的速度往桶里放入令牌，而如果请求需要被处理，则需要先从桶里获取一个令牌，当桶里没有令牌可取时，则拒绝服务；  ### (2) 设置 系统参数配置中，可以设定每个appId每秒请求数限制：  ### (3) 注意 >[danger]正常的访问平台是通过接口限流策略，实现了业务可用性保障；对应非正常的访问，平台则通过DDOS防御设施，实现业务可用性保障； ## 八、同步服务接口与异步服务接口 微服务的服务类型包括两种： >[danger] > 1、同步服务，请求该服务的时候，立即实时返回结果； > 2、异步服务，请求该服务的时候，微服务只是将该请求记录下来，后续通过调度服务平台来执行一系列的动作或命令。适合比较耗时的业务，优点是提高客户端的体验，让它无须长时间等待即可返回； ## 九、典型接口说明 ~~~[api] post:/test/validation *string:appId=s123#联系我们获取 *string:timeStamp=1584362438966#当前时间戳，13位数字，该时间戳在30分钟内会失效，30分钟后访问该地址，会返回请求时间戳不合法； *paramLong#参数1 *paramFloat#参数2 *string:sign=xxrreedfasdfsafsfs231999999oo#签名，按照约定规则 <<< success { "responseMessage": "成功", "responseCode": 1, "requestStartTime": 1584837900324, "requestEndTime": 1584837901513, "responseCostTime": "1189毫秒", "feedback": { "isBusinessSuccess": true, "executionMessage": "实时接口,直接显示查询结果", "data": "data" } } <<< error { "responseCode": -99, "responseMessage": "失败", "requestStartTime": 1584837900324, "requestEndTime": 1584837901513, "responseCostTime": "1189毫秒" } ~~~ >[danger] 只有responseCode为1，才能说明这个api执行成功了，否则，都是失败，只是失败原因各不相同，具体可以参照下表； > | 错误码 | 错误原因 | | --- | --- | | -1 | 当前ip地址不在访问白名单,请联系管理员. | | -2 | 不支持当前http请求模式 | | -3 | 当前请求的url不符合约定的组成语法，一般是您的url请求地址没按照约定提供 | | -4 | 当前请求参数没有包含appId. | | -5 | 当前请求参数没有包含时间戳. | | -6 | 当前请求参数没有包含签名. | | -7 | 当前请求appId无效. | | -8 | 当前请求签名不合法. | | -9 | 当前请求时间已经超时. | | -10 | 当前请求的api不存在. | | -11 | 当前appId请求数超过允许的限制 | | -12 | 当前请求的api没有获得授权 | | -99 | 业务自身错误信息 | ## 十、平台功能 平台提供了相关的功能，具体可以参考：[系统平台/开放服务](系统平台/开放服务.md)