.NET API 中的字符串或 URI？

Posted 2023-02-19

【中文标题】.NET API 中的字符串或 URI？

【英文标题】：Strings or URI in .NET APIs?

【发布时间】：2010-09-17 21:40:12

【问题描述】：

我正在为 Netflix API 编写一个 .NET 包装 API。

此时我可以选择将 URL 表示为字符串或 URI 对象。在我看来，两者都有很好的案例。

那么，如果您使用的是 API，您会更喜欢哪一种？

【问题讨论】：

愿意分享您可以为两者制作的案例吗？

【参考方案1】：

以下引用来自：Framework Design Guildelines 我强烈向任何在 .Net 上开发框架的人推荐这本书

请使用 System.Uri 来表示 URI / URL 数据。（对于参数， 属性和返回值）

System.Uri 更安全、更丰富 表示 URI 的方式。广泛的 使用 URI 相关数据的操作 纯字符串已被证明会导致 许多安全性和正确性 问题。

考虑为最常用的提供基于字符串的重载 具有 System.Uri 参数的成员。

在使用模式的情况下 从用户那里获取一个字符串将是 很常见，你应该考虑 添加便利重载 接受一个字符串。基于字符串的 过载应在实施 基于 Uri 的重载术语。

不要使用一个版本自动重载所有基于 Uri 的成员 接受一个字符串。

通常，基于 Uri 的 API 是 首选。基于字符串的重载是 应该是最多的帮手 常见的场景。因此，你 不应自动提供 所有基于字符串的重载 基于 Uri 的成员的变体。是 有选择性并提供这样的帮助者 只针对最常用的 变种。

编辑（每 cmets）：该书特别指出：“使用纯字符串对 URI 相关数据的广泛操作已被证明会导致许多安全性和正确性问题。” 我不确定您希望使用 System.Uri / UriBuilder 有什么额外的理由。此外，您为什么不想利用框架来读取/操作 URI？

在设计将被其他人使用的 API 时，重要的是要使其易于使用，以及可靠。出于这个原因，本书确实提到，您应该为常见功能提供“不错的”重载。但是，为了确保正确性，您应该始终使用 URI 实现底层代码。

您能否说明您的需求或仅使用字符串的原因？

【讨论】：

提供本书链接的奖励积分，我直到现在才知道。

但是为什么呢？我读过这本书，它实际上并不能证明这个决定是正确的。

您问，“为什么不想利用框架来读取/操作 URI？”。好吧，大多数框架提供的用于操作 URI 的函数都适用于字符串，而不是 System.Uri。正是这种认识首先提出了这个问题。

【参考方案2】：

我会说你应该将它表示为 URI。但是，如果我是您的 API 的用户，并且我必须不断地将基于字符串的 URL 转换为 URI 以使用您的 API，那么我将是一个生气的用户。

我的意思是，您需要评估什么样的受众会使用您的 API。

【讨论】：

为什么要使用 URI？它真正给了你什么？

【参考方案3】：

我发现的一件事是，在编写 string-accepting 方法时，我总是必须初始化一个 Uri 对象来验证字符串，这样 UriFormatException 就会传播出方法如果用户传递了错误的字符串。但是，如果你只接受Uris，就像我在被 FxCop （正确地）大喊大叫之后所做的那样，那么你总是知道你的输入是有效的——这对我来说似乎是一个很好的迹象，表明你正在设计你的 API正确。

【讨论】：

碰巧，我知道我所有的网址都是正确的，因为它们要么由我生成，要么由受信任的来源提供给我。所以除了验证之外，它真的能给你什么吗？

嗯，它给了你同样的东西，当你想要一个整数时接受一个“int”（而不是一个字符串，然后调用 int.Parse）给你。