问题标签 [api-design]

我在大约 12 人的开发团队中工作，我们构建了一组合理的 API，我们仅在内部严格使用这些 API。通常，所有类和接口都是公共的，因为这就是它们的完成方式。我经常考虑将一些构造函数设为内部的价值，这样 API 的使用者（尽管是内部的）必须使用工厂或其他我现在想不到的原因。

这是你和你的团队练习的吗？

这对您的单元测试有何影响？您是否发现可以通过它的工厂对一个类进行单元测试，或者您是否可以通过 PrivateObject 之类的东西访问构造函数？

我正在尝试向现有库添加新功能。我需要将新数据添加到类层次结构中，以便根类具有它的访问器。任何人都应该能够获取这些数据，只有子类可以设置它（即公共 getter 和受保护的 setter）。

为了保持向后兼容性，我知道我不能执行以下任何操作（列表仅包括与我的问题相关的操作）：

• 添加或删除虚拟功能
• 添加或删除成员变量
• 更改现有成员变量的类型
• 更改现有函数的签名

我可以想到两种将这些数据添加到层次结构的方法：向根类添加新成员变量或添加纯虚拟访问器函数（以便数据可以存储在子类中）。但是，为了保持向后兼容性，我不能做这些。

该库正在广泛使用pimpl成语，但不幸的是我必须修改的根类不使用这个成语。然而，子类使用这个习语。

现在我能想到的唯一解决方案是用静态哈希映射模拟成员变量。所以我可以创建一个静态哈希映射，将这个新成员存储到其中，并为它实现静态访问​​器。像这样的东西（在伪 C++ 中）：

现在，虽然这个解决方案可能有效，但我发现它非常丑陋（当然我也可以添加非静态访问器函数，但这不会消除丑陋）。

还有其他解决方案吗？

谢谢你。

我需要说服管理层（产品管理和其他），与创建公共 API 候选者的最佳实践相比，仅“公开”内部私有 API 是一个坏主意，在内部使用它并在满意时将其公开。谁能帮我找到一些事实，比如帮助我提出论点的研究论文？

我正在为 Web 框架创建一个 Url 路由器。尽量让用户友好地使用。API 看起来像：

它将与该正则表达式匹配的任何 Url 路由到该方法的位置，这可能看起来像这样：

它自动处理类型转换。

该方法采用的参数和参数之间存在相关性(?<id>...)。该View()函数必须接受名称捕获提供的所有参数。但是，它可以接受更多参数，只要它们是可选的。例如，该正则表达式也将匹配 function View(int id, int extraArg=2)，因为我们并不真正需要extraArg调用该函数。

问题是，该路由是否也应该与函数匹配View()——没有参数？id捕获很容易被丢弃，我们仍然可以很好地调用该函数。还是应该抛出异常（就像现在一样）？

我正在编写一个 Web 框架，一个简洁的功能 (IMO) 是您可以为内联函数定义网址，如下所示：

然后该函数将在您访问时自动被调用/profile:someusername，someusername并将被传递到函数中并自动进行类型转换。

但是对于那些喜欢旧的做事方式的人，你仍然可以在一个地方指定所有的路线：

现在我只是想决定应该以什么顺序处理这两种不同的方法。

哦，将全局路由放在首位意味着您可以在内联路由抢夺它们之前预先处理所有特殊情况，但是 OTOH，如果您将全局路由放在前面，您就不能将所有后备路由放在那里。所以我不能完全决定哪个顺序更好......

我猜的另一个解决方案是使用优先级队列，用户可以为某些路由赋予更高或更低的优先级。

编写纯 API 似乎带来了一些挑战。例如，我习惯于编写 winforms/asp.net 应用程序，如果我的输入无效，我可以通过编程方式打开一个对话框/网页。

但是，API 不知道可以从中执行它的 GUI 应用程序。如果我有一个名为 TakeString (String s) 的方法，并且字符串不能超过 5 个字母，如果是这样，我将如何将控制权返回给客户端？一个例外似乎有点矫枉过正？如果我在方法中返回某些内容，则简单的返回将不起作用。

谢谢

我目前正在做一些API设计工作，涉及到一些接口的规范作为抽象，稍后将由各种具体类实现。

碰巧，我使用的是 Java，但我认为这个问题与任何支持类似接口概念的语言有关。

我注意到通常有以下选择：

• 用各种方法制作大界面
• 制作多个接口，每个接口都包含全部方法的一个子集（单个具体类可能必须实现这些接口中的几个或全部）

每种方法的优缺点是什么？

设计 JavaScript API 的好方法是什么？

我对 JavaScript 比较陌生，并且学习了该语言的主要优秀特性，主要来自“JavaScript: The Good Parts”。目前，我正在设计一个基于网络的工具来教授统计学。代码库变得笨拙的部分原因是我不了解如何设计 JavaScript API。

我的背景是 Java 和 C++，习惯于设计接口，然后独立实现这些接口。显然，这在 JavaScript 中效果不佳。

感谢您的任何帮助和建议。

更新：此处工具的最终版本：http ://www.lock5stat.com/statkey/index.html

我即将为某些功能设计一个 C api，我想让它异步，因为公开的功能可能需要一些时间。使用阻塞 api 可能不是一个好主意，因为 api 的用户需要同时进行许多调用。

设计界面的正确方法是什么，以便我可以通知用户异步操作已完成？

我可以想到几种不同的方法，但我不能说我知道这方面的最佳实践。有没有人有类似 API:s 的经验？

在此示例中，目的是返回一个包含答案的 int。

回调函数：

轮询：

平台特定的事件队列

这个 API 的用户通常是事件驱动的，所以像下面这样的设计可能不是一个好主意。

期货：

平台特定的“期货”/事件：

一些 api 需要字符数。

有些 apis 需要字节数。

在设计函数或数据结构时，如何确定 cb 或 cch？为什么？
要为调用者设计更好的 api，我应该知道什么？