问题标签 [api-design]

哪个 API 更好？我认为后一种方法更好，因为字符串是实习的。但我渴望简洁。你认为哪个更好？

[Task("Assortment", Author = "好先生", MenuTree = "The>Quick>Brown>Megan")] public partial class Form1 : MycForm, ITaskPlugin { }

或者这个（字符串可以被实习）：

[Task("Assortment", Author = "好先生", MenuTree = new string[] { "The", "Quick", "Brown", "Megan"} )] public partial class Form1 : MycForm, ITaskPlugin { }

我正在开发一个包含一堆互锁部分（服务器、客户端、库等）的产品，其中一个是一个微型库，用户将链接到他们自己的客户端代码（有点像 Flickr API 或谷歌地图 API）。一旦他们包含了那个库，所有的互锁位都会神奇地连接在一起。所以 API 的简单性是一个主要的、重要的目标。

我向用户公开的 API 总共有两个类和七个公共方法。简单的豌豆，柠檬汁。

但简单是一种精心制作的错觉。我分发的库实际上依赖于另一个库，它自己有 136 个类（以及一千多个公共方法）。在构建过程中，我将这两个库链接到一个可交付成果中，以方便 API 使用者的集成和部署。

我现在面临的问题是，我不希望最终用户（集成我的软件以增强他们自己的功能的应用程序开发人员）被所有这些额外的麻烦所困扰，淹没在不必要的复杂性洪流中。

从外面看，这个库应该看起来正好包含两个公共类，正好有七个公共方法。

您如何在自己的项目中处理此类事情？我对与语言无关的解决方案以及针对不同语言、编译器和构建工具的各种技术感兴趣。

在我的具体情况下，我正在为带有 SWC 库文件的 flash 平台（AIR/Flex/Actionscript）进行开发。构建方法类似于 Java 平台，其中所有类都捆绑到具有相同可见性的压缩代码模块中（从概念上讲，Actionscript SWC 文件与 Java JAR 文件几乎完全相同）。

.NET 没有用于类和方法的“内部”修饰符吗？这正是我正在寻找的东西，如果有人知道隐藏 SWC 边界之间类的可见性的棘手技术，我很想听听。

公开自定义集合与通用集合的框架设计指南是什么？例如

VS

我目前正在为需要预编译二进制/DLL（它将是跨平台的）的产品设计面向公众的 C++ API。我希望 API 允许用户使用我们支持的任何 POD（如果适用），但基本要求是最大的灵活性和二进制兼容性。我正在做一些类似于 CPLEX 的 API 的事情（这是几个灵感之一），但我认为指定类型信息的方式可能比他们所做的更好（关于 IloInt、IloNum、IloAny、Ilo* var等，见链接（希望）用于 IloExtractable 分支）而不会弄乱二进制兼容性。我错了吗？我有一些想法，但我不记得它是什么，或者它是否会起作用，我相信它类似于访问者或装饰者模式，但对于类型，有人可以在这个问题上启发我吗？我面前有一本由 GoF 编写的设计模式书。

注意：这里可能出现的任何语法错误都不是当前问题的一部分。

我认为我不能使用的示例以及原因：

可能......但这可能会使表达式树变得复杂。

可能会影响未来的扩张。

丑陋如罪，可能会引起很多微妙的问题。

编辑：作为对 Mads Elvheim 的回应（在找到此链接后），我现在意识到我不需要从我的可能性中排除模板，这很好，但我仍然不确定这是最好的主意 - 至少对于 Constraints 类（即使它在概念上是合理的），请原谅我没有我想的那么清楚。

为了使我的 API 易于使用，我使用 bnf 定义了语法（这对我来说相当新）。这导致了表达式、约束和其他将与约束交互的类的抽象语法树。因为其他类将与约束交互，所以我宁愿避免在“最后一分钟”之前尽可能多地传递类型信息。可以这么说。我觉得我可能错过了一个抽象层次。

学习 CPLEX 给我的印象是，他们通过遵循数字域（整数和实数）、线性方程表达式（当然）以及相应的可能性来建模他们的类型，这绝对是有道理的，嗯……

（显然我不能发布多个链接，因为我是新用户。）

编辑 2：作为第一步，我决定ConstraintExpressionArgument在 Constraint 和 Expression 类之间添加一个，这样我仍然可以在我的表达式树中识别一个约束，而无需知道它所操纵的类型是好的。

我可能忽略提及的另一个细节是，与在 CPLEX 中 Constraint 类本身不可用的情况不同，我的 Constraint 类目前是一个可用的用户类，但就像在 CPLEX 中一样，我也想留出扩展空间（因此是打字问题）。 ..

无论如何，目前我有相当于

正如大多数人现在痛苦地意识到的那样，用于处理日历日期（特别是类java.util.Date和java.util.Calendar）的 Java API 是一团糟。

在我的头顶上：

• 日期是可变的
• Date 表示时间戳，而不是日期
• 没有简单的方法在日期组件（日、月、年...）和日期之间进行转换
• 日历使用起来很笨拙，并试图将不同的日历系统组合到一个类中

这篇文章总结得很好，JSR-310也解释了这些问题。

现在我的问题是：

这些类是如何进入 Java SDK 的？大多数这些问题看起来都相当明显（尤其是 Date 是可变的）并且应该很容易避免。那么它是怎么发生的呢？时间压力？还是只是回想起来问题很明显？

我意识到这不是一个严格的编程问题，但我会发现了解 API 设计如何会出错很有趣。毕竟，错误总是一个很好的学习机会（我很好奇）。

我从外部开发人员那里收到了一个定义良好的 API（C++ 和 Java）形式的库。可以进行哪些测试来检查库是否是线程安全的？

我需要设计一个新的 API 来模拟具有大量属性的联网设备，这些属性根据设备的类型变化很大。属性集不是完全任意的，它是一大组已知属性。也就是说，新设备带来了新属性，因此情况永远不会完全解决。

网络设备本身一直来来去去，因此这是 API 设计的核心部分。此外，最好通过观察者模式的某些变体来获取属性/属性集的更新。

注意：我不是在谈论网络管理，尽管这听起来可能是这样。也就是说，这些系统上的 API 可能非常适合/值得一看。

所以我的问题是，你知道开源世界中有什么好的 API，我可以从中学习并从中获得一些灵感吗？

该系统将基于 Java，因此示例最好来自密切相关的语言，例如 Java（当然 :)）、C#、Scala 和其他类似的静态类型语言。

我遇到了 JLS 的一个奇怪之处，或者一个 JavaC 错误（不确定是哪个）。请阅读以下内容并提供解释，并酌情引用 JLS 段落或 Sun Bug ID。

假设我有一个人为的项目，其中包含三个“模块”中的代码 -

1. API - 定义框架 API - 思考 Servlet API
2. Impl - 定义 API 实现 - 想想 Tomcat Servlet 容器
3. App——我写的应用程序

以下是每个模块中的类：

API -MessagePrinter.java

API - MessageHolder.java（是的，它引用了一个“impl”类 - 稍后会详细介绍）

Impl - MessagePrinterInternal.java- 这个类依赖于一个 API 类。顾名思义，它是为我的小框架中其他地方的“内部”使用而设计的。

最后，App 模块中的唯一类...MyApp.java

所以，现在我尝试编译我的小应用程序 MyApp.java。假设我的 API jar 是通过一个 jar 导出的，比如 api.jar，并且作为一个好公民，我只在我的类路径中引用了那个 jar——而不是 impl.jar 中的 Impl 类。

现在，显然我的框架设计存在缺陷，API 类不应该对“内部”实现类有任何依赖。然而，令人惊讶的是 MyApp.java 根本没有编译。

问题是由于方法重载，编译器正在尝试解析要使用的版本 print()。但是，编译错误有点出乎意料，因为其中一种方法是包私有的，因此对 MyApp 不可见。

那么，这是一个 javac 错误，还是 JLS 的一些奇怪之处？

编译器：Sun javac 1.6.0_14

我一直在研究一个 API（它包装了各种各样的网络服务），而且它的功能已经完成了。

我最初将这个 API 设计为始终延迟/延迟加载；考虑到使用 Web 服务固有的延迟，如果您只对可用数据的一小部分感兴趣，那么这非常有意义。但是，我没有考虑一些用例，在这些用例中，对于 API 的使用者来说，预先加载会更容易。

所以，我的问题是：你希望看到一个主要是延迟加载的 API 公开一种获取热加载版本的类的机制吗？

我倾向于explicit演员阵容，但Eager.AsEager(SomeDelayLoadingObject)如果更冗长的话，类似的东西也似乎很自然。

我正在尝试设计将在内部用于我的应用程序的界面。效仿 Google 的例子，我努力减少公共 API 的混乱。但是，有一些便利方法是根据最小方法定义的。当我在方便和整洁之间寻求平衡时，我应该考虑哪些因素？

谷歌示例：在HashBiMap（文档）中：

为什么 BiMap 没有 getKeyForValue() 方法？

我们确实考虑过（Doug Lea 甚至半开玩笑地建议将其命名为 teg()！）。但你并不真的需要它；只需调用 inverse().get()。

Google 收藏集常见问题解答

接口上的一个例子Set：add()andremove()是最小的方法，而addAll()andremoveAll()是为了方便起见。addAll()可以add()根据Set. 但它确实清理了客户端代码。

我考虑过创建一个Utility包含更多便利方法的类。但是后来我离开了 OOP，我必须在每次调用中包含正在操作的对象作为参数。虽然我猜这遵循 JavaCollections类的例子。