0226 rest接口設計

           

背景

爲了更方便的書寫和闡述問題，文章中按照第一人稱的角度書寫。做爲一個以java爲主要開發語言的工程師，我所描述的都是java相關的編碼和設計。

工程師的靜態輸出就是代碼和文檔，動態的就是各類應用程序（app,h5站點，微信公衆號，小程序）。動態的先不討論，主要討論靜態的。
隨意查看一個代碼庫，能夠看到代碼的編寫過程，某些代碼可能在如今看來實現很低效和好笑，可是在當時的技術和時間場景下，確定是最優的輸出。
也能夠在gitlab上看看每次的pull request ,看看當時對這些代碼的codeReview ;
反饋出的問題就是程序的設計很是重要。而接口是功能的抽象，相對比較穩定，對團隊來講影響比較大。

**

API設計原則

---

先給接口來個簡單的定義：即協議，約定了請求和響應的參數和格式。

接口設計要求是：
1.簡潔；
2.考慮到向後兼容；

業界有一些基本的原則：

1 restfull

restfull是一種設計風格，一切接口皆是資源。


目前是設計的主流，思想也很是先進。

2 參數結構化

請求和響應中的參數要結構化，好處是易讀易用。

3 安全

這個怎麼重要都不爲過，接口設計必須考慮認證和受權，保證特定的人只能訪問特定的資源。


同時須要注意在日誌中不能含有用戶和系統的敏感信息。

4 客戶端無關

也就是接口要通用，能夠處理不一樣客戶端的請求。通常在接口設計的時候，能夠帶入透傳參數，好比時區，位置（省市區），系統類型，系統版本，應用類型，應用版本等；

5 冪等

即接口的第一次請求的結果和後面N次的重試結果要不變，須要結合場景來保證。

API設計實踐

---

接口框架選型

有了接口設計的原則，能夠挑選一個可靠的接口框架來支持本身的工做，

一個好的接口框架應該有以下特色：

1. 對訪問控制的支持；
2. 自動測試的支持；
3. 請求響應格式和序列化的支持；
4. 日誌和日誌過濾的支持；
5. 自動生成文檔的支持；
6. 對架構和性能的影響較小；

我通常選的springmvc，由於平時工做跟spring貼合的比較緊，並且spring有各類生態，適合在不一樣的行業和公司使用。jersey也用，雖然靈活，可是不具有廣泛適用性；

設計中的平衡

1 設定團隊的API設計和實現模式

api太自由，會影響團隊的協做，而共同約定api的設計模式和實現模式能夠解決這個問題。

2 避免過分設計

要綜合考慮向後的兼容性，可是隻實現當前軟件當前階段必須的功能點。

3 謹慎使用AOP

面向切面編程能夠在跟業務無關的垂直領域處理問題，好比日誌，監控，解析等；能夠提升代碼的重用性和規範性；

可是也有缺點，好比，增長了測試和分析的難度，也對研發人員要求比較高。

因此須要綜合考慮。

4 可維護性和性能之間要平衡

接口實現進行封裝能夠提升可維護性，可是也會帶來性能開銷，因此也是須要綜合考慮的。

**

小結

---

經過本篇文章你能夠學到以下內容：

• [ ] 接口設計的原則
• [ ] 接口設計框架選型要點
• [ ] 接口設計過程當中的設計實踐問題

設計良好的接口，能夠提升軟件的複用性，提升團隊的輸出效率和質量。

原創不易，轉載請註明出處，歡迎溝通交流。