方案 之 API规范

总规则

---

参数命名原则：都使用驼峰式。如userName。禁止使用，多种形式的命名：userManage-name、userManage_name等。禁止使用没有明确表示的简写，如：userName写成usName等。

针对老旧接口改造原则：在会影响现有功能（主要考虑APP）的前提下，遵循不动老接口，新增接口原则。

传入参数

---

参数使用具体说明

同一接口禁止出现body与query，表单参数（form data）混搭的情况

参数位置	说明	备注
header	带用户信息的权限参数	如（userId、token、orgId、设备Id）
body	业务参数	所有的服务中同业务下的key值保持一致<br/>如：现有a服务，b服务，其中a，b服务都有用户模块，对于用户的id必须统一，如都采用userId
query	不使用	针对老接口不改动，如确保无影响可进行删除
cookie	不使用	目前未使用
表单参数（form data）	主要应用于文件传输	--

传入校验

如某接口需要多个参数或某种固定格式的参数（如手机号，身份证等）需对其进行非空及格式校验，并进行统一文案返回。
例：手机号格式错误，手机号格式不正确（需统一一种文案）（设定枚举类，进行统一返回）

响应方式

---

除遇上传文件，下载文件等其他特殊传输方式，统一采用POST

    method: POST

响应参数

---

同类型接口数据结构一致原则

  {
      code: 0, // 返回状态 0 正常 其他 失败
      data: {}, // 返回数据
      msg: '' // 报错信息，正确信息
  }

接口数据结构中在逻辑不同情况下，遵守不能缺失参数原则

  // 正常
  {
      code: 0,
      data: {
          name: '张三'
      },
      msg: '获取成功' 
  }
  // 非正常
  {
      code: 1,
      data: {
          name: ''  //保证参数结构及参数的数据类型前后统一
      },
      msg: '获取失败' 
  }
  // 错误示范
  {
      code: 1,
      data: null
      msg: '获取失败' 
  }

时间参数一致性原则（前后端传递统一使用时间戳）

   // 错误示范
    {
        code: 0,
        data: {
            createTime: ’2019-01-17‘
        },
        msg: '获取成功' 
    }
    // 统一采用时间戳格式
        {
        code: 0,
        data: {
            createTime: 1579251620621
        },
        msg: '获取成功' 
    }

0错误返回原则

   {
       code: 1,
       data: null,
       msg: 'Error setting expression 'user.companyName' with value '[Ljava.lang.String;@57a41eae'' 
       // 错误需要进行有效合理的过滤，不应返回给前端，前端可能会将其报错信息展示给用户
   }

路径规则

---

统一使用多层级接口。如下：
接口 water/deviceDate/selectDeviceDateAll 中
接口名由服务名+相关controller名+实际方法的接口名组成，应遵守以下规则：
1.服务名相关组成统一由网关配置
2.相关controller名统一与实际controller名一致（可以省略controller单词），并且在相关controller文件中的类名上方定义。
3.实际方法的接口名需要见名知意，不可将单词做随意的简写。接口名在相应方法上方定义。

/serverName/businessName/version

// 例如：水质某接口
/water/waterQualityList/v1  //2019-12-31  第一版接口
/water/waterQualityList/v2  //2019-01-12  第二版接口

注释

---

注释需要尽可能详细，项目中个人负责模块，代码与注释占比应该达到6：4或者更多。

接口统一采用 Swagger + 注释 的形式
每个关键方法前面必须带有 @description 注释

@Autowired
private EmployeeReposiroty employeeReposiroty;
    /**
     * @description 增加人物
     * @param employee
     * @return
     */
    @PostMapping(value = "employee")
    @ApiOperation(value = "新增一个用户",notes = "新增之后返回对象")
    @ApiImplicitParam(paramType = "query",name = "employee",value = "用户",required = true)
    @ApiResponse(code = 400,message = "参数没有填好",response = String.class)
    public String insert(Employee employee){
        Employee employee1 = employeeReposiroty.save(employee);
        if(employee1 != null) {
            return SysNode.Judge.SUCCESS.getResult();
        }else {
            return SysNode.Judge.FAILD.getResult();
        }
    }

错误示例

---

Request URL: https://r.moyuantech.com/admin/suggest/getBannerList
Request Method: POST
Status Code: 200 

// header
token: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyb2wiOiJST0xFX3VzZXIiLCJpc3MiOiJTbmFpbENsaW1iIiwiaWF0IjoxNTc5MTU5ODkwLCJzdWIiOiIxNTU1NTU1NTU1NSIsImV4cCI6MTU4MTc1MTg5MH0.i1dlZPydBZ4mkhhIfZqR4lnYOyWjMuSpLNolzQURkKo
userId: 4
orgId: 66

// body
pageNum: 1
pageSize: 10

{
    "code":0,
    "msg":"ok",
    "data": 
        {
            "total":5,
            "havePerPage":false,
            "pageIndex":1,
            "totalPage":1,
            "haveNexPage":false,
            "isLastPage":true,
            "isFristPage":true,
            "pageSize":10,
            "list":[
                    {
                    "imgurl":"https://web-ct-1258601646.cos.ap-shanghai.myqcloud.com/waterway-app-static/banner5.png",
                    "link":"http://ls.hangzhou.gov.cn/art/2019/12/9/art_1596533_40913367.html",
                    "updateTime":"2020-01-10T19:45:47.000+0000",
                    "id":12125,
                    "state":"1",
                    "putaway":"1",
                    "title":"新闻详情",
                    "showorder":5
                    }
                ]
        }
}

常规异常说明

• 在参数不够的情况下

  • 如未传当前页码，或其他业务参数，需提示，参数错误，或具体到xx参数格式不正确等
  • 如数据库查询异常，网络等综合因素，导致查询失败，应保持返回code:非0状态，并在msg中填入响应的错误信息：如系统异常

常规错误说明

• 参数驼峰形式

  * imgurl----> imgUrl
  * showorder--->showOrder
  * putaway--->putAway

• 时间格式统一

  * pdateTime:"2020-01-10T19:45:47.000+0000"--->updateTime:1579251620621