通用接口标准规范v1

接口标准规范

目录

接口标准规范 (1)

第1章概述 (3)

第2章基本要求 (4)

2.1信息通讯安全 (4)

2.1.1 安全评估 (4)

2.1.2 访问控制 (4)

2.1.3 防恶意代码 (4)

2.1.4 加密 (5)

2.2支持高并发 (6)

2.3可监控 (6)

2.3.1 日志全覆盖 (6)

2.4系统资源的动态扩展 (6)

2.5异常处理机制 (7)

2.6业务扩展 (7)

第3章接口通讯方式 (7)

3.1同步请求/应答方式 (7)

3.2异步请求/应答方式 (7)

3.3会话方式 (7)

3.4广播通知方式 (7)

3.5事件订阅方式 (7)

3.7可靠消息传输 (8)

第4章传输控制要求 (8)

4.1负载均衡 (8)

4.2伸缩性与动态配置管理 (8)

4.3网络调度 (9)

4.4充分理由 (9)

4.5单一职责 (9)

4.6高内聚低耦合 (9)

4.7状态及消息 (10)

4.8控制数据量 (10)

4.9禁止随意拓展参数 (10)

第5章接口技术 (10)

第6章接口规范 (11)

6.1域名规范 (11)

6.1.1 http接口 (11)

6.1.2 webservice接口 (11)

6.2 API路径规范 (11)

6.2.1 http接口 (11)

6.2.2 webservice接口 (11)

6.3版本控制规范 (12)

6.3.1 http接口 (12)

6.3.2 webservice接口 (12)

6.4 API命名规范 (12)

6.4.1 新增方法 (13)

6.4.2 删除方法 (13)

6.4.3 修改方法 (13)

6.4.4 获取方法 (13)

6.4.5 获取列表方法 (13)

6.5.1 参数需要命名规则 (14)

6.5.2 请求参数加密方法 (14)

6.6列表请求特殊规范 (15)

6.7返回数据规范 (15)

第7章接口文档规范 (16)

第8章接口管理 (16)

8.1对接口分类、编码排序。 (16)

8.2在线文档。 (16)

第1章概述

本文主要为了明确标准和规范，为服务使用方和服务提供方提供开发参考。

第2章基本要求

为了保证系统的完整性和健壮性，系统接口应满足下列基本要求：

2.1信息通讯安全

2.1.1安全评估

保证接口的自身安全，通过接口实现技术上的安全控制，做到对安全事件的“可知、可控、可预测”，是实现系统安全的一个重要基础。

2.1.2访问控制

如果客户端很频繁的请求服务器，会给给服务器造成很大的压力，需要对客户端对API的请求做一些限制。比如单位时间内同一IP只能请求多少次。

2.1.3防恶意代码

2.1.

3.1用户名sql注入

例如：用户名sql注入登录名输入：lilei'#

select *from student where user='lilei' and psd='123456'

sql语句就变成了select *from student where user='lilei'#'and psd='123456'(#/--后面的内容都会被注释掉)

2.1.

3.2跨站脚本

例如脚本攻击测试：

命令注入：PHP提供部分函数用来执行外部应用程序

异常字符测试：结束符、换行符，针对字符串，在中间插入特殊字符，比如结束符等，服务端没有进行验证

1、调用可执行的系统命令函数。

2、函数活着函数的参数控制。

3、拼接注入命令。

命令注入：PHP提供部分函数用来执行外部应用程序

异常字符测试：结束符、换行符，针对字符串，在中间插入特殊字符，比如结束符等，服务端没有进行验证

1、调用可执行的系统命令函数。

2、函数活着函数的参数控制。

3、拼接注入命令。

2.1.4加密

2.1.4.1接口调用方和接口提供方约定好统一的参数加密算法。

（加密方法参照接口规范的请求参数规范）

2.1.4.2接口调用方在调用时把加密后的_sign放在参数中去请求接口。

2.1.4.3接口提供方接到响应后，判断时间戳是不是在有效时间内（这个时间间隔根据

你的安全范围可以是10分钟，5分钟，20秒等，过期失效，前提是需要保证

接口提供方和调用方的服务器时间为准确的网络同步时间）。

2.1.4.4把参数中除了_sign以外的参数进行加密，然后把加密结果和传过来的_sign比

较，相同则执行调用请求。

2.1.4.5如果服务器和客户端的时间没有同步，可以返回错误的同时候在返回一个服务

器的当前时间，客户端接收到该错误后再请求上一个接口，时间则传服务器刚

刚返回的时间。

2.1.4.6涉及到比较重要的信息，可以用AES对value进行加密，防止抓包拉取到上传

的数据。

2.2支持高并发

根据实际情况选择合适的方式方法来实现，可动态通过集群节点进行扩展。

例如：Java的并发包提供了三个常用的并发队列实现，分别是：ArrayBlockingQueue、ConcurrentLinkedQueue 和LinkedBlockingQueue

2.3可监控

2.3.1日志全覆盖

2.3.1.1正常运行信息

2.3.1.2异常捕获信息

2.3.1.3日志打印规范

满足运维需求、日志格式统一规范。

2.4系统资源的动态扩展

保证在充分利用系统资源的前提下，实现系统平滑的移植和扩展，同时在系统并发增加时提供系统资源的动态扩展，以保证系统的稳定性。

2.5异常处理机制

表单验证、唯一性检查、或其他可预期的错误。我们需要编写特定代码来捕获这类错误，并抛出一个包含提示信息的全局异常，捕获并返回给客户端。

2.6业务扩展

在进行新业务扩展时，应能提供快速、方便和准确的实现方式。

第3章接口通讯方式

3.1同步请求/应答方式

客户端向服务器端发送服务请求，客户端阻塞等待服务器端返回处理结果。

3.2异步请求/应答方式

客户端向服务器端发送服务请求，与同步方式不同的是，在此方式下，服务器端处理请求时，客户端继续运行；当服务器端处理结束时返回处理结果。

3.3会话方式

客户端与服务器端建立连接后，可以多次发送或接收数据，同时存储信息的上下文关系3.4广播通知方式

由服务器端主动向客户端以单个或批量方式发出未经客户端请求的广播或通知消息，客户端可在适当的时候检查是否收到消息并定义收到消息后所采取的动作

3.5事件订阅方式

客户端可事先向服务器端订阅自定义的事件，当这些事件发生时，服务器端通知客户端事件发生，客户端可采取相应处理。事件订阅方式使客户端拥有了个性化的事件触发功能，极大方便了客户端及时响应所订阅的事件

3.6文件传输

客户端和服务器端通过文件的方式来传输消息，并采取相应处理

3.7可靠消息传输

在接口通讯中，基于消息的传输处理方式，除了可采用以上几种通讯方式外，还可采用可靠消息传输方式，即通过存储队列方式，客户端和服务器端来传输消息，采取相应处理

第4章传输控制要求

传输控制利用高速数据通道技术实现把前端的大数据量并发请求分发到后端，从而保证应用系统在大量客户端同时请求服务时，能够保持快速、稳定的工作状态。

系统应采用传输控制手段降低接口网络负担，提高接口吞吐能力，保证系统的整体处理能力。具体手段包括负载均衡、伸缩性与动态配置管理、网络调度等功能：

4.1负载均衡

有必要时为了确保接口服务吞吐量最大，接口应自动地在系统中完成动态负载均衡调度。

4.2伸缩性与动态配置管理

由系统自动伸缩管理方式或动态配置管理方式实现队列管理、存取资源管理，以及接口应用

的恢复处理等。

4.3网络调度

当对接口有较高通讯保障要求时可能会在在双方接口之间设置多个网络通道，需要实现接口的多数据通道和容错性，保证当有一网络通道通讯失败时，进行自动的切换，实现接口连接的自动恢复。

4.3.1.1接口设计原则

4.4充分理由

不是随便一个功能、需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。

4.5单一职责

一个接口只负责一个业务功能。

4.6高内聚低耦合

一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。还是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，如果这时一条完整的业务流水线，那么就应该在一个接口里完成，而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。

4.7状态及消息

提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。

4.8控制数据量

一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。

4.9禁止随意拓展参数

拓展接口可能是难以避免的，但是不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端调用的变化，容易产生版本兼容性问题。

第5章接口技术

主要使用的接口技术的有webService和http。

第6章接口规范

6.1域名规范

每个项目要有且仅有一个自己唯一的域名（或ip地址）+端口。如果一个域名（或ip地址）满足不了要求，那么就需要再添加一个。

6.1.1http接口

格式规范如下：

“https://127.0.0.1:8080/”;

“https://192.168.0.1:8080/”;

6.1.2webservice接口

格式规范如下：

https://127.0.0.1:8080/services/searchData?wsdl

6.2API路径规范

6.2.1http接口

作为接口路径为了和其他路径完美区分，必须在路径中添加api目录

格式规范如下：

“https://127.0.0.1:8080/api/”;

必须以字母开头，并以“/”结尾。

6.2.2webservice接口

因为webservice本身就是专门做接口用的技术所以接口路径可以不用添加【api/】用来区分接口路径。

例如：https://127.0.0.1/services/searchData?wsdl

6.3版本控制规范

项目正式上线后，正式版本要确定接口版本、并备份接口代码。

为方便管理，需要在接口路径中加入版本号信息。

6.3.1http接口

格式规范如下：

”https://127.0.0.1:8080/api/v1/”;

必须以字母开头，并以“/”结尾。

更新版本后可以使用v2 v3等、依次递加。

6.3.2webservice接口

Webservice的接口对应函数命名格式采用小驼峰式方式命名，在函数名的最后加上版本V1。更新版本后可以用V2、V3等、依次递加。

6.4API命名规范

根据域名规范、API路径规范和版本控制规范。Api地址值等于三个相加。

格式规范如下：

“https://127.0.0.1:8080/api/v1/”

接口方法必须要有自己的规范，命名必须统一使用小驼峰命名法。比如：（upperCamelCase）。所有接口命名方式，必须遵循如下规范。

6.4.1新增方法

如新增一个地址、新增一个联系人。

命名规范：

必须以“add”为前缀。例如addAddress

事例地址：https://127.0.0.1:8080/api/v1/addAddress

6.4.2删除方法

如删除一个地址。

命名规范：

必须以“delete”为前缀。例如deleteAddress

事例地址：https://127.0.0.1:8080/api/v1/deleteAddress

6.4.3修改方法

如修改一个地址。

命名规范：

必须以“update”为前缀。例如updateAddress

事例地址：https://127.0.0.1:8080/api/v1/updateAddress

6.4.4获取方法

如获取一个地址。

命名规范：

必须以“get”为前缀。例如getAddress

事例地址：https://127.0.0.1:8080/api/v1/getAddress

6.4.5获取列表方法

如获取一个地址列表。

命名规范：

必须以“get”为前缀、“List”为后缀。例如getAddressList

事例地址：https://127.0.0.1:8080/api/v1/getAddressList

其他规范：发送验证码使用‘send’为前缀、保存一个数据以‘save’为前缀、上传图片以‘uploadImage’为名称等等。

目的：一目了然、降低维护成本。

6.5请求参数规范

6.5.1参数需要命名规则

6.5.2请求参数加密方法

1）对除签名外的所有请求参数按key做的升序排列,value无需编码。（假设当前时间的时间戳是12345678）

例如：有c=3,b=2,a=1 三个参，另加上时间戳后，按key排序后为：a=1，b=2，c=3，_timestamp=12345678。

2）把参数名和参数值连接成字符串，得到拼装字符：a1b2c3_timestamp12345678

3 ）用申请到的appkey连接到接拼装字符串尾部，然后进行32位MD5加密，最后将到得MD5加密摘要转化成大写。（如果没有appkey则不需要拼接，需要加密盐时另行约定告知）示例：假设appkey=test，md5(a1b2c3_timestamp12345678test)，取得MD5摘要值C5F3EB5D7DC2748AED89E90AF00081E6 。

最后访问连接参照

https://127.0.0.1:8080/api/v1/getAddressList?a=1&b=2&c=3&_timestamp=12345678&_sign = C5F3EB5D7DC2748AED89E90AF00081E6

6.6列表请求特殊规范

列表请求，请求参数规范，必须传参：页数和每页个数的字段。并可包含查询等信息。

1. 列表接口必传字段（分页、使用小写字母）。

page ：页数，从1开始。例如：{ “page”: 1 }

subnumber : 每页数量。

2. 列表接口选传字段。

只要是列表接口、一般情况下都会存在检索条件，例如淘宝商品检索。检索条件为选填。后台需进行非空非null判断，选传字段为空为null默认查询全部。有值则需要接收，并进行sql查询。

规范事例：

普通列表接口：https://127.0.0.1:8080/api/v1/getBannerList

（不传page、后台默认返回全部数据）

（banner接口不需要使用检索条件）

需检索列表接口：https://127.0.0.1:8080/api/v1/getOrderList

（不传page、后台默认返回全部数据）

（订单接口需要检索条件，不传就不检索，只进行分页查询）

（如果有时间、价格等检索条件，不传就不检索，传了就进行条件查询，并返回相应数据）

6.7返回数据规范

注：列表数据返回，没有特殊情况的条件下，必须最新数据在上面，依次排序。

返回事例：

{

"list":[],

"object":{}, //"object":""

"status":"SUCCESS",

"message":"我是提示消息",

...

"page":1,

"subnumber":10,

}

必选-命名规范：小驼峰命名法。

必选-新增键值规则：名字对应固定的格式（list就是数组[]）。

比如：比如一个"list":[]满足不了需求，那么可以新增一个"map":[]。

比如如一个"object":{"name":"小明"}满足不了需求，那么可以新增一个"details":{"name":"小红"}。名字对应固定的格式，数组就是数组、实体类就是实体类、字段就是字段。不能data在这个接口返回的是实体类、另一个接口又返回数组了。

第7章接口文档规范

接口文档需要包含以下部分：

文档名称。

版本号。

编写人。

编写、修改日期。

baseUrl地址（例如https://127.0.0.1:8080/api/v1）。

更新日志。

接口详情。（详情规范如下）

接口详情编辑规范：

一个完整的接口需要由以下几部分组成

1.请求地址例如：https://127.0.0.1:8080/xxx/xxx/xxx

2.请求方式例如：POST、GET等

3.请求参数

4.返回参数例如：{ json... } 参考上面的接口规范

第8章接口管理8.1对接口分类、编码排序。

8.2在线文档。

比如比较常用的有Swagger、Blueprint、eolinker