歡迎光臨
每天分享高質量文章

我的編碼習慣 —— API 接口定義

點擊上方“芋道原始碼”,選擇“置頂公眾號”

技術文章第一時間送達!

原始碼精品專欄

 

來源:https://zhuanlan.zhihu.com/p/28708259

工作中,少不了要定義各種接口,系統集成要定義接口,前後臺掉呼叫也要定義接口。接口定義一定程度上能反應程式員的編程功底。列舉一下工作中我發現大家容易出現的問題:

1. 傳回格式不統一

同一個接口,有時候傳回陣列,有時候傳回單個;成功的時候傳回物件,失敗的時候傳回錯誤信息字串。工作中有個系統集成就是這樣定義的接口,真是辣眼睛。這個對應代碼上,傳回的型別是map,json,object,都是不應該的。實際工作中,我們會定義一個統一的格式,就是ResultBean,分頁的有另外一個PageResultBean

錯誤範例:

 //傳回map可讀性不好,儘量不要
 @PostMapping("/delete")
  public Map delete(long id, String lang) {

  }

  // 成功傳回boolean,失敗傳回string,大忌
  @PostMapping("/delete")
  public Object delete(long id, String lang) {
    try {
      boolean result = configService.delete(id, local);
      return result;
    } catch (Exception e) {
      log.error(e);
      return e.toString();
    }
  }

2. 沒有考慮失敗情況

一開始只考慮成功場景,等後面測試發現有錯誤情況,怎麼辦,改接口唄,前後臺都改,勞民傷財無用功。

錯誤範例:

 //不傳回任何資料,沒有考慮失敗場景,容易返工
 @PostMapping("/update")
  public void update(long id, xxx) {

  }

3. 出現和業務無關的輸入引數

如lang語言,當前用戶信息 都不應該出現引數裡面,應該從當前會話裡面獲取。後面講ThreadLocal會說到怎麼樣去掉。除了代碼可讀性不好問題外,尤其是引數出現當前用戶信息的,這是個嚴重問題。

錯誤範例:

 // (當前用戶刪除資料)引數出現lang和userid,尤其是userid,大忌
 @PostMapping("/delete")
  public Map delete(long id, String lang, String userId) {

  }

4. 出現複雜的輸入引數

一般情況下,不允許出現例如json字串這樣的引數,這種引數可讀性極差。應該定義對應的bean。

錯誤範例:

 // 引數出現json格式,可讀性不好,代碼也難看
 @PostMapping("/update")
  public Map update(long id, String jsonStr) {

  }

5. 沒有傳回應該傳回的資料

例如,新增接口一般情況下應該傳回新物件的id標識,這需要編程經驗。新手定義的時候因為前臺沒有用就不傳回資料或者只傳回true,這都是不恰當的。別人要不要是別人的事情,你該傳回的還是應該傳回。

錯誤範例:

 // 約定俗成,新建應該傳回新物件的信息,只傳回boolean容易導致返工
 @PostMapping("/add")
  public boolean add(xxx) {
    //xxx
    return configService.add();
  }

很多人看了我的這篇文章 程式員你為什麼這麼累?,都覺得裡面的技術也很簡單,沒有什麼特別的地方,但是,實現這個代碼框架之前,就是要你的接口的統一的格式ResultBean,aop才好做。有些人誤解了,我那篇文章說的都不是技術,重點說的是編碼習慣工作方式,如果你重點還是放在什麼技術上,那我也幫不了你了。同樣,如果我後面的關於習慣和規範的帖子,你重點還是放在技術上的話,那是丟了西瓜撿芝麻,有很多貼還是沒有任何技術點呢。

附上ResultBean,沒有任何技術含量:

@Data
public class ResultBean<Timplements Serializable {

  private static final long serialVersionUID = 1L;

  public static final int SUCCESS = 0;

  public static final int FAIL = 1;

  public static final int NO_PERMISSION = 2;

  private String msg = "success";

  private int code = SUCCESS;

  private T data;

  public ResultBean() {
    super();
  }

  public ResultBean(T data) {
    super();
    this.data = data;
  }

  public ResultBean(Throwable e) {
    super();
    this.msg = e.toString();
    this.code = FAIL ;
  }
}

統一的接口規範,能幫忙規避很多無用的返工修改和可能出現的問題。能使代碼可讀性更加好,利於進行aop和自動化測試這些額外工作。大家一定要重視。



如果你對 Dubbo / Netty 等等原始碼與原理感興趣,歡迎加入我的知識星球一起交流。長按下方二維碼噢

目前在知識星球更新了《Dubbo 原始碼解析》目錄如下:

01. 除錯環境搭建
02. 專案結構一覽
03. 配置 Configuration
04. 核心流程一覽

05. 拓展機制 SPI

06. 執行緒池

07. 服務暴露 Export

08. 服務取用 Refer

09. 註冊中心 Registry

10. 動態編譯 Compile

11. 動態代理 Proxy

12. 服務呼叫 Invoke

13. 呼叫特性 

14. 過濾器 Filter

15. NIO 服務器

16. P2P 服務器

17. HTTP 服務器

18. 序列化 Serialization

19. 集群容錯 Cluster

20. 優雅停機

21. 日誌適配

22. 狀態檢查

23. 監控中心 Monitor

24. 管理中心 Admin

25. 運維命令 QOS

26. 鏈路追蹤 Tracing

… 一共 69+ 篇

目前在知識星球更新了《Netty 原始碼解析》目錄如下:

01. 除錯環境搭建
02. NIO 基礎
03. Netty 簡介
04. 啟動 Bootstrap

05. 事件輪詢 EventLoop

06. 通道管道 ChannelPipeline

07. 通道 Channel

08. 位元組緩衝區 ByteBuf

09. 通道處理器 ChannelHandler

10. 編解碼 Codec

11. 工具類 Util

… 一共 61+ 篇

目前在知識星球更新了《資料庫物體設計》目錄如下:


01. 商品模塊
02. 交易模塊
03. 營銷模塊
04. 公用模塊

… 一共 17+ 篇


目前在知識星球更新了《Spring 原始碼解析》目錄如下:


01. 除錯環境搭建
02. IoC Resource 定位
03. IoC BeanDefinition 載入

04. IoC BeanDefinition 註冊

05. IoC Bean 獲取

06. IoC Bean 生命周期

… 一共 35+ 篇


原始碼不易↓↓↓

點贊支持老艿艿↓↓

赞(0)

分享創造快樂