Eine kurze Analyse der Java 8 API-Designerfahrung

Dieser Artikel wurde ursprünglich von Xiaofeng von MaNong.com übersetzt. Bitte lesen Sie die Nachdruckanforderungen am Ende des Artikels, um an unserem kostenpflichtigen Beitragsplan teilzunehmen.

Jeder, der Java-Code schreibt, ist ein API-Designer! Unabhängig davon, ob der Programmierer den Code mit anderen teilt, wird der Code dennoch verwendet: entweder von anderen, von ihm selbst oder von beiden. Daher ist es für alle Java-Entwickler wichtig, die Grundlagen eines guten API-Designs zu verstehen.

Ein gutes API-Design erfordert sorgfältiges Denken und viel Erfahrung. Glücklicherweise können wir von anderen, klügeren Leuten wie Ference Mihaly lernen, dessen Blog mich dazu inspiriert hat, diesen Nachtrag zur Java 8 API zu schreiben. Bei der Gestaltung der Speedment-API haben wir uns stark auf seine Schnittstellenliste verlassen. (Ich empfehle, seinen Leitfaden zu lesen.)

Es ist wichtig, dies von Anfang an zu tun, denn sobald die API veröffentlicht ist, wird sie zu einer soliden Grundlage für diejenigen, die die API verwenden. Wie Joshua Bloch einmal sagte: „Öffentliche APIs halten wie Diamanten ewig. Wenn Sie die Chance haben, es richtig zu machen, sollten Sie Ihr Bestes geben, um es zu tun.“

Eine gut gestaltete API kombiniert beides Das Wesentliche dieser Welt ist sowohl eine solide und präzise Grundlage als auch ein hohes Maß an Implementierungsflexibilität, was letztendlich API-Designern und API-Benutzern zugute kommt.

Warum müssen wir die Schnittstellenliste verwenden? Die richtige API (d. h. den sichtbaren Teil, der eine Sammlung von Java-Klassen definiert) zu finden, ist viel schwieriger als das Schreiben der Implementierungsklassen, die die eigentliche Arbeit hinter der API ausmachen. Es ist eine Kunst, die wirklich nur wenige Menschen beherrschen. Durch die Verwendung einer Schnittstellen-Checkliste können Leser die offensichtlichsten Fehler vermeiden, ein besserer Programmierer werden und viel Zeit sparen.

Es wird API-Designern dringend empfohlen, sich in die Perspektive des Client-Codes zu versetzen und diese Sicht im Hinblick auf Einfachheit, Benutzerfreundlichkeit und Konsistenz zu optimieren – anstatt über die eigentliche API-Implementierung nachzudenken. Gleichzeitig sollten sie versuchen, so viele Implementierungsdetails wie möglich zu verbergen.

Null nicht zurückgeben, um einen Nullwert darzustellen

Es wurde nachgewiesen, dass die inkonsistente Nullbehandlung (die zur allgegenwärtigen NullPointerException führt) der größte Fehler in Java-Anwendungen ist Geschichte die einzige Quelle. Einige Entwickler betrachten die Einführung des Nullkonzepts als einen der schlimmsten Fehler in der Informatik. Glücklicherweise war der erste Schritt zur Entschärfung der Null-Handhabungsprobleme von Java die Einführung der Optional-Klasse in Java 8. Stellen Sie sicher, dass Methoden mit einem Null-Rückgabewert „Optional“ und nicht „Null“ zurückgeben.

Dies zeigt API-Konsumenten deutlich an, dass die Methode möglicherweise einen Wert zurückgibt oder auch nicht. Lassen Sie sich aus Leistungsgründen nicht dazu verleiten, null statt optional zu verwenden. Wie auch immer, die Escape-Analyse von Java 8 optimiert die meisten optionalen Objekte. Vermeiden Sie die Verwendung von Optional in Parametern und Feldern.

Sie können auch so schreiben

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

anstatt so zu schreiben

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

Verwenden Sie keine Arrays als eingehende Parameter und Rückgabewerte der API

Bei der Einführung des Enum-Konzepts in Java 5 ist ein schwerwiegender API-Fehler aufgetreten. Wir alle wissen, dass die Enum-Klasse über eine Methode namens „values()“ verfügt, die ein Array aller verschiedenen Enum-Werte zurückgibt. Da das Java-Framework nun sicherstellen muss, dass Clientcode den Wert einer Enum nicht ändern kann (z. B. durch direktes Schreiben in das Array), muss für jeden Aufruf der value()-Methode eine Kopie des internen Arrays erstellt werden.

Dies führt zu schlechter Leistung und schlechter Benutzerfreundlichkeit des Client-Codes. Wenn eine Enum eine nicht veränderbare Liste zurückgibt, die bei jedem Aufruf wiederverwendet werden kann, hat der Clientcode Zugriff auf ein besseres und nützlicheres Modell von Enum-Werten. Wenn eine API eine Reihe von Elementen zurückgibt, sollten Sie im Allgemeinen die Bereitstellung eines Streams in Betracht ziehen. Dies zeigt deutlich, dass das Ergebnis schreibgeschützt ist (im Gegensatz zu einer Liste, die über eine set()-Methode verfügt).

Es ermöglicht dem Client-Code auch, einfach Elemente aus einer anderen Datenstruktur zu sammeln oder sie im laufenden Betrieb zu bearbeiten. Darüber hinaus kann die API Elemente langsam generieren, sobald sie verfügbar sind (z. B. aus einer Datei, einem Socket oder aus einer Datenbank gezogen). Ebenso stellt die verbesserte Escape-Analyse von Java 8 sicher, dass tatsächlich die wenigsten Objekte auf dem Java-Heap erstellt werden.

Verwenden Sie Arrays auch nicht als Eingabeargumente für Methoden, da es – sofern keine Schutzkopie des Arrays erstellt wird – möglich ist, dass ein anderer Thread den Inhalt des Arrays während der Methodenausführung ändert.

Sie können auch so schreiben

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

anstatt so zu schreiben

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 cb4f314346501f136be324eca3ec9a0a并将其应用于内部的通用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(Functionee2b8263933625d1848a755ff2bdf311 renderer) 和add(Predicate44a45ae2deb400dab67a6f07325591bb 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中文网（www.php.cn）！