Продолжаем предыдущую статью — так что без долгих предисловий идём к примерам.
Авто-dispose
Зачем?
Удобнее «повесить» аннотацию на поле, которое нужно «выключить» при удалении объекта, чем делать это вручную и спускаться в метод dispose.
Как это должно выглядеть?
Определим сущности, к которым хотим применить макрос — это сущности, у которых есть:
-
метод
dispose; -
метод
close(например,StreamController); -
метод
cancel(например,StreamSubscription). -
альтернативный метод «выключения».
Что будет, если мы применим макрос к полю, у которого нет метода dispose/close/cancel? Ничего критичного, просто анализатор сообщит нам, что, сюрприз, метода dispose у поля нет.
@AutoDispose() class SomeModel { @disposable final ValueNotifier<int> a; @closable final StreamController<int> b; @cancelable final StreamSubscription<int> c; @Disposable('customDispose') final CustomDep d; SomeModel({required this.a, required this.b, required this.c, required this.d}); } class CustomDep { void customDispose() {} }augment library 'package:test_macros/3.%20auto_dispose/example.dart'; augment class SomeModel { void dispose() { a.dispose(); b.close(); c.cancel(); d.customDispose(); } }Как это реализовать?
Для начала самое простое — создадим аннотации disposable, cancelable, closable и Disposable:
const disposeMethod = 'dispose'; const closeMethod = 'close'; const cancelMethod = 'cancel'; const disposableAnnotationName = 'disposable'; const closableAnnotationName = 'closable'; const cancelableAnnotationName = 'cancelable'; const customDisposableAnnotationName = 'Disposable'; const customDisposableFieldName = 'disposeMethodName'; const disposable = Disposable(disposeMethod); const closable = Disposable(closeMethod); const cancelable = Disposable(cancelMethod); class Disposable { final String disposeMethodName; const Disposable(this.disposeMethodName); }Пора создавать макрос. Как и в предыдущих случаях, выберем фазу макроса:
-
фаза типов нам не подходит — мы не собираемся создавать новые типы;
-
фаза объявления позволяет нам добавлять код внутри класса — мы этого и хотим;
-
фаза определения словно бы нам не нужна, потому что всё необходимое мы можем сделать в фазе объявления.
import 'dart:async'; import 'package:macros/macros.dart'; macro class AutoDispose implements ClassDeclarationsMacro { const AutoDispose(); @override FutureOr<void> buildDeclarationsForClass(ClassDeclaration clazz, MemberDeclarationBuilder builder) async { final fields = await builder.fieldsOf(clazz); } }Соберём словарь, где ключом будет имя поля, а значением — имя метода, который надо вызвать:
final fields = await builder.fieldsOf(clazz); /// Ключ - имя поля, значение - имя метода для вызова. final disposables = <String, Object>{}; for (final field in fields) { Object? methodName; final annotations = field.metadata; /// Ищем аннотацию Disposable с кастомным именем метода. final customDispose = annotations.whereType<ConstructorMetadataAnnotation>().firstWhereOrNull( (element) => element.type.identifier.name == customDisposableAnnotationName, ); if (customDispose != null) { methodName = customDispose.namedArguments[customDisposableFieldName]; } else { /// Если аннотация не найдена, ищем стандартные аннотации. /// /// - отсеиваем константные аннотации; /// - ищем аннотации, которые содержат нужные нам идентификаторы. /// - сопоставляем идентификаторы с методами. methodName = switch ((annotations.whereType<IdentifierMetadataAnnotation>().firstWhereOrNull( (element) => [ disposableAnnotationName, closableAnnotationName, cancelableAnnotationName, ].contains(element.identifier.name), ))?.identifier.name) { disposableAnnotationName => disposeMethod, closableAnnotationName => closeMethod, cancelableAnnotationName => cancelMethod, _ => null, }; } if (methodName != null) { disposables[field.identifier.name] = methodName; } }Дело за малым — собираем код метода dispose и добавляем его в класс:
final code = <Object>[ '\tvoid dispose() {\n', ...disposables.entries.map((e) { return ['\t\t${e.key}.', e.value, '();\n']; }).expand((e) => e), '\t}\n', ]; builder.declareInType(DeclarationCode.fromParts(code));Казалось бы, победа! Но вот мы смотрим на сгенерированный код и видим такую картину:
augment library 'package:test_macros/3.%20auto_dispose/example.dart'; augment class SomeModel { void dispose() { a.dispose(); b.close(); c.cancel(); d.'customDispose'(); } }Снова нож в спину от ExpressionCode. Мы можем получить только код выражения, но не его значение. А поскольку код выражения содержит значение строки (с кавычками), то мы не можем использовать его в качестве имени метода.
Ищем обходные пути. Мы могли бы дать возможность пользователям реализовывать собственные аннотации. Но тогда макрос должен знать названия новых аннотаций — чтобы он принимал их во внимание во время генерации метода dispose. Кроме того, он должен знать и названия методов, которые нужно вызвать.
Так, единственный вариант, который мы придумали — передавать в макрос словарь, где ключ это название аннотации, а значение — название метода:
@AutoDispose( disposeMethodNames: { 'customDepDispose': 'customDispose', }, ) class SomeModel { @disposable final ValueNotifier<int> a; @closable final StreamController<int> b; @cancelable final StreamSubscription<int> c; @customDepDispose final CustomDep d; SomeModel({required this.a, required this.b, required this.c, required this.d}); } const customDepDispose = Disposable('customDispose'); class CustomDep { void customDispose() {} }Выглядит ужасно, да. Но ничего лучше не пришло нам в головы.
Внесём изменения в макрос — сначала соберём словарь всех возможных аннотаций и методов:
macro class AutoDispose implements ClassDeclarationsMacro { final Map<String, String> disposeMethodNames; const AutoDispose({ this.disposeMethodNames = const {}, }); @override FutureOr<void> buildDeclarationsForClass(ClassDeclaration clazz, MemberDeclarationBuilder builder) async { final allMethodNames = { disposableAnnotationName: disposeMethod, closableAnnotationName: closeMethod, cancelableAnnotationName: cancelMethod, ...disposeMethodNames, }; ... } }Поиск кастомного метода нам больше не нужен, как и switch — теперь это будет поиск по ключу в словаре:
for (final field in fields) { Object? methodName; final annotations = field.metadata; final annotationName = ((annotations.whereType<IdentifierMetadataAnnotation>().firstWhereOrNull( (element) => allMethodNames.keys.contains(element.identifier.name), ))?.identifier.name); methodName = allMethodNames[annotationName]; if (methodName != null) { disposables[field.identifier.name] = methodName; } }Остальной код остаётся без изменений. Проверяем сгенерированный код и, наконец-то, видим заветное:
augment library 'package:test_macros/3.%20auto_dispose/example.dart'; augment class SomeModel { void dispose() { a.dispose(); b.close(); c.cancel(); d.customDispose(); } }Пробуем запустить проект и в очередной раз получаем нож в спину:
Error: This macro application didn't apply correctly due to an unhandled map entry.Несмотря на то, что наш входной параметр отвечает требованиям спецификации (это словарь с примитивными типами данных), макрос не может его обработать. Можем передавать параметры в виде строки (например, ‘customDepDispose: customDispose’), но это неудобно и нечитаемо.
Помимо этого, у нашего примера есть ещё одна проблема — он не поддерживает вызов метода базового (не augment) класса. По официальным примерам можно вызывать метод augmented() внутри augment-метода, однако на практике мы получаем ошибку — будто бы такого метода не существует.
Результат
Мы получили макрос, который будет работать с предустановленными сущностями. Однако для работы с кастомными нужна дополнительная настройка, которая из-за текущих ограничений макросов может быть огранизована только через костыли. Но мы вернули веру в пользу аннотаций после их провала в первом эксперименте.
DI контейнер
Зачем?
Типичный DI-контейнер в условиях Flutter-приложения выглядит так:
class AppScope implements IAppScope { late final SomeDep _someDep; late final AnotherDep _anotherDep; late final ThirdDep _thirdDep; ISomeDep get someDep => _someDep; IAnotherDep get anotherDep => _anotherDep; IThirdDep get thirdDep => _thirdDep; AppScope(String someId) { _someDep = SomeDep(someId); } Future<void> init() async { _anotherDep = await AnotherDep.create(); _thirdDep = ThirdDep(_someDep); } } abstract interface class IAppScope { ISomeDep get someDep; IAnotherDep get anotherDep; IThirdDep get thirdDep; }Было бы здорово вместо этого получить контейнер, который:
-
позволяет указывать зависимости прямо в инициализаторе;
-
поддерживает асинхронную инициализацию;
-
защищён от циклических зависимостей;
-
выглядит лаконично.
Как это должно выглядеть?
Примерно так:
@DiContainer() class AppScope { late final Registry<SomeDependency> _someDependency = Registry(() { return SomeDependency(); }); late final Registry<AnotherDependency> _anotherDependency = Registry(() { return AnotherDependency(someDependency); }); late final Registry<ThirdDependency> _thirdDependency = Registry(() { return ThirdDependency(someDependency, anotherDependency); }); }augment class AppScope { late final ISomeDependency someDependency; late final IAnotherDependency anotherDependency; late final IThirdDependency thirdDependency; Future<void> init() async { someDependency = await _someDependency(); anotherDependency = await _anotherDependency(); thirdDependency = await _thirdDependency(); } }Как это реализовать?
Разобьём задачу на подзадачи:
-
выбор фазы и создание аннотации;
-
создание класса
Registry; -
создание метода
init; -
построение порядка инициализации;
-
создание
late finalполей.
Выбор фазы и создание аннотации
Выберем фазу объявления — нам нужно добавить код внутри класса. Создадим аннотацию DiContainer:
macro class DiContainer implements ClassDeclarationsMacro { const DiContainer(); @override FutureOr<void> buildDeclarationsForClass( ClassDeclaration clazz, MemberDeclarationBuilder builder, ) async {} }Создание класса Registry
Создадим класс Registry:
class Registry<T> { final FutureOr<T> Function() create; Registry(this.create); FutureOr<T> call() => create(); }Создание метода init
Тут всё просто — используем старый-добрый builder.declareInType:
@override FutureOr<void> buildDeclarationsForClass( ClassDeclaration clazz, MemberDeclarationBuilder builder, ) async { final initMethodParts = <Object>[ 'Future<void> init() async {\n', ]; initMethodParts.add('}'); builder.declareInType(DeclarationCode.fromParts(initMethodParts)); }Построение порядка инициализации
А здесь начинается самое интересное и сложное. Мы стремимся определить порядок инициализации полей. Для этого нам нужно:
-
собрать список зависимостей для каждого поля;
-
определить порядок инициализации таким образом, чтобы зависимости инициализировались раньше зависимых от них полей.
В первую очередь соберём словарь: ключом будет название поля с зависимостью, а значением — список параметров, которые требуются для её инициализации. Условно, для нашего примера словарь будет таким:
{ someDependency: [], anotherDependency: [someDependency], thirdDependency: [someDependency, anotherDependency], }Сделаем это:
final dependencyToConstructorParams = <String, List<String>>{}; for (final field in fields) { final type = field.type; if (type is! NamedTypeAnnotation) continue; /// Отсекаем все поля, которые не являются Registry. if (type.identifier.name != 'Registry') continue; final generic = type.typeArguments.firstOrNull; if (generic is! NamedTypeAnnotation) continue; final typeDeclaration = await builder.typeDeclarationOf(generic.identifier); if (typeDeclaration is! ClassDeclaration) continue; final fields = await builder.fieldsOf(typeDeclaration); final constructorParams = fields.where((e) => !e.hasInitializer).toList(); dependencyToConstructorParams[field.identifier.name.replaceFirst('_', '')] = constructorParams.map((e) => e.identifier.name.replaceFirst('_', '')).toList(); }Теперь определим порядок инициализации. Для этого используем топологическую сортировку. Граф у нас уже есть, осталось реализовать сам алгоритм:
List<T> _topologicalSort<T>( Map<T, List<T>> graph, MemberDeclarationBuilder builder, ) { /// Обработанные вершины. final visited = <T>{}; /// Вершины, в которых мы находимся на текущий момент. final current = <T>{}; /// Вершины, записанные в топологическом порядке. final result = <T>[]; /// Рекурсивная функция обхода графа. /// Возвращает [T], который образует цикл. Если цикла нет, возращает null. T? process(T node) { /// Если вершина уже обрабатывается, значит, мы нашли цикл. if (current.contains(node)) { return node; } /// Если вершина уже обработана, то пропускаем её. if (visited.contains(node)) { return null; } /// Добавляем вершину в текущие. current.add(node); /// Повторяем для всех соседей. for (final neighbor in graph[node] ?? []) { final result = process(neighbor); if (result != null) { return result; } } current.remove(node); visited.add(node); result.add(node); return null; } for (final node in graph.keys) { final cycleAffectingNode = process(node); /// Если обнаружен цикл, то выбрасываем исключение. if (cycleAffectingNode != null) { builder.report( Diagnostic( DiagnosticMessage( '''Cycle detected in the graph. ''' '''$cycleAffectingNode requires ${graph[cycleAffectingNode]?.join(', ')}''', ), Severity.error, ), ); throw Exception(); } } return result; }Теперь, когда у нас есть порядок вызовов, можем дособрать функцию init:
@override FutureOr<void> buildDeclarationsForClass( ClassDeclaration clazz, MemberDeclarationBuilder builder, ) async { ... final sorted = _topologicalSort( dependencyToConstructorParams, builder, ); for (final dep in sorted) { if (!dependencyToConstructorParams.keys.contains(dep)) continue; /// Получаем что-то вроде: /// ``` /// someDependency = await _someDependency(); /// ``` initMethodParts.addAll([ '\t\t$dep = await _$dep();\n', ]); } initMethodParts.add('}'); builder.declareInType(DeclarationCode.fromParts(initMethodParts)); }Создание late final полей
Наконец, создаём late final поля. К сожалению, Registry использует дженерик конкретного типа. Из-за этого напрямую нам недоступен интерфейс класса, за которым мы хотим скрыть реализацию. Поэтому мы берём первый из доступных интерфейсов (если он есть):
for (final field in fields) { ... dependencyToConstructorParams[field.identifier.name.replaceFirst('_', '')] = constructorParams.map((e) => e.identifier.name.replaceFirst('_', '')).toList(); ++ final superClass = typeDeclaration.interfaces.firstOrNull; ++ ++ builder.declareInType( ++ DeclarationCode.fromParts( ++ [ ++ 'late final ', ++ superClass?.code ?? generic.code, ++ ' ${field.identifier.name.replaceFirst('_', '')};', ++ ], ++ ), ++ ); ++ }Результат
Применим макрос к классу AppScope:
@DiContainer() class AppScope { late final Registry<SomeDependency> _someDependency = Registry(() { return SomeDependency(); }); late final Registry<AnotherDependency> _anotherDependency = Registry(() { return AnotherDependency(someDependency); }); late final Registry<ThirdDependency> _thirdDependency = Registry(() { return ThirdDependency(someDependency, anotherDependency); }); AppScope(); }и получим:
augment library 'package:test_macros/5.%20di_container/example.dart'; import 'package:test_macros/5.%20di_container/example.dart' as prefix0; import 'dart:core'; import 'dart:async'; augment class AppScope { late final prefix0.ISomeDependency someDependency; late final prefix0.IAnotherDependency anotherDependency; late final prefix0.IThirdDependency thirdDependency; Future<void> init() async { someDependency = await _someDependency(); anotherDependency = await _anotherDependency(); thirdDependency = await _thirdDependency(); } }Попробуем добавить IAnotherDependency как параметр для зависимости SomeDependency:
@DiContainer() class AppScope { late final Registry<SomeDependency> _someDependency = Registry(() { return SomeDependency(anotherDependency); }); ... }И получим ошибку:
Результат
В этой реализации много «тонких» мест. Например, мы завязаны на том, что пользователь должен задавать инициализаторы строго приватными. А ещё мы не можем задавать имена публичных полей (даже с использованием аннотаций, так как переданные в них параметры будут доступны нам только как ExpressionCode).
Не можем и в явном виде указывать интерфейс, под которым хотели бы видеть публичное поле. В теории, конечно, можно добавить второй дженерик к Registry, но это лишит нас лаконичности.
Несмотря на всё это, мы получили работающий прототип DI-контейнера, который можно дорабатывать и улучшать.
Retrofit на макросах
Зачем?
Классическая версия retrofit для Dart работает с помощью build_runner. Похоже на потенциальную цель, чтобы перенести её на макросы.
Как это должно выглядеть?
@RestClient() class Client { Client( this.dio, { this.baseUrl, }); @GET('/posts/{id}') external Future<UserInfoDto> getUserInfo(int id); @GET('/convert') external Future<SomeEntity> convert(@Query() String from, @Query() String to); }augment class Client { final Dio dio; final String? baseUrl; augment Future<PostEntity> getUserInfo(int id) async { final queryParameters = <String, dynamic>{}; final _result = await dio.fetch<Map<String, dynamic>>(Options( method: 'GET', ) .compose( dio.options, "/posts/${id}", queryParameters: queryParameters, ) .copyWith(baseUrl: baseUrl ?? dio.options.baseUrl)); final value = PostEntity.fromJson(_result.data!); return value; } augment Future<PostEntity> convert(String from, String to) async { final queryParameters = <String, dynamic>{ 'from': from, 'to': to, }; final _result = await dio.fetch<Map<String, dynamic>>(Options( method: 'GET', ) .compose( dio.options, "/convert", queryParameters: queryParameters, ) .copyWith(baseUrl: baseUrl ?? dio.options.baseUrl)); final value = PostEntity.fromJson(_result.data!); return value; } }Пока мы ограничимся GET-запросами, query- и path-параметрами.
Как это реализовать?
По классике — начнём с создания аннотаций:
const query = Query(); class Query { const Query(); }Тут будет два макроса:
-
RestClientдля класса; -
GETдля методов.
Наиболее подходящая фаза макроса для клиента — фаза объявления: нам нужно добавить два поля в класс.
Создадим макрос и запишем название полей класса в константы:
import 'dart:async'; import 'package:macros/macros.dart'; const baseUrlVarSignature = 'baseUrl'; const dioVarSignature = 'dio'; macro class RestClient implements ClassDeclarationsMacro { @override FutureOr<void> buildDeclarationsForClass(ClassDeclaration clazz, MemberDeclarationBuilder builder) async { /// Добавим импорт Dio. builder.declareInLibrary(DeclarationCode.fromString('import \'package:dio/dio.dart\';')); } }Получим список полей, убедимся, что поля, которые мы собираемся создать, отсутствуют, и, если так, создадим их:
final fields = await builder.fieldsOf(clazz); builder.declareInLibrary(DeclarationCode.fromString('import \'package:dio/dio.dart\';')); /// Проверяем, имеет ли класс поле baseUrl. final indexOfBaseUrl = fields.indexWhere((element) => element.identifier.name == baseUrlVarSignature); if (indexOfBaseUrl == -1) { final stringType = await builder.resolveIdentifier(Uri.parse('dart:core'), 'String'); builder.declareInType(DeclarationCode.fromParts(['\tfinal ', stringType, '? $baseUrlVarSignature;'])); } else { builder.report( Diagnostic( DiagnosticMessage('$baseUrlVarSignature is already defined.'), Severity.error, ), ); return; } final indexOfDio = fields.indexWhere((element) => element.identifier.name == dioVarSignature); if (indexOfDio == -1) { builder.declareInType(DeclarationCode.fromString('\tfinal Dio $dioVarSignature;')); } else { builder.report( Diagnostic( DiagnosticMessage('$dioVarSignature is already defined.'), Severity.error, ), ); return; }Теперь займёмся методом. Для макроса GET берём фазу определения — нам нужно написать реализацию уже объявленного метода. Также добавляем фазу объявления, чтобы добавить импорты. Они упростят нам жизнь и избавят от необходимости импортировать кучу типов вручную.
macro class GET implements MethodDeclarationsMacro, MethodDefinitionMacro { final String path; const GET(this.path); @override FutureOr<void> buildDeclarationsForMethod(MethodDeclaration method, MemberDeclarationBuilder builder) async { builder.declareInLibrary(DeclarationCode.fromString('import \'dart:core\';')); } @override FutureOr<void> buildDefinitionForMethod(MethodDeclaration method, FunctionDefinitionBuilder builder) async { } }Перед нами стоит несколько задач:
-
определить возвращаемый тип значения, чтобы реализовать парсинг;
-
собрать query-параметры;
-
подставить параметры в path, если они есть;
-
собрать это всё.
Нам нужно определить возвращаемый тип. Предполагается, что мы применим к нему метод fromJson, чтобы спарсить ответ сервера. Стоит учесть кейсы, когда мы пытаемся получить коллекцию (List) или не получаем никакого значения (void). Заведём enum для типов возвращаемых значений:
/// Общий тип, который возвращает метод: /// - коллекция /// - одно значение /// - ничего enum ReturnType { collection, single, none }Теперь можно определять возвращаемый тип (то есть, достать дженерик из Future либо Future<List>):
@override FutureOr<void> buildDefinitionForMethod(MethodDeclaration method, FunctionDefinitionBuilder builder) async { /// Здесь у нас будет что-то вроде `Future<UserInfoDto>`. var type = method.returnType; /// Сюда запишем тип возвращаемого значения. NamedTypeAnnotation? valueType; late ReturnType returnType; /// На случай, если тип возвращаемого значения опущен при объявлении метода, попробуем его получить. if (type is OmittedTypeAnnotation) { type = await builder.inferType(type); } if (type is NamedTypeAnnotation) { /// Проверяем, что тип возвращаемого значения - Future. if (type.identifier.name != 'Future') { builder.report( Diagnostic( DiagnosticMessage('The return type of the method must be a Future.'), Severity.error, ), ); return; } /// Получаем джинерик типа. У Future он всегда один. final argType = type.typeArguments.firstOrNull; valueType = argType is NamedTypeAnnotation ? argType : null; switch (valueType?.identifier.name) { case 'List': returnType = ReturnType.collection; valueType = valueType?.typeArguments.firstOrNull as NamedTypeAnnotation?; case 'void': returnType = ReturnType.none; default: returnType = ReturnType.single; } } else { builder.report( Diagnostic( DiagnosticMessage('Cannot determine the return type of the method.'), Severity.error, ), ); return; } if (valueType == null) { builder.report( Diagnostic( DiagnosticMessage('Cannot determine the return type of the method.'), Severity.error, ), ); return; } }Теперь соберём query-параметры в словарь вида:
final _queryParameters = <String, dynamic>{ 'from': from, 'to': to, };Для этого соберём все поля (именованные и позиционные) и возьмём те, у которых есть аннотация @query:
/// Сюда будем собирать код для создания query параметров. final queryParamsCreationCode = <Object>[]; final fields = [ ...method.positionalParameters, ...method.namedParameters, ]; /// Собираем query параметры. final queryParams = fields.where((e) => e.metadata.any((e) => e is IdentifierMetadataAnnotation && e.identifier.name == 'query')).toList();Добавим к числу наших констант название переменной для query-параметров:
const baseUrlVarSignature = 'baseUrl'; const dioVarSignature = 'dio'; ++ const queryVarSignature = '_queryParameters';Теперь, если у нас есть query-параметры, добавим их в словарь:
queryParamsCreationCode.addAll([ '\t\tfinal $queryVarSignature = <String, dynamic>{\n', ...queryParams.map((e) => "\t\t\t'${e.name}': ${e.name},\n"), '\t\t};\n', ]);Займёмся путём запроса — подставим в него path-параметры.
Например, если у нас есть путь /posts/{id}, то мы должны получить строку '/posts/$id'.
пример, если у нас есть путь /posts/{id}, то мы должны получить строку '/posts/$id'. final substitutedPath = path.replaceAllMapped(RegExp(r'{(\w+)}'), (match) { final paramName = match.group(1); final param = fields.firstWhere((element) => element.identifier.name == paramName, orElse: () => throw ArgumentError('Parameter \'$paramName\' not found')); return '\${${param.identifier.name}}'; });Пришло время собрать запрос. Не забываем, что мы можем получить не только одиночное значение, но и коллекцию. Ну или ничего. Это важно учесть при использовании метода fetch и при парсинге ответа:
builder.augment(FunctionBodyCode.fromParts([ 'async {\n', ...queryParamsCreationCode, '\t\tfinal _result = await $dioVarSignature.fetch<', switch (returnType) { ReturnType.none => 'void', ReturnType.single => 'Map<String, dynamic>', ReturnType.collection => 'List<dynamic>', },'>(\n', '\t\t\tOptions(\n', '\t\t\t\tmethod: "GET",\n', '\t\t\t)\n', '\t\t.compose(\n', '\t\t\t$dioVarSignature.options,\n', '\t\t\t"$substitutedPath",\n', '\t\t\tqueryParameters: $queryVarSignature,\n', '\t\t)\n', '\t\t.copyWith(baseUrl: $baseUrlVarSignature ?? $dioVarSignature.options.baseUrl));\n', ...switch (returnType) { ReturnType.none => [''], ReturnType.single => ['\t\tfinal value = ', valueType.code, '.fromJson(_result.data!);\n'], ReturnType.collection => [ '\t\tfinal value = (_result.data as List).map((e) => ', valueType.code, '.fromJson(e)).toList();\n', ], }, if (returnType != ReturnType.none) '\t\treturn value;\n', '\t}', ]));Для проверки результата воспользуемся JSONPlaceholder — бесплатным API для тестирования HTTP-запросов.
// ignore_for_file: avoid_print @DisableDuplicateImportCheck() library example; import 'package:test_macros/5.%20retrofit/annotations.dart'; import 'package:test_macros/5.%20retrofit/client_macro.dart'; import 'package:dio/dio.dart'; @RestClient() class Client { Client(this.dio, {this.baseUrl}); @GET('/posts/{id}') external Future<PostEntity> getPostById(int id); @GET('/posts') external Future<List<PostEntity>> getPostsByUserId(@query int user_id); } class PostEntity { final int? userId; final int? id; final String? title; final String? body; PostEntity({ required this.userId, required this.id, required this.title, required this.body, }); factory PostEntity.fromJson(Map<String, dynamic> json) { return PostEntity( userId: json['userId'], id: json['id'], title: json['title'], body: json['body'], ); } Map<String, dynamic> toJson() { return { 'userId': userId, 'id': id, 'title': title, 'body': body, }; } } Future<void> main() async { final dio = Dio()..interceptors.add(LogInterceptor(logPrint: print)); final client = Client(dio, baseUrl: 'https://jsonplaceholder.typicode.com'); const idOfExistingPost = 1; final post = await client.getPostById(idOfExistingPost); final userId = post.userId; if (userId != null) { final posts = await client.getPostsByUserId(userId); print(posts); } }Запускаем и видим следующее:
Error: 'String' isn't a type. Error: 'int' isn't a type. Error: 'dynamic' isn't a type. ...Это ещё одна обнаруженная в ходе написания статьи проблема макросов. Из-за того, что в одном файле есть одинаковые импорты — с префиксом и без — проект не может запуститься:
import "dart:core"; import "dart:core" as prefix01;Так что нам придётся переписать почти весь код макроса, чтобы использовать только типы с префиксами.
Получать эти типы мы будем с помощью метода resolveIdentifier, который принимает uri-библиотеки и название типа, а также отмечен как deprecated ещё до релиза:
@override FutureOr<void> buildDefinitionForMethod(MethodDeclaration method, FunctionDefinitionBuilder builder) async { const stringTypeName = 'String'; const dynamicTypeName = 'dynamic'; const mapTypeName = 'Map'; const optionsTypeName = 'Options'; const listTypeName = 'List'; final stringType = await builder.resolveIdentifier(Uri.parse('dart:core'), stringTypeName); final dynamicType = await builder.resolveIdentifier(Uri.parse('dart:core'), dynamicTypeName); final mapType = await builder.resolveIdentifier(Uri.parse('dart:core'), mapTypeName); final optionsType = await builder.resolveIdentifier(Uri.parse('package:dio/src/options.dart'), optionsTypeName); final listType = await builder.resolveIdentifier(Uri.parse('dart:core'), listTypeName); /// Шорткат для `<String, dynamic>`. final stringDynamicMapType = ['<', stringType, ', ', dynamicType, '>']; ... }Теперь нам следует заменить все вхождения String, dynamic, Map, Options и List на полученные нами «разрешённые» типы:
queryParamsCreationCode.addAll([ -- '\t\tfinal $queryVarSignature = <String, dynamic>{\n', ++ '\t\tfinal $queryVarSignature = ', ...stringDynamicMapType, '{\n', ...queryParams.map((e) => "\t\t\t'${e.name}': ${e.name},\n"), '\t\t};\n', ]);И в таком духе продолжаем во всех остальных местах (_dio.fetch<Map<String, dynamic>>, Options и так далее).
Теперь любуемся на результат.
Результат
Применим макрос к классу Client:
@RestClient() class Client { Client(this.dio, {this.baseUrl}); @GET('/posts/{id}') external Future<UserInfoDto> getUserInfo(int id); @GET('/convert') external Future<SomeEntity> convert(@query String from, @query String to); } и получим следующий код: augment library 'package:test_macros/5.%20retrofit/example.dart'; import 'dart:async' as prefix0; import 'package:test_macros/5.%20retrofit/example.dart' as prefix1; import 'dart:core' as prefix2; import 'package:dio/src/options.dart' as prefix3; import 'package:dio/dio.dart'; import 'dart:core'; augment class Client { final String? baseUrl; final Dio dio; augment prefix0.Future<prefix1.PostEntity> getPostById(prefix2.int id, ) async { final _queryParameters = <prefix2.String, prefix2.dynamic>{ }; final _result = await dio.fetch<prefix2.Map<prefix2.String, prefix2.dynamic>>( prefix3.Options( method: "GET", ) .compose( dio.options, "/posts/${id}", queryParameters: _queryParameters, ) .copyWith(baseUrl: baseUrl ?? dio.options.baseUrl)); final value = prefix1.PostEntity.fromJson(_result.data!); return value; } augment prefix0.Future<prefix2.List<prefix1.PostEntity>> getPostsByUserId(prefix2.int user_id, ) async { final _queryParameters = <prefix2.String, prefix2.dynamic>{ 'user_id': user_id, }; final _result = await dio.fetch<prefix2.List<prefix2.dynamic>>( prefix3.Options( method: "GET", ) .compose( dio.options, "/posts", queryParameters: _queryParameters, ) .copyWith(baseUrl: baseUrl ?? dio.options.baseUrl)); final value = (_result.data as prefix2.List).map((e) => prefix1.PostEntity.fromJson(e)).toList(); return value; } }На самом деле, это вершина айсберга — с полной версией так называемого macrofit можно познакомиться на pub.dev. Этот пакет находится в стадии разработки, но с его помощью можно делать GET, POST, PUT и DELETE запросы и работать с query-, path- и part-параметрами, задавать заголовки и тело запроса. Однако работать это начнёт только после того, как будет исправлена эта проблема.
Что же касается нашего маленького примера — макросы идеально подходят для таких задач, как генерация сетевых запросов. А уж если объединить это с @JsonCodable и @DataClass, то мы получаем полностью автоматизированный процесс создания сетевых запросов. И всё, что от нас требуется, — это написать каркас класса и добавить аннотации.
Выводы
Несмотря на все возможности, макросы не позволяют генерировать код столь же свободно, как это позволяет code_builder. У них есть ограничения, некоторые из которых мы обсудили в этой статье.
Но даже с учётом этого, макросы — это гигантский шаг вперёд для Dart. Их появление коренным образом изменит подход к написанию кода и позволит автоматизировать многие рутинные задачи. При этом они таят в себе опасность — код, обильно сдобренный макросами, будет сложно читать. А возможность сайд-эффектов, причина которых будет неочевидна, существенно возрастёт. Но если использовать этот инструмент с умом, его польза значительно превысит возможные недостатки.
При этом у нас сформировалось стойкое ощущение, что макросы ещё слишком сыры и нестабильны для релиза в начале 2025 года. Хочется верить, что мы ошибаемся.
Все примеры из первой и второй частей этой статьи вы найдёте в репозитории.
Больше полезного про Flutter — в Telegram-канале Surf Flutter Team.
Кейсы, лучшие практики, новости и вакансии в команду Flutter Surf в одном месте. Присоединяйтесь!
ссылка на оригинал статьи https://habr.com/ru/articles/844640/
Добавить комментарий