小心重载API方法

重载方法是API设计中的重要概念，尤其是当您的API是流利的API或DSL（特定于域的语言）时。

对于jOOQ就是这种情况，在这种情况下，您经常想使用与完全相同的方法名称来与库进行各种交互。

示例：jOOQ条件

package org.jooq;public interface Condition {// Various overloaded forms of the "AND" operation:Condition and(Condition other);Condition and(String sql);Condition and(String sql, Object... bindings);// [...]}

所有这些方法都使用“ AND”运算符将两个条件相互关联。理想情况下，实现相互依赖，从而造成单点故障。这会使事情变干：

package org.jooq.impl;abstract class AbstractCondition implements Condition {// The single point of failure@Overridepublic final Condition and(Condition other) {return new CombinedCondition(Operator.AND, Arrays.asList(this, other));}// "Convenience methods" delegating to the other one@Overridepublic final Condition and(String sql) {return and(condition(sql));}@Overridepublic final Condition and(String sql, Object... bindings) {return and(condition(sql, bindings));}}

泛型和重载的麻烦

当使用Eclipse开发时，Java 5世界似乎比实际情况更加光彩照人。 Varargs和泛型作为Java 5中的语法糖引入。它们在JVM中并不是真的存在。这意味着编译器必须正确链接方法调用，在需要时推断类型，并在某些情况下创建综合方法。根据JLS（ Java语言规范），当在重载方法中使用varargs / generics时，存在很多歧义。

让我们详细介绍一下泛型：

在jOOQ中要做的一件好事是将常量值与字段一样对待。在许多地方，字段参数像这样重载：

// This is a convenience method:public static <T> Field<T> myFunction(Field<T> field, T value) {return myFunction(field, val(value));}// It's equivalent to this one.public static <T> Field<T> myFunction(Field<T> field, Field<T> value) {return MyFunction<T>(field, value);}

在大多数情况下，上面的方法效果很好。您可以像这样使用上述API：

Field<Integer> field1  = //...Field<String>  field2  = //...Field<Integer> result1 = myFunction(field1, 1);Field<String>  result2 = myFunction(field2, "abc");

但是，当<T>绑定到对象时，就会出现麻烦！

// While this works...Field<Object>  field3  = //...Field<Object>  result3 = myFunction(field3, new Object());// ... this doesn't!Field<Object>  field4  = //...Field<Object>  result4 = myFunction(field4, field4);Field<Object>  result4 = myFunction(field4, (Field) field4);Field<Object>  result4 = myFunction(field4, (Field<Object>) field4);

当<T>绑定到Object时，两种方法突然都适用，并且根据JLS，它们都不是更具体的！尽管Eclipse编译器通常比较宽容（并且在这种情况下直观地链接了第二个方法），但是javac编译器不知道该调用要做什么。而且没有办法解决。您不能将field4强制转换为Field或Field <Object>强制链接器链接至第二种方法。对于API设计人员来说，这是个坏消息。

有关此特殊情况的更多详细信息，请考虑以下堆栈溢出问题，我将此问题报告给Oracle和Eclipse。让我们看看哪种编译器实现是正确的：
http://stackoverflow.com/questions/5361513/reference-is-ambiguous-with-generics

静态导入的麻烦，varargs

Varargs是Java 5中引入的另一个重要功能。尽管它只是语法糖，但在将数组传递给方法时可以节省很多代码：

// Method declarations with or without varargspublic static String concat1(int[] values);public static String concat2(int... values);// The above methods are actually the same.String s1 = concat1(new int[] { 1, 2, 3 });String s2 = concat2(new int[] { 1, 2, 3 });// Only, concat2 can also be called like this, convenientlyString s3 = concat2(1, 2, 3);

那是众所周知的。它与原始类型数组的工作方式与与Object []相同。它也可以与T []一起使用，其中T是泛型类型！

// You can now have a generic type in your varargs parameter:public static <T> T[] array(T... values);// The above can be called "type-safely" (with auto-boxing):Integer[] ints   = array(1, 2, 3);String[] strings = array("1", "2", "3");// Since Object could also be inferred for T, you can even do this:Object[] applesAndOranges = array(1, "2", 3.0);

最后一个例子实际上已经暗示了这个问题。如果T没有任何上限，则类型安全性完全消失。这是一种错觉，因为最后，总是可以将varargs参数推断为“ Object…”。这就是当您重载此类API时这会引起麻烦的方式。

// Overloaded for "convenience". Let's ignore the compiler warning// caused when calling the second methodpublic static <T> Field<T> myFunction(T... params);public static <T> Field<T> myFunction(Field<T>... params);

起初，这看起来像个好主意。参数列表可以是常量值（T…）或动态字段（Field…）。因此，原则上，您可以执行以下操作：

// The outer function can infer Integer for <T> from the inner// functions, which can infer Integer for <T> from T...Field<Integer> f1 = myFunction(myFunction(1), myFunction(2, 3));// But beware, this will compile too!Field<?> f2 = myFunction(myFunction(1), myFunction(2.0, 3.0));

内部函数将推断<T>的Integer和Double。对于不兼容的返回类型Field <Integer>和Field <Double>，带有“ Field <T> ...”参数的“打算”方法不再适用。因此，编译器将带有“ T…”的方法一链接为唯一适用的方法。但是您不会猜测<T>的（可能）推断范围。这些是可能的推断类型：

// This one, you can always do:Field<?> f2 = myFunction(myFunction(1), myFunction(2.0, 3.0));// But these ones show what you're actually about to doField<? extends Field<?>>                       f3 = // ...Field<? extends Field<? extends Number>>        f4 = // ...Field<? extends Field<? extends Comparable<?>>> f5 = // ...Field<? extends Field<? extends Serializable>>  f6 = // ...

编译器可以推断出Field <？将Number＆Comparable <？>和Serializable>扩展为<T>的有效上限。但是，<T>没有有效的精确界限。因此，必要的<？扩展[上限]>。

结论

将varargs参数与泛型结合使用时要特别小心，尤其是在重载方法中。如果用户将通用类型参数正确绑定到您想要的目标，则一切正常。但是，如果有一个拼写错误（例如，将Integer与Double混淆），那么您的API用户就注定了。而且他们不会轻易发现自己的错误，因为没有人能读懂这样的编译器错误消息：

Test.java:58: incompatible types
found   : Test.Field<Test.Field<? extends java.lang.Number&java.lang.Comparable<? extends java.lang.Number&java.lang.Comparable<?>>>>
required: Test.Field<java.lang.Integer>Field<Integer> f2 = myFunction(myFunction(1),myFunction(2.0, 3.0));

参考：在JAVA，SQL和JOOQ博客上，我们的JCG合作伙伴 Lukas Eder 谨慎使用了重载API方法。

相关文章：