Как создать хороший, регулярный API

Люди имеют твердое мнение о том, как разработать хороший API. Следовательно, в сети много страниц и книг, объясняющих, как это сделать. Эта статья будет посвящена конкретному аспекту хороших API: регулярности. Регулярность — это то, что происходит, когда вы следуете « Принципу наименьшего удивления ». Этот принцип действует независимо от того, какой личный вкус и стиль вы хотели бы использовать в своем API, в противном случае. Таким образом, это одна из самых важных функций хорошего API.

При разработке «обычного» API необходимо учитывать следующее.

Правило № 1: Установите сильные условия

Если ваш API будет расти, вы будете снова и снова использовать одни и те же термины. Например, некоторые действия будут иметь несколько разновидностей, что приведет к различным классам / типам / методам, которые отличаются лишь незначительным поведением. Тот факт, что они похожи, должен отражаться в их именах. Имена должны использовать сильные термины. Взять, к примеру, JDBC. Независимо от того, как вы выполняете заявление , вы всегда будете использовать этот термин execute. Например, вы будете вызывать любой из этих методов:

• execute(String)
• executeBatch()
• executeQuery(String)
• executeUpdate(String)

Подобным образом, вы всегда будете использовать термин closeдля освобождения ресурсов, независимо от того, какой ресурс вы выпускаете. Например, вы позвоните:

• Connection.close()
• Statement.close()
• ResultSet.close()

На самом деле, closeэто настолько сильный и устоявшийся термин в JDK, что он привел к интерфейсам java.io.Closeable(начиная с Java 1.5) и java.lang.AutoCloseable(начиная с Java 1.7), которые обычно устанавливают договор об освобождении ресурсов.

Нарушение правила: наблюдаемое

Это правило нарушается пару раз в JDK. Например, в java.util.Observableклассе. В то время как другие «коллекционные» типы установили условия

• size()
• remove()
• removeAll()

… Этот класс объявляет

• countObservers()
• deleteObserver(Observer)
• deleteObservers()

В этом контексте нет веских оснований для использования других терминов. То же самое относится к Observer.update(), который на самом деле должен называться notify(), другому термину, установленному в API JDK.

Нарушение правила: весна. Большинство из этого

Весна действительно стала популярной в те дни, когда J2EE был странным, медленным и громоздким. Подумайте об EJB 2.0 … Там могут быть похожие мнения о Spring, которые не по теме для этого поста. Вот как Spring нарушает это конкретное правило. Пара случайных примеров, в которых Spring не может установить строгие термины и вместо этого использует длинные конкатенации бессмысленных, неконкретных слов:

• AbstractBeanFactoryBasedTargetSourceCreator
• AbstractInterceptorDrivenBeanDefinitionDecorator
• AbstractRefreshablePortletApplicationContext
• AspectJAdviceParameterNameDiscoverer
• BeanFactoryTransactionAttributeSourceAdvisor
• ClassPathScanningCandidateComponentProvider
• … это может продолжаться бесконечно, мое любимое существо …
• J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource . Обратите внимание, я писал о краткости раньше …

Помимо «ощущения» как ужасного API (для меня), вот еще несколько объективный анализ:

• В чем разница между а CreatorиFactory
• В чем разница между а Sourceи а Provider?
• В чем неощутимая разница между Advisorи Provider?
• В чем неощутимая разница между а Discovererи а Provider?
• Это Advisorсвязано с AspectJAdvice?
• Это ScanningCandidateили CandidateComponent?
• Что TargetSource? И как бы это отличалось от a SourceTargetесли не a SourceSourceили моего любимого: A SourceSourceTargetProviderSource?

Гари Флеминг прокомментировал мой предыдущий пост в блоге о забавных именах Spring:

Я готов поспорить, что имя класса, сгенерированного цепочкой Маркова (на основе Spring Security), будет неотличимо от реального.

Вернуться к большей серьезности …

Правило № 2: применяйте симметрию к комбинациям терминов

Как только вы установили сильные условия, вы начнете их комбинировать. Когда вы смотрите на коллекции API , в JDK, вы заметите, что они симметричны таким образом , что они установлены сроки add(), remove(), contains(), и all, прежде чем объединять их симметрично:

• add(E)
• addAll(Collection<? extends E>)
• remove(Object)
• removeAll(Collection<?>)
• contains(Object)
• containsAll(Collection<?>)

Теперь Collectionтип является хорошим примером, где может быть приемлемо исключение из этого правила , когда метод не «тянет свой вес» . Это, вероятно, имеет место для retainAll(Collection<?>), который не имеет эквивалентного retain(E)метода. Впрочем, это может быть и регулярным нарушением этого правила.

Нарушение правила: карта

Это правило постоянно нарушается, в основном из-за того, что некоторые методы не увеличивают свой вес (что в конечном итоге является вопросом вкуса). С методами защиты Java 8 больше не будет оправданий для того, чтобы не добавлять реализации по умолчанию для полезных служебных методов, которые должны были быть в некоторых типах. Например: Map. Это нарушает это правило пару раз:

• Это keySet()такжеcontainsKey(Object)
• Это values()такжеcontainsValue(Object)
• Имеет entrySet()но нетcontainsEntry(K, V)

Заметьте также, что нет смысла использовать термин Setв именах методов. Подпись метода уже указывает, что у результата есть Setтип. Это было бы более последовательным и симметричным , если эти методы будут уже были названы keys(), values(), entries(). (В дополнение к этому, Setsи Listsеще одна тема, о которой я скоро напишу в блоге, так как я думаю, что эти типы также не имеют собственного веса)

В то же время Mapинтерфейс нарушает это правило, предоставляя

• put(K, V) а также putAll(Map)
• remove(Object), но нет removeAll(Collection<?>)

Кроме того, нет необходимости устанавливать термин clear()вместо повторного использования removeAll()без аргументов. Это относится ко всем членам Collection API. На самом деле, clear()метод также нарушает правило № 1. Это не сразу очевидно, если clearчто-то немного отличается от removeудаления элементов коллекции.

Правило № 3: добавьте удобства за счет перегрузки

В большинстве случаев есть только одна веская причина, по которой вы хотите перегружать метод: удобство. Часто вы хотите делать одно и то же в разных контекстах, но создание этого очень специфического типа аргумента метода обременительно. Поэтому для удобства вы предлагаете своим пользователям API другой вариант того же метода с установленным «дружественным» типом аргумента. Это можно наблюдать снова в Collectionтипе. У нас есть:

• toArray(), что является удобной перегрузкой…
• toArray(T[])

Другим примером является Arraysслужебный класс. У нас есть:

• copyOf(T[], int), что является несовместимой перегрузкой …
• copyOf(boolean[], int), и из…
• copyOf(int[], int)
• … и все остальные

Перегрузка в основном используется по двум причинам:

1. Предоставление поведения аргумента «по умолчанию», как в Collection.toArray()
2. Поддержка нескольких несовместимых, но «похожих» наборов аргументов, как в Arrays.copyOf ()

Другие языки включили эти понятия в свой языковой синтаксис. Многие языки (например, PL / SQL) формально поддерживают именованные аргументы по умолчанию. Некоторые языки (например, JavaScript) даже не заботятся о том, сколько на самом деле аргументов. И еще один новый язык JVM под названием Ceylon избавился от перегрузки , объединив поддержку именованных аргументов по умолчанию с типами объединения. Так как Ceylon является языком статической типизации, это, вероятно, самый мощный подход для повышения удобства вашего API.

Нарушение правила: TreeSet

Трудно найти хороший пример случая, когда это правило нарушается в JDK. Но есть одно: TreeSetи TreeMap. Их конструкторы перегружены несколько раз. Давайте посмотрим на эти два конструктора:

• TreeSet(Collection<? extends E>)
• TreeSet(SortedSet<E>)

Последнее «умно» добавляет некоторое удобство к первому в том, что оно извлекает хорошо известное Comparatorиз аргумента, SortedSetчтобы сохранить порядок. Это поведение сильно отличается от совместимого (!) Первого конструктора, который не выполняет instanceofпроверку набора аргументов. Т.е. эти два вызова конструктора приводят к разному поведению:

SortedSet<Object> original = // [...]

// Preserves ordering:
new TreeSet<Object>(original);

// Resets ordering:
new TreeSet<Object>((Collection<Object>) original);

String[] files = file.list();

// You should never forget this null check!
if (files != null) {
    for (String file : files) {
        // Do things with your file
    }
}