API 设计 - 使用对象或集合作为参数？

Question

以下哪一项设计被认为更适合 API，为什么？

apiMethod(Map<A, B> aToB)

或

apiMethod(MapWrapper<A, B> mapWrapper) 其中 MapWrapper 只是一个包含对地图的引用的 class。

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

Answer 1

你总是争取 "minimalistic" API。

在这种情况下：当您的 API 在传递 Map 时有效 - 那么您当然会选择该路径。为什么要先 wrap 那张地图让你的客户负担？！

选项 1 的优点是 - 这是最直接的路径。

而选项 2 的唯一缺点是更难使用 API。

换句话说：如果该参数的 central "property" 是 "to be a map" - 那么它应该作为地图传递。但是当 "central theme" 是不同的东西时——然后你传递了与另一个主题相一致的东西。

Answer 2

我认为使用 Map 作为 API 的参数是不好的做法，因为很难理解 API 真正需要什么。在一些古老的代码中，我发现了这样的方法：

doSomeStuff(Session session){
  String aa = session.get("aa");
  String bb = session.get("bb");
  return aa + bb;
}

这段代码的重构将是：

doSomeStuff(String aa, String bb){
  return aa + bb;
}

并且您知道您需要 aa 和 bb 才能调用您的 API。

API Design - Use object or collection as parameter?