api - 显式 API 方法与广义的基于参数的 API 方法

Question

在定义客户可访问的 API 时，以下是首选的行业惯例:

a) 定义一组显式 API 方法，每个方法都有非常狭窄和特定的目的，例如:

SetUserName    <name>
SetUserAge     <age>
SetUserAddress <address>

b)定义一组更通用的基于参数的API方法，例如:

SetUserAttribute <attribute>

enum attribute {
    name,
    age,
    address
}

我的看法:

赞成 (a)

对于基于 bool 值的方法(例如 EnableFoo)，我绝对赞成选项 (a)，因为意图更加明确，将来不太可能需要扩展，并且它使代码更具可读性。

例如，一个名为 EnableDisableFoo 的方法采用一个 bool 参数来指示是启用还是禁用，这将不是很清楚，也没有内聚的目的。

在有多个选项的情况下，问题会变得更加复杂。

赞成 (b)

选项 (b) 是在 API 中提供可扩展性的好方法，但以牺牲可用性为代价。对于选项 (a)，API 方法名称本身提供了足够的信息来表明它在做什么。对于选项 (b)，用户必须同时查找方法名称和要使用的适当枚举/参数。从理论上讲，从可用性的角度来看，这会使选项 (b) 变得更糟——但也许方法更少是一件好事，所以即使这也不完全正确。

其他想法

有必要在可用性和可扩展性之间取得良好的平衡，而这两者往往相互矛盾。但我想有一种更客观的方法来分析这一点，而不是依赖于 API 设计者的意见。

有没有人对此有任何想法？

Answer 1

我个人赞成 (a)，因为我们的目标是使“静态”代码尽可能准确可靠。

通过使用通用形式，我们引入了运行时错误的风险。例如，我可以设置一个年龄类型的属性，其值实际上是一个字符串等。

这与定义和使用枚举或显式类型而不是在旧 C 风格中使用和返回整数的论点非常相似，因为您获得了更高级别的保证。

虽然我同意 (b) 允许可扩展性，但我还没有看到太多的 API 需要这种可扩展性以用于完全不同类型的属性。 (b) 的唯一常见用途是在多态代码中，其中函数在技术上可以接受任何东西，包括扩展。