文章目錄

• 介面設計規範
• 1 介面示例
• 2 基本規範
• 2.1 公共引數
• 2.2 響應資料
• 2.3 欄位型別規範
• 2.4 上傳/下載
• 2.5 避免精度丟失
• 3 瘦客戶端
• 4 拓展性
• 5 安全性
• 6 相容性
• 7 效能優化

介面設計規範

介面規範化以後，會少很多坑，避免自己下次再遇到。

1 介面示例

介面描述：使用者登陸成功後，或進入個人中心時會獲取一次使用者資訊

請求引數

響應引數

json示例

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

2 基本規範

2.1 公共引數

公共引數是每個介面都要攜帶的引數，描述每個介面的基本資訊，用於統計或其他用途，放在header或url引數中。例如

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 效能優化

合併介面。一個頁面一個介面

欄位簡寫

無用欄位清理

圖片裁剪

區域性重新整理。頁面需要的資料，可以用前一個頁面帶來。

預載入