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

Proper API architecture for building AngularJS applications

本文关键字：API 架构构建 AngularJS 应用程序用于更新时间：2023-09-26

最近我一直在和我的许多中层开发人员讨论如何构建 API，以便更好地适应 AngularJS 提供的 2 向绑定。我们一直在尝试决定 API 是否应该非常明确地说明它们的定义，这些定义在 Angular 下会更好，但会导致中层的工作更多，或者更隐含，并且在 Angular 中有额外的逻辑来"按摩"数据到一个好的 Angular 模型中。

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

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

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

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

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

我认为您描述的设计中有 2 个坏主意。

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

在您的特定情况下，我认为您的一个 UI 下拉列表将控制retentionPeriod，另一个将控制retentionValue。但我这样做的理由不是因为它碰巧以直接的方式与您当前的 UI 实现配对(这更像是一个令人高兴的巧合(，而是因为它更清晰地表示数据。

也就是说，根据我的经验，这个特定的例子在糟糕方面相当温和。我会更强烈地担心数组与对象的错误选择、模糊或混乱的命名、巨大的数据结构、过于健谈的 API 等。