# 项目开发约定1.0

**Repository Path**: kangchang/iot

## Basic Information

- **Project Name**: 项目开发约定1.0
- **Description**: 项目开发约定1.0
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://www.zybuluo.com/ck875079028/note/1236091
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2018-07-11
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用接口返回值格式定义

#### 1.客户端返回值格式


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




# 公用返回码


```


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

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

 
# 规范示例
#### 1：处理stateCode示例

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



#### 1、分页返回示例


```
    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、单个对象返回示例


```
    params: {
        "code":"021ZLZY32oEkpN0IJRX32n88Z32ZLZYc"
        "url"： ""  //
    }
    response：
    {
        "stateCode":"200",
        "message":"请求成功",
        "object":{
                "timeStamp":"1530690245",
                "signature":"eb3f4b99de2ac50c5921766fd268001992a8b09c",
                "nonceStr":"08dbcdf0-70c7-4809-b517-d52a33155705"
               }
    }
```


#### 4、单个属性返回示例


```
    params: {
        "phone":"111"
        "password"： "11"  
    }
    response：
    {
        "stateCode":"200",
        "message":"请求成功",
        "object":"gjfkdddddddddddddddddjk"
    }
```



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


```
    params: {
        "phone":"111"
        "password"： "11"  
    }
    response：
    {
        "stateCode":"200",
        "message":"请求成功",
        "object":{
            "card": {
                "id":111
            },
            "userInfo":{
                "name":"张三"
        }
        }
    }
```

#### 6、数组返回示例(list)


```
    params: {
        "type":"111"
    }
    response：
     {
        "stateCode":"200",
        "message":"请求成功",
        "object":[{
            "status":0，
            "statusName": "在线"
        },{
            "status":1，
            "statusName": "离线"
        }]
    }
```

#### 6：含有时间的数据返回

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



#### 7：接口文档格式

```
接口文档统一使用swagger
```


#### 8：异常处理机制

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

#### 9：SpringBoot版本

```
1.5.8.RELEASE
```

#### 10：svn提交注释规范

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

#### 11：文件内容简洁

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