Уменьшаем написание boilerplate с помощью File Templates

Всем привет! На связи Дима Котиков, и я все еще люблю разбираться в технологиях, разрабатывать под Android и KMP и пить латте на фундучном молоке 🙂

Рассказываю о генерации файлов с boilerplate-кодом с помощью удобного механизма задания File Templates в средах разработки Intellij. File Templates позволяет в пару кликов создавать несколько файлов с каким-либо boilerplate-кодом. Хоть статья приводит примеры создания File Templates для Android/Kotlin Multiplatform, она может быть полезна всем, кто работает в средах разработки от Intellij.

Шаблонный код

Каждый разработчик в повседневной работе сталкивается с созданием однотипных файлов и шаблонных конструкций, будь то файлы а-ля Controller/Service/Repository в backend-разработке или Fragment-, ViewModel-, State-, SideEffect-, Store-сущности в Android/KMP-разработке. 

Файлы с таким кодом могут иметь схожие префиксы и суффиксы в названии, похожий или одинаковый код внутри них по типу инициализации сущностей, логирования, аналитики, вызовов методов жизненного цикла и тому подобное. 

Каждый раз писать один и тот же код бывает довольно утомительно, неинтересно, затратно по времени, да и фокус внимания на бизнес-задаче или какой-то уникальной логике начинает уменьшаться. 

Для примера приведу код одного шаблонного экрана мобильного приложения:

// file: SomeFeatureScreen   @Composable fun SomeFeatureScreen(     viewModel: SomeFeatureViewModel,     router: SomeFeatureRouter, ) {     val lifecycle = LocalLifecycleOwner.current.lifecycle       LaunchedEffect(viewModel) {         viewModel.sideEffectFlow             .flowWithLifecycle(lifecycle)             .onEach { sideEffect: SomeFeatureSideEffect ->                 handleSideEffect(sideEffect, router)             }             .launchIn(this)     }       val state: SomeFeatureState by viewModel.stateFlow.collectAsStateWithLifecycle()       SomeFeatureStateContent(         state = state,         onEvent = { uiEvent -> viewModel.dispatch(uiEvent) }     ) }   private fun handleSideEffect(sideEffect: SomeFeatureSideEffect, router: SomeFeatureRouter) {     // some feature-specific logic }   @Composable private fun SomeFeatureStateContent(     state: SomeFeatureState,     onEvent: (SomeFeatureUiEvent) -> Unit ) {      // some feature-specific logic } 

// file: SomeFeatureViewModel   class SomeFeatureViewModel : ViewModel() {       private val _stateFlow = MutableStateFlow<SomeFeatureState>(SomeFeatureState())     val stateFlow: StateFlow<SomeFeatureState>         get() = _stateFlow.asStateFlow()       private val sideEffectChannel = Channel<SomeFeatureSideEffect>()     val sideEffectFlow: Flow<SomeFeatureSideEffect>         get() = sideEffectChannel.receiveAsFlow().flowOn(Dispatchers.Main.immediate)       fun dispatch(uiEvent: SomeFeatureUiEvent) {         // some feature-specific logic      }       private fun reduceState(reducer: (SomeFeatureState) -> SomeFeatureState) {         _stateFlow.update(reducer)     }       private fun sendSideEffect(sideEffect: SomeFeatureSideEffect) {         viewModelScope.launch {             sideEffectChannel.send(sideEffect)         }     }        // other functions with some feature-specific logic    } 

// file: SomeFeatureState   @Immutable data class SomeFeatureState(     val isLoading: Boolean,     ... // other some feature-specific fields ) 

// file: SomeFeatureSideEffect   @Immutable sealed interface SomeFeatureSideEffect {       data class ShowUnknownError(val error: Throwable) : SomeFeatureSideEffect       // other some feature-specific subclasses } 

// file: SomeFeatureUiEvent   @Immutable sealed interface SomeFeatureUiEvent {       data object NavigateBack : SomeFeatureUiEvent       // other some feature-specific subclasses } 

// file: SomeFeatureRouter   interface SomeFeatureRouter {       fun navigateBack()       // other some feature-specific functions   } 

// file: SomeFeatureRouterImpl   class SomeFeatureRouterImpl : SomeFeatureRouter {       override fun navigateBack() {         // some feature-specific logic     }       // other some feature-specific functions   } 

Код немного утрирован для понимания того, что происходит в представленном примере, в production-коде некоторые конструкции могут быть вынесены в интерфейсы или абстрактные классы.

Если мы внимательно посмотрим на код, то легко сможем выделить некоторые конструкции, которые можно назвать шаблонными:

• Названия сущностей именуются как «<feature name>» + «<suffix>», где «<feature name>» — специфичное название для фичи или экрана, а «<suffix>» — шаблонный суффикс, обозначающий, что это за сущность: экран, вьюмодель, роутер, модель состояния экрана и тому подобное.

• У сущностей есть шаблонные вызовы, например в SomeFeatureScreen вызываются подписки на состояние (viewModel.stateFlow.collectAsStateWithLifecycle()) и side effect-ы (код внутри LaunchedEffect). В классе SomeFeatureViewModel мы видим стандартный подход к хранению сущности состояния (StateFlow<SomeFeatureState>) и его смены (функция reduceState()), а также хранение и отправка sideEffect-ов (one-time-events).

Если бы приложения состояли только из одного экрана и нам нужно было единожды написать шаблонный код, то особых проблем не возникло бы. На деле даже в небольших мобильных приложениях количество фич и экранов может достигать 50—100 штук. Представим, сколько времени суммарно может уйти, чтобы вручную 100 раз создать по семь файлов с шаблонным кодом, не говоря уже о том, что на каждом экране нужно прописать бизнес-логику, верстку, взаимодействие с сетью, локальным хранилищем, навигацию и так далее.

Как уменьшить боль от boilerplate-кода

Вариантов для решения проблемы несколько:

Сделать отдельную папку, в которой можно создать файлы с кодом, а потом копипастить в package-ы. Наверное, это самый плохой способ решения проблемы, потому что каждый раз придется вручную переименовывать каждый файл, класс и так далее. Ускорение по времени от такого подхода сомнительное.

Написать annotation- или symbol-processor для генерации файлов или классов на базе аннотаций. Инструмент мощный, но не особо подходит для решения нашей проблемы. Все равно нужно руками создать как минимум один файл, написать какой-то базовый код, расставить аннотации, запустить компиляцию и только после этого пользоваться сгенерированными файлами и кодом в них. 

А еще нужно помнить, что в сгенерированных файлах не получится дописать свой код, так как при следующей компиляции файлы запросто могут быть переписаны процессором аннотаций. Добавим к этому тот факт, что написание таких процессоров — штука нетривиальная и требует специфичного API, рефлексии и т. д. В общем, путь, который подходит скорее для создания библиотек и фреймворков, но не для решения нашей проблемы.

Написать плагин для Intellij — вариант рабочий, но потребует погружения в документацию по написанию плагинов и, по сути, тоже достаточно сложный процесс для решения нашей задачи.

Использовать встроенный в Intellij-среду механизм Live Templates — частично решает проблему с генерацией шаблонного кода, но не решает задачу создания и именования семи файлов.

Использовать встроенный в Intellij-среду механизм File Templates — наш выбор, так как умеет создавать файлы по шаблонам, причем сразу несколько. Плюс ко всему есть возможность для написания шаблонного кода по различным условиям.

А если вы знаете другие способы работы с бойлерплейтом — пишите в комментариях 😊

В моих вариантах нет обобщения в базовые классы и интерфейсы. Этими механизмами можно и нужно пользоваться, но мы приняли за аксиому, что от boilerplate нельзя уйти. Мы все равно с ним столкнемся, но уже с использованием абстракций и обобщений.

Плюсы, возможности и синтаксис File Templates 

Есть несколько весомых причин выбрать File Templates:

• инструмент решает нашу проблему — генерирует файлы и контент в них по шаблонам;

• генерирует несколько файлов в одно действие;

• задает пользовательские переменные, которые можно использовать при генерации шаблонного кода;

• для написания шаблонов не нужно глубоких и специфических знаний — достаточно изучить несколько базовых конструкций, чтобы решать большинство проблем с созданием шаблонов;

• инструмент интегрирован в Intellij-подобные среды разработки, поэтому дополнительных действий, связанных с установкой и первоначальной настройкой (как это нужно для плагинов), не требуется.

Примеры покажу в Android Studio, но практически вся информация валидна и для остальных сред разработки на базе Intellij IDEA.

Чтобы добраться до инструмента File Templates, нужно открыть Settings → Editor → File and Code Templates:

В меню много заготовленных шаблонов, но большинство из них имеют пару строчек с базовыми конструкциями, поэтому будем писать свои.

Нас интересуют вкладки Files и Includes. На вкладке Files располагаются коллекции с шаблонами, а во вкладке Includes — шаблоны, предназначенные для переиспользования в шаблонах из вкладки Files.

Весь шаблонный код, который мы будем писать, по сути своей будет миксом из кода языка и из вспомогательного кода, состоящего из специальных переменных для File Templates и конструкций, написанных на Apache Velocity — языке, используемом для шаблонов.

Из стандартных переменных чаще всего приходится использовать ${NAME} и ${PACKAGE_NAME}. Можно создавать свои переменные, для этого их достаточно просто объявить в месте использования в шаблоне и тогда при создании шаблона появится отдельное поле для ввода кастомной переменной.

Посмотрим синтаксис Apache Velocity, так как на нем пишется логика для шаблонов.

Первое, что можно увидеть в стандартных шаблонах, — указание package name для файлов через конструкцию if:

#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")     package ${PACKAGE_NAME}  #end

Есть возможность писать конструкции if-else:

#if (${NAME} != "")     class ${PACKAGE_NAME}  #else      class Unknown  #end

Или if-elseif-else:

#if (${NAME} == "")     class Unknown  #elseif (${NAME} == "a")     class OneLetter  #else      class ${NAME}  #end

Все ключевые слова начинаются со знака #, ссылки на переменные с $. Как указано в документации: ссылки начинаются со знака $ и используются для получения чего-либо. Директивы начинаются со знака # и используются, чтобы сделать что-либо (присвоить значение, обработать что-либо и т. п.).

Присвоение переменной и ее последующее применение выполняется так:

#set( $someVar = "Hello, World!" ) $someVar

Если мы хотим, чтобы переменная была задана путем пользовательского ввода, ее нужно сразу указывать в месте использования без set-конструкции:

$USER_INPUT  // or ${USER_INPUT}

А еще нам доступны циклы:

#set( $customerParts = ["John", "Doe"] ) #set( $customerFull = "" ) #set( $part = "" )   #foreach( $part in $customerParts )     #set( $customerFull = $customerFull + $part ) #end  $customerFull  // prints `JohnDoe`

Ключевые слова #break позволяют прервать цикл #foreach, а #stop прекращает выполнение кода в template-файле.

Для переиспользования скриптов между файлами шаблонов нужно задать шаблон во вкладке Includes, а потом в целевых файлах вызвать с помощью конструкции #parse — простейший пример есть в шаблонах для проставления хедера файла:

#parse("File Header.java")

Аналогично #parse есть еще конструкции #include:

#include("SharedData.java")

Ключевые отличия #parse от #include:

• #parse допускает, что в передаваемом в параметры файле может содержаться VLT-код, который будет выполнен в месте вызова. #include же просто добавит контент из передаваемого в параметрах файла прямиком как есть в место вызова, без обработки VLT-кода.

• #parse может принимать в себя только один аргумент, а #include — несколько:

#parse("File1.java", "File2.java") // ERROR, 2 parameters passed. Must be 1 parameter #include("File1.java", "File2.java") // CORRECT, more than 1 parameters available

Еще есть директива #define, которая позволяет задать какой-то шаблон с переменными, которые должны вычислиться позже, к примеру:

#define( $block )     Hello $who #end #set( $who = 'World!' )  $block // "Hello World!" will be print

Есть возможность задать переиспользуемые части с помощью конструкции #macro:

#macro( cell ) <tr><td></td></tr> #end

Заданную в #macro конструкцию дальше в шаблоне можно вызвать так:

#cell // "<tr><td></td></tr>" will be print #cell // "<tr><td></td></tr>" will be print

В VLT-коде нам доступны функции из Java-мира. Особенно полезны функции работы со строками, например:

$NAME.replaceAll("([a-z])([A-Z])", "$1_$2").toLowerCase() // replaces "SomeString" camel-case string to "some_string" snake-case string

Указанных конструкций в большинстве случаев должно хватить при написании шаблонов. Больше информации можно найти в документации по ссылкам: User Guide, VLT Reference, Glossary.

Итоги первой части

В этой части мы выделили проблему с необходимостью написания шаблонного кода и рассмотрели возможные варианты уменьшения боли. А еще познакомились со встроенным инструментом File Templates и основным синтаксисом.

В следующей статье рассмотрим примеры использования File Templates для решения типовых сценариев, где требуется шаблонный код. Не переключайтесь 🙂