Почти не засеянное поле как пишется

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

Мы собрали простые (и гениальные) приемы семи культовых писателей — они помогут перенастроиться и начать писать лучше уже сейчас. 

Харуки Мураками

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

1. Старайся никого не обидеть. Пиши так, чтобы не оскорбить чувств читателей. Эмпатия в тексте работает лучше, чем обвинения или осуждение. «Что бы ты ни написал, есть вероятность, что кто-то получит травму или расстроится. Поэтому я изо всех сил стараюсь написать то, что никому не повредит», — говорит Мураками.

2. Отправь читателя в путешествие. Рассказ должен увлекать читателя так, чтобы тот мог полностью в него погрузиться. Добавь в свой текст деталей, которые помогут ощутить себя в месте, где разворачивается действие. 

Этот прием использовали в ролике Mitsubishi All New L200 Triton Sport 2017: там автомобиль проносится через средневековое поле боя. Картинка увлекает так, что кажется не рекламой, а скорее трейлером к захватывающему фильму:

3. Пиши, чтобы порадовать и утешить. Читатель запоминает не текст, а эмоции, которые пережил. Радостные хочется вспоминать чаще, тревожные — быстрее забыть, поэтому в своих книгах Мураками играет на поле светлых и сентиментальных чувств.

Задача рекламы — вызвать эмоцию. Именно на этом Coca-Cola выстраивает нарратив в ролике The Great Meal. Он стал частью первой кампании бренда с начала пандемии. История показывает семьи, которые хоть и застряли вместе в период локдауна, но все равно могут найти что-то хорошее в изоляции: они готовят любимые блюда:

Стивен Кинг

Кинг — мастер держать читателя в напряжении и очень продуктивный писатель: он опубликовал уже 60 романов, его произведения экранизировали более 100 раз. В своей работе он руководствуется такими принципами: 

1. Будь готов к критике. Когда Кинг начинал свою карьеру, на стене в его комнате был вбит гвоздь, на который он крепил письма с отказами от издательств. Чем популярнее становились его книги — тем больше негативных отзывов он слышал.

Если ты пишешь — будь готов к тому, что твою работу будут обсуждать. Часто в гораздо более жестком ключе, чем она того заслуживает.

Такой масштабной критике подверглась кампания Nike — Dream Crazy. В ролике снялся футболист Колин Каперник, который во время исполнения национального гимна встал на одно колено (а не остался стоять, как другие) в знак протеста против расовой дискриминации в США. Реклама привела к скандалу, из-за которого многие начали сжигать кроссовки Nike, — но настоящие фанаты бренда, наоборот, поддержали его.

 2. Пиши в первую очередь для себя. Писать нужно только тогда, когда не можешь этого не делать. Это занятие должно драйвить и наполнять. Если ты пишешь через силу — это чувствуется в тексте. Как говорит Кинг: «Я пишу, потому что мне это нравится. И если ты можешь делать это потому, что тебе нравится, — то сможешь делать это вечно».  

3. Используй свой словарь. Писать нужно так, как говоришь — простым языком, живыми фразами. Например, вместо «меня это впечатлило» герой скажет «я просто обалдел». А подруга вместо «кажется, ты перестаралась» прокомментирует «чего ты вырядилась как на свадьбу?».

На живой разговорной речи агентство Banda построило рекламную кампанию попкорна Pumpidup со слоганом «Попкорн, який всюди норм». Например, в ролике вместо «встретиться» звучит «пересечься», а вместо «велосипед» — «велик»:

Чарльз Буковски

Журнал Time назвал Буковски «лауреатом американской дурной жизни». Он стал известным только к 46 годам, а до этого жил бедно, пил много и писал об этом честно.

Вот три совета от писателя-бунтаря:

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

2. Пиши честно. «У меня была дрянная жизнь, вот и все. Дерьмовая жизнь, о которой можно писать», — говорил Буковски. Он пережил буллинг в школе, нищету, одиночество и алкоголизм. В своих произведениях он рассказывал о том, что переживал. Ты не сможешь хорошо описать вещи, о которых не знаешь. Лучшие истории — те, в которых у тебя есть личный опыт.

3. Продолжай писать. Буковски писал рассказы, романы и стихи, работал за печатной машинкой почти каждый день. Он не редактировал свои произведения и советовал думать только о том, что напишешь завтра, а не о том, что уже написал.

Отказываться от редактуры мы не советуем (если ты не бунтарь), но зацикливаться и дорабатывать произведение из чистого перфекционизма — не нужно. 

Чак Паланик

Чак Паланик начал свою писательскую карьеру с журналистики. Оттуда же он вынес свой стиль: лаконичный, динамичный — минимум описаний, максимум действия. Вот три совета по писательству от автора «Бойцовского клуба»:

1. Дай читателю почувствовать себя умным. Если описываешь события в историческом контексте — напомни, что тогда происходило. Если сыплешь отсылками — расшифровывай их. Читателю должно быть понятно, что происходит в тексте, иначе после пары поисковых запросов он просто бросит твое произведение.

Пояснения должны дать человеку возможность подумать: «да-да, я когда-то об этом слышал» — и почувствовать себя умным.

2. Не называй эмоции — создавай ситуацию, которая их опишет. Описание эмоции не вызывает эмоций, поэтому наречия вроде «грустно», «весело» и «впечатляюще» вычеркивай из текста сразу.

Пример от Паланика: «Вместо того чтобы говорить, что один из твоих персонажей убит горем, расскажи о соленых каплях слез, которые он оставил на документах о разводе, когда заснул за своим столом».

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

Разворачивай картинку так, как ее видит герой. Так ты не только разнообразишь текст емкими сравнениями, но и раскроешь характер персонажа, от имени которого ведешь рассказ. Например, вместо «на улице стало холодно» напиши «она сжала ладони в кулаки и спрятала их в рукавах свитера».

Этот прием использовали HP в ролике 3D Scanning Made Easy, снятом от первого лица. В рекламе сканера объемных объектов не говорят о его технических характеристиках, а показывают процесс работы с гаджетом с точки зрения дизайнера:

 Эрнест Хемингуэй

«Краткий» — самое точное слово, чтобы описать стиль Хемингуэя. Такому емкому, драматичному и динамичному письму можно научиться. Вот три главных писательских совета от «старика Хэма»:

1. Пиши о том, что знаешь. Хемингуэй использовал реальных людей и события в качестве материала для своих рассказов. Он считал, что именно это заставляет его истории оживать: персонажи выходят объемными, а история — правдоподобной.

2. Короткие предложения. У Хемингуэя все работы написаны так, чтобы читать было легко. 

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

Метод коротких предложений хорошо использовать в роликах, где текст — это основной фокус, а картинка — только его иллюстрация, как в бренд-манифестах.  

Этот прием использует H&M в одном из своих роликов об «устойчивой» моде. Бренд перечисляет фэшн-стереотипы, чтобы сказать, что в моде нет правил, кроме одного — сдавать одежду на переработку.

3. Существительные и глаголы вместо прилагательных и наречий. Долгие описания и абстрактные характеристики захламляют текст, при этом не добавляя ему смысла. Чтобы нарратив был динамичным, избегай детальных и громоздких описаний.

Антон Чехов

Чехов написал более 300 произведений, стал мастером краткой формы и создал «метод ружья» — принцип, по которому все детали рассказа должны иметь значение. «Нельзя ставить на сцене заряженное ружье, если никто не имеет в виду выстрелить из него», — считал Чехов.

Вот три совета по писательству от автора, который стал одной из главных фигур в мастерстве драматургии:

1. Жалей своих персонажей. Чтобы вызывать эмпатию, читателю должно быть легко ассоциировать персонажей с собой. А узнать себя в идеальных людях довольно сложно. Оставь маленький скол на личности персонажа — покажи его слабости и не осуждай их в тексте, а оправдывай.

Это же важно и для создания рекламы. Например, ролик приложения для здоровья и фитнеса BetterMe поддерживает героиню и в хорошие, и в плохие дни. История построена на том, что девушка выходит замуж за саму себя, чтобы «принимать себя и в горе и в радости».

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

Этот подход выбрала общественная организация Donate Life. Она призывает подключиться к программе донорства органов в случае смерти через абсолютно неприятного персонажа:

3. Покажи, что в твоих смешных рассказах есть не только юмор. Пиши истории так, чтобы они были короткими и смешными — но если их чуть-чуть продлить, то откроется трагичность происходящего.  

Например, в рассказе Чехова «Разговор человека с собакой» пьяный персонаж ведет беседы с овчаркой, и это комично. В рассказе «Тоска» герой тоже говорит с животным — лошадью, но это уже драма: у старика-извозчика умер сын, и ему не с кем разделить свое горе.

Если «Разговору человека с собакой» добавить контекст или развитие событий — почему герой стал пить и что с ним случилось потом — история из смешной превратится в трагичную.

Генри Миллер

Автор «Тропика Рака» сформулировал свои профессиональные советы в 11 лаконичных заповедях писателя. Мы выбрали из них те три, которые помогают посмотреть на работу над текстами под другим углом.

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

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

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

3. Встречайся с людьми, ходи куда-нибудь, пей, если хочешь. Нельзя загнать себя в четыре стены, отключить интернет и ждать результата. Выгорание — спутник творческих людей, и «выжать» из себя хороший текст силой просто невозможно. Кроме того, писателю нужен материал. А его сложно найти в пределах рабочего места. 

Привет! Начну с главного — я лентяй. Я очень-очень ленивый разработчик. Мне приходится писать много кода — как для бэка, так и для фронта. И моя лень постоянно терзает меня, говоря: Ты мог бы не писать этот код, а ты пишешь… Так и живем.

Но что делать? Как можно избавиться от необходимости писать хотя бы часть кода?

Есть много подходов к решению этой проблемы. Давайте посмотрим на некоторые из них.

OpenAPI

Предположим, ваш backend — это набор REST-сервисов. Первое, с чего стоило бы начать — изучить документацию вашего бэка в надежде наткнуться на спецификацию OpenAPI. Идеальной будет ситуация, когда ваш бэк предоставляет максимально полную спеку, в которой будут описаны все методы, которые используются клиентами, а также все передаваемые и получаемые данные и возможные ошибки. На самом деле, я пишу эти строки и думаю, что это само собой разумеющееся: кажется очевидным, что если ты разрабатываешь API, то должна быть и спецификация, причем не в виде простого перечисления методов, а максимально полная, и, самое главное — генерируемая из кода, а не написанная руками, но так дело обстоит далеко не везде, поэтому надо стремиться к лучшему.

Ну ок, вот мы нашли нашу спеку, она полноценная, без темных пятен. Отлично — дело почти сделано. Теперь осталось использовать ее для достижения наших коварных целей. Так уж вышло, что я пишу еще и приложения на Flutter и в качестве клиента буду рассматривать именно его, но подход, применяемый тут — подойдет и для web-клиентов (да и для любых других тоже найдется что заюзать).

Генерация по инициативе клиента

Думаю, не будет откровением, что магии то и нет. Чтобы фича появилась — все равно должен появиться некий код. И да, мы не будем его писать, но будет кодогенератор. И вот тут-то и начинается самое интересное. Есть библиотеки для Flutter (да и не только для него), которые сгенерируют код для работы с бэком исходя из аннотаций, которые вы можете накидать на псевдо-сервисы (которые вам все еще придется написать).

Выглядит это примерно так:

import 'package:dio/dio.dart';
import 'package:json_annotation/json_annotation.dart';
import 'package:retrofit/retrofit.dart';

part 'example.g.dart';

@RestApi(baseUrl: "https://5d42a6e2bc64f90014a56ca0.mockapi.io/api/v1/")
abstract class RestClient {
  factory RestClient(Dio dio, {String baseUrl}) = _RestClient;

  @GET("/tasks/{id}")
  Future<Task> getTask(@Path("id") String id);

  @GET('/demo')
  Future<String> queries(@Queries() Map<String, dynamic> queries);

  @GET("https://httpbin.org/get")
  Future<String> namedExample(@Query("apikey") String apiKey, @Query("scope") String scope, @Query("type") String type, @Query("from") int from);

  @PATCH("/tasks/{id}")
  Future<Task> updateTaskPart(@Path() String id, @Body() Map<String, dynamic> map);

  @PUT("/tasks/{id}")
  Future<Task> updateTask(@Path() String id, @Body() Task task);

  @DELETE("/tasks/{id}")
  Future<void> deleteTask(@Path() String id);

  @POST("/tasks")
  Future<Task> createTask(@Body() Task task);

  @POST("http://httpbin.org/post")
  Future<void> createNewTaskFromFile(@Part() File file);

  @POST("http://httpbin.org/post")
  @FormUrlEncoded()
  Future<String> postUrlEncodedFormData(@Field() String hello);
}

@JsonSerializable()
class Task {
  String id;
  String name;
  String avatar;
  String createdAt;

  Task({this.id, this.name, this.avatar, this.createdAt});

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);

  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

После запуска генератора мы получим рабочий сервис, готовый к использованию:

import 'package:logger/logger.dart';
import 'package:retrofit_example/example.dart';
import 'package:dio/dio.dart';

final logger = Logger();
void main(List<String> args) {
  final dio = Dio(); // Provide a dio instance
  dio.options.headers["Demo-Header"] = "demo header";
  final client = RestClient(dio);
  
  client.getTasks().then((it) => logger.i(it));
}

Данный способ (применимый на любых типах клиентов) может сэкономить вам немало времени и в случае, если ваш бэк не имеет нормальной OpenAPI схемы — то у вас то и не особо большой выбор, однако, если качественная схема есть, то по сравнению с тем способом генерации кода, о котором мы поговорим дальше у текущего варианта есть несколько недостатков:

• Вам все еще нужно писать код, меньше, чем раньше, но немало

• Вы должны самостоятельно отслеживать изменения в бэкенде и вслед за ними менять написанный вами код

На последнем пункте стоит остановиться немного подробнее — если (когда) произойдут изменения на бэке в методах, которые уже используются в вашем приложении — то вам нужно самостоятельно отслеживать эти изменения, дорабатывать модели DTO, и, возможно, endpoint’а. Также, если по какой-то невероятнейшей причине произойдут обратно-несовместимые изменения метода, то узнаете вы об этом только в рантайме (в момент вызова данного метода) — чего может не произойти во время разработки (особенно, если у вас нет или недостаточно тестов) и тогда у вас будет крайне неприятный баг в проде.

Генерация без «тумана войны»

Вы же еще не забыли, что у нас есть качественная OpenAPI-схема? Отлично! Все поле боя вам открыто и нет смысла идти наощупь (я добавил эту фразу, чтобы хоть как-то оправдать заголовок этого блока, придумывать которые, со скрипом, приходится самому; генерация тут не поможет). Тогда стоит обратить внимание на те инструменты, которые предлагает вся экосистема OpenAPI в принципе!

Из всего многообразия молотков и микроскопов сейчас нас интересует всего один. И имя ему — OpenAPI Generator. Данный напильник позволяет генерировать код для любого языка (ну почти), а также — как для клиентов, так и для сервера (чтобы сделать mock-сервер, к примеру).

Давайте уже перейдем к коду:

В качестве схемы мы возьмем то, что предлагает демка Swagger. Затем, нам надо установить сам генератор. Вот прекрасное пособие для этого. Если вы читаете эту статью, то с высокой долей вероятности у вас уже установлена Node.js, а значит, одним из самых простых способов установки будет использование npm-версии.

Следующий шаг — сама генерация. Есть парочка способов сделать это:

• Использование сугубо консольной команды

• Использование команды в сочетании с файлом конфигурации

На нашем примере 1й способ будет выглядить следующим образом:

openapi-generator-cli generate -i https://petstore.swagger.io/v2/swagger.json -g dart-dio -o .pet_api --additional-properties pubName=pet_api

Альтернативный способ — описание параметров в файле openapitools.json, например так:

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "5.1.1",
    "generators": {
      "pet": {
        "input-spec": "https://petstore.swagger.io/v2/swagger.json",
        "generator-name": "dart-dio",
        "output": ".pet_api",
        "additionalProperties": {
          "pubName": "pet_api"
        }
      }
    }
  }
}

И последующий запуск команды:

openapi-generator-cli generate

Полный перечень доступных параметров для Dart представлен здесь. А для любого другого генератора список этих параметров можно узнать, выполнив следующую консольную команду:

# <generator-name>, dart-dio - for example
openapi-generator-cli config-help -g dart-dio

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

Так, начиная с версии 5.1.0 генератор использует null-safety, но реализует это посредством явных проверок, а не возможностей самого языка Dart (пока это так, к сожалению). К примеру — если в вашей схеме некоторые из полей модели размечены как обязательные, то если ваш бэкенд вернет модель без этого поля — то случится ошибка в рантайме.

flutter: Deserializing '[id, 9, category, {id: 0, name: cats}, photoUrls, [string], tags, [{id: 0, na...' to 'Pet' failed due to: Tried to construct class "Pet" with null field "name". This is forbidden; to allow it, mark "name" with @nullable.

А все из-за того, что поле name модели Pet явным образом указано, как обязательное, но отсутствует в ответе запроса:

{
  "Pet": {
    "type": "object",
    "required": [
      "name", // <- required field
      "photoUrls" // <- and this too
    ],
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "category": {
        "$ref": "#/definitions/Category"
      },
      "name": {
        "type": "string",
        "example": "doggie"
      },
      "photoUrls": {
        "type": "array",
        "xml": {
          "wrapped": true
        },
        "items": {
          "type": "string",
          "xml": {
            "name": "photoUrl"
          }
        }
      },
      "tags": {
        "type": "array",
        "xml": {
          "wrapped": true
        },
        "items": {
          "xml": {
            "name": "tag"
          },
          "$ref": "#/definitions/Tag"
        }
      },
      "status": {
        "type": "string",
        "description": "pet status in the store",
        "enum": [
          "available",
          "pending",
          "sold"
        ]
      }
    },
    "xml": {
      "name": "Pet"
    }
  },
  "Category": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    },
    "xml": {
      "name": "Category"
    }
  },
  "Tag": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64"
      },
      "name": {
        "type": "string"
      }
    },
    "xml": {
      "name": "Tag"
    }
  }
}

Что же, генератор запущен — дело сделано и осталось несколько несложных шагов, в которых нам почти не придется писать код (ради этого же все затевалось!). Стандартный openapi-generator сгенерирует только базовый код, в котором используются библиотеки, полагающиеся уже на кодогенерацию средствами самого Dart. Поэтому, после завершения базовой генерации необходимо запустить и Dart генератор:

cd .pet_api
flutter pub get  
flutter pub run build_runner build --delete-conflicting-outputs

На выходе мы получаем готовый пакет, который будет располагаться там, где вы указали в файле конфигурации или консольной команде. Осталось включить его в pubspec.yaml:

name: openapi_sample
description: Sample for OpenAPI
version: 1.0.0
publish_to: none

environment:
  flutter: ">=2.0.0"
  sdk: ">=2.12.0 <3.0.0"

dependencies:
  flutter:
    sdk: flutter
  pet_api: # <- our generated library
    path: .pet_api

И использовать данную библиотеку следующим образом:

import 'package:dio/dio.dart';
import 'package:pet_api/api/pet_api.dart';
import 'package:pet_api/model/pet.dart';
import 'package:pet_api/serializers.dart'; // <- we must use [standartSerializers] from this package module

Future<Pet> loadPet() async {
  final Dio dio = Dio(BaseOptions(baseUrl: 'https://petstore.swagger.io/v2'));
  final PetApi petApi = PetApi(dio, standardSerializers);
  const petId = 9;
  final Response<Pet> response = await petApi.getPetById(petId, headers: <String, String>{'Authorization': 'Bearer special-key'});
  return response.data;
}

Из важного в ней — необходимость прописать, какие мы будем использовать сериализаторы (standartSerializers) для того, чтобы JSON’ы превращались в нормальные модели. А также прокидывать инстансы Dio в сгенерированные ...Api, указывая в них базовые урлы серверов.

Нюансы Dart

Вроде бы и все, что можно сказать по этой теме, но Dart не так давно получил крупное обновление, в нем появилась null-safety. И все пакеты активно обновляются, а проекты мигрируют на новую версию языка, более устойчивую к ошибкам нашим. Однако, на данный момент, генератор не поддерживает эту новую версию, причем — сразу по нескольким направлениям:

• Версия языка в пакете (в последней версии генератора — 5.1.1, используется Dart 2.7.0)

• Устаревшие пакеты

• Обратная несовместимость некоторых из используемых пакетов (в актуальной версии Dio некоторые методы имеют другие названия и много чего еще)

name: pet_api
version: 1.0.0
description: OpenAPI API client

environment:
  sdk: '>=2.7.0 <3.0.0' # -> '>=2.12.0 <3.0.0'

dependencies:
  dio: '^3.0.9' # Actual -> 4.0.0
  built_value: '>=7.1.0 <8.0.0' # -> 8.1.0
  built_collection: '>=4.3.2 <5.0.0' # -> 5.1.0

dev_dependencies:
  built_value_generator: '>=7.1.0 <8.0.0' # -> 8.1.0
  build_runner: any # -> 2.0.5
  test: '>=1.3.0 <1.16.0' # -> 1.17.9

И это может доставлять сразу несколько проблем — если вы уже перешли на Flutter 2.0+ и Dart 2.12+, то, чтобы запустить кодогенерацию второго этапа (которая на Dart) — вам придется переключать язык на старую версию, FVM позволяет это сделать довольно быстро, но это все равно неудобство.

Второй минус заключается в том, что данный сгенированный api-пакет теперь является legacy-зависимостью, что не позволит запустить ваш новый проект с sound-null-safety. Вы сможете использовать преимущества null-safety при написании кода, но рантайм проверки и оптимизации вам будут недоступны, а проект будет работоспособен только при использовании дополнительного параметра Flutter: --no-sound-null-safety.

Варианта исправления этой ситуации три:

• Сделать pull-request, с обновлением openapi-generator

• Дождаться, пока это сделает кто-то другой, через пол года это, скорее всего, случится

• Исправить сгенерированный код, чтобы он уже сейчас стал sound-null-safety

Третий пункт звучит так, будто нам придется писать код… Немного придется, но не тот.

До начала наших манипуляций покажу вам bash-скрипт, который получился на данный момент и который запускает всю нашу логику генерации кода:

openapi-generator-cli generate  
cd .pet_api || exit 
flutter pub get  
flutter pub run build_runner build --delete-conflicting-outputs

Данный скрипт полагается и на файл конфигурации, который мы обсуждали выше. Давайте дополним этот скрипт, чтобы он сразу же и обновлял все зависимости нашего сгенированного пакета:

openapi-generator-cli generate  
cd .pet_api || exit  
echo "name: pet_api  
version: 1.0.0  
description: OpenAPI API client  
  
environment:  
 sdk: '>=2.12.0 <3.0.0'  
dependencies:  
 dio: ^4.0.0 built_value: ^8.1.0 built_collection: ^5.1.0  
dev_dependencies:  
 built_value_generator: ^8.1.0 build_runner: ^2.0.5 test: ^1.17.9" > pubspec.yaml  
flutter pub get  
flutter pub run build_runner build --delete-conflicting-outputs

Теперь — наш генератор корректно запустится и с новой версией Dart (>2.12.0) в системе. Все бы ничего, но использовать наш api-пакет по прежнему не получится! Во первых — сгенерированный код изобилует аннотациями, привязывающими его к старой версии языка:

//  
// AUTO-GENERATED FILE, DO NOT MODIFY!  
//  
// @dart=2.7  <--
  
// ignore_for_file: unused_import

А во вторых — есть обратная несовместимость в логике Dio и пакетов, которые используются для сериализации / десериализации моделей. Давайте исправим это! Для исправления нам потребуется написать совсем немного утилитарного кода, который будет исправлять несовместимости, которые появятся в нашем сгенерированном коде. Я упоминал выше, что советовал бы ставить генератор посредством npm, как самого простого способа, если у вас есть Node.js, соответственно, по инерции — и утилитарный код будет написан на JS. При желании его несложно переписать на Dart, если у вас нет Node.js и нет желания с ней связываться.

Давайте взглянем на эти нехитрые манипуляции:

const fs = require('fs');
const p = require('path');

const dartFiles = [];

function main() {
  const openapiDirPath = p.resolve(__dirname, '.pet_api');
  searchDartFiles(openapiDirPath);
  for (const filePath of dartFiles) {
    fixFile(filePath);
    console.log('Fixed file:', filePath);
  }
}

function searchDartFiles(path) {
  const isDir = fs.lstatSync(path).isDirectory();
  if (isDir) {
    const dirContent = fs.readdirSync(path);
    for (const dirContentPath of dirContent) {
      const fullPath = p.resolve(path, dirContentPath);
      searchDartFiles(fullPath);
    }
  } else {
    if (path.includes('.dart')) {
      dartFiles.push(path);
    }
  }
}

function fixFile(path) {
  const fileContent = fs.readFileSync(path).toString();
  const fixedContent = fixOthers(fileContent);
  fs.writeFileSync(path, fixedContent);
}

const fixOthers = fileContent => {
  let content = fileContent;
  for (const entry of otherFixers.entries()) {
    content = content.replace(entry[0], entry[1]);
  }
  return content;
};

const otherFixers = new Map([
  // ? Base fixers for Dio and standard params
  [
    '// @dart=2.7',
    '// ',
  ],
  [
    /response.request/gm,
    'response.requestOptions',
  ],
  [
    /request: /gm,
    'requestOptions: ',
  ],
  [
    /Iterable<Object> serialized/gm,
    'Iterable<Object?> serialized',
  ],
  [
    /(?<type>^ +Uint8List)(?<value> file,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +String)(?<value> additionalMetadata,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +ProgressCallback)(?<value> onReceiveProgress,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +ProgressCallback)(?<value> onSendProgress,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +ValidateStatus)(?<value> validateStatus,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +Map<String, dynamic>)(?<value> extra,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +Map<String, dynamic>)(?<value> headers,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +CancelToken)(?<value> cancelToken,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(@nullablen)(?<annotation>^ +@.*n)(?<type>.*)(?<getter> get )(?<variable>.*n)/gm,
    '$<annotation>$<spaces>$<type>?$<getter>$<variable>',
  ],
  [
    'final result = <Object>[];',
    'final result = <Object?>[];',
  ],
  [
    'Iterable<Object> serialize',
    'Iterable<Object?> serialize',
  ],
  [
    /^ *final _response = await _dio.request<dynamic>(n +_request.path,n +data: _bodyData,n +options: _request,n +);/gm,
    `_request.data = _bodyData;
    
    final _response = await _dio.fetch<dynamic>(_request);
    `,
  ],
  // ? Special, custom params for concrete API
  [
    /(?<type>^ +String)(?<value> apiKey,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +String)(?<value> name,)/gm,
    '$<type>?$<value>',
  ],
  [
    /(?<type>^ +String)(?<value> status,)/gm,
    '$<type>?$<value>',
  ],
]);

main();

Включим использование данного скрипта после openapi-генератора и до Dart-генератора:

rm -rf ".pet_api" || echo ".pet_api folder not found"
openapi-generator-cli generate
cd .pet_api || exit
echo "name: pet_api
version: 1.0.0
description: OpenAPI API client
environment:
  sdk: '>=2.12.0 <3.0.0'
dependencies:
  dio: ^4.0.0
  built_value: ^8.1.0
  built_collection: ^5.1.0
dev_dependencies:
  built_value_generator: ^8.1.0
  build_runner: ^2.0.5
  test: ^1.17.9
" > pubspec.yaml
node ../openapi_updater.js # <--
flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs

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

Выводы

Подход к генерации клиентского кода, при наличии качественной OpenAPI схемы является крайне простой задачей, вне зависимости от языка клиента. В случае Dart — все еще есть определенные неудобства, вызванные, сугубо, переходным периодом на null-safety. Но в рамках данной заметки мы успешно преодолели все неурядицы и получили полностью работоспособную библиотеку для работы с бэкендом, зависимости которой (и сама она) обновлены до самой новой версии и могут быть использованными в проекте на Flutter с sound-null-safety без каких-либо ограничений.

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

Также, есть и другие способы, которые позволят не писать то, что можно не писать. А тем временем, весь код из статьи с рабочими заплатками, позволяющими использовать генератор с null-safety уже сейчас можно найти тут.

18:01 24.12.2021 (обновлено: 20:30 24.12.2021)