用於構建AngularJS應用程序的適當API體系結構

Question

最近，我一直在與很多中級開發人員討論如何構建API以更好地適應AngularJS提供的雙向綁定。我們一直試圖確定API是否應該非常明確，它們的定義可以更好地使用w/Angular，但是會爲中間層帶來更多的工作量，或者更加隱含，並且在Angular中有額外的邏輯來「按摩」將數據轉化爲良好的Angular模型。

讓我們從一個例子開始。假設我們正在談論某種數據備份服務。該服務允許您備份數據並將數據保留X年或無限期。 UI有2個元素來控制這個邏輯。有一個<select>，允許用戶選擇他們是否要刪除數據「從不」或「之後」X年。如果選擇「從不」，那麼我們會隱藏年份輸入，但如果選擇「之後」，那麼我們會顯示年份輸入並允許他們輸入1-99之間的數字。

這樣做我已經引入了2個不同的元素控件，每個控件都控制$scope模型上的不同屬性。

但是，在API上，我的中間層人員想要使用名爲「YearsRetention」的單個屬性來控制所有這些。如果YearsRetention == 0那麼「隱含」意味着我們想要無限制的保留，但是如果它被設置爲任何> 0，那麼保留被設置爲該值。

所以基本上他想要使用這個單一值來控制保留設置，這將迫使我編寫某種轉換函數，以便在$ scope中設置值以實現UI中的相同效果。這種轉換將不得不在傳入和傳出數據上發生。最後，我想知道是否應該隱式定義API（API發送單個值，然後Angular需要將數據轉換爲可用的視圖模型），或者顯式地（API發送直接綁定所需的所有值到用戶界面，並減少需要轉換的JSON）？

Answer 1

我認爲在你描述的設計中有兩個不好的想法。

1. 基於UI的便利性定義數據結構。這是一個糟糕的主意，因爲您希望您的API清晰，多用途（支持具有不同UI的不同客戶端）和長期（API重構在操作上很昂貴）。相反，請嘗試以最純粹，最準確，最通用的形式準確簡潔地表示您的數據，並將格式設置，截斷，本地化，度量單位，頁面佈局等演示文稿問題留給UI。
2. 重載單個數據字段來表達一個概念，它並不是通過「魔法值」自然建模的。爲數字零指定額外的語義含義就是一個例子，它通常被認爲是容易出錯和令人困惑的抽象概念。每個客戶都必須編碼「零」意味着永久的魔術語義。當然，還有明顯的認知失調，即零的真正意義是「完全不」。我將這個模型設置爲2個字段，一個名爲retentionPeriod的枚舉允許正好兩個值：「PERMANENT」和「YEARS」以及一個單獨的字段，用於存儲代表年份的整數。如果你最終失去了與後端開發者的爭論，我至少會爭辯說，魔法值應該是-1意味着永遠而不是0.（我也認爲null比「永遠」比「永遠」更匹配這就是爲什麼我認爲-1是不良魔法選項中最差的。有一些先例在那裏對於這一點，至少）

在特定情況下，我要說你的用戶界面的下拉列表將控制retentionPeriod之一，另一個將控制retentionValue。但是我的推理並不是因爲它恰好以直接的方式與當前的UI實現配對（這更加巧合），這是因爲它更清晰地表示了數據。

這就是說，在我的經驗，這個特定的實例是相當溫和在它的惡。我會更加強烈地關心陣VS對象，模糊或混淆的命名，龐大的數據結構，過於健談的API不正確的選擇，等