通用接口标准规范v

1、接口标准规范NO.修改后版本号修改的页码及条款修改类型、原因及说明修改人修改时间1V1.0.0全文创建2019/1/1目录 TOC o 1-3 h z u 接口标准规范 PAGEREF _Toc3805457 h 1第1章概述 PAGEREF _Toc3805458 h 3第2章基本要求 PAGEREF _Toc3805459 h 42.1 信息通讯安全 PAGEREF _Toc3805460 h 42.1.1 安全评估 PAGEREF _Toc3805461 h 42.1.2 访问控制 PAGEREF _Toc3805462 h 42.1.3 防恶意代码 PAGEREF _Toc380546

2、3 h 42.1.4 加密 PAGEREF _Toc3805464 h 52.2 支持高并发 PAGEREF _Toc3805465 h 62.3 可监控 PAGEREF _Toc3805466 h 62.3.1 日志全覆盖 PAGEREF _Toc3805467 h 62.4 系统资源的动态扩展 PAGEREF _Toc3805468 h 62.5 异常处理机制 PAGEREF _Toc3805469 h 72.6 业务扩展 PAGEREF _Toc3805470 h 7第3章接口通讯方式 PAGEREF _Toc3805471 h 73.1 同步请求/应答方式 PAGEREF _Toc38

3、05472 h 73.2 异步请求/应答方式 PAGEREF _Toc3805473 h 73.3 会话方式 PAGEREF _Toc3805474 h 73.4 广播通知方式 PAGEREF _Toc3805475 h 73.5 事件订阅方式 PAGEREF _Toc3805476 h 73.6 文件传输 PAGEREF _Toc3805477 h 83.7 可靠消息传输 PAGEREF _Toc3805478 h 8第4章传输控制要求 PAGEREF _Toc3805479 h 84.1 负载均衡 PAGEREF _Toc3805480 h 84.2 伸缩性与动态配置管理 PAGEREF

4、_Toc3805481 h 84.3 网络调度 PAGEREF _Toc3805482 h 94.4 充分理由 PAGEREF _Toc3805483 h 94.5 单一职责 PAGEREF _Toc3805484 h 94.6 高内聚低耦合 PAGEREF _Toc3805485 h 94.7 状态及消息 PAGEREF _Toc3805486 h 104.8 控制数据量 PAGEREF _Toc3805487 h 104.9 禁止随意拓展参数 PAGEREF _Toc3805488 h 10第5章接口技术 PAGEREF _Toc3805489 h 10第6章接口规范 PAGEREF _T

5、oc3805490 h 116.1 域名规范 PAGEREF _Toc3805491 h 116.1.1 http接口 PAGEREF _Toc3805492 h 116.1.2 webservice接口 PAGEREF _Toc3805493 h 116.2 API路径规范 PAGEREF _Toc3805494 h 116.2.1 http接口 PAGEREF _Toc3805495 h 116.2.2 webservice接口 PAGEREF _Toc3805496 h 116.3 版本控制规范 PAGEREF _Toc3805497 h 126.3.1 http接口 PAGEREF _

6、Toc3805498 h 126.3.2 webservice接口 PAGEREF _Toc3805499 h 126.4 API命名规范 PAGEREF _Toc3805500 h 126.4.1 新增方法 PAGEREF _Toc3805501 h 136.4.2 删除方法 PAGEREF _Toc3805502 h 136.4.3 修改方法 PAGEREF _Toc3805503 h 136.4.4 获取方法 PAGEREF _Toc3805504 h 136.4.5 获取列表方法 PAGEREF _Toc3805505 h 136.5 请求参数规范 PAGEREF _Toc380550

7、6 h 146.5.1 参数需要命名规则 PAGEREF _Toc3805507 h 146.5.2 请求参数加密方法 PAGEREF _Toc3805508 h 146.6 列表请求特殊规范 PAGEREF _Toc3805509 h 156.7 返回数据规范 PAGEREF _Toc3805510 h 15第7章接口文档规范 PAGEREF _Toc3805511 h 16第8章接口管理 PAGEREF _Toc3805512 h 168.1 对接口分类、编码排序。 PAGEREF _Toc3805513 h 168.2 在线文档。 PAGEREF _Toc3805514 h 16概述本文

8、主要为了明确标准和规范，为服务使用方和服务提供方提供开发参考。基本要求为了保证系统的完整性和健壮性，系统接口应满足下列基本要求：信息通讯安全安全评估保证接口的自身安全，通过接口实现技术上的安全控制，做到对安全事件的“可知、可控、可预测”，是实现系统安全的一个重要基础。访问控制如果客户端很频繁的请求服务器，会给给服务器造成很大的压力，需要对客户端对API的请求做一些限制。比如单位时间内同一IP只能请求多少次。防恶意代码用户名sql注入例如：用户名sql注入登录名输入：lilei#select *from student where user=lilei and psd=123456sql语句就变

9、成了select *from student where user=lilei#and psd=123456(#/-后面的内容都会被注释掉)跨站脚本例如脚本攻击测试：alter(123456)命令注入：PHP提供部分函数用来执行外部应用程序异常字符测试：结束符、换行符，针对字符串，在中间插入特殊字符，比如结束符等，服务端没有进行验证1、调用可执行的系统命令函数。2、函数活着函数的参数控制。3、拼接注入命令alter(123456)。命令注入：PHP提供部分函数用来执行外部应用程序异常字符测试：结束符、换行符，针对字符串，在中间插入特殊字符，比如结束符等，服务端没有进行验证1、调用可执行的系统命

10、令函数。2、函数活着函数的参数控制。3、拼接注入命令。加密接口调用方和接口提供方约定好统一的参数加密算法。（加密方法参照接口规范的请求参数规范）接口调用方在调用时把加密后的_sign放在参数中去请求接口。接口提供方接到响应后，判断时间戳是不是在有效时间内（这个时间间隔根据你的安全范围可以是10分钟，5分钟，20秒等，过期失效，前提是需要保证接口提供方和调用方的服务器时间为准确的网络同步时间）。把参数中除了_sign以外的参数进行加密，然后把加密结果和传过来的_sign比较，相同则执行调用请求。如果服务器和客户端的时间没有同步，可以返回错误的同时候在返回一个服务器的当前时间，客户端接收到该错误后

11、再请求上一个接口，时间则传服务器刚刚返回的时间。涉及到比较重要的信息，可以用AES对value进行加密，防止抓包拉取到上传的数据。支持高并发根据实际情况选择合适的方式方法来实现，可动态通过集群节点进行扩展。例如：Java的并发包提供了三个常用的并发队列实现，分别是：ArrayBlockingQueue、ConcurrentLinkedQueue 和 LinkedBlockingQueue可监控日志全覆盖正常运行信息异常捕获信息日志打印规范满足运维需求、日志格式统一规范。系统资源的动态扩展保证在充分利用系统资源的前提下，实现系统平滑的移植和扩展，同时在系统并发增加时提供系统资源的动态扩展，以保证

12、系统的稳定性。异常处理机制表单验证、唯一性检查、或其他可预期的错误。我们需要编写特定代码来捕获这类错误，并抛出一个包含提示信息的全局异常，捕获并返回给客户端。业务扩展在进行新业务扩展时，应能提供快速、方便和准确的实现方式。接口通讯方式同步请求/应答方式客户端向服务器端发送服务请求，客户端阻塞等待服务器端返回处理结果。异步请求/应答方式客户端向服务器端发送服务请求，与同步方式不同的是，在此方式下，服务器端处理请求时，客户端继续运行；当服务器端处理结束时返回处理结果。会话方式客户端与服务器端建立连接后，可以多次发送或接收数据，同时存储信息的上下文关系广播通知方式由服务器端主动向客户端以单个或批量方

13、式发出未经客户端请求的广播或通知消息，客户端可在适当的时候检查是否收到消息并定义收到消息后所采取的动作事件订阅方式客户端可事先向服务器端订阅自定义的事件，当这些事件发生时，服务器端通知客户端事件发生，客户端可采取相应处理。事件订阅方式使客户端拥有了个性化的事件触发功能，极大方便了客户端及时响应所订阅的事件文件传输客户端和服务器端通过文件的方式来传输消息，并采取相应处理可靠消息传输在接口通讯中，基于消息的传输处理方式，除了可采用以上几种通讯方式外，还可采用可靠消息传输方式，即通过存储队列方式，客户端和服务器端来传输消息，采取相应处理传输控制要求传输控制利用高速数据通道技术实现把前端的大数据量并发

14、请求分发到后端，从而保证应用系统在大量客户端同时请求服务时，能够保持快速、稳定的工作状态。系统应采用传输控制手段降低接口网络负担，提高接口吞吐能力，保证系统的整体处理能力。具体手段包括负载均衡、伸缩性与动态配置管理、网络调度等功能：负载均衡有必要时为了确保接口服务吞吐量最大，接口应自动地在系统中完成动态负载均衡调度。伸缩性与动态配置管理由系统自动伸缩管理方式或动态配置管理方式实现队列管理、存取资源管理，以及接口应用的恢复处理等。网络调度当对接口有较高通讯保障要求时可能会在在双方接口之间设置多个网络通道，需要实现接口的多数据通道和容错性，保证当有一网络通道通讯失败时，进行自动的切换，实现接口连接

15、的自动恢复。接口设计原则充分理由不是随便一个功能、需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。单一职责一个接口只负责一个业务功能。高内聚低耦合一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。还是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，如果这时一条完整的业务流水线，那么就应该在一个接口里完成，而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。状态及

16、消息提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。控制数据量一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。禁止随意拓展参数拓展接口可能是难以避免的，但是不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端调

17、用的变化，容易产生版本兼容性问题。接口技术主要使用的接口技术的有webService和http。接口规范域名规范每个项目要有且仅有一个自己唯一的域名（或ip地址）+端口。如果一个域名（或ip地址）满足不了要求，那么就需要再添加一个。http接口格式规范如下： “:8080/”; “:8080/”;webservice接口格式规范如下：:8080/services/searchData?wsdlAPI路径规范http接口作为接口路径为了和其他路径完美区分，必须在路径中添加api目录格式规范如下：“:8080/api/”;必须以字母开头，并以“/”结尾。webservice接口因为webservi

18、ce本身就是专门做接口用的技术所以接口路径可以不用添加【api/】用来区分接口路径。例如：/services/searchData?wsdl版本控制规范项目正式上线后，正式版本要确定接口版本、并备份接口代码。为方便管理，需要在接口路径中加入版本号信息。http接口格式规范如下：”:8080/api/v1/”;必须以字母开头，并以“/”结尾。更新版本后可以使用v2 v3等、依次递加。webservice接口Webservice的接口对应函数命名格式采用小驼峰式方式命名，在函数名的最后加上版本V1。更新版本后可以用V2、V3等、依次递加。API命名规范根据域名规范、API路径规范和版本控制规范。A

19、pi地址值等于三个相加。格式规范如下： “:8080/api/v1/” 接口方法必须要有自己的规范，命名必须统一使用小驼峰命名法。比如：（upperCamelCase）。所有接口命名方式，必须遵循如下规范。新增方法如新增一个地址、新增一个联系人。命名规范：必须以“add”为前缀。例如addAddress事例地址：:8080/api/v1/addAddress删除方法如删除一个地址。命名规范：必须以“delete”为前缀。例如deleteAddress事例地址：:8080/api/v1/deleteAddress修改方法如修改一个地址。命名规范：必须以“update”为前缀。例如updateAd

20、dress事例地址：:8080/api/v1/updateAddress获取方法 如获取一个地址。命名规范：必须以“get”为前缀。例如getAddress事例地址：:8080/api/v1/getAddress获取列表方法如获取一个地址列表。命名规范：必须以“get”为前缀、“List”为后缀。例如getAddressList事例地址：:8080/api/v1/getAddressList其他规范：发送验证码使用send为前缀、保存一个数据以save为前缀、上传图片以uploadImage为名称等等。目的：一目了然、降低维护成本。请求参数规范参数需要命名规则特殊情况需要按照小驼峰命名，指明数

21、据类型。参数中文名英文名数据类型是否必填调用方idappKeySting例如（wuzheng）时间戳timeStamplong时间戳xxxloginIdString不可为空请求参数加密方法1）对除签名外的所有请求参数按key做的升序排列,value无需编码。（假设当前时间的时间戳是12345678）例如：有c=3,b=2,a=1 三个参，另加上时间戳后， 按key排序后为：a=1，b=2，c=3，_timestamp=12345678。2）把参数名和参数值连接成字符串，得到拼装字符：a1b2c3_timestamp123456783 ）用申请到的appkey连接到接拼装字符串尾部，然后进行32

22、位MD5加密，最后将到得MD5加密摘要转化成大写。（如果没有appkey则不需要拼接，需要加密盐时另行约定告知）示例：假设appkey=test，md5(a1b2c3_timestamp12345678test)，取得MD5摘要值 C5F3EB5D7DC2748AED89E90AF00081E6 。最后访问连接参照:8080/api/v1/getAddressList?a=1&b=2&c=3&_timestamp=12345678&_sign= C5F3EB5D7DC2748AED89E90AF00081E6列表请求特殊规范列表请求，请求参数规范，必须传参：页数和每页个数的字段。并可包含查询等信息。1. 列表接口必传字段（分页、使用小写字母）。page ：页数，从1开始。例如： “page”: 1 subnumber : 每页数量。2. 列表接口选传字段。只要是列表接口、一般情况下都会存在检索条件，例如淘宝商品检索。检索条件为选填。后台需进行非空非null判断，选传字段为空为null默认查询全部。有值则需要接收，并进行sql查询