Une brève analyse de l'expérience de conception de l'API Java 8

Cet article a été initialement traduit par Xiaofeng de MaNong.com. Veuillez lire les exigences de réimpression à la fin de l'article pour la réimpression. Bienvenue pour participer à notre plan de contribution payante !

Quiconque écrit du code Java est un concepteur d'API ! Que le codeur partage ou non le code avec d'autres, le code est toujours utilisé : soit par d'autres, par lui-même, ou les deux. Il est donc important que tous les développeurs Java comprennent les bases d’une bonne conception d’API.

Une bonne conception d’API nécessite une réflexion approfondie et beaucoup d’expérience. Heureusement, nous pouvons apprendre d'autres personnes plus intelligentes comme Ference Mihaly, dont le blog m'a inspiré pour écrire cet addendum à l'API Java 8. Lors de la conception de l'API Speedment, nous nous sommes fortement appuyés sur sa liste d'interfaces. (Je recommande de lire son guide.)

Il est important de le faire dès le début, car une fois l'API publiée, elle deviendra une base solide pour tous ceux qui l'utilisent. Comme l'a dit un jour Joshua Bloch : "Les API publiques, comme les diamants, durent éternellement. Si vous avez une chance de le faire correctement, vous devriez faire de votre mieux pour le faire

Une API bien conçue combine les deux." L'essence de ce monde est à la fois une base solide et précise et un haut degré de flexibilité de mise en œuvre, bénéficiant en fin de compte aux concepteurs et aux utilisateurs d'API.

Quant à savoir pourquoi nous devons utiliser la liste d'interfaces ? Obtenir l'API correcte (c'est-à-dire la partie visible qui définit une collection de classes Java) est beaucoup plus difficile que d'écrire les classes d'implémentation qui constituent le travail réel derrière l'API. C'est un art que très peu de gens maîtrisent. L'utilisation d'une liste de contrôle d'interface permet aux lecteurs d'éviter les erreurs les plus évidentes, de devenir un meilleur programmeur et de gagner beaucoup de temps.

Il est fortement recommandé aux concepteurs d'API de se mettre dans la perspective du code client et d'optimiser cette vue en termes de simplicité, de facilité d'utilisation et de cohérence - plutôt que de penser à l'implémentation réelle de l'API. Dans le même temps, ils devraient essayer de cacher autant de détails de mise en œuvre que possible.

Ne retournez pas Null pour indiquer une valeur nulle

Il a été prouvé qu'une gestion incohérente des valeurs nulles (entraînant l'omniprésente NullPointerException) est le plus gros bug d'application Java dans l’histoire est la seule source. Certains développeurs considèrent l’introduction du concept nul comme l’une des pires erreurs commises en informatique. Heureusement, la première étape vers l'atténuation des problèmes de gestion des valeurs nulles de Java a été l'introduction de la classe Optionnel dans Java 8. Assurez-vous que les méthodes avec une valeur de retour nulle renvoient Facultatif au lieu de null.

Cela indique clairement aux consommateurs d'API que la méthode peut ou non renvoyer une valeur. Ne soyez pas tenté d'utiliser null au lieu de Facultatif pour des raisons de performances. Quoi qu'il en soit, l'analyse d'échappement de Java 8 optimisera la plupart des objets facultatifs. Évitez d'utiliser Facultatif dans les paramètres et les champs.

Tu peux écrire comme ça

public Optional<String> getComment() {
    return Optional.ofNullable(comment);
}

au lieu d'écrire comme ça

public String getComment() {
    return comment; // comment is nullable
}

Ne pas utiliser de tableaux comme paramètres entrants et valeurs de retour de l'API

Lorsque le concept Enum a été introduit dans Java 5, une erreur API majeure s'est produite. Nous savons tous que la classe Enum possède une méthode appelée valeurs(), qui renvoie un tableau de toutes les différentes valeurs Enum. Désormais, comme le framework Java doit garantir que le code client ne peut pas modifier la valeur d'un Enum (par exemple, en écrivant directement dans le tableau), une copie du tableau interne doit être effectuée pour chaque appel à la méthode value().

Cela entraîne de mauvaises performances et une mauvaise utilisation du code client. Si un Enum renvoie une liste non modifiable qui peut être réutilisée à chaque appel, alors le code client a accès à un modèle meilleur et plus utile de valeurs Enum. En général, si une API renvoie un ensemble d'éléments, envisagez d'exposer un Stream. Cela illustre clairement que le résultat est en lecture seule (par opposition à une liste qui possède une méthode set()).

Il permet également au code client de collecter facilement des éléments d'une autre structure de données ou de les exploiter à la volée. De plus, l'API peut générer paresseusement des éléments dès qu'ils deviennent disponibles (par exemple, extraits d'un fichier, d'un socket ou d'une base de données). De même, l'analyse d'échappement améliorée de Java 8 garantira que le moins d'objets soient réellement créés sur le tas Java.

N'utilisez pas non plus de tableaux comme arguments d'entrée des méthodes car - à moins qu'une copie de protection du tableau ne soit créée - il est possible qu'un autre thread modifie le contenu du tableau pendant l'exécution de la méthode.

Tu peux écrire comme ça

public Stream<String> comments() {
    return Stream.of(comments);
}

au lieu d'écrire comme ça

public String[] comments() {
    return comments; // Exposes the backing array!
}

考虑添加静态接口方法以提供用于对象创建的单个入口点

避免允许客户端代码直接选择接口的实现类。允许客户端代码创建实现类直接创建了一个更直接的API和客户端代码的耦合。它还使得API的基本功能更强，因为现在我们必须保持所有的实现类，就像它们可以从外部观察到，而不仅仅只是提交到接口。

考虑添加静态接口方法，以允许客户端代码来创建（可能为专用的）实现接口的对象。例如，如果我们有一个接口Point有两个方法int x() 和int y() ，那么我们可以显示一个静态方法Point.of( int x，int y) ，产出接口的（隐藏）实现。

所以，如果x和y都为零，那么我们可以返回一个特殊的实现类PointOrigoImpl（没有x或y字段），否则我们返回另一个保存给定x和y值的类PointImpl。确保实现类位于另一个明显不是API一部分的另一个包中（例如，将Point接口放在com.company。product.shape中，将实现放在com.company.product.internal.shape中）。

你可以这样写

Point point = Point.of(1,2);

而不要这样写

Point point = new PointImpl(1,2);

青睐功能性接口和Lambdas的组合优于继承

出于好的原因，对于任何给定的Java类，只能有一个超类。此外，在API中展示抽象或基类应该由客户端代码继承，这是一个非常大和有问题的API 功能。避免API继承，而考虑提供静态接口方法，采用一个或多个lambda参数，并将那些给定的lambdas应用到默认的内部API实现类。

这也创造了一个更清晰的关注点分离。例如，并非继承公共API类AbstractReader和覆盖抽象的空的handleError（IOException ioe），我们最好是在Reader接口中公开静态方法或构造器，接口使用Consumer 并将其应用于内部的通用ReaderImpl。

你可以这样写

Reader reader = Reader.builder()
    .withErrorHandler(IOException::printStackTrace)
    .build();

而不要这样写

Reader reader = new AbstractReader() {
    @Override
    public void handleError(IOException ioe) {
        ioe. printStackTrace();
    }
};

确保你将@FunctionalInterface注解添加到功能性接口

使用@FunctionalInterface注解标记的接口，表示API用户可以使用lambda实现接口，并且还可以通过防止抽象方法随后被意外添加到API中来确保接口对于lambdas保持长期使用。

你可以这样写

@FunctionalInterface
public interface CircleSegmentConstructor {
    CircleSegment apply(Point cntr, Point p, double ang);
    // abstract methods cannot be added
}

而不要这样写

public interface CircleSegmentConstructor {
    CircleSegment apply(Point cntr, Point p, double ang);
    // abstract methods may be accidently added later
}

避免使用功能性接口作为参数的重载方法

如果有两个或更多的具有相同名称的函数将功能性接口作为参数，那么这可能会在客户端侧导致lambda模糊。例如，如果有两个Point方法add(Function renderer) 和add(Predicate logCondition)，并且我们尝试从客户端代码调用point.add(p -> p + “ lambda”) ，那么编译器会无法确定使用哪个方法，并产生错误。相反，请根据具体用途考虑命名方法。

你可以这样写

public interface Point {
    addRenderer(Function<Point, String> renderer);
    addLogCondition(Predicate<Point> logCondition);
}

而不要这样写

public interface Point {
    add(Function<Point, String> renderer);
    add(Predicate<Point> logCondition);
}

避免在接口中过度使用默认方法

默认方法可以很容易地添加到接口，有时这是有意义的。例如，想要一个对于任何实现类都期望是相同的并且在功能上要又短又“基本”的方法，那么一个可行的候选项就是默认实现。此外，当扩展API时，出于向后兼容性的原因，提供默认接口方法有时是有意义的。

众所周知，功能性接口只包含一个抽象方法，因此当必须添加其他方法时，默认方法提供了一个安全舱口。然而，通过用不必要的实现问题来污染API接口以避免API接口演变为实现类。如果有疑问，请考虑将方法逻辑移动到单独的实用程序类和/或将其放置在实现类中。

你可以这样写

public interface Line {
    Point start();
    Point end();
    int length();
}

而不要这样写

public interface Line {
    Point start();
    Point end();
    default int length() {
        int deltaX = start().x() - end().x();
        int deltaY = start().y() - end().y();
    return (int) Math.sqrt(
        deltaX * deltaX + deltaY * deltaY
        );
    }
}

确保在执行之前进行API方法的参数不变量检查

在历史上，人们一直草率地在确保验证方法输入参数。因此，当稍后发生结果错误时，真正的原因变得模糊并隐藏在堆栈跟踪下。确保在实现类中使用参数之前检查参数的空值和任何有效的范围约束或前提条件。不要因性能原因而跳过参数检查的诱惑。

JVM能够优化掉冗余检查并产生高效的代码。好好利用Objects.requireNonNull()方法。参数检查也是实施API约定的一个重要方法。如果不想API接受null但是却做了，用户会感到困惑。

你可以这样写

public void addToSegment(Segment segment, Point point) {
    Objects.requireNonNull(segment);
    Objects.requireNonNull(point);
    segment.add(point);
}

而不要这样写

public void addToSegment(Segment segment, Point point) {
    segment.add(point);
}

不要简单地调用Optional.get()

Java 8的API设计师犯了一个错误，在他们选择名称Optional.get()的时候，其实应该被命名为Optional.getOrThrow()或类似的东西。调用get()而没有检查一个值是否与Optional.isPresent()方法同在是一个非常常见的错误，这个错误完全否定了Optional原本承诺的null消除功能。考虑在API的实现类中使用任一Optional的其他方法，如map()，flatMap()或ifPresent()，或者确保在调用get()之前调用isPresent()。

你可以这样写

Optional<String> comment = // some Optional value 
String guiText = comment
  .map(c -> "Comment: " + c)
  .orElse("");

而不要这样写

Optional<String> comment = // some Optional value 
String guiText = "Comment: " + comment.get();

考虑在不同的API实现类中分行调用接口

最后，所有API都将包含错误。当接收来自于API用户的堆栈跟踪时，如果将不同的接口分割为不同的行，相比于在单行上表达更为简洁，而且确定错误的实际原因通常更容易。此外，代码可读性将提高。

你可以这样写

Stream.of("this", "is", "secret") 
  .map(toGreek()) 
  .map(encrypt()) 
  .collect(joining(" "));

而不要这样写

Stream.of("this", "is", "secret").map(toGreek()).map(encrypt()).collect(joining(" "));

 以上就是Java 8 API 设计经验浅析 的内容，更多相关内容请关注PHP中文网（m.sbmmt.com）！