Java 8 API 設計経験の簡単な分析

この記事は、MaNong.com の Xiaofeng によって翻訳されたものです。転載については、記事の最後にある転載要件をお読みください。有料投稿プランへの参加を歓迎します。

Java コードを書く人は誰でも API デザイナーです。コーダーがコードを他の人と共有するかどうかに関係なく、コードは他の人、自分自身、またはその両方によって使用されます。したがって、すべての Java 開発者にとって、優れた API 設計の基本を理解することが重要です。

優れた API 設計には、慎重な思考と多くの経験が必要です。幸いなことに、私たちは Ference Mihaly のような他の賢明な人々から学ぶことができます。Ference Mihaly のブログが私にこの Java 8 API の付録を書くきっかけを与えてくれました。 Speedment API を設計するとき、私たちは彼のインターフェースのリストに大きく依存しました。 (彼のガイドを読むことをお勧めします。)

API がリリースされると、API を使用する人にとって強固な基盤となるため、これを最初から行うことが重要です。 Joshua Bloch がかつて言ったように、「パブリック API はダイヤモンドのように永遠に続きます。正しく実行できるチャンスがあるのであれば、最善を尽くしるべきです

適切に設計された API は、両方の長所を組み合わせたものです。」これは強固で正確な基盤であり、実装の柔軟性も高く、最終的には API 設計者と API ユーザーに利益をもたらします。

なぜインターフェースリストを使用する必要があるのか​​というと、 API (つまり、Java クラスのコレクションを定義する目に見える部分) を正しく理解することは、API の背後で実際の作業を構成する実装クラスを記述することよりもはるかに困難です。それは本当に少数の人がマスターする芸術です。インターフェイス チェックリストを使用すると、読者は最も明らかな間違いを回避し、より優れたプログラマーになり、時間を大幅に節約できます。

API 設計者は、実際の API 実装について考えるのではなく、クライアント コードの視点に立って、シンプルさ、使いやすさ、一貫性の観点からこのビューを最適化することを強くお勧めします。同時に、実装の詳細をできるだけ隠すように努める必要があります。

null 値を示すために Null を返さないでください

一貫性のない null 処理 (遍在する NullPointerException を引き起こす) が、Java アプリケーション エラーの史上最大の原因であることが証明されています。一部の開発者は、ヌル概念の導入をコンピューター サイエンスで犯した最悪の間違いの 1 つと考えています。幸いなことに、Java の null 処理の問題を軽減するための最初のステップは、Java 8 での Optional クラスの導入でした。戻り値が null のメソッドは、null ではなく Optional を返すようにしてください。

これは、メソッドが値を返す場合と返さない場合があることを API コンシューマーに明確に示します。パフォーマンス上の理由から、Optional の代わりに null を使用しないでください。とにかく、Java 8 のエスケープ分析は、ほとんどの Optional オブジェクトを最適化して取り除きます。パラメーターとフィールドで Optional を使用することは避けてください。

このように書く代わりに、次のように書くこともできます

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

APIの受信パラメータや戻り値として配列を使用しないでください

Enumの概念が導入されたときJava 5 には、重大な API バグがありました。 Enum クラスには、すべての異なる Enum 値の配列を返す、values() というメソッドがあることは誰もが知っています。 Java フレームワークでは、クライアント コードが Enum の値を変更できないようにする必要があるため (配列に直接書き込むなど)、value() メソッドを呼び出すたびに内部配列のコピーを作成する必要があります。

これにより、パフォーマンスが低下し、クライアント コードの使いやすさが低下します。 Enum が呼び出しごとに再利用できる変更不可能な List を返す場合、クライアント コードは Enum 値のより優れた有用なモデルにアクセスできます。一般に、API が要素のセットを返す場合は、ストリームを公開することを検討してください。これは、結果が (set() メソッドを持つ List とは対照的に) 読み取り専用であることを明確に示しています。

また、クライアント コードが別のデータ構造から要素を簡単に収集したり、オンザフライで要素を操作したりできるようになります。さらに、API は、要素が利用可能になると (ファイル、ソケット、データベースから取得するなど)、要素を遅延生成できます。同様に、Java 8 の改良されたエスケープ分析により、Java ヒープ上に実際に作成されるオブジェクトが最小限に抑えられます。

また、配列の保護コピーが作成されない限り、メソッドの実行中に別のスレッドが配列の内容を変更する可能性があるため、メソッドへの入力引数として配列を使用しないでください。

このように書く代わりに、次のように書くこともできます

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

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

避免允许客户端代码直接选择接口的实现类。允许客户端代码创建实现类直接创建了一个更直接的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）！