1. Введение
В этом уроке мы поговорим о параметрах конфигурации Lombok. Мы рассмотрим множество различных вариантов, а также то, как правильно настроить нашу конфигурацию.
2. Обзор конфигурации
Lombok — это библиотека, которая помогает нам избавиться почти от всех стандартных шаблонов наших Java-приложений. Мы протестируем многие свойства и конфигурации. Первым делом нужно добавить зависимость Lombok :
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.20</version>
<scope>provided</scope>
</dependency>
Система конфигурации Lombok предлагает нам множество ценных настроек, которые часто одинаковы для всех компонентов нашего проекта. Тем не менее, он также позволяет нам изменять или настраивать поведение Lombok, а иногда даже определяет, что можно или нельзя использовать из всех доступных функций. Например, мы можем указать Lombok показывать предупреждение или ошибку, если используется какая-либо экспериментальная функция.
Чтобы начать определять или настраивать поведение Lombok, нам нужно создать файл с именем lombok.config. Этот файл можно оставить в корне нашего проекта, исходного кода или любого пакета. После создания все исходные файлы в дочерних каталогах наследуют конфигурации, определенные в таком файле. Можно иметь несколько файлов конфигурации. Например, мы можем определить файл конфигурации в нашем корневом каталоге с общими свойствами и создать еще один в данном пакете, определяющем другие свойства.
Новые конфиги будут влиять на все классы данного пакета и все дочерние пакеты. Кроме того, в случае нескольких определений одного и того же свойства преимущество имеет более близкое к классу или члену.
3. Основные конфигурации
Первое, что нужно упомянуть, это слишком много свойств функций, чтобы их обсуждать. По этой причине мы увидим только самые распространенные из них. Чтобы проверить доступные параметры, давайте перейдем на страницу Ломбока , загрузим банку и запустим в терминале следующую команду:
java -jar lombok.jar config -g --verbose
В результате мы увидим полный список всех свойств и их возможных значений, а также краткое описание, объясняющее его назначение.
Теперь давайте посмотрим на типичный файл lombok.config :
config.stopBubbling = true
lombok.anyconstructor.addconstructorproperties = false
lombok.addLombokGeneratedAnnotation = true
lombok.experimental.flagUsage = WARNING
# ... more properties
Свойства, используемые в файле, предназначены только для иллюстрации. Мы обсудим их позже. Но здесь мы можем наблюдать формат свойств Lombok и их определение.
Начнем со свойства config.stopBubbling — этот параметр указывает системе конфигурации не искать файлы конфигурации в родительских каталогах . Рекомендуется добавить это свойство в корень вашей рабочей области или проекта. По умолчанию его значение равно false .
4. Основные свойства
4.1. Глобальные ключи конфигурации
Ключи глобальной конфигурации — это конфигурации, которые могут влиять на многие системы конфигурации . Далее мы увидим несколько примеров таких ключей.
Первый ключ, который мы обсудим, — это lombok.anyConstructor.addConstructorProperties. Он добавляет аннотацию @java.beans.ConstructorProperties ко всем конструкторам с аргументами. Обычно фреймворкам, использующим отражение в конструкторах, нужна эта аннотация для сопоставления свойств и определения правильного порядка параметров в конструкторе. Вот код в версии Lombok:
@AllArgsConstructor
@NoArgsConstructor
@Getter
@Setter
public class Account {
private double balance;
private String accountHolder;
}
И вот сгенерированный код:
public class Account {
private double balance;
private String accountHolder;
@ConstructorProperties({"balance", "accountHolder"})
@Generated
public Account(double balance, String accountHolder) {
this.balance = balance;
this.accountHolder = accountHolder;
}
@Generated
public Account() {}
// default generated getter and setters
}
В приведенном выше фрагменте кода мы видим сгенерированный класс, содержащий аннотацию @ConstructorProperties .
Далее у нас есть lombok.addLombokGeneratedAnnotation . Если true , Lombok пометит все сгенерированные методы тегом @lombok.Generated. Это удобно при удалении сгенерированных Lombok методов из инструментов сканирования пакетов или покрытия кода .
Еще один полезный ключ — lombok.addNullAnnotations. Это свойство поддерживает многие встроенные параметры, такие как javax (JSR305), eclipse, JetBrains, NetBeans, Android и другие. Также можно использовать определенные нами аннотации, например CUSTOM:com.example.NonNull:example.Nullable . Lombok добавит аннотации nullable или NotNull всякий раз, когда это имеет смысл.
Наконец, у нас есть lombok.addSuppressWarnings, что если false , Lombok прекращает добавлять аннотацию @SuppressWarnings («все»), что является текущим поведением по умолчанию. Это полезно, если мы используем статические анализаторы сгенерированного кода.
4.2. Другие ключи конфигурации
Будучи первым ключом для конкретной функции, lombok.accessors.chain, если true , изменяет поведение методов установки. Вместо void return эти методы вернут this . Разрешение цепочки вызовов, как показано ниже:
@Test
void should_initialize_account() {
Account myAccount = new Account()
.setBalance(2000.00)
.setAccountHolder("John Snow");
assertEquals(2000.00, myAccount.getBalance());
assertEquals("John Snow", myAccount.getAccountHolder());
}
Подобно предыдущему, lombok.accessors.fluent заставляет Lombok удалить набор префиксов и получить из методов доступа, используя только имена свойств для их именования.
Ключ lombok.log.fieldName изменяет имя сгенерированного поля журнала при настройке пользователем. По умолчанию ключ lombok.log.fieldName использует log для именования поля, но в нашем примере мы изменили его на domainLog :
#Log name customization
lombok.log.fieldName = domainLog
Затем мы можем увидеть его в действии:
@AllArgsConstructor
@NoArgsConstructor
@Getter
@Setter
@Log
public class Account {
// same as defined previously
public Account withdraw(double amount) {
if (this.balance - abs(amount) < 0) {
domainLog.log(Level.INFO, "Transaction denied for account holder: %s", this.accountHolder);
throw new IllegalArgumentException(String.format("Not enough balance, you have %.2f", this.balance));
}
this.balance -= abs(amount);
return this;
}
}
Следующий — ломбок.(featureName).flagUsage. Этот набор свойств имеет предупреждения , ошибки и разрешения в качестве возможных значений. Мы можем использовать их, чтобы контролировать, какие функции Lombok разрешены в наших проектах. Например, можно использовать слово « экспериментальный » и значение « предупреждение » для вывода сообщения в журнал, если используется какая-либо экспериментальная функция:
/home/dev/repository/git/tutorials/lombok/src/main/java/com/foreach/lombok/configexamples/TransactionLog.java:9:
warning: Use of any lombok.experimental feature is flagged according to lombok configuration.
@Accessors(prefix = {"op"})
4.3. Специальные ключи конфигурации
Некоторые ключи не являются обычными свойствами пар "ключ-значение", например lombok.copyableAnnotations. Это свойство отличается тем, что оно представляет список полностью определенных типов аннотаций. При добавлении в поле Lombok скопирует эти аннотации в конструкторы, геттеры и сеттеры, связанные с полем. Типичным вариантом использования этой функции являются определения bean-компонентов в Spring, где аннотации @Qualifier и @Value часто приходится копировать в аргументы конструктора . Другие фреймворки также используют эту функцию.
Чтобы добавить аннотации в список, пользователь должен использовать следующее выражение: lombok.copyableAnnotations += com.test.MyAnnotation . Библиотека использует механизм для распространения упомянутой ранее аннотации, допускающей значение NULL:
@NoArgsConstructor
@AllArgsConstructor
@Getter
@Setter
@Log
public class Account {
@NonNull
private Double balance = 0.;
@NonNull
private String accountHolder = "";
// other methods
}
Теперь код, сгенерированный Lombok:
public class Account {
@Generated
private static final Logger domainLog = Logger.getLogger(Account.class.getName());
@NonNull
private Double balance = 0.0D;
@NonNull
private String accountHolder = "";
@ConstructorProperties({"balance", "accountHolder"})
@Generated
public Account(@NonNull Double balance, @NonNull String accountHolder) {
if (balance == null) {
throw new NullPointerException("balance is marked non-null but is null");
} else if (accountHolder == null) {
throw new NullPointerException("accountHolder is marked non-null but is null");
} else {
this.balance = balance;
this.accountHolder = accountHolder;
}
}
@NonNull
@Generated
public Double getBalance() {
return this.balance;
}
@NonNull
@Generated
public String getAccountHolder() {
return this.accountHolder;
}
// Rest of the class members...
}
И, наконец, у нас есть четкая директива lombok.(anyConfigKey) . `Он восстанавливает любой ключ конфигурации до значения по умолчанию. Если кто-то изменил значение данного ключа в любом родительском конфигурационном файле, теперь оно будет проигнорировано. Мы можем использовать директиву clear,` за которой следует любой ключ конфигурации Lombok:
clear lombok.addNullAnnotations
4.4. Файловые директивы
Теперь у нас есть хорошее представление о том, как работает система конфигурации Lombok, и о некоторых ее функциях. Конечно, это не был обширный список всех доступных функций, но отсюда у нас должно быть четкое представление о том, как их использовать. И последнее, но не менее важное: давайте посмотрим, как импортировать конфигурации, определенные в другом файле, в наш текущий файл конфигурации.
Для импорта файла конфигурации внутри другого директивы должны идти поверх файла, а путь может быть как относительным, так и абсолютным :
## relative or absolute path
import lombok_feature.config
config.stopBubbling = true
lombok.anyconstructor.addconstructorproperties=false
lombok.addLombokGeneratedAnnotation = true
lombok.addSuppressWarnings = false
Просто для иллюстрации импортированный файл:
# lombok_feature.config file
lombok.experimental.flagUsage = warning
5. Вывод
В этой статье мы рассмотрели систему конфигурации от Lombok, ее различные свойства и то, как они влияют на ее функционирование. Хотя, как упоминалось ранее, доступно гораздо больше вариантов, мы рассмотрели только самые распространенные из них. Не стесняйтесь проверить больше на странице Ломбок .
Как обычно, все примеры кода, использованные в этой статье, доступны на GitHub .