大家好！今天我們要討論的是 API 設計中的一個關鍵步驟——界定 API 邊界。這個過程就像是在建造一個圖書館之前，先確定每個區域的用途：哪些地方是放書的、哪些地方是供人閱讀的，以及哪些地方需要與其他部門協作。通過合理界定 API 的邊界，我們可以確保 API 的功能既精確又高效，避免陷入過度設計或欠缺設計的陷阱。
1.什麼是API邊界？
API 的邊界決定了它的功能範圍，就像圖書館的功能區劃一樣。清晰地界定 API 的邊界，不僅能夠幫助你專注於 API 的核心功能，還能避免捲入不必要的複雜性和業務耦合，從而提高系統的靈活性和可維護性。
我們先來反向思考一下：如果 API 沒有明確的邊界，會變成什麼樣子？
沒有邊界的 API：多合一反模式
假設今天你要為公司開發一個客戶管理系統，這個系統需要對公司客戶進行 CRUD 操作（Create, Read, Update, Delete），具體需求包括：
- 查詢單筆客戶
- 查詢多筆客戶
- 新增客戶
- 修改單筆客戶
- 批次修改客戶
- 刪除單筆客戶
如果我們不清楚地界定 API 的邊界，而是選擇一個「多合一」的 API 來處理這些需求，那麼 API 可能會設計成這樣：
public class Customer
{
public string Id { get; set; }
public string Name { get; set; }
public string Email { get; set; }
}
public class ApiResult
{
public bool Success { get; set; }
public string Message { get; set; }
public List<Customer> Customers { get; set; }
public Customer SingleCustomer { get; set; }
}
public ApiResult CustomerAction(List<Customer> customers, string actionType)
{
switch (actionType)
{
case "GetSingle":
// 查詢單筆客戶邏輯
break;
case "GetMultiple":
// 查詢多筆客戶邏輯
break;
case "Create":
// 新增客戶邏輯
break;
case "UpdateSingle":
// 修改單筆客戶邏輯
break;
case "UpdateBatch":
// 批次修改客戶邏輯
break;
case "Delete":
// 刪除客戶邏輯
break;
default:
return new ApiResult { Success = false, Message = "無效的操作類型" };
}
return new ApiResult { Success = true, Message = "操作成功" };
}
或許部分初學者會覺得這不就是switch case 的用法，根據Type來分類並執行他的動作，但若是把詳細的各動作邏輯都寫出來，程式碼的閱讀性會變的非常糟糕。不妨看看下面這個將邏輯部分完整呈現的範例：
public class Customer
{
public string Id { get; set; }
public string Name { get; set; }
public string Email { get; set; }
}
public class ApiResult
{
public bool Success { get; set; }
public string Message { get; set; }
public List<Customer> Customers { get; set; }
public Customer SingleCustomer { get; set; }
}
private List<Customer> _customers = new List<Customer>();
public ApiResult CustomerAction(List<Customer> customers, string actionType, string customerId = null)
{
switch (actionType)
{
case "GetSingle":
var customer = _customers.FirstOrDefault(c => c.Id == customerId);
if (customer == null)
{
return new ApiResult { Success = false, Message = "客戶不存在" };
}
return new ApiResult { Success = true, Message = "查詢成功", SingleCustomer = customer };
case "GetMultiple":
return new ApiResult { Success = true, Message = "查詢成功", Customers = _customers };
case "Create":
foreach (var newCustomer in customers)
{
_customers.Add(newCustomer);
}
return new ApiResult { Success = true, Message = "新增成功" };
case "UpdateSingle":
var existingCustomer = _customers.FirstOrDefault(c => c.Id == customerId);
if (existingCustomer == null)
{
return new ApiResult { Success = false, Message = "客戶不存在" };
}
existingCustomer.Name = customers[0].Name;
existingCustomer.Email = customers[0].Email;
return new ApiResult { Success = true, Message = "更新成功" };
case "UpdateBatch":
foreach (var updatedCustomer in customers)
{
var customerToUpdate = _customers.FirstOrDefault(c => c.Id == updatedCustomer.Id);
if (customerToUpdate != null)
{
customerToUpdate.Name = updatedCustomer.Name;
customerToUpdate.Email = updatedCustomer.Email;
}
}
return new ApiResult { Success = true, Message = "批次更新成功" };
case "Delete":
var customerToDelete = _customers.FirstOrDefault(c => c.Id == customerId);
if (customerToDelete == null)
{
return new ApiResult { Success = false, Message = "客戶不存在" };
}
_customers.Remove(customerToDelete);
return new ApiResult { Success = true, Message = "刪除成功" };
default:
return new ApiResult { Success = false, Message = "無效的操作類型" };
}
}
看到這一大陀的程式碼，如果要針對特定的功能進行測試與修改，你要先能一眼找出要修改的點變的非常困難，更何況上述還不是很完整的處理商業邏輯，還是非常省略過後的程式。因此我們能看到
沒有邊界的 API 帶來的問題
這種多合一的 API 設計看起來很方便，所有的操作都集中在一個方法中。然而，這種設計會帶來以下問題：
- 可讀性差： 隨著功能的增多，CustomerAction 方法的代碼將變得越來越長，難以維護。每次新增或修改功能，都需要改動這個方法，容易引入錯誤。
- 高耦合度： 不同的業務邏輯被耦合在一起，任何一個操作的改變都可能影響到其他操作，導致代碼的穩定性下降。
- 難以測試： 由於所有操作都集中在一個方法中，對這個方法進行單元測試時需要考慮多種情況，測試複雜度大大增加。
- 無法擴展： 當你需要為客戶管理系統新增更多功能時，這個多合一 API 的複雜性會成倍增長，最終導致代碼難以擴展。
有邊界的 API 設計：分而治之
為了解決上述問題，我們需要明確 API 的邊界，將不同的操作分散到不同的 API 方法中。這樣，每個 API 只負責一項具體的功能，既清晰又易於維護。
public ApiResult GetCustomerById(string id)
{
// 查詢單筆客戶邏輯
}
public ApiResult GetCustomers()
{
// 查詢多筆客戶邏輯
}
public ApiResult CreateCustomer(Customer customer)
{
// 新增客戶邏輯
}
public ApiResult UpdateCustomer(Customer customer)
{
// 修改單筆客戶邏輯
}
public ApiResult UpdateCustomers(List<Customer> customers)
{
// 批次修改客戶邏輯
}
public ApiResult DeleteCustomer(string id)
{
// 刪除單筆客戶邏輯
}
有邊界的 API 帶來的好處
- 清晰的結構： 每個 API 方法只負責一項具體任務，代碼結構清晰，易於閱讀和理解。
- 低耦合度： 不同的業務邏輯被分開，修改某一個功能時，不會影響到其他功能，代碼更穩定。
- 易於測試： 由於每個 API 方法只負責一個功能，測試變得簡單，能夠專注於測試單一功能的正確性。
- 良好的可擴展性： 當需要新增功能時，可以輕鬆地添加新的 API 方法，而不會影響到現有的功能。
上面的程式範例，還不是主流的架構設計下的程式碼範例，帶篇幅慢慢帶到，會一步一步將程式碼修正到較好的架構與設計。
2. 如何界定 API 邊界？
界定 API 邊界涉及多個步驟，從理解業務需求到識別核心資源，再到劃分功能責任。這些步驟幫助我們構建一個精確且靈活的 API，能夠滿足業務需求而不會過度膨脹。
- 理解業務需求： 首先，你需要深入理解 API 所服務的業務領域。這意味著你必須清楚地了解業務流程，以及哪些功能是 API 必須支持的。例如，在圖書館管理系統中，圖書的借閱和歸還是核心功能，因此這部分必須由 API 來處理。
- 識別核心資源： 核心資源是 API 必須管理的主要對象，這些資源通常是業務中最重要的實體。在圖書館管理系統中，核心資源可能包括「圖書」、「用戶」和「借閱記錄」。這些資源的管理需要被 API 清晰地界定和實現。
- 劃分功能責任： 明確哪些功能應該由 API 來處理，哪些應該留給其他系統或模組來完成。例如，圖書館的書籍管理和借閱系統可以由 API 處理，但身份驗證和支付功能可能應該交給專門的第三方服務來負責。這種劃分可以讓 API 聚焦於核心業務，同時保持整個系統的靈活性和可擴展性。
- 正確的HTTP 規格：
正確使用 HTTP 方法和狀態碼是界定 API 邊界的重要部分。遵循 RESTful 設計原則，我們可以更清晰地定義 API 的功能和行為：
同時，使用適當的 HTTP 狀態碼可以更好地表達 API 的響應：
通過正確使用 HTTP 方法和狀態碼，我們可以更好地定義 API 的邊界，使其行為更加清晰和可預測。 - GET： 用於獲取資源，不應該對資源進行修改。例如，獲取圖書信息或借閱記錄。
- POST： 用於創建新資源。例如，添加新的圖書或創建新的借閱記錄。
- PUT： 用於更新現有資源。例如，更新圖書信息或修改借閱記錄。
- DELETE： 用於刪除資源。例如，刪除過期的借閱記錄。
- PATCH： 用於部分更新資源。例如，更新圖書的部分信息而不是全部。
- 200 OK： 請求成功。
- 201 Created： 資源創建成功。
- 204 No Content： 請求成功，但無返回內容（如刪除操作）。
- 400 Bad Request： 請求格式錯誤。
- 404 Not Found： 請求的資源不存在。
- 500 Internal Server Error： 服務器內部錯誤。
3. 案例分析：圖書館管理系統的 API 邊界
假設你正在設計一個圖書館管理系統的 API，我們可以通過以下方式來界定它的邊界：
- 應該處理的功能：
- 圖書管理： API 應該負責圖書的新增、查詢、更新和刪除。這些操作直接關係到圖書館的核心業務——書籍管理。
- 借閱管理： API 還應該負責處理書籍的借閱和歸還，包括借閱記錄的維護，這是圖書館運作的關鍵部分。
- 不應該處理的功能：
- 身份驗證： 這部分應該由專門的身份驗證系統處理，API 只需接收來自身份驗證系統的驗證結果並據此進行操作。
- 支付處理： 如果涉及到罰款或其它支付項目，應該由第三方支付服務來處理，API 只需與該支付系統進行集成，處理支付結果即可。
這樣的劃分可以幫助 API 專注於圖書館的核心業務，而不會因為捲入過多的非核心功能而變得複雜難維護。
總結：
界定 API 邊界是設計高效且可維護 API 的第一步。通過明確 API 的職責範圍，我們可以確保它專注於核心業務，並且能夠靈活應對未來的需求變更。這種精確的劃分可以避免過度設計和欠缺設計，從而提高整個系統的穩定性和可擴展性。明天，我們將在此基礎上進一步討論如何建立 API 模型，這將為 API 的實際開發奠定堅實的基礎。
