因为是接口框架,首先要做的就是制定接口规范,好的接口规范能约束开发人员,能降低前后端人员之间的沟通协调,能避免后期联调带来的一系列问题。
接口规范接口规范包含以下内容:请求类型及参数返回值及返回码权限及版本控制接口示例接口请求说明Api使用Restful风格,接口地址:http://host:port接口请求类型分为两种,GET和POST,GET通常为请求获取资源;POST通常为提交资源到服务器;接口请求返回值基本分为两种:GET的请求若无错误,则返回所需资源的JSON格式内容,若有错误则返回一致的JSON格式内容,如:{“success”:false,“message”:“提交的参数不正确”,data:{}},其中data为额外的对象,具体值根据接口而定;POST的请求的Body部分可以将对象格式化为JSON的字符串后提交,也可以使用传统的Form表单形式提交,返回一致的JSON格式内容:如:{“success”:true,“message”:null,data:{id:1}},其中data的内容也是具体根据接口而定。返回码说明:
00请求成功400客户端请求时所提交的参数不正确401未提供accessToken403权限不足404找不到该资源500服务发生错误
实际生产中,请求基本都为POST接口权限说明接口权限验证使用OAUTH0标准,即先请求授权服务获取accessToken,得到accessToken后使用其内容封装到request的头中,用以请求被保护的资源;accessToken封装在Headers中是以Authorization键值对形式组成的,如:accessToken为4cac113f-29b1-4585-99a8-16e39331ccb封装的内容为:Authorization:4cac113f-29b1-4585-99a8-16e39331ccb3这种形式。接口请求版本说明各个接口在header里面都加Version字段,用于控制接口的版本,服务端程序可以根据版本号来动态返回数据,也可以根据版本号来提示app升级。不加version默认0。公共返回码为了保证接口的规范性,特制定标准返回码:成功类:
0001保存成功10002删除成功10003操作成功10004审核成功
失败类
0001操作失败20002代码已存在30001无权限30002系统错误30003参数错误30004路径不存在
接口示例
接口示例.png
上述是登录接口的文档标识
总结设计接口规范是一个相当复杂的事情,要综合考虑很多技术及实现细节。后续章节依次讲述这些细节,并不断完善规范文档。
文章为作者独立观点,不代表股票自动交易程序化数据接口观点