用于构建AngularJS应用程序的适当API体系结构

Question

最近，我一直在与很多中层开发人员讨论如何构建API，以便更好地适应AngularJS提供的双向绑定。我们一直在尝试决定API是否应该非常明确地使用它们的定义，这些定义可以更好地使用Angular，但是会为中间层做更多的工作，或者更隐含，并且在Angular中有更多的逻辑到＃34 ;按摩＆＃34;将数据转化为一个好的Angular模型。

让我们从一个例子开始。假设我们正在谈论某种数据备份服务。该服务允许您备份数据并将数据保留X年或无限期。 UI有2个元素来控制这个逻辑。有<select>允许用户选择是否要删除数据＆＃34;从不＆＃34;或＆＃34;之后＆＃34; X年。如果＆＃34;从不＆＃34;选择然后我们隐藏年份输入，但如果＆＃34; After＆＃34;选中，然后我们显示年份输入并允许他们输入1-99之间的数字。

这样做我引入了2个不同的元素控件，每个控件都控制$scope模型上的不同属性。

然而，在API上我的中级人员希望使用名为＆＃34; YearsRetention＆＃34;的单个属性来控制所有这一切。如果YearsRetention == 0那么＆＃34;隐含地＆＃34;意味着我们想要无限制的保留，但如果设置为任何＆gt; 0然后保留设置为该值。

所以基本上他想使用这个单一值来控制保留设置，这会迫使我编写某种转换函数，以便在$ scope上设置值以在UI中实现相同的效果。这种转换必须在传入和传出数据上发生。

最后，我想知道是否应该隐式定义API（API发送单个值，然后Angular必须将数据转换为可用的视图模型）或显式（API发送直接绑定所需的所有值） UI并减少了转换JSON的需要）？

Answer 1

我认为您描述的设计中有两个不好的想法。

1. 基于UI便利性定义数据结构。这是一个坏主意，因为您希望您的API清晰，多用途（可能支持具有不同UI的不同客户端），并且长期存在（API重构在操作上非常昂贵）。相反，尝试以最纯粹，最准确，最通用的形式准确，简洁地表示您的数据，并将演示文稿问题（如格式化，截断，本地化，度量单位，页面布局等）留给UI。
2. 重载单个数据字段以表达一个概念，即它不会通过“魔法值”自然地进行建模＆＃34;。为零号分配额外的语义含义就是一个例子，它通常被认为是容易出错和混乱以及漏洞的抽象。每个客户端都必须编码零意味着永远的魔术语义。当然，有明显的认知失调，零的真正含义将是“完全没有”＃34;。我将其建模为2个字段，一个名为retentionPeriod的枚举，只允许2个值：＆＃34; PERMANENT＆＃34;和＆＃34;年＆＃34;和一个单独的字段retentionValue可以存储表示年份的整数。如果你最终失去了与后端开发者的争论，我至少会争辩说魔术值应该是-1意味着永远而不是0.（我也认为null匹配＆＃34;不是在所有＆＃34;超过＆＃34;永远＆＃34;这就是为什么我认为-1是坏魔术选项中最不好的原因。至少有一些先例可以做到这一点，至少）

在您的具体情况下，我认为您的某个UI下拉菜单会控制retentionPeriod而另一个会控制retentionValue。但我的理由不是因为它恰好以一种简单的方式与你当前的UI实现配对（这更令人愉快的巧合），这是因为它更清晰地代表了数据

那就是说，根据我的经验，这个具体的例子相当温和。我更关心的是数组与对象的错误选择，模糊或混淆的命名，巨大的数据结构，过于繁琐的API等等。