开发规范

(Updated: )
技术

通用接口返回值格式定义

1.客户端返回值格式

1
2
3
4
5
{
    "stateCode":"String",
    "message":"String",
    "object":int || String || {} || []  //data里的数据是个java对象
}

公用返回码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18


- 200    请求成功服务器成功响应
- 201    账号不存在
- 202    密码错误
- 204    未获取到内容服务器成功处理，但是无返回内容
- 400    没有登录
- 401    无效token
- 403    请联系系统管理员用户无操作该功能权限
- 404    请联系系统维护员请求的xxx不存在
- 405    登录身份不匹配
- 408    服务器等候请求时发生超时服务器等候请求时发生超时
- 500    服务器内部错误系统内部错误
- 0xxx   因客户端请求引起的不成功，根据具体接口参数数量和名称具体定义
- 1xxx   因服务器处理引起的不成功，根据具体接口参数数量和名称具体定义

- 客户端直接提示返回值中的message即可，后端需要在返回值的message中写明失败原因
- 特殊情况在定义新的code码

规范示例

1：处理stateCode示例

1
2
3
4
5
6
7
if(stateCode == "200"){
        //进行成功操作
      }else if(stateCode == "400"){
            //提示用户message中的信息，进行未登录操作
         }else{
                //直接提示用户message中的信息，或根据详细stateCode并做相应操作
              }

1、分页返回示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
params: {
    "pageNum": 1,// 页码
    "pageSize"： 20， //每页大小
}
response：
{
    "stateCode":"200",
    "message":"请求成功",
    "object":{
            "pageNum":1, //当前页码
            "pageSize":20, //每页显示记录数大小
            "size":4,  //当前页记录数量
            "orderBy":null,
            "startRow":1,  //开始行数
            "endRow":4,  //结束行数
            "total":4,  //数据总记录数
            "pages":1,  //总页数
            "list":[{...},{...},{...}],  //当前页数据
            "firstPage":1, //第一页页码
            "prePage":0, //上一页页码
            "nextPage":0,//下一页页码
            "lastPage":1, //最后一页页码
            "isFirstPage":true, //是否是第一页
            "isLastPage":true, //是否是最有一页
            "hasPreviousPage":false, //是否有上一页
            "hasNextPage":false, //是否有下一页
            "navigatePages":8, //导航页码数
            "navigatepageNums":[1] // //所有导航页号
        } 
}

3、单个对象返回示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
params: {
    "code":"021ZLZY32oEkpN0IJRX32n88Z32ZLZYc"
    "url"： ""  //
}
response：
{
    "stateCode":"200",
    "message":"请求成功",
    "object":{
            "timeStamp":"1530690245",
            "signature":"eb3f4b99de2ac50c5921766fd268001992a8b09c",
            "nonceStr":"08dbcdf0-70c7-4809-b517-d52a33155705"
           }
}

4、单个属性返回示例

1
2
3
4
5
6
7
8
9
10
params: {
    "phone":"111"
    "password"： "11"  
}
response：
{
    "stateCode":"200",
    "message":"请求成功",
    "object":"gjfkdddddddddddddddddjk"
}

5、同时返回多个对象示例(map)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
params: {
    "phone":"111"
    "password"： "11"  
}
response：
{
    "stateCode":"200",
    "message":"请求成功",
    "object":{
        "card": {
            "id":111
        },
        "userInfo":{
            "name":"张三"
    }
    }
}

6、数组返回示例(list)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
params: {
    "type":"111"
}
response：
 {
    "stateCode":"200",
    "message":"请求成功",
    "object":[{
        "status":0，
        "statusName": "在线"
    },{
        "status":1，
        "statusName": "离线"
    }]
}

6：含有时间的数据返回

1
时间数据需要给客户端返回是时间戳，不需要后台格式化(可以考虑数据库存储的也是时间戳)

7：接口文档格式

1
接口文档统一使用swagger

8：异常处理机制

1
每个项目必须加上全局异常捕捉，并按照上文约定格式返回状态码为500的结果，避免将异常和错误直接展示在页面。

9：SpringBoot版本

1
1.5.8.RELEASE

10：svn提交注释规范

1
2
3
4
5
6
7
1. 新增功能：说明新增内容(例如：接口/方法/sql/功能等)
2. 功能优化：描述描述优化的内容
3. BUG修复：描述修改的问题和内容
4. 修改配置：描述修改前和修改后的内容
5. 删除功能：描述删除的功能
6. 代码整理：描述整理内容(例如：清除空格/清除回车/整理缩进/代码格式化/清除警告/添加注释等)
7. 修改功能：描述将原来的什么修改为什么

11：文件内容简洁

1
2
1. 不写多余的方法和添加多余的文件
2. 不写多余的sql语句