Юрий Артамонов — IntelliJ IDEA — учим IDE понимать API правильно

Какой разработчик не любит писать свои фреймворки? Берем модную технологию, сдабриваем соглашениями и добавляем щепотку аннотаций. А где потом взять подходящий инструмент? В этом докладе мы напишем плагин к IntelliJ IDEA для Java-фреймворка, чтобы IDE смогла понять его API и помогла вам работать продуктивнее. Будем приближать технологическую сингулярность, совершенствуя свой инструмент самостоятельно.

Доклад будет полезен всем, кто создает библиотеки и фреймворки для Java и хочет получить максимум возможностей от своей IDE.

Transcript

1. IntelliJ IDEA — учим IDE понимать API правильно Юрий Артамонов
2. Автор ты кто Юрий Артамонов @jreznot ▪ Разрабатывал фреймворки и библиотеки для Java на протяжении 9 лет ▪ Грустил от их несовершенной поддержки в IDE ▪ Недавно пришёл в команду IntelliJ IDEA 2
3. План действий 1. Система плагинов IntelliJ IDEA 2. Моделируем Java фреймворк 3. Пишем к нему полезный плагин 4. Когда это делать не нужно? 5. Куда копать дальше? 3
4. Мотивация ▪ У всех есть свои наработки: in-house фреймворки, библиотеки, конфиги, процессы и соглашения ▪ Рутинная работа, связанная с исходным кодом, проектом, тестами, развёртыванием 4
5. Как бороться с рутиной ▪ Делать больше фреймворков! ▪ Генерировать больше кода! ▪ Улучшать свой основной инструмент - IDE 5
6. Делимся опытом! 6
7. Возможности плагинов ★ Языки и форматы файлов ★ Статический анализ кода на лету ★ Навигация по коду ★ Улучшения редактора ★ Рефакторинг и генерация кода ★ Взаимодействие с инструментами и сервисами ★ Миграция старого кода на новый API 7
8. Ключевые внутренности IDE ▪ Компоненты и сервисы ▪ Виртуальная файловая система (VFS) ▪ Поддержка языков (PSI) ▪ Редактор кода ▪ Инспекции ▪ Индексы ▪ Фоновые процессы ▪ UI библиотека ▪ Точки расширения IntelliJ Platform IDEA CE (Java, Groovy, Kotlin) PHP Support Ruby Support IDEA Ultimate PHP Storm RubyMine 8
9. Система плагинов Все JetBrains IDE состоят из плагинов: 1. Классы плагина загружаются отдельным загрузчиком классов 2. Каждый плагин реализует точки расширения IDE и может объявлять свои 3. Плагины могут зависеть от модулей IDE и от других плагинов 9 Groovy Plugin Java Plugin Properties Plugin Ultimate Modules optional
10. Как начать 10 1. Проверить/включить Plugin DevKit 2. Создать Gradle проект с библиотекой IntelliJ Platform Plugin 3. Объявить и реализовать нужные точки расширения Рекомендуем Kotlin!
11. Структура плагина .../resources/META-INF/plugin.xml <idea-plugin> <id>micronaut-intellij-plugin</id> <name>Micronaut Framework Support</name> <description><![CDATA[ Provides support for Micronaut Framework for JVM languages ]]></description> <depends>com.intellij.modules.java</depends> <extensions defaultExtensionNs="com.intellij"> <!-- Add your extensions here → </extensions> <actions> <!-- Add your actions here → </actions> </idea-plugin> 11 Метаданные Исходный код Файл сборки
12. Точки расширения ▪ Огромное множество: action, inspection, intention action, reference contributor, ui settings group, language parser, language formatter и т.д. ▪ Регистрируются в XML-файле – дескрипторе плагина plugin.xml ▪ Полный список: LangExtensionPoints.xml, PlatformExtensionPoints.xml, VcsExtensionPoints.xml, etc. Пример: поддержка Groovy – плагин ( plugin.xml > 1300 строк ) github.com/JetBrains/intellij-community 12
13. Micronaut - вид сбоку Фреймворк для построения легковесных модульных приложений на JVM (Java / Kotlin / Groovy) Возможности: ▪ Dependency Injection ▪ HTTP Web Services (Sync/Async) ▪ HTTP Client ▪ Data Repositories ▪ Compile-time everywhere ▪ AOT Compatible 13
14. Что посмотреть 1. Graeme Rocher - Introduction to Micronaut 2. Кирилл Толкачёв, Максим Гореликов - Micronaut vs Spring Boot, или Кто тут самый маленький? 14
15. Что тут в вашем фреймворке поддерживать? 15
16. Наносим непоправимую пользу Проблема: 1. Создали проект 2. Запустили 3. Profit Ничего не происходит! Документация: If you are using Java or Kotlin and IntelliJ IDEA make sure you have enabled annotation processing. 16 Проверим, что в Micronaut проектах включены Annotations Processors!
17. Internal Mode Специальный режим работы IDE, в котором доступны опции для разработчиков. ▪ Internal Actions ▪ View PSI / Dump UAST ▪ Dumb Mode Switch ▪ … Включить в VM Options: -Didea.is.internal=true 17
18. Находим нужную точку расширения 1. Реализуем интерфейс com.intellij.openapi.startup.StartupActivity: <extensions defaultExtensionNs="com.intellij"> <postStartupActivity implementation="demo.CheckAnnotationProcessorsStartupActivity"/> 2. Используем UI Inspector (Ctrl+Alt+Click): 18
19. Implicit Usages Проблема: фреймворки нынче умные и любят неявности. @Controller class WelcomeController { @View("welcome") @Get("/") public HttpResponse<?> welcome() { return HttpResponse.ok(); } } Class ‘WelcomeController’ is never used. 19 Давайте научим IDE понимать неявности правильно!
20. Implicit Usage Provider Регистрируем новую точку расширения: <implicitUsageProvider implementation="demo.MicronautImplicitUsageProvider"/> class MicronautImplicitUsageProvider : ImplicitUsageProvider { override fun isImplicitWrite(element: PsiElement?): Boolean { TODO() } override fun isImplicitRead(element: PsiElement?): Boolean { TODO() } override fun isImplicitUsage(element: PsiElement?): Boolean { TODO() } } 20
21. Основы работы с синтаксическими деревьями PSI - Program Structure Interface, специальное представление: ▪ Синтаксические структуры проекта и кода ▪ Включает данные о семантике ▪ Всё может быть представлено в виде PsiElement (ну почти) ▪ Каждый язык предоставляет свои PSI элементы 21 PsiFile PsiElement PsiElement PsiElement PsiElement PSI Tree
22. Java PSI модель Основные элементы: ▪ PsiJavaFile ▪ PsiImportList ▪ PsiClass ▪ PsiAnnotation ▪ PsiField ▪ PsiMethod ▪ ... См. Tools - View PSI Structure of Current File 22
23. Кто-то постоянно косячит в cron expressions Пример: @Singleton public class VisitProcessor { @Scheduled(cron = "0 55 11 * * * .") public void run() { // do work } } Что тут пошло не так? 23
24. Пишем инспекции Инспекции: ▪ Выполняют статический анализ кода на лету ▪ Обходят PSI дерево ▪ Могут предоставлять автоматические исправления См. LocalInspectionTool LocalQuickFix 24
25. Проверим @Scheduled cron expression Регистрируем класс инспекции: <localInspection language="JAVA" displayName="@Scheduled bean inspection" groupName="Micronaut" enabledByDefault="true" implementationClass="demo.MicronautScheduledInspection"/> Определяем, что хотим проверять: class MicronautScheduledInspection : AbstractBaseJavaLocalInspectionTool() { override fun checkMethod(method: PsiMethod, manager: InspectionManager, isOnTheFly: Boolean) : Array<ProblemDescriptor>? { // check here return ProblemDescriptor.EMPTY_ARRAY } } 25
26. Поддерживаем зоопарк JVM-языков Universal Abstract Syntax Tree (UAST) ▪ Описывает JVM languages superset: Java, Kotlin и Groovy ▪ Элементы ◦ UElement, UFile, UClass, UMember, UField, UMethod, ... ▪ Конструкции ◦ UComment, UDeclaration, UExpression, UBlockExpression, UCallExpression, USwitchExpression, … ▪ Если не хватает возможностей - спускаемся на уровень PSI (resolve) ▪ Не поддерживается кодогенерация (используем PSI) См. org.jetbrains.uast 26
27. UAST инспекции 1. Изменить language на UAST в plugin.xml <localInspection language="UAST" displayName="@Inject field inspection" groupName="Micronaut" implementationClass="demo.MicronautFieldInjectionInspection"/> 2. Получить UElement 3. Найти проблему в UAST дереве (или в синтетическом PSI) 4. Получить sourcePsi 5. Зарегистрировать проблему для элемента из sourcePsi См. Tools - Internal Actions - Dump UAST Tree Примеры: intellij-community/plugins/devkit/ и Android Studio 27
28. Реализуем свою навигацию Publish/Subcribe с @EventListener: ▪ События это сложно ▪ Разработчики воют ▪ IDE не хочет нам помогать Идея: Иконки в gutter для навигации к publishers / subsribers! См. LineMarkerProvider RelatedItemLineMarkerProvider 28
29. Базовые индексы ▪ Индекс слов ◦ Ключ – хешкод слова ◦ Значение – битовая маска места вхождения (в коде, в комментарии, в строке) ◦ Используется в Find in Path, Find Usages ▪ Индексы имён и типов файлов ▪ Индекс имён Java-классов См. PsiSearchHelper 29
30. Как что-то нужное найти Модуль java-indexing-api предоставляет методы поиска по стандартным индексам: ▪ ReferencesSearch ▪ MethodReferenceSearch ▪ AnnotatedElementsSearch ▪ … Query<PsiReference> MethodReferencesSearch.search(psiMethod, scope, strict) Query<PsiReference> AnnotatedElementsSearch.searchPsiMethods(annotationClass, scope) 30
31. Кэширование во спасение Искать это долго! Давайте кэшировать! 31 val cacheManager = CachedValuesManager.getManager(module.project) return cacheManager.getCachedValue(module) { val result = heavyFunction(module) CachedValueProvider.Result.create( result , PsiModificationTracker.MODIFICATION_COUNT, // << track code changes everywhere ProjectRootManager.getInstance(module.project) // and in project structure ) } См. CachedValuesManager
32. Ссылки в PSI дереве ▪ Позволяют установить связь между PsiElement и его использованиями: usage ➜ declaration ▪ Могут предоставлять варианты для авто дополнения ▪ Можно добавить cсылки без необходимости расширять язык! См. PsiReferenceContributor PsiLanguageInjectionHost 32
33. Расставляем ссылки В Micronaut любые аннотации могут содержать подстановки свойств из application.properties в виде ${some.property-name}: @Value("${datasources.default.url}") private String datasourceUrl; Идея: давайте свяжем такие строки со свойствами из конфига! 33
34. А что делать дальше? 34
35. Правильная поддержка фреймворка Основные возможности IDE для поддержки в плагине: ▪ Implicit Usages ▪ References ▪ Inspections and Quick Fixes ▪ Intention Actions ▪ Line Markers ▪ Language Injection ▪ New Project Wizard ▪ File Templates 35
36. Кода бывает нужно много Spring Framework Support в цифрах: ▪ 260k LOC Java ▪ 20k LOC Kotlin ▪ 350k LOC Total ▪ 3400 Tests 36
37. Распространяем плагин в компании Достаточные условия: ▪ HTTP сервер (например Nginx) ▪ Файл updatePlugins.xml <plugins> <!-- Each <plugin> element describes one plugin in the repository. → <plugin id="fully.qualified.id.of.this.plugin" url="https://www.mycompany.com/my_repository/mypluginname.jar" version="major.minor.update"> <idea-version since-build="181.3" until-build="191.*" /> </plugin> <plugin> <!-- And so on for other plugins... → </plugin> </plugins> См. Publishing a Plugin to a Custom Plugin Repository 37
38. Как можно обойтись без плагина Если можно не писать плагин - не надо писать плагин! А вместо этого: ▪ Suppress unused for class annotated with … ▪ Настроить инспекции и плагины ▪ Закоммитить директорию .idea в VCS ▪ Настроить Language Injection ▪ Использовать JetBrains annotations (nullity, contract, pure, language) dependencies { compileOnly 'org.jetbrains:annotations:17.0.0' } 38
39. Структурный поиск для инспекций Проверяем код без плагина: ▪ Включить Inspections - Structured Search Inspection ▪ Настроить шаблоны поиска и замены Пример: @Inject $Field$ 39
40. Куда копать дальше ▪ Исходный код IntelliJ IDEA CE: github.com/JetBrains/intellij-community ▪ Документация Plugin DevKit: jetbrains.org/intellij/sdk/docs/basics.html ▪ Forum: IntelliJ IDEA Open API and Plugin Development ▪ Slack: jetbrains-platform NEW! https://plugins.jetbrains.com/slack 40
41. Анонсы ▪ Скоро: установка плагинов без перезапуска ▪ Великое удаление deprecated API и иконок в IntelliJ IDEA 2020.1 ▪ Пользователи будут получать уведомления об использовании deprecated API в плагине при его установке 41
42. Вопросы ? Исходный код: github.com/jreznot/micronaut-intellij-plugin Twitter: @Yuriy_Artamonov
43. Фреймворки и микросевисы! Новые возможности IntelliJ IDEA 2019.3 1. Microservice Frameworks: Micronaut, Quarkus, Helidon 2. OpenAPI Support 3. Endpoints View 4. URL Completion 5. Injectable URL References 43