javascript - 用于构建 AngularJS 应用程序的正确 API 架构

Question

最近我一直在与我的许多中层开发人员讨论如何构建 API 以便更好地适应 AngularJS 提供的双向绑定(bind)。我们一直在尝试决定 API 是否应该非常明确地定义它们，这样可以更好地使用 Angular，但会为中间层带来更多的工作，或者更隐含，并且在 Angular 中有额外的逻辑来“按摩”将数据转化为良好的 Angular 模型。

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

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

但是，在 API 上，我的中层人员希望使用一个名为“YearsRetention”的属性来控制所有这些。如果YearsRetention == 0那么“隐式”意味着我们想要无限保留，但如果它被设置为大于 0 的任何值，则保留被设置为该值。

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

最后，我想知道 API 应该隐式定义(API 发送单个值，然后 Angular 必须将数据转换为可用的 View 模型)还是显式定义(API 发送所有需要的值直接绑定(bind)到UI 并减少转换 JSON 的需要)？

Answer 1

我认为您描述的设计中有 2 个糟糕的想法。

1. 根据用户界面的便利性定义数据结构。这是一个坏主意，因为您希望您的 API 清晰、多用途(可能支持具有不同 UI 的不同客户端)和长生命周期(API 重构在操作上代价高昂)。相反，尝试以最纯粹、最准确、最通用的形式准确简洁地表示您的数据，并将格式、 chop 、本地化、度量单位、页面布局等呈现问题留给 UI。
2. 重载单个数据字段以表达它不会通过“魔法值”自然建模的概念。为数字零分配额外的语义就是一个例子，它通常被认为容易出错、令人困惑并且是一种有漏洞的抽象。每个客户端都必须对零意味着永远的神奇语义进行编码。当然，存在明显的认知失调，即零的真正含义是“一点也不”。我将其建模为 2 个字段，一个名为 retentionPeriod 的枚举只允许 2 个值:“PERMANENT”和“YEARS”以及一个单独的字段可能是 retentionValue 来存储表示的整数这些年。如果你最终输掉了与后端开发人员的争论，我至少会争辩说魔法值应该是 -1，意思是永远而不是 0。(我还认为 null 匹配“根本不匹配” "而不是 "永远"，这就是为什么我认为 -1 是坏魔法选项中最不坏的。至少有一些先例)

在您的特定情况下，我认为您的 UI 下拉菜单之一将控制 retentionPeriod，而另一个将控制 retentionValue。但我对此的推理并不是因为它恰好以一种直接的方式与您当前的 UI 实现配对(这更像是一个快乐的巧合)，而是因为它更清晰地表示数据。

也就是说，根据我的经验，这个特定实例的坏处相当轻微。我会更加担心数组与对象的错误选择、模糊或困惑的命名、庞大的数据结构、过于繁琐的 API 等。