接口如何设计

在企业中，前后端分离开发是一种常见的开发模式。在这种模式下，Java 程序员通常负责设计和实现后端 API 接口，而前端工程师则根据这些接口来开发用户界面和功能。

首先明确该接口是一个前后端交互接口，该接口由前端通过HTTP协议进行调用，前端去调用接口需要知道以下内容：

1. HTTP请求方法

2. 接口路径

3. 请求参数类型

4. 请求参数内容

5. 响应结果类型

6. 响应结果状态码

7. 响应结果内容

所以我们设计接口需要设计这些内容。

1. HTTP请求方法

根据RESTful规范:

查询方法用GET，请求参数比较多可用POST

新增方法用POST

修改方法用PUT

删除方法用DELETE

2. 接口路径

定义为RESTful风格的路径。

接口路径为：/微服务名/客户端/具体服务/操作

        示例： /foundations/manager/serve/page

可以在类上边使用@RequestMapping指定该类中接口的路径的基础路径。

在方法中指定具体的路径。

3. 请求参数类型

3.1 json格式

application/json，传递json格式字符串，当传递的参数是属于一个对象的属性时可用此格式，比如：新增、修改时通常传递的数据是某个对象的信息就可以使用此格式。

3.2 表单格式：

application/x-www-form-urlencoded，传递key/value串，就是在url后通过？和&进行拼接的参数，比如：

/foundations/manager/serve/page?pageNo=1&pageSize=10

当传递的参数比较杂且不属于某个特定的对象时使用此格式。

4. 请求参数内容

请求参数的内容根据需求文档和界面原型去识别。

示例：

分页式查询首先有当前页码和每页显示记录数。

对于查询类的接口还有常用的参数有：排序方式、排序字段。

例如，查询某个区域下的服务需要传递一个区域id。

等。

5.响应结果类型

常见的类型有：text/html、text/plain、application/json等。

一般使用application/json。

6. 响应结果状态码

HTTP状态码是服务器返回给客户端的数字代码（三位数字），共分为五类：

1xx: 表示服务器接收到了客户端请求并正在处理

2xx: 表示成功状态码

3xx：表示重向定状态码

4xx：表示客户端错误状态码

5xx: 表示服务端错误状态码

当服务端处理成功返回200，其它表示失败。

7. 响应结果内容

响应结果内容，需要根据界面原型进行分析。

以分页查询为例：

分页查询通用的响应内容有：数据列表、总页数、总记录数；数据列表中需要分析具体的属性，根据界面原型进行分析。

制定分页查询通用的响应内容如下：

msg、code、 data（list、total、pages）是固定的；data中List数据的内容对于不同的分页查询会不一样。

分页查询响应示例：

{
        "msg": "OK",
        "code": 200,
        "data": {
                "list": [
                        {
                                "serveTypeId": 0,
                                "serveItemName": "",
                                "updateTime": "",
                                "saleStatus": 0,
                                "serveItemId": 0,
                                "referencePrice": 0,
                                "createTime": "",
                                "regionId": 0,
                                "price": 0,
                                "id": 0,
                                "isHot": 0,
                                "serveTypeName": ""
                        }
                ],
                "total": 0,
                "pages": 0
        }
}