Java 8 API 디자인 경험에 대한 간략한 분석

이 기사는 원래 MaNong.com에서 Xiaofeng이 번역한 것입니다. 재인쇄하려면 기사 끝에 있는 재인쇄 요구 사항을 읽어보세요. 유료 기부 계획에 참여하신 것을 환영합니다!

Java 코드를 작성하는 사람은 누구나 API 디자이너입니다! 코더가 코드를 다른 사람과 공유하는지 여부에 관계없이 해당 코드는 다른 사람이 사용하거나 스스로 사용하거나 둘 다 사용합니다. 따라서 모든 Java 개발자는 좋은 API 디자인의 기본 사항을 이해하는 것이 중요합니다.

좋은 API 디자인에는 신중한 사고와 많은 경험이 필요합니다. 다행히도 우리는 내가 이 Java 8 API 부록을 작성하도록 영감을 준 블로그인 Ference Mihaly와 같은 더 똑똑한 다른 사람들로부터 배울 수 있습니다. Speedment API를 설계할 때 우리는 그의 인터페이스 목록에 크게 의존했습니다. (가이드를 읽어보시길 권합니다.)

API가 출시되면 API를 사용하는 모든 사람에게 견고한 기반이 될 것이기 때문에 처음부터 이를 수행하는 것이 중요합니다. Joshua Bloch가 말했듯이 "공개 API는 다이아몬드처럼 영원히 지속됩니다. 제대로 할 수 있는 기회가 있다면 최선을 다해 노력해야 합니다.

잘 설계된 API는 두 가지를 모두 결합합니다." 이 세상의 본질은 견고하고 정확한 기반과 높은 수준의 구현 유연성이며 궁극적으로 API 디자이너와 API 사용자에게 도움이 됩니다.

인터페이스 목록을 사용해야 하는 이유는 무엇인가요? 올바른 API(즉, Java 클래스 컬렉션을 정의하는 가시적인 부분)를 얻는 것은 API 뒤에 있는 실제 작업을 구성하는 구현 클래스를 작성하는 것보다 훨씬 어렵습니다. 정말 소수의 사람들만이 마스터할 수 있는 예술입니다. 인터페이스 체크리스트를 사용하면 독자는 가장 명백한 실수를 피하고 더 나은 프로그래머가 되며 많은 시간을 절약할 수 있습니다.

API 디자이너는 실제 API 구현에 대해 생각하기보다는 클라이언트 코드의 관점에서 단순성, 사용 용이성 및 일관성 측면에서 이 뷰를 최적화하는 것이 좋습니다. 동시에 구현 세부 사항을 최대한 숨기려고 노력해야 합니다.
이는 메소드가 값을 반환할 수도 있고 반환하지 않을 수도 있음을 API 소비자에게 명확하게 나타냅니다. 성능상의 이유로 Optional 대신 null을 사용하려는 유혹에 빠지지 마십시오. 어쨌든 Java 8의 이스케이프 분석은 대부분의 Optional 객체를 최적화합니다. 매개변수와 필드에 Optional을 사용하지 마세요.

이렇게 써도 됩니다

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

이렇게 쓰는 대신

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

API의 들어오는 매개변수와 반환값으로 배열을 사용하지 마세요

Java 5에서 Enum 개념이 도입되었을 때 심각한 API 오류가 발생했습니다. 우리 모두는 Enum 클래스에 다른 모든 Enum 값의 배열을 반환하는 value()라는 메서드가 있다는 것을 알고 있습니다. 이제 Java 프레임워크는 클라이언트 코드가 Enum의 값을 변경할 수 없도록(예: 배열에 직접 쓰는 방식으로) 보장해야 하므로 value() 메서드를 호출할 때마다 내부 배열의 복사본을 만들어야 합니다.

이로 인해 성능이 저하되고 클라이언트 코드 사용성이 저하됩니다. Enum이 모든 호출에서 재사용할 수 있는 수정 불가능한 목록을 반환하는 경우 클라이언트 코드는 더 우수하고 유용한 Enum 값 모델에 액세스할 수 있습니다. 일반적으로 API가 요소 집합을 반환하는 경우 스트림 노출을 고려하세요. 이는 결과가 읽기 전용임을 명확하게 보여줍니다(set() 메소드가 있는 List와 반대).

또한 이를 통해 클라이언트 코드는 다른 데이터 구조에서 요소를 쉽게 수집하거나 즉석에서 작업할 수 있습니다. 또한 API는 요소가 사용 가능해지면(예: 파일, 소켓 또는 데이터베이스에서 가져옴) 요소를 느리게 생성할 수 있습니다. 마찬가지로 Java 8의 향상된 이스케이프 분석을 통해 Java 힙에 실제로 생성되는 개체의 수를 최소화할 수 있습니다.

또한 배열의 보호 복사본이 생성되지 않는 한 메서드 실행 중에 다른 스레드가 배열의 내용을 수정할 수 있으므로 배열을 메서드에 대한 입력 인수로 사용하지 마십시오.

이렇게 써도 됩니다

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

이렇게 쓰는 대신

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中文网（www.php.cn）！