标签: api-design

我发现自己不会有私人课程.如果可能的话,所有候选私有类函数,而不是我放入未命名的命名空间,并将所有必要的信息作为函数参数传递.我没有一个合理的解释,为什么我这样做,但至少它对我来说更自然.因此,我需要在头文件中公开更少的内部细节.

你有什么看法 - 这是正确的做法吗？

我经常听说jQuery做出了一些糟糕的API决策.虽然jQuery不是我最喜欢的库,但它是我经常使用的库,我发现很难指出API设计中的具体错误或者如何改进它.

jQuery的API的哪些部分可以做得更好,它如何实现不同,为什么不同的实现会更好？

问题扩展到API的低级别个别详细信息和API的高级详细信息.我们只讨论API中的缺陷而不是库的高级设计/目的中的缺陷,jQuery仍然是以选择器引擎为中心的DOM操作库.

由于在流行的库中需要API冻结,jQuery仍处于当前状态并且开发人员做得很好.从最近的.attrvs .prop变化可以看出,开发人员没有灵活性来改变他们的任何设计决策(这是一种耻辱!).

我能想到的一个具体例子是

$.each(function(key, val) { })

VS

$.grep(function(val, key) { })

令人困惑的是,我必须仔细检查频繁的参数.

请不要将jQuery 库与dojo和YUI等完整的框架进行比较,并抱怨缺少功能.

我注意到以下代码片段......

@Override
public boolean equals(Object otherObject) {
    ...
}

......不允许的枚举,由于该方法equals(Object x)被定义为final在Enum.为什么会这样？

我想不出任何需要覆盖equals(Object)Enum的用例.我只是想知道这种行为背后的原因.

我正在使用SQLAlchemy(查询MySQL)设计API,我想强制所有查询都有page_size(LIMIT)和page_number(OFFSET)参数.

使用SQLAlchemy是否有一种干净的方法？也许构建某种工厂来创建自定义Query对象？或者也许有一个很好的方法来使用mixin类吗？

我尝试了显而易见的事情并且它不起作用,因为.limit()和.offset()必须在应用所有过滤条件后调用:

def q(page=0, page_size=None):
    q = session.query(...)
    if page_size: q = q.limit(page_size)
    if page: q = q.offset(page*page_size)
    return q

当我尝试使用它时,我得到了例外:

sqlalchemy.exc.InvalidRequestError: Query.filter() being called on a Query which already has LIMIT or OFFSET applied. To modify the row-limited results of a  Query, call from_self() first.  Otherwise, call filter() before limit() or offset() are applied.

从一个好的设计/实践的角度来看,我们何时应该创建和使用自定义java异常类而不是已经在java中预定义的异常类？

在某些应用程序中,我几乎看不到,甚至没有创建自定义异常类,他们总是努力使用本机java异常.另一方面,有一些应用程序为所有内容定义自定义异常.

什么是最佳做法？

谢谢!

Iterables提供了两种方法getLast

 public static <T> T getLast(Iterable<T> iterable);
 public static <T> T getLast(Iterable<T> iterable, @Nullable T defaultValue);

但只有一个 getFirst

 public static <T> T getFirst(Iterable<T> iterable, @Nullable T defaultValue);

是否存在破坏对称性的设计/实施原因？

我正在学习Objective-C,并且拥有C/C++背景.

• 在面向对象的C++中,总是需要在定义(实现)它之前声明方法,即使它是在父类中声明的.

• 在过程式C,IIRC中,只要定义一个函数,只要从同一个编译单元中的其他东西(即同一个文件)调用它就可以远离文件中的某个函数(嗯,提供)你没有在其他地方用"extern"声明它.

• 现在,在Objective-C中,您似乎只需要在头文件中声明选择器,如果它们将被外部使用,并且您可以在.m文件中组合选择器就好了,并在其中调用它们.m文件.此外,似乎永远不会(重新)定义委托方法或继承的方法.

我是在正确的轨道上吗？什么时候需要在Objective-C中定义一个选择器？

AtomicBoolean的Oracle JDK Javadoc声明:

https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicBoolean.html

可以原子方式更新的布尔值.有关原子变量属性的描述,请参阅java.util.concurrent.atomic包规范.AtomicBoolean用于诸如原子更新标志的应用程序中,不能用作布尔值的替代.

一位同事和我试图找出一个用例,其中AtomicBoolean不能替代,我们唯一能想到的是布尔对象有的方法,而AtomicBoolean却没有.

这是唯一的原因还是在撰写时还有其他想法？

这个问题是关于最佳REST API设计和我在嵌套资源和根级别集合之间选择的问题.

为了说明这个概念,假设我有收藏City,Business和Employees.典型的API可以如下构造.想象一下,ABC,X7N和WWW是关键,例如guids:

GET Api/City/ABC/Businesses                       (returns all Businesses in City ABC)
GET Api/City/ABC/Businesses/X7N                   (returns business X7N)
GET Api/City/ABC/Businesses/X7N/Employees         (returns all employees at business X7N)
PUT Api/City/ABC/Businesses/X7N/Employees/WWW     (updates employee WWW)

这看起来很干净,因为它遵循原始域结构 - 业务在城市,员工在公司.单个项目可通过集合下的密钥访问(例如,../Businesses返回所有业务,同时../Businesses/X7N返回单个业务).

以下是API消费者需要做的事情:

• 在城市中获得业务 (GET Api/City/ABC/Businesses)
• 让所有员工都参与进来 (GET Api/City/ABC/Businesses/X7N/Employees)
• 更新个人员工信息 (PUT Api/City/ABC/Businesses/X7N/Employees/WWW)

第二次和第三次调用虽然看起来在正确的位置,但使用了许多实际上不必要的参数.

• 为了让员工参与到业务中,唯一需要的参数是business(X7N)的关键.
• 要更新单个员工,唯一的参数需要员工的密钥(WWW)

后端代码中的任何内容都不需要非关键信息来查找业务或更新员工.因此,相反,以下端点看起来更好:

GET Api/City/ABC/Businesses                       (returns all Businesses in City ABC)
GET Api/Businesses/X7N                            (returns business X7N)
GET Api/Businesses/X7N/Employees                  (returns all employees at business …

我正在为新手程序员编写一个库,所以我试图保持API尽可能干净.

我的库需要做的一件事就是对大量的int或long进行一些复杂的计算.我的用户需要从中计算这些值所需的大量场景和业务对象,因此我认为最好的方法是使用流来允许用户将业务对象映射到IntStream或者LongStream然后计算收集器内的计算.

但是IntStream和LongStream只有3参数collect方法:

collect(Supplier<R> supplier, ObjIntConsumer<R> accumulator, BiConsumer<R,R> combiner)

而且没有简单的collect(Collector)方法Stream<T>.

所以不是能够做到的

Collection<T> businessObjs = ...
MyResult result = businessObjs.stream()
                              .mapToInt( ... )
                              .collect( new MyComplexComputation(...));

我必须提供像这样的供应商,蓄电池和组合器:

MyResult result = businessObjs.stream()
                              .mapToInt( ... )
                              .collect( 
                                  ()-> new MyComplexComputationBuilder(...),
                                  (builder, v)-> builder.add(v),
                                  (a,b)-> a.merge(b))
                              .build(); //prev collect returns Builder object

对于我的新手用户来说这太复杂了,而且非常容易出错.

我的工作是创建一个静态方法,它接受IntStream或LongStream作为输入,并为您隐藏收集器的创建和执行

public static MyResult compute(IntStream stream, ...){
       return .collect( 
                        ()-> new MyComplexComputationBuilder(...),
                        (builder, v)-> builder.add(v),
                        (a,b)-> a.merge(b))
               .build();
} …