前言

前幾天提到要將後端分離另外寫成API，
那麼命名也是其中非常重要的一點，
因為重構舊系統，裡面的內容要能保留可讀性，
並且讓前端串接的開發者方便串接，
這一篇來整理一下關於API命名。

API命名

在軟體開發中，API（Application Programming Interface）是不可或缺的組成部分。
API允許不同的軟體系統之間進行通信，提供了功能和數據的交互方式。
然而，設計良好的API需要注意多個方面，其中一個關鍵因素是命名。
本篇文章將討論API命名的重要性，以及如何通過良好的API命名來提升開發者體驗和系統可讀性。

API命名的重要性

API命名的質量對軟體開發有著深遠的影響，因為API是不同軟體模塊之間的接口，
也是不同開發者之間溝通的一種方式。以下是一些API命名的重要性：

1. 開發者體驗

良好的API命名可以提升開發者的體驗。
當API元素的名稱清晰、一致和具有描述性時，開發者更容易理解API的功能和如何使用它。
這可以減少學習曲線，加速開發過程，並降低犯錯的風險。

2. 可讀性和可維護性

良好的API命名有助於提高代碼的可讀性和可維護性。
當代碼中使用具有描述性的名稱時，代碼更容易理解，並且不需要過多的註釋。
這使得代碼庫更容易維護，並且新的開發者可以更快地融入團隊。

3. 減少混淆和錯誤

不清晰或混淆的API命名可能導致錯誤和混淆。
如果不同的API元素使用相似或含糊不清的名稱，開發者可能會誤用它們，這可能導致系統錯誤。
明確的API命名有助於避免這些問題。

4. 提高系統的可互操作性

當多個系統或服務需要進行集成時，具有一致和明確API命名的API使得不同系統之間更容易互操作。
開發者可以更輕鬆地理解如何使用其他系統的API，而不需要深入研究文檔。

API命名的範例

現在我們已經理解了API命名的重要性，接下來我們將討論一些API命名的範例。

1. 使用有描述性的名稱

API元素的名稱應具有明確的描述性。
開發者應該能夠根據名稱理解該元素的功能和目的。
例如，一個購物車應該使用名稱"getShoppingCart"，而不是"getInfo"。

2. 遵循命名慣例

在API命名中，應該遵循一致的命名慣例。
包括使用駝峰命名法（camelCase）或其他廣泛接受的風格。
有助於提高代碼的一致性，使其更易讀。

3. 使用規範性詞彙

避免使用模棱兩可或專有的詞彙。
API名稱應使用通用和規範性的詞彙，以便更多的開發者能夠理解它們。
例如，使用"saveUser"而不是"saveUsr"。

4. 避免縮寫

縮寫可能導致混淆。
盡量避免在API命名中使用縮寫，除非該縮寫是廣泛接受的，並且不會引起混淆。
例如，使用"updateUser"而不是"updateUsr"。

5. 提供清晰的文檔

除了良好的API命名，也應該提供清晰的文檔。
文檔應該描述API元素的功能、參數、返回值和使用示例。
有助於開發者更好地理解和使用API。

一些API命名的示例

以下是一些常見的API元素以及不佳和最佳的API命名示例：

1. 購物車API

不佳命名：

• getInfo
• retrieveData
• updateThing

較好的命名：

• getShoppingCart
• fetchCartData
• updateCartItem

在這個案例中，良好的API命名使得開發者能夠清晰地理解每個API的目的。

2. 用戶管理API

不佳命名：

• saveUsr
• deleteU
• updatecustomer

較好的命名：

• saveUser
• deleteUser
• updateCustomer

良好的API命名在這裡有助於消除拼寫錯誤，使代碼更容易閱讀。

結語

API命名是軟體開發過程中至關重要的一環。
良好的API命名可以提升開發者體驗、增加代碼的可讀性、減少錯誤和混淆，並提高系統的可互操作性。
遵循API命名的規則，使用有描述性的名稱、遵循命名慣例、使用規範性詞彙、避免縮寫，
並提供清晰的文檔，將有助於創建優秀的API。
通過投資時間和精力來設計和命名API，
可以大大提高軟體項目的成功機會，並為未來的開發者提供更好的開發體驗。