接口设计规范

ゞ浴缸里的玫瑰 2022-05-10 15:16 239阅读 0赞

### 文章目录 ###

*  接口设计规范
 *   *  1 接口示例
     *  2 基本规范
     *   *  2.1 公共参数
         *  2.2 响应数据
         *  2.3 字段类型规范
         *  2.4 上传/下载
         *  2.5 避免精度丢失
     *  3 瘦客户端
     *  4 拓展性
     *  5 安全性
     *  6 兼容性
     *  7 性能优化

# 接口设计规范 #

接口规范化以后，会少很多坑，避免自己下次再遇到。

## 1 接口示例 ##

接口描述：用户登陆成功后，或进入个人中心时会获取一次用户信息

<table> 
 <thead> 
  <tr> 
   <th>URI</th> 
   <th>方法</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>/userinfo</td> 
   <td>GET</td> 
  </tr> 
 </tbody> 
</table>

请求参数

响应参数

<table> 
 <thead> 
  <tr> 
   <th>名称</th> 
   <th>类型</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>id</td> 
   <td>String</td> 
   <td>用户id</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>String</td> 
   <td>姓名，例：张三</td> 
  </tr> 
  <tr> 
   <td>age</td> 
   <td>String</td> 
   <td>年龄，例：20</td> 
  </tr> 
 </tbody> 
</table>

json示例

{ 
        "code":200,
        "msg":"成功",
        "time":"1482213602000",
        "data": { 
            "id":"1001",
            "name":"张三",
            "age":"20"
        }
    }

## 2 基本规范 ##

### 2.1 公共参数 ###

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，用于统计或其他用途，放在header或url参数中。例如

<table> 
 <thead> 
  <tr> 
   <th>字段名称</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>version</td> 
   <td>客户端版本。1.0.0</td> 
  </tr> 
  <tr> 
   <td>token</td> 
   <td>登录令牌</td> 
  </tr> 
  <tr> 
   <td>os</td> 
   <td>手机系统版本。12</td> 
  </tr> 
  <tr> 
   <td>from</td> 
   <td>请求来源。android/ios/h5</td> 
  </tr> 
  <tr> 
   <td>screen</td> 
   <td>手机尺寸。1080*1920</td> 
  </tr> 
  <tr> 
   <td>model</td> 
   <td>机型。IPhone7</td> 
  </tr> 
  <tr> 
   <td>net</td> 
   <td>网络状态。wifi</td> 
  </tr> 
 </tbody> 
</table>

### 2.2 响应数据 ###

响应数据统一格式：code、msg、data。

array类型数据。通过list字段，保证data的Object结构。

分页类型数据。返回总条数，用于判断是否可以加载更多。

// object类型数据
    { 
        "code":1,
        "msg":"成功",
        "data":{ }
    }
    // array类型数据。
    { 
        "code":1,
        "msg":"成功",
        "data":{ 
            "list":[]
        }
    }
    // 分页类型数据。
    { 
        "code":1,
        "msg":"成功",
        "data":{ 
            "list":[]
            "total":"10"
        }
    }

列表类数据接口，无论是否要求分页，最好支持分页，pageSize=Integer.Max即可。

### 2.3 字段类型规范 ###

统一使用String类型。某些情况，统一使用String可以防止解析失败，减少类型转化操作。

Boolean类型，1是0否。客户端处理时，非1都是false。

if("1".equals(isVip)){ 
        
    }else{ 
        
    }

status类型字段，从1+开始，区别Boolean的0和1。“0”有两种含义，（1）Boolean类型的false，（2）默认的status

### 2.4 上传/下载 ###

上传/下载，参数增加文件md5，用于完整性校验（传输过程可能丢失数据）。

### 2.5 避免精度丢失 ###

缩小单位保存数据，如：钱以分为单位、距离以米为单位。

## 3 瘦客户端 ##

客户端尽量不处理逻辑

客户端不处理金额

客户端参数校验规则可以通过接口返回，同时提供默认规则，接口不通则使用默认规则。

## 4 拓展性 ##

图片文案等，与校验规则类似，通过接口返回，并提供默认。

列表界面

// 静态列表
    { 
        "name": "张三",
        "sex": "男",
        "age": "20岁",
        "nickName": "小张"
    }
    // 动态列表
    { 
        "userInfos":[
        { 
            "key":"姓名",
            "value":"张三"
        },{ 
            "key":"性别",
            "value":"男"
        },{ 
            "key":"年龄",
            "value":"20岁"
        },{ 
            "key":"昵称",
            "value":"小张"
        }]
    }

多个boolean可以flag替换

{
        "flag":"7" // 二进制：111，三位分别表示三个boolean字段
    }
    
    long flag = 7;
    System.out.println("bit="+Long.toBinaryString(flag));
    System.out.println("第一位="+((flag&1)==1));
    System.out.println("第二位="+((flag&2)==1));
    System.out.println("第三位="+((flag&4)==1));

## 5 安全性 ##

so层，不懂

## 6 兼容性 ##

区分版本

## 7 性能优化 ##

合并接口。一个页面一个接口

字段简写

无用字段清理

图片裁剪

局部刷新。页面需要的数据，可以用前一个页面带来。

预加载