接口编写 文档规范 总结

正文：

一：协议规范

为进一步确保数据交互安全。正式地址（生产地址）必须遵循HTTPS协议。

二：域名规范

每个项目要有且仅有一个自己唯一的域名+端口。在项目配置文件中要添加静态变量专门进行存储。

如果一个域名满足不了要求，那么就需要再添加一个。

格式规范如下：

（java）public static final String URL_BASE = “https://127.0.0.1:8080/”;

（java）public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;

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

三：API路径规范

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

格式规范如下：

（java）public static final String URL_API = “api/”;

（PHP）php目录是加index.php/api/

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

四：版本控制规范

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

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

格式规范如下：

（java）public static final String URL_VERSION =”v1/”;

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

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

五：API命名规范

根据二：域名规范、三：API路径规范、四：版本控制规范。项目中必须在配置文件中增加BaseUrl静态常量。值=三个相加。

格式规范如下：

（java）public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;

具体代码如下：

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

重要的事情说三遍。

根据业务需求，可以在v1版本文件夹里创建，一个或者多个接口文件。

一个的规范：

https://127.0.0.1:8080/api/v1/getBanner

这就是一个获取banner的接口。

多个的规范是根据业务需求来区分：

https://127.0.0.1:8080/api/v1/home/getBanner

https://127.0.0.1:8080/api/v1/user/userLogin

新建user文件，里面存放用户级别的操作：如登陆、注册、修改密码等等。

新建sms文件，里面存放对短信的接口操作：如发送验证码、验证手机号等等。

所以，接口方法文件必须要有自己的规范，命名必须统一使用驼峰命名法或者下划线拼接命名法。举个栗子：（upperCamelCase）（upper_camel_case）。所有接口命名方式，必须遵循如下规范。

（1）新增方法：如新增一个地址、新增一个联系人。

命名规范：

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

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

（2）删除方法：如删除一个地址。

命名规范：

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

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

（3）修改方法：如修改一个地址。

命名规范：

必须以“updata”为前缀。例如updataAddress

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

（4）获取方法：如获取一个地址。

命名规范：

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

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

（5）获取列表方法：如获取一个地址列表。

命名规范：

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

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

其他规范：

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

具体地址就等于（BASEURL+“address/getAddressList”）

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

六：请求参数规范

请求方式：公共数据使用get方式请求，私有数据使用post方式请求。尽量全部是用post。

请求头：请求头根据项目需求添加配置参数。如：accept=‘application/json

’等。请求头根据项目需求可以要求传入用户token、app名称版本、唯一验签码等加密数据。

​ 请求参数：

根据数据库字段进行命名、保持一致最省事。