Я большой фанат TypeScript. Каждый свой новый проект я предпочитаю писать на нём, а не на чистом JavaScript. В данной статье я не буду рассматривать причины выбора TypeScript или о его преимуществах и недостатках. Я хочу, чтобы данный пост стал своего рода шпаргалкой для тех, кто хочет понять, как настраивать tsconfig, разложить по полочкам его многочисленные флаги и, возможно, узнать некоторые полезные трюки.

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

Если открыть официальный референс tsconfig, то там будет полный список всех настроек, разделённых по группам. Однако, это не даёт понимания, с чего начать и что из данного обширного списка опций обязательно, а на что можно не обращать внимания (по крайней мере до поры до времени). Плюс, иногда опции сгруппированы по некому техническому, а не логическому смыслу. Например, некоторые флаги проверок можно найти в группе Strict Checks, некоторые в Linter Checks, а другие в Advanced. Это не всегда удобно для понимания.

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

Структура tsconfig

Рассмотрим структуру и некоторые особенности конфига.

• tsconfig.json состоит из двух частей. Какие-то опции необходимо указывать в root, а какие-то в compilerOptions

• tsconfig.json поддерживает комментарии. Такие IDE как WebStorm и Visual Studio Code знают об этом не выделяют комментарии как синтаксическую ошибку

• tsconfig.json поддерживает наследование. Опции можно разделить по некоторому принципу, описать их в разных файлах и объединить с помощью специальной директивы

Это болванка нашего tsconfig.json:

{  // extends позволяет обогатить опции другими опциями из указанного файла  // файлом tsconfig-checks.json займёмся во второй части статьи  "extends": "./tsconfig-checks.json",  // в корне конфига находятся project-specific опции  "compilerOptions": {    // здесь все настройки, связанные с компилятором  }}

К root опциям относится только следующие: extends, files, include, exclude, references, typeAcquisition. Из них мы будем рассматривать первые 4. Все остальные опции размещаются в compilerOptions.

Иногда в root секции конфига можно встретить такие опции как compileOnSave и ts-node. Эти опции не являются официальными и используются IDE для своих целей.

Секция root

extends

Type: string | false, default: false.

Указывает путь к файлу из которого нужно унаследовать опции. По большей части, служит инструментом упорядочивания. Можно разделить опции по некой логике, чтобы они не смешивались. Например, вынести настройки строгости в отдельный файл, как в примере болванки конфига. Однако, учитывая поддержку комментариев в tsconfig.json это можно сделать проще:

{  "compilerOptions": {    // блок базовых настроек    // блок настроек строгости  }}

Рассмотрим другой use-case, где комментариями отделаться не получится. Если необходимо создать production и development конфиги. Так бы мог выглядеть tsconfig-dev.json версия конфига:

{  "extends": "./tsconfig.json",  "compilerOptions": {    // переопределяем настройки, которые нужны только для dev режима    "sourceMap": true,    "watch": true  }}

В целом, я рекомендую пользоваться extends. Однако, сильно дробить настройки не рекомендую. Это может привести к запутыванию. В том числе по причине того, что множественное наследование не поддерживается.

Если вы решите использовать эту опцию. То увидеть итоговую, объединённую версию конфига поможет команда tsc --showConfig.

files

Type: string[] | false, default: false, связана с include.

Указать список конкретных файлов для компиляции можно использовав данную опцию.

{  "compilerOptions": {},  "files": [    "core.ts",    "app.ts"  ]}

Данная опция подходит лишь для совсем маленьких проектов из нескольких файлов.

include

Type string[], default: зависит от значения files, связана с exclude.

Если опция files не указана, то TypeScript будет использовать эту директиву для поиска компилируемых файлов. Если include так же не указана, то её значение будет неявно объявлено как ["**/*"]. Это означает, что поиск файлов будет осуществляться во всех папках и их подпапках. Такое поведение не оптимально, поэтому в целях производительности лучше всегда указывать конкретные пути. Можно прописывать как пути к конкретным файлам, так и паттерны путей.

{  "compilerOptions": {},  "include": [    "src/**/*",    "tests/**/*"  ]}

Если паттерны не указывают конкретных расширений, то TypeScript будет искать файлы с расширениями .ts, .tsx, and .d.ts. А если включен флаг allowJs, то ещё .js и .jsx.

Следующие форматы записей делают одно и тоже src, ./src, src/**/*. Я предпочитаю вариант ./src.

Технически, используя опции include и exclude, TypeScript сгенерирует список всех подходящих файлов и поместит их в files. Это можно наблюдать если выполнить команду tsc --showConfig.

exclude

Type: string[], default: ["nodemodules", "bowercomponents", "jspm_packages"].

Директива служит для того, чтобы исключать некоторые лишние пути или файлы, которые включились директивой include. По умолчанию, опция имеет значение путей пакетных менеджеров npm, bower и jspm, так как модули в них уже собраны. Помимо этого, TypeScript будет так же игнорировать папку из опции outDir, если она указана. Это папка, куда помещаются собранные артефакты сборки. Логично, что их нужно исключить. Если добавить свои значения в эту опцию, то необходимо не забыть восстановить умолчания. Так как пользовательские значения не объединяются со значениями по умолчанию. Другими словами, необходимо вручную указать корень модулей своего пакетного менеджера.

{  "compilerOptions": {},  "exclude": [    "node_modules",    "./src/**/*.spec.ts"  ]}

Опция exclude не может исключить файлы, указанные через files.

Опция exclude не может исключить файлы, если они импортируются в других файлах, которые не исключены.

Секция compilerOptions

target

Type: string, default: ES3, влияет на опции lib, module.

Версия стандарта ECMAScript, в которую будет скомпилирован код. Здесь большой выбор: ES3, ES5, ES6 (он же ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ESNext. Для backend приложений/пакетов подойдёт ES6, если рассчитываете только на современные версии Node.js и ES5, если хотите поддержать более старые версии. На данный момент стандарт ES6, с небольшими оговорками, поддерживается 97.29% браузеров. Так что для frontend приложений ситуация аналогичная.

module

Type: string, default: зависит от target, влияет на опцию moduleResolution.

Модульная система, которую будет использовать ваше собранное приложение. На выбор: None, CommonJS, AMD, System, UMD, ES6, ES2015, ES2020 or ESNext. Для backend приложений/пакетов подойдёт ES6 или CommonJS в зависимости от версий Node.js, которые хотите поддерживать. Для frontend приложений под современные браузеры также подходит ES6. А для поддержки более старых браузеров и для изоморфных приложений, определённо стоит выбрать UMD.

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

moduleResolution

Type: string, default: зависит от module.

Стратегия, которая будет использоваться для импорта модулей. Здесь всего две опции: node и classic. При этом classic в 99% не будет использоваться, так как это legacy. Однако, я специально упомянул этот флаг, так как он меняется в зависимости от предыдущего флага. При изменении значения module режим moduleResolution может переключиться на classic и в консоли начнут появляться сообщения об ошибках на строчках с импортами.

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

lib

Type: string[], default: зависит от target.

В зависимости от того какой target установлен в конфиге, TypeScript подключает тайпинги (*.d.ts-файлы) для поддержки соответствующих спецификаций. Например, если ваш target установлен в ES6, то TypeScript подключит поддержку array.find и прочих вещей, которые есть в стандарте. Но если target стоит ES5, то использовать метод массива find нельзя, так как его не существует в этой версии JavaScript. Можно подключить полифилы. Однако, для того, чтобы TypeScript понял, что теперь данную функциональность можно использовать, необходимо подключить необходимые тайпинги в секции lib. При этом, можно подключить как весь стандарт ES2015, так и его часть ES2015.Core (только методы find, findInex и т.д.).

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

Для --target ES5 подключаются: DOM, ES5, ScriptHostДля --target ES6: DOM, ES6, DOM.Iterable, ScriptHost

Как только вы что-либо добавляете в lib умолчания сбрасываются. Необходимо руками добавить то, что нужно, например DOM:

{  "compilerOptions": {    "target": "ES5",    "lib": [      "DOM",      "ES2015.Core"    ]  }}

outDir

Type: string, default: равняется корневой директории.

Конечная папка, куда будут помещаться собранные артефакты. К ним относятся: .js, .d.ts, и .js.map файлы. Если оставить не указывать значение для данной опции, то все вышеуказанные файлы будут повторять структуру исходных файлов в корне вашего проекта. В таком случае будет сложно удалять предыдущие билды и описывать .gitignore файлы. Да и кодовая база будет похожа на свалку. Советую складывать все артефакты в одну папку, которую легко удалить или заигнорировать системой контроля версий.

Если оставить опцию outDir пустой:

 module    core.js    core.ts index.js index.ts

Если указать outDir:

 dist    module   |    core.js    index.js module    core.ts index.ts

outFile

Type: string, default: none.

Судя по описанию, данная опция позволяет объединить все файлы в один. Кажется, что бандлеры вроде webpack больше не нужны Однако, опция работает только если значение module указано None, System, or AMD. К огромному сожалению, опция не будет работать с модулями CommonJS or ES6. Поэтому скорее всего использовать outFile не придётся. Так как опция выглядит максимально привлекательно, но работает не так как ожидается, я решил предупредить вас об этом гигантском подводном камне.

allowSyntheticDefaultImports

Type: boolean, default: зависит от module или esModuleInterop.

Если какая-либо библиотека не имеет default import, лоадеры вроде ts-loader или babel-loader автоматически создают их. Однако, d.ts-файлы библиотеки об этом не знают. Данный флаг говорит компилятору, что можно писать следующим образом:

// вместо такого импортаimport * as React from 'react';// можно писать такойimport React from 'react';

Опция включена по умолчанию, если включен флаг esModuleInterop или module === "system".

esModuleInterop

Type: boolean, default: false.

За счёт добавления болерплейта в выходной код, позволяет импортировать CommonJS пакеты как ES6.

// библиотека moment экспортируется только как CommonJS// пытаемся импортировать её как ES6import Moment from 'moment';// без флага esModuleInterop результат undefinedconsole.log(Moment);// c флагом результат [object Object]console.log(Moment);

Данный флаг по зависимости активирует allowSyntheticDefaultImports. Вместе они помогают избавиться от зоопарка разных импортов и писать их единообразно по всему проекту.

alwaysStrict

Type: boolean, default: зависит от strict.

Компилятор будет парсить код в strict mode и добавлять use strict в выходные файлы.

По умолчанию false, но если включен флаг strict, то true.

downlevelIteration

Type: boolean, default: false.

Спецификация ES6 добавила новый синтаксис для итерирования: цикл for / of, array spread, arguments spread. Если код проекта преобразовывается в ES5, то конструкция с циклом for / of будет преобразована в обычный for:

// код es6const str = 'Hello!';for (const s of str) {  console.log(s);}

// код es5 без downlevelIterationvar str = "Hello!";for (var _i = 0, str_1 = str; _i < str_1.length; _i++) {  var s = str_1[_i];  console.log(s);}

Однако, некоторые символы, такие как emoji кодируются с помощью двух символов. Т. е. такое преобразование в некоторых местах будет работать не так, как ожидается. Включенный флаг downlevelIteration генерирует более многословный и более "правильный", но менее производительный код. Код получается действительно очень большим, поэтому не буду занимать место на экране. Если интересно посмотреть пример, то перейдите в playground и выберете в настройках target -> es5, downlevelIteration -> true.

Для работы данного флага, необходимо, чтобы в браузере была реализация Symbol.iterator. В противном случае необходимо установить полифил.

forceConsistentCasingInFileNames

Type: boolean, default: false.

Включает режим чувствительности к регистру (case-sensitive) для импорта файлов. Таким образом, даже в case-insensitive файловых системах при попытке сделать импорт import FileManager from './FileManager.ts', если файл в действительности называется fileManager.ts, приведёт к ошибке. Перестраховаться лишний раз не повредит. TypeScript - это про строгость.

Опции секции compilerOptions, которые нужны не в каждом проекте

declaration

Type: boolean, default: false.

С помощью включения данного флага, помимо JavaScript файлов, к ним будут генерироваться файлы-аннотации, известные как d.ts-файлы или тайпинги. Благодаря тайпингам становится возможным определение типов для уже скомпилированных js файлов. Другими словами код попадает в js, а типы в d.ts-файлы. Это полезно в случае, например, если вы публикуете свой пакет в npm. Такой библиотекой смогут пользоваться разработчики, которые пишут как на чистом JavaScript, так и на TypeScript.

declarationDir

Type: string, default: none, связан с declaration.

По умолчанию тайпинги генерируются рядом с js-файлами. Используя данную опцию можно перенаправить все d.ts-файлы в отдельную папку.

emitDeclarationOnly

Type: boolean, default: false, связан с declaration.

Если по какой-то причине вам нужны только d.ts-файлы, то включение данного флага предотвратит генерацию js-файлов.

allowJs

Type: boolean, default: false.

Портировать ваш JavaScript проект на TypeScript поможет данный флаг. Активировав allowJs TypeScript компилятор будет обрабатывать не только ts файлы, но и js. Нет нужды полностью мигрировать проект, прежде чем продолжить его разработку. Можно это делать файл за файлом, просто меня расширение и добавляя типизацию. А новый функционал сразу можно писать на TypeScript.

checkJs

Type: boolean, default: false, связан с allowJs.

TypeScript будет проверять ошибки не только в ts, но и в js-файлах. Помимо встроенных тайпингов для языковых конструкций JavaScript, TS-компилятор так же умеет использовать jsDoc для анализа файлов. Я предпочитаю не использовать этот флаг, а наводить порядок в коде в момент его типизации. Однако, если в вашем проекте хорошее покрытие кода jsDoc, стоит попробовать.

С версии 4.1 при включении checkJs, флаг allowJs включается автоматически.

experimentalDecorators и emitDecoratorMetadata

Type: boolean, default: false.

Декоратор - это стандартный паттерн из мира ООП и его можно реализовывать классическим образом, создавая классы или функции-обёртки. Однако, с помощью двух вышеперечисленных флагов можно включить экспериментальный синтаксис декораторов. Данный синтаксис позволяет декорировать классы, их методы и свойства, модификаторы доступа, а так же аргументы функций используя простой и распространённый во многих языках программирования синтаксис @.

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

Для работы emitDecoratorMetadata необходимо подтянуть в проект библиотеку reflect-metadata.

resolveJsonModule

Type: boolean, default: false.

Флаг позволяет включить возможность импортировать *.json файлы. Ничего дополнительно устанавливать не требуется.

// необходимо указывать расширение .jsonimport config from './config.json'

jsx

Type: string, default: none.

Если проект использует React, необходимо включить поддержку jsx. В подавляющем большинстве случаев будет достаточно опций react или react-native. Так же есть возможность оставить jsx-код нетронутым с помощью опции preserve или использовать кастомные преобразователи react-jsx и react-jsx.

Завершение первой части

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

Для будущих студентов курса "React.js Developer" подготовили перевод материала.

Также предлагаем всем желающим посмотреть открытый вебинар на тему ReactJS: быстрый старт. Сильные и слабые стороны.

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

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

1. Используйте event.target.name для обработчиков событий.

2. Как избежать ручной привязки обработчиков событий к this?

3. Используйте React hooks для обновления состояния.

4. Кэширование затратных операций с useMemo.

5. Разделение функций на отдельные элементы для улучшения качества кода.

6. Как создавать собственные хуки в React?

#1: Используйте имя обработчика события

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

Однако, пишете ли Вы десять обработчиков событий, когда у Вас форма с десятью полями ввода? Ответ нет.

Мы можем установить свойство имени на поле ввода и получить доступ к нему из обработчика события. Это значение позволяет нам использовать один обработчик входных данных для событий onChange.

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

export default class App extends React.Component {    constructor(props) {        super(props);        this.state = {            item1: "",            item2: "",            items: "",            errorMsg: ""        };        this.onFirstInputChange = this.onFirstInputChange.bind(this);        this.onSecondInputChange = this.onSecondInputChange.bind(this);    }    onFirstInputChange(event) {        const value = event.target.value;        this.setState({            item1: value        });    }    onSecondInputChange(event) {        const value = event.target.value;        this.setState({            item2: value        });    }    render() {        return (            <div>                <div className="input-section">                    {this.state.errorMsg && (                        <p className="error-msg">{this.state.errorMsg}</p>                    )}                    <input                        type="text"                        name="item1"                        placeholder="Enter text"                        value={this.state.item1}                        onChange={this.onFirstInputChange}                    />                    <input                        type="text"                        name="item2"                        placeholder="Enter more text"                        value={this.state.item2}                        onChange={this.onSecondInputChange}                    />                </div>            </div>      );    }}

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

Давайте рассмотрим эту ситуацию по-другому, используя поле имени. Мы можем получить доступ к этому значению через свойство event.target.name. Теперь создадим одну функцию, которая сможет обрабатывать оба события одновременно. Таким образом, мы можем удалить обе функции onFirstInputChange и onSecondInputChange.

onInputChange = (event) => {  const name = event.target.name;  const value = event.target.value;  this.setState({    [name]: value  });};

Полегче, да? Конечно, вам часто требуется дополнительная проверка данных, которые вы сохраняете в своем состоянии (state). Вы можете использовать утверждение switch для добавления собственных правил валидации для каждого введенного значения.

#2: Избегайте ручной привязки (binding) this

Скорее всего, вы знаете, что React не сохраняет привязку this при прикреплении обработчика к событию onClick или onChange. Поэтому мы должны связать это вручную. Почему мы связываем *this*? Мы хотим связать this обработчика события (event handler) с экземпляром компонента (component instance), чтобы не потерять его контекст, когда мы передадим его в качестве обратного вызова.

Вот классический пример привязки, который происходит в конструкторе.

class Button extends Component {  constructor(props) {    super(props);    this.state = { clicked: false };    this.handleClick = this.handleClick.bind(this);  }    handleClick() {    this.props.setState({ clicked: true });  }    render() {    return <button onClick={this.handleClick}>Click me!</button>;  );}

Однако привязка больше не требуется, так как команда CLI createe-react-app использует @babel/babel-plugin-transform-class-properties плагин версии >=7 и babel/plugin-proposal class-properties плагин версии <7.

Примечание: Вы должны изменить синтаксис обработчика событий (event handler) на синтаксис функции стрелок (arrow function).

Ниже приведен пример синтаксиса стрелочной функции. Здесь нет необходимости писать дополнительный код в конструкторе, чтобы связать this.

class Button extends Component {  constructor(props) {    super(props);    this.state = { clicked: false };  }    handleClick = () => this.setState({clicked: true });  render() {    return <button onClick={this.handleClick}>Click me!</button>;  );}

Это так просто! Вам не нужно беспокоиться о привязке функций в вашем конструкторе.

#3: Используйте React hooks чтобы обновить ваше состояние

Начиная с версии 16.8.0, теперь можно использовать методы состояния и жизненного цикла (state and lifecycle methods) внутри функциональных компонентов с помощью React Hooks. Другими словами, мы можем писать более читаемый код, который также намного проще в обслуживании.

Для этого мы будем использовать useState hook. Для тех, кто не знает, что такое hook и зачем его использовать вот краткое определение из React documentation..

Что такое Hook? Hook это специальная функция, которая позволяет подключиться к функциям React. Например, useState это Hook, который позволяет добавлять состояние React к функциональным компонентам.

Когда я буду использовать Hook? Если вы пишете компонент функции и понимаете, что вам нужно добавить некоторое состояние к нему, ранее вы должны были преобразовать его в класс. Теперь вы можете использовать Hook внутри существующего функционального компонента.

Во-первых, давайте посмотрим, как мы обновляем состояние с помощью setState hook.

this.setState({    errorMsg: "",    items: [item1, item2]});

А теперь давайте воспользуемся useState hook. Нам нужно импортировать этот hook из react библиотеки. Теперь мы можем объявить новые переменные состояния и передать им начальное значение. Мы будем использовать деструктуризацию,чтобы извлечь переменную для получения значения и еще одну для установки значения (это будет функция).Рассмотрим, как это можно сделать в приведенном выше примере.

import React, { useState } from "react";const App = () => {  const [items, setIems] = useState([]);  const [errorMsg, setErrorMsg] = useState("");};export default App;

Теперь вы можете получить прямой доступ как к константам items, так и к errorMsg в вашем компоненте.

Далее, мы можем обновить состояние внутри такой функции:

import React, { useState } from "react";const App = () => {  const [items, setIems] = useState([]);  const [errorMsg, setErrorMsg] = useState("");  return (    <form>        <button onClick={() => setItems(["item A", "item B"])}>          Set items        </button>    </form>  );};export default App;

Вот как ты можешь использовать state hooks (хуки состояния).

#4: Кэширование затратных операций с помощью useMemo

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

Поэтому мы можем использовать hook useMemo для запоминания вывода при передаче тех же параметров в мемоизуемую функцию (memoized function). Hook useMemo принимает функцию и вводимые параметры для запоминания. React ссылается на это как на массив зависимостей. Каждое из значений, упоминаемое внутри функции, также должно появиться в массиве зависимостей.

Вот простой, абстрактный пример. Мы передаем два параметра a и b затратной функции. Так как функция использует оба параметра, то мы должны добавить их в массив зависимостей для нашего useMemo hook.

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

#5: Разделение функций на чистые функции (Pure functions, PF) для улучшения качества кода

В соответствии с общепринятой практикой React, вы должны разделить функции, которые не используют ваш компонент. Другими словами, функция, которая не зависит от какого-либо состояния или React hooks.

Таким образом, функция сортировки является прекрасным примером, которую можно извлечь как чистую функцию.

Вы можете недоумевать, зачем вам нужно заниматься функциональным программированием?

Функциональное программирование это процесс создания программного обеспечения путем компоновки чистых функций, избегая общего для всех состояния, изменчивых (mutable) данных и побочных эффектов. Чистые функции более читабельны и легче поддаются тестированию. Поэтому они улучшают качество кода.

- freeCodeCamp

Теперь давайте применим эту концепцию к React-компонентам. Вот функция, которая может располагаться как внутри компонента React, так и снаружи. Обе они являются функциями сравнения, которые можно передать затратной функции сортировки, принимающей два входных параметра. Так как нет взаимодействия с состоянием, мы можем извлечь обе функции в чистые функции. Это позволяет нам разместить чистые функции в отдельном файле и при необходимости импортировать их в различные локации.

function ascSort (a, b) {  return a < b ? -1 : (b > a ? 1 : 0);}function descSort (a, b) {  return b < a ? -1 : (a > b ? 1 : 0);}

#6: Создайте собственные React Hooks

Мы научились использовать useState и useMemo React hooks. Тем не менее, React позволяет вам устанавливать свои собственные React hooks, чтобы сформировать необходимую логику и делать компоненты более читабельными.

Мы можем задать пользовательские React hooks, начиная с ключевого слова use, как и все другие React hooks. Это выгодно, когда вы хотите распределить логику между различными функциями. Вместо копирования функции, мы можем определить логику как React hook и повторно использовать ее в других функциях.

Вот пример React-компонента, который обновляет состояние, когда размер экрана становится меньше 600 пикселей. Если это происходит, переменная isScreenSmall устанавливается в true. В противном случае переменная устанавливается в false. Мы используем событие resize из объекта окна для обнаружения изменения размера экрана.

const LayoutComponent = () => {  const [onSmallScreen, setOnSmallScreen] = useState(false);  useEffect(() => {    checkScreenSize();    window.addEventListener("resize", checkScreenSize);  }, []);  let checkScreenSize = () => {    setOnSmallScreen(window.innerWidth < 768);  };  return (    <div className={`${onSmallScreen ? "small" : "large"}`}>      <h1>Hello World!</h1>    </div>  );};

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

import { useState, useEffect } from "react";const useSize = () => {  const [isScreenSmall, setIsScreenSmall] = useState(false);  let checkScreenSize = () => {    setIsScreenSmall(window.innerWidth < 600);  };  useEffect(() => {    checkScreenSize();    window.addEventListener("resize", checkScreenSize);    return () => window.removeEventListener("resize", checkScreenSize);  }, []);  return isScreenSmall;};export default useSize;

Мы можем создать пользовательский React hook, путем использования логики с функцией use.

В этом примере мы назвали пользовательский React hook useSize. Теперь мы можем импортировать useSize hook в любом месте, где нам это необходимо.

React custom hooks в этом нет ничего нового. Вы обертываете логику с функцией и даете ей имя, которое начинается с use. Она действует как обычная функция. Однако, следуя правилам "use", вы говорите всем, кто её импортирует, что это hook (хук). Более того, поскольку это hook, вы должны структурировать его так, чтобы следовать rules of hooks (правилам хуков).

Вот как сейчас выглядит наш компонент. Код становится намного чище!

import React from 'react'import useSize from './useSize.js'const LayoutComponent = () => {  const onSmallScreen = useSize();  return (    <div className={`${onSmallScreen ? "small" : "large"}`}>      <h1>Hello World!</h1>    </div>  );}

Бонусный совет: Мониторинг фронтенда

Мониторинг вашего фронтенда является обязательным, если вы хотите взять на себя ответственность за то, что ваши пользователи делают и как ваше приложение реагирует на их запросы. Asayer это инструмент мониторинга фронтенда, который отображает все, что делают пользователи, и показывает, как веб-приложение ведет себя при возникновении любой проблемы. Он позволяет воспроизводить проблемы, объединять ошибки JS и контролировать производительность вашего веб-приложения.

Вот и все! Эта статья научила вас шести методикам улучшения читабельности и качества кода.

Узнать подробнее о курсе "React.js Developer".

Посмотреть открытый вебинар на тему ReactJS: быстрый старт. Сильные и слабые стороны.

Как написать код один раз, а продать 20 мобильных приложений? Мы нашли ответ путём проб и факапов и разложили опыт по пунктам: из статьи вы узнаете, как безболезненно реализовать White Label android-проект.

Greetings and salutations! По работе я однажды получил крутую задачу по разработке White Label android-приложения. Изучил достижения коллег в этой области и нашёл только:

• входные гайды (раз, два, три, etc) о механизмах, но без промышленного дизайна;

• статьи, в которых освещены узкие аспекты задачи (раз, два, etc).

На мой взгляд, теме не хватает цельного гайда, который проведёт от потребностей к требованиям, от требований к архитектуре и вооружит best practices. Поэтому я решил сделать его сам.

1 Ставим задачу

И малый, и средний бизнес нуждается в дешёвых приложениях для систем лояльности: крупные ретейлеры уже обзавелись такими продуктами и приучили пользователей к мобильным приложениям.

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

Бюджет ограничен... фичи типовые... да здравствует конструктор приложений! Или White Label продукт? Пока отложим термины и опишем задачу: генерировать приложения из единой кодовой базы, каждое с дизайном под бренд клиента и только нужными ему фичами.

Задача: создавать приложения для разных клиентов из единой кодовой базы

1.1 Визуализируем решение

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

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

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

Как реализовать такой проект без боли? Прочитайте статью и найдёте ответ.

1.2 Детализируем требования

Разложим видение по полочкам: как в ТЗ, но проще.

Функциональные требования

1. Реализовать общие модули фичей:

   • новости клиент узнаёт об акциях и жизни сети магазинов;

   • лояльность получает дисконтную карту, узнаёт баланс, пробивает на кассе;

   • ...

2. Задавать отдельно для каждого приложения:

   • наборы фичей, чтобы выбирать сами модули и настраивать их параметры;

   • бренд, чтобы настраивать цвета и менять ресурсы: шрифты, картинки, зашитый контент.

Нефункциональные

• у приложений должен быть общий код;

• настройка нового приложения меньше четырёх часов разработчика;

• архитектура должна упрощать расширение модулей и поддержку от 10 до 100 приложений.

1.3 Что пилим то? Конструктор? White Label?

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

1. Что даёт конструктор/платформа:

   • универсальный сервис сборки приложений из готовых компонентов;

   • например, AppGyver dragndrop вёрстка, программирование на низкоуровневых фичах (открыть экран, сделать фото);

   • творим что угодно от приложений по покупке золота до приёмки грузов.

2. Что даёт White Label:

   • конструктор для конкретного типа приложений, например для такси;

   • ребрендинг под клиента и настройка высокоуровневых фич (новости, профиль)

Наш фокус на системах лояльности. Значит, делаем White Label. Гуглим white label android development и находим то, что нужно.

2 Проектируем и воплощаем

Строим системную схему White Label приложения

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

и получим четыре жирные проблемы:

1. Как шарить кодовую базу между приложениями?

2. Как сделать ребрендинг?

3. Как задавать конфиги?

4. Как отключать ненужные модули и настраивать необходимые?

В очередь, проблемы, в очередь!

2.1 Шарим код

Задача одна кодовая база, до 100 приложений. Решение Gradle Product Flavors.

Если вы ещё не знакомы с Gradle Product Flavors, советую почитать документацию или общие статьи. А можно и сразу в контексте White Label: кратко или в формате инструкции

В двух словах, создаём варианты базового приложения. Каждый получает изолированные папки с кодом и ресурсами, сохраняя доступ к общим из main.

Главное преимущество. Относительная простота переиспользования кода и ресурсов, удобство сборки.

Главный недостаток. Если вариантов больше 100, то в проекте и конфигах будет тяжело ориентироваться. Но у нас меньше, поэтому ок.

Альтернативы, на мой взгляд, рассматривать нет смысла: решение надёжное, из коробки.

Пример flavors. Допустим, на старте делаем два приложения:

1. Лояка абстрактная компания;

2. Ювелирия сеть ювелирных магазинов.

Назовём flavors соответственно loyaka и jewelry. Сразу реализуем best practice конфиг каждого flavor вынесем в отдельный файлик. Зачем? Станет ясно чуть позже.

Пока создадим:

1. папку project_flavors;

2. в ней gradle-скрипты flavor_loyaka.gradle, flavor_jewelry.gradle и flavors_common.gradle;

3. задействуем скрипты в build.gradle уровня app.

Здесь и далее привожу сокращённые примеры из тестового проекта к статье.

flavor_loyaka.gradle

apply from: "$rootDir/project_flavors/flavors_common.gradle"  android {    productFlavors {        loyaka {            dimension APP_DIMENSION            resValue "string", APP_NAME_VAR, 'Лояка'            applicationId BASE_PACKAGE + 'loyaka'        }    }}

flavor_jewelry.gradle

apply from: "$rootDir/project_flavors/flavors_common.gradle"  android {    productFlavors {        jewerly {            dimension APP_DIMENSION            resValue "string", APP_NAME_VAR, 'Ювелирия'            applicationId BASE_PACKAGE + 'jewelry'        }    }}

flavors_common.gradle

android {    ext.DIMENSION_APP = "app"    ext.APP_NAME_VAR = "app_name"    ext.BASE_PACKAGE = "com.livetyping."}

Наконец, задействуем flavors в build.gradle уровня app:

...apply from: "$rootDir/project_flavors/flavor_loyaka.gradle"apply from: "$rootDir/project_flavors/flavor_jewelry.gradle"apply from: "$rootDir/project_flavors/flavors_common.gradle"android {    ...    flavorDimensions APP_DIMENSION}...

2.2 Перекрашиваем

2.2.1 Концепт

У каждого приложения свой бренд, который складывается из:

• цветовой схемы;

• шрифтов, картинок, строк;

• зашитого контента (соглашений, ссылок в соц. сети).

Благодаря flavors тоже решим задачу просто. Загрузим в голову 3 факта:

1. общие код и ресурсы проекта лежат в папке main;

2. для gradle main это как дефолтный flavor;

3. у каждого flavor свои исходники. Например, общие ресурсы лежат в main/res, а специфичные для флэйвора loyaka в loyaka/res;

Что произойдёт, если в main/res и loyaka/res будут картинки с одинаковым именем animal.webp? Возникнет конфликт, и чтобы решить его, Gradle переопределит базовые ресурсы кастомными. Если непонятно, поможет диаграмма:

Задача решена! Уберём дефолтные ресурсы в main, а в конкретных flavor будем переопределять по необходимости.

2.2.2 Best practices

Крайне важно заранее договориться с дизайнерами:

• ресурсы в приложениях называем одинаково вставляем в проект прямиком из дизайна;

• тему задаём чётким набором цветов для перекрашивания копируем colors.xml в новый flavor и просто меняем значения.

И, конечно, соблюдаем договорённости, ведь впереди ждут испытания. Например, мы сразу решили, что задаём строгий набор цветов. Однако в очередном приложении цвета не сошлись часть элементов цвета primary в новом дизайне стали accent. Сразу обсудили и изменили дизайн, а ведь могли бы и вставить костыль.

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

Создать и поддерживать чёткую схему для всех приложений на порядок дешевле, чем расширять код, состоящий из уникальных косяков.

2.2.3 Пример схемы цветов

Задаём цвета бренда в файле project_styleguide.xml:

• для Лояки loyaka/res/values/project_styleguide.xml:

<?xml version="1.0" encoding="utf-8"?><resources>    <color name="active">#68b881</color>    <color name="background">#36363f</color>    <color name="disabled">#daede0</color>    <color name="field_dark">#f5f5f5</color>    ...</resources

• для Ювелирии jewelry/res/values/project_styleguide.xml:

<?xml version="1.0" encoding="utf-8"?><resources>    <color name="active">#a160d5</color>    <color name="background">#f6ebff</color>    <color name="disabled">#e2c8f6</color>    <color name="field_dark">#f5f5f5</color>    ...</resources>

2.3 Задаём конфиг

2.3.1 Концепт

Фичи настраиваем на двух уровнях:

1. отключаем ненужные модули;

2. меняем параметры внутри самих модулей.

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

Упрощённый пример дока в формат модуль-фича-параметры:

1. Подключаемые модули:

   • лояльность;

   • новости;

2. Аутентификация:

   • логин пользователя: телефон или email;

   • маска логина.

3. Карта лояльности:

   • тип штрих-кода: EAN-8, EAN-13, CODE-128.

2.3.2 Пути решения

Как сделать качественный конфиг? Само качество определим так:

1. удобство работы простота чтения, простота заполнения (в идеале, хотим DSL);

2. Скорость обработки важно, чтобы чтение конфига не тормозило приложение.

Выделим основные пути:

1. Gradle buildConfigField

   • задаём переменные в gradle скрипте;

   • во время компиляции генерится java класс BuildConfig, переменные доступны как его поля.

2. JSON

   • json объект в файле;

   • зашит локально, либо получаем с сервера.

Кратко оценим пути по критериям.

2.3.3 Путь 1. Gradle buildConfigField

Плюсы:

• удобство создания делаем DSL на минималках: выносим типы и возможные значения параметров в переменные; выявляем синтаксические ошибки на компиляции;

• простота большинству уже знаком;

• скорость обращаемся к классу BuildConfig в памяти.

Главный минус отвратительная читаемость: переменная состоит из четырёх блоков, подсветки синтаксиса нет.

Пример переменной на условном DSL:

buildConfigField MAIN_SCREEN_TYPE, MAIN_SCREEN_VAR, MS_SHOPS

2.3.4 Путь 2. JSON

Плюсы:

• удобство чтения особенно в формате HOCON;

• удобство создания делаем DSL через JSON Schema, проверяем на ошибки по мере написания;

• переиспользование шарим между iOS и Android.

Минусы:

• скорость придётся перед запуском считать из файла или получать с сервера;

• время на освоение по сравнению с первым вариантом JSON Schema наверняка менее популярна.

2.3.5 Так что же лучше?

Когда делали проект, даже не изучали альтернативы. Сразу сделали через Gradle. На мой взгляд, JSON + Schema его побеждает. Удобство чтения приоритет, при этом удобство создания остаётся на том же уровне, если не лучше. Дополнительная секунда для загрузки файла на общем фоне незначительна.

Сделали конфиг через Gradle, не изучая альтернатив. Но оказалось, что JSON Schema удобнее для чтения и это её главное преимущество.

2.3.6 Best practices для buildConfigField

Если выбрали buildConfigField, то в сыром виде с ним будут проблемы:

1. чтобы использоватьEnum, придётся указать полный путь к пакету как в типе, так и в значениях;

2. при изменение имени или типа переменной придётся делать Find & Replace по всем конфигам.

Решение: DSL на минималках. Заводим переменные для названий параметров, а также кастомных типов и вариантов значений. Создаём отдельный gradle-скрипт на каждый модуль. Параметры описываем в формате экран-параметр-переменные. Скрипты кладём в папку business_rules.

Пример: модуль лояльности loyalty_business_rules.gradle:

/*_______________ENTER USER ID________________*//*________User ID________*//*__Variable__*/ext.USER_ID_VAR = "USER_ID"ext.USER_ID_TYPE = "com.example.whitelabelexample.domain.models.UserIdType"/*__Values__*/ext.UI_PHONE = USER_ID_TYPE + ".PHONE"ext.UI_EMAIL = USER_ID_TYPE + ".EMAIL"/*_______________NO CARD________________*//*________Obtain card methods________*//*__Variable__*/ext.OBTAIN_METHODS_VAR = "OBTAIN_CARD_METHODS"ext.OBTAIN_METHODS_ENUM = "com.example.whitelabelexample.domain.models.ObtainCardMethod"ext.OBTAIN_METHODS_TYPE = "java.util.List<" + OBTAIN_METHODS_ENUM + ">"/*__Optional values__*/ext.OM_GENERATE = OBTAIN_METHODS_ENUM + ".GENERATE_VIRTUAL"ext.OM_BIND = OBTAIN_METHODS_ENUM + " .BIND_PHYSICAL"...

UI_PHONE что за UI_? Это сокращение переменной UserId: добавляем префиксы, чтобы избежать коллизий.

Дальше настраиваем приложения в скриптах flavor, которые на первом шаге заботливо вытащили по файлам.

Пример: flavor_loyaka.gradle:

...loyaka {    ...    /* MAIN SCREEN */    buildConfigField MAIN_SCREEN_TYPE, MAIN_SCREEN_VAR, MS_CARD    /* MODULES */    buildConfigField APP_MODULES_TYPE, APP_MODULES_VAR, list(AM_LOYALTY, AM_SHOWCASE)    /* REGISTRATION */    buildConfigField USER_ID_TYPE, USER_ID_VAR, UI_EMAIL    ...}

flavor_jewelry.gradle:

...jewelry {    ...    /* MAIN SCREEN */    buildConfigField MAIN_SCREEN_TYPE, MAIN_SCREEN_VAR, MS_SHOPS    /* MODULES */    buildConfigField APP_MODULES_TYPE, APP_MODULES_VAR, list(AM_LOYALTY, AM_SHOPS)    /* REGISTRATION */    buildConfigField USER_ID_TYPE, USER_ID_VAR, UI_PHONE    ...}

2.3.7 Получаем доступ к конфигу

Спроектируем решение в контексте Clean Architecture.

Классы конфигов приравниваю к источникам в слое data, ибо они только предоставляют данные. Тогда ui получает параметры посредством domain.

Как сгруппировать параметры по классам? Мы на проекте за группу взяли экран, а зря. С одной стороны, компактные классы, а с другой возникли коллизии, например на экранах ввода номера телефона и подтверждения кода нужна маска номера. Пришлось реализовать считывание из конфига 2 раза.

С BuildConfig это легко, но с JSON будет грязно. Считаю, что оптимально группировать по процессу (флоу). Под процессом здесь понимаю целевой use case и вторичные по отношению к нему. Обычно это группа экранов, например в модуле лояльности два целевых процесса:

1. аутентификация чтобы авторизоваться, придётся ввести логин, а затем код подтверждения;

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

Пример реализации конфига для второго процесса: фрагмент BuildCardConfig.kt:

class BuildCardConfig : CardConfig {    override fun numberMask(): String = BuildConfig.CARD_NUMBER_MASK    override fun barcodeType(): BarcodeType = BuildConfig.BARCODE_TYPE    override fun obtainmentMethods(): List<ObtainCardMethod> = BuildConfig.OBTAIN_CARD_METHODS    ...}

В итоге получим архитектуру работы с конфигом (диаграмма классов UML; в ui MVVM):

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

2.3.8 Валидируем конфиг

Зачем нужна прослойка в domain? Она же будет пустая! Необязательно. В идеале, хотим защиту от дурака проверку параметров фичей на непротиворечивость. Допустим, дано 2 параметра:

1. включённые модули;

2. главный экран.

Если модуль новости и акции выключён, то логично, что главным экраном новости быть не может. Но на уровне Gradle или JSON Schema подобное ограничение сделать нетривиально таким правилам и место в domain.

Например, реализуем описанное условие в GetMainTabUseCase.kt:

class GetMainTabUseCase(    private val mainConfig: MainConfig) {    operator fun invoke(): NavigationTab {        val mainTab = mainConfig.mainTab()        val mainModule = tabsByModules.entries.find { it.value == mainTab }!!.key        val isModuleEnabled = BuildConfig.APP_MODULES.contains(mainModule)        if (isModuleEnabled.not()) {            throw IllegalStateException("Can't use a tab ($mainTab) as main, it's module is disabled   fix config!")        }        return mainTab    }}

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

Альтернатива создавать UseCase только по надобности, но тогда возникает неоднородность: в ui используются одновременно и Config и UseCase. Рискуем использовать параметры, которые требуют валидации, в её обход, и следом за этим растёт вероятность багов.

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

2.4 Настраиваем фичи

2.4.1 Выбираем модули

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

Модуль здесь крупный связный и независимый кусок функциональности.

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

Рассмотрим главные точки связи модуля с приложением:

1. Переходы изui боттом навигация, рандомная кнопка, etc;

2. Реакция на события кастомные (выбран город), платформы (найдена сеть), etc.

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

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

На события в Лояке реагирует только модуль пушей. Когда юзер выбирает свой город подписываемся на соответствующий новостной канал. Опять же обрабатываем каждый кейс.

Всплывает неочевидный минус buildConfigField придётся указывать параметры даже для выключенных модулей, хотя бы как null, иначе проект не соберётся.

2.4.2 Настраиваем экраны и бизнес-правила

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

На уровне UseCase берём параметр из нужного класса Config.

GetCardUseCase.kt:

class GetCardUseCase(    private val netRep: CardNetRepository,    private val storageRep: CardStorageRepository,    private val config: CardConfig) {    operator fun invoke(): Card? {        return if (config.isCacheCard()) {            try {                val card = netRep.getCard()                storageRep.save(card)                card            } catch (exception: Exception) {                return storageRep.get()            }        } else {            netRep.getCard()        }    }}

В ui же обращаемся к UseCase на уровне ViewModel или Presenter.

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

Реализация: NoCardViewModel.kt:

class NoCardViewModel(    private val getObtainMethodsUseCase: GetObtainMethodsUseCase,    ...){    private val cardObtainMethods by lazy { getObtainMethodsUseCase() }    val isShowGetVirtualButton by lazy {        cardObtainMethods.contains(ObtainCardMethod.GENERATE_VIRTUAL)    }    val isShowBindPlasticButton by lazy {        cardObtainMethods.contains(ObtainCardMethod.BIND_PHYSICAL)    }    ...}

fragment_nocard.xml:

...<com.google.android.material.button.MaterialButton    android:id="@+id/no_card_bind_plastic_button"    ...    app:isVisible="@{viewmodel.isShowBindPlasticButton}" /><com.google.android.material.button.MaterialButton    android:id="@+id/no_card_get_virtual_button"    ...    app:isVisible="@{viewmodel.isShowGetVirtualButton}" />...

2.4.3 Ещё один трюк

Иногда вариативную вёрстку целесообразнее сделать без конфига.

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

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

3 Подведём итог

Мы успешно спроектировали архитектуру White Label android-проекта, которая соответствует поставленным требованиям, а именно позволяет:

развивать общую кодовую базу расширять модули фичей и собирать из одного кода разные приложения, от 10 до 100;

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

Горькими уроками поделились, best practices передали. Надеюсь, наш опыт создал цельное представление о создании White Label android-приложений и комфортную отправную точку для вашего проекта.

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

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

4 Куда развить решение?

• Мы продаём целую систему, а что если продавать модули в другие приложения? Тот же White Label, но на системный уровень ниже. Мы такую задачу решали, если интересно напишите в комментах, расскажем.

• Когда количество приложений растёт, хочется CI и CD. В этом репозитории есть подробный гайд по настройке Azure Devops.

• Если не нужна детальная настройка фичей, а писать flavors руками надоело сделайте автогенерацию flavors по json конфигу.

• Бизнес бьёт ключом, клиентов больше сотни? Пора автоматизировать создание приложений.

Если знаете кейсы, на которые нет ссылок в нашей статье, то обязательно скиньте их в комменты вместе мы точно соберём крутую библиографию!

P.S. Shout-out дорогим коллегам за работу над проектом и помощь в написании статьи - без вас это было бы невозможно :)

Перед вами вторая часть руководства по антипаттернам деплоя в Kubernetes. Советуем также ознакомиться с первой частью.

Список антипаттернов, которые мы рассмотрим:

1. Использование образов с тегом latest

2. Сохранение конфигурации внутри образов

3. Использование приложением компонентов Kubernetes без необходимости

4. Использование для деплоя приложений инструментов для развёртывания инфраструктуры

5. Изменение конфигурации вручную

6. Использование кubectl в качестве инструмента отладки

7. Непонимание сетевых концепций Kubernetes

8. Использование неизменяемых тестовых окружений вместо динамических сред

9. Смешивание кластеров Production и Non-Production

10. Развёртывание приложений без Limits

11. Неправильное использование Health Probes

12. Не используете Helm

13. Не собираете метрики приложений, позволяющие оценить их работу

14. Отсутствие единого подхода к хранению конфиденциальных данных

15. Попытка перенести все ваши приложения в Kubernetes

6. Использование кubectl в качестве инструмента отладки

Утилита kubectl незаменима при работе с кластерами Kubernetes. Но не стоит использовать её как единственный отладочный инструмент.

При возникновении проблем, особенно в production кластере, вашим первым импульсом не должен быть запуск kubectl. Если вы поступаете именно так, то вы уже проиграли битву, особенно если сейчас 3 часа ночи, сервисы не работают, и вы на связи.

kubectl get nskubectl get pods -n saleskubectl describe pod prod-app-1233445 -n saleskubectl get svc - n saleskubectl describe...

Вместо этого все ваши кластеры Kubernetes должны иметь надлежащие системы мониторинга, трассировки и сбора логов, которые можно использовать для своевременного выявления проблем. Если вам нужно запустить kubectl для проверки чего-либо, это означает, что вы не учли это, настраивая вашу систему мониторинга.

Сложно переоценить ценность метрик и трассировок, мы расскажем о них отдельно в одном из следующих антипаттернов.

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

Например, обратите внимание на Kubevious, это универсальная панель управления Kubernetes, которая позволяет вам искать и отображать ресурсы Kubernetes в соответствии с настраиваемыми правилами.

7. Непонимание сетевых концепций Kubernetes

Прошли те времена, когда единственный балансировщик нагрузки был всем, что необходимо для настройки подключения к вашему приложению. Kubernetes представляет свою собственную сетевую модель, и вам нужно разобраться с её основными концепциями. По крайней мере, вы должны быть знакомы с типами сервисов - Load Balancer, Cluster IP, Node Port и понимать, чем сервисы отличаются от Ingress.

Сервисы типа Сluster IP используются внутри кластера, Node Port также могут использоваться внутри кластера, но при этом доступны снаружи, а балансировщики нагрузки могут принимать только входящий трафик.

Но это ещё не всё потребуется разобраться, как в кластере Kubernetes работает DNS. И не забывать, что весь трафик между служебными компонентами шифруется и нужно контролировать срок действия сертификатов.

Будет полезно разобраться, что такое Service Mesh и какие проблемы она решает. Необязательно разворачивать Service Mesh в каждом кластере Kubernetes. Но желательно понимать, как она работает и зачем вам это нужно.

Вы можете возразить, что разработчику не нужно знать множество сетевых концепций для развертывания приложения, и вы будете правы. Нам нужна абстракция для разработчиков поверх Kubernetes, но у нас ее пока нет.

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

8. Использование неизменяемых тестовых окружений вместо динамических сред

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

Один из наиболее распространенных подходов наличие как минимум трех сред (QA / Staging / Production), в зависимости от размера компании их может быть больше. Наиболее важной из них является интеграционная, которая содержит результат слияния всех обновлений с основной веткой.

Когда вы используете неизменяемые тестовые среды, вы платите за них, даже если они не используются. Но наиболее серьёзной проблемой является изоляция обновлений для последующего тестирования.

Если вы используете единое окружение для интеграции, когда несколько разработчиков выполняют слияние результатов работы и что-то ломается, не сразу становится понятно, какая из функций вызвала проблему. Если 3 разработчика объединяют свои функции в промежуточной среде и развертывание завершается неудачно (либо сборка завершается неудачно, либо тесты интеграции терпят неудачу, либо показатели взрываются...), тогда существует несколько сценариев:

1. Обновление A содержит ошибки, B и C в порядке

2. Обновление B содержит ошибки, A и C в порядке

3. Обновление C содержит ошибки, B и A в порядке

4. Каждое обновление в отдельности работает, но при работе вместе с обновлениями A и B возникает ошибка

5. Каждое обновление в отдельности работает, но при работе вместе с обновлениями A и C возникает ошибка

6. Каждое обновление в отдельности работает, но при работе вместе с обновлениями B и C возникает ошибка

7. Каждое обновление в отдельности работает, но все 3 обновления вместе не работают

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

Способы избежать подобных проблем:

1. "Резервирование" промежуточного (stage) окружения разработчиками, чтобы они имели возможность тестировать свои обновления изолированно.

2. Компания создает несколько staging сред, которые разработчики используют для тестирования своих обновлений (поскольку единственное staging окружение может быстро стать узким местом).

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

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

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

Есть много способов реализовать этот сценарий, по крайней мере, каждый запрос Pull Request должен создавать динамическую среду, содержащую только этот запрос Pull Request и ничего больше. Среда автоматически уничтожается, когда Pull Request объединяется / закрывается или по прошествии определенного времени.

Преимущество динамических сред это полная свобода разработчиков. Если я разработчик и только что закончил работу с обновлением A, а мой коллега завершил работу над обновлением B, я должен иметь возможность:

git checkout mastergit checkout -b feature-a-b-togethergit merge feature-agit merge feature-bgit push origin feature-a-b-together

Как по волшебству, будет создана динамическая среда:feature-a-b-together.staging.company.comилиstaging.company.com/feature-a-b-together.

Для создания динамических сред вы можете использовать, например, пространства имен Kubernetes.

Обратите внимание, что это нормально, если у вашей компании есть постоянные staging среды для специализированных нужд, таких как нагрузочное тестирование, тестирование на проникновения, развертывание A / B и т. д. Но для базового сценария Я разработчик и хочу, чтобы моё обновление работало изолированно и запускались интеграционные тесты динамические среды лучшее решение.

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

9. Смешивание кластеров Production и Non-Production

Несмотря на то, что Kubernetes специально разработан для оркестрирования кластеров, вы не должны создавать единый кластер для всех ваших окружений. Как минимум у вас должно быть два кластера: производственный и непроизводственный.

Прежде всего, смешивание Production и Non-Production кластеров может привести к нехватке ресурсов.

Так как приложение, работающее некорректно, может утилизировать слишком много ресурсов.

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

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

Если вы объедините этот антипаттерн со вторым (сохранение конфигурации внутри образов), должно стать очевидно, что может произойти множество негативных сценариев, например:

1. Разработчик создает новое пространство имен, используемое для тестирования и production.

2. Далее развертывается приложение и запускаются интеграционные тесты.

3. Интеграционные тесты записывают фиктивные данные или очищают БД.

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

Чтобы не попасть в эту ловушку, гораздо проще просто создать Production и Non-Production кластера. К сожалению, многие руководства описывают сценарий при котором, пространства имен можно использовать для разделения сред, и даже в официальной документации Kubernetes есть примеры с пространствами имен prod / dev.

Обратите внимание, что в зависимости от размера вашей компании у вас может быть больше кластеров, чем два, например:

1. Production

2. Pre Production (Shadow) клон production, но с меньшими ресурсами

3. Development кластер, который мы уже обсуждали выше

4. Специализированный кластер для нагрузочного тестирования / тестирования безопасности

5. И даже отдельный кластер для служебных инструментов

10. Развёртывание приложений без Limits

По умолчанию приложение, развернутое в Kubernetes, не имеет ограничений на использование ресурсов. Это означает, что ваше приложение потенциально может мешать работе всего кластера, поскольку утечка памяти или высокая загрузка ЦП нанесут ущерб остальным приложениям, работающим в кластере.

Это означает, что все ваши приложения (независимо от окружения) должны иметь ограничения на использование ресурсов.

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

Одно из преимуществ Kubernetes эластичность ресурсов. Если кластер убивает / перезапускает ваше приложение, когда оно начинает обрабатывать значительную нагрузку (например, ваш интернет-магазин испытывает всплеск трафика), вы не используете все преимущества Kubenetes. Вы можете решить эту проблему с использованием vertical pod auto-scaler (VPA).

ASP.NET контроллеры должны быть тонкими

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

Почему они должны быть тонкими? Какой в этом плюс? Как сделать их тонкими, если они сейчас не такие? Как сохранить их тонкими?

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

Чтобы начать шаги по превращению наших контроллеров в тонкие, сначала необходимо понять, как контроллеры становятся толстыми.

По моему опыту, есть 6 основных видов кода, проникающих в наши контроллеры, хотя им там вовсе не место. На самом деле этот список не исчерпывающий, и я уверен, что их ещё больше.

1. Маппинг объектов передачи данных (DTO)

Так как наши контроллеры находятся на передовой процесса обработки запроса, часто возникает необходимость создания объектов для запроса и ответа, если нужно получить что-то сложнее, чем просто параметры из адреса, и вернуть не только код ответа HTTP.

Вы понимаете, это что-то вроде:

public IActionResult CheckOutBook([FromBody]BookRequest bookRequest){    var book = new Book();    book.Title = bookRequest.Title;    book.Rating = bookRequest.Rating.ToString();    book.AuthorID = bookRequest.AuthorID;    //...}

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

2. Валидация

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

Однако, мне нравится относиться к контроллерам как к шеф-поварам. Их ассистенты подготавливают все ингредиенты, поэтому сами они занимаются только финальной компоновкой. И существует множество способов настройки валидаторов в процессе обработки запроса ASP.NET MVC, чтобы контроллеры могли считать запрос валидным и передавать его дальше по цепочке.

Вот такому коду нет оправданий!

public IActionResult Register([FromBody]AutomobileRegistrationRequest request){    // Проверяем, что VIN номер был заполнен...    if (string.IsNullOrEmpty(request.VIN))    {        return BadRequest();    }        //...}

3. Бизнес-логика

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

Иногда это пересекается и с валидацией тоже. Если в вашей валидации есть правила, продиктованные бизнесом (а не просто проверка принадлежности числа диапазону или наличия строки), то велик риск, что этот код будет повторён в другом месте.

4. Авторизация

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

Аналогично в случае с валидацией, ASP.NET предлагает множество путей для выноса авторизации (ПО промежуточного слоя и фильтры, например).

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

5. Обработка ошибок

Это больно, это БОЛЬНО!

public IActionResult GetBookById(int id){    try    {      // Важный код, который должен выполнять шеф-повар...    }    catch (DoesNotExistException)    {      // Код, который должен выполнять ассистент...    }    catch (Exception e)    {      // Пожалуйста, только не это...    }}

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

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

6. Сохранение/получение данных

Часто в целях экономии времени в контроллерах появляется код, получающий или сохраняющий объекты, используя Репозитории. Если контроллер предоставляет только CRUD операции, то к чёрту, пускай.

У меня даже есть статья, показывающая использование контроллеров таким образом.

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

Для начала взглянем на это с архитектурной точки зрения (фокусируясь на Принципе Единой Ответственности). Если ваши контроллеры используют объекты, предназначенные для хранения данных, то у контроллеров есть явно больше одной причины для изменения.

public IActionResult CheckOutBook(BookRequest request){    var book = _bookRepository.GetBookByTitleAndAuthor(request.Title, request.Author);    // Если у вас уже есть логика получения книги, то вы скорее    // всего захотите добавить сюда и логику выдачи этой книги  // ...return Ok(book);}

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

Именно здесь мне нравится использовать некий сервис (спрятанный за интерфейсом) для обработки запроса или делегирования какому-нибудь CQRS объекту.

На этом всё!

Статья закончилась, а у вас есть ещё примеры, которые не были освещены? Не согласны с каким-то из пунктов? Или просто хотите задать вопрос? Добро пожаловать в комментарии!

Перевод статьи подготовлен в преддверии старта курса "C# ASP.NET Core разработчик".

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

Ссылка для записи на вебинар

Обеспечить представление данных из любой большой системы так, чтобы человек мог спокойно с этими данными работать задача нетривиальная, но давно решенная. В этой гонке уже давно победило "дерево". Папочные структуры в операционных системах знакомы всем и каждому и исторически простое дерево в UI/UX становится первым решением для упорядочивания и хранения данных. Сегодня поговорим о тестировании, так что в нашем случае объектами хранения будут выступать тест-кейсы. Как их хранят чаще всего? Верно, в папочках!

Привычно? Да. Но так ли это решение хорошо и универсально? Вопрос подкрепляется существованием исключений: почта, JIRA-тикеты и много чего другого хранится не в папках. Давайте разбираться, почему.

Единое дерево

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

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

Что с ним не так?

Представим, что у нас есть замечательный веб-сервис, тесты на него написаны, разложены по папкам (по одной на каждую страницу) и выполняются раз в неделю, все счастливы. Однако, в какой-то момент к руководителю QA приходит менеджер (а они всегда приходят!) и просит рассказать о покрытии тестами микросервисов. Это не то, чтобы большая проблема просто теперь в дополнение к существующей структуре нужно как-то собрать информацию о тестах из папочек и соотнести ее с микросервисами и сделать соответствующий (новый) отчет. Впрочем, чтобы в следующий раз не заниматься рутиной, старший тестировщик предлагает ввести фиксированные уровни у дерева: так у нас появится возможность иметь данные по командам в нашей структуре данных, а команды намного быстрее будут со своими репозиториями разбираться! Отличное решение, только в следующий раз менеджер просит статистику покрытия по фичам (еще один новый отчет)... Если тестов много, сотни или тысячи, то создание каждого нового среза потребует погружения внутрь всех вложенных ветвей и перераспределения тест-кейсов по новой структуре для анализа.

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

Минусы дерева папок отсутствие гибкости в доступе к данным и аналитике и сложность рефакторинга в условиях, когда требования к тестированию меняются.

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

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

В итоге папочки станут снова управляемыми, уровни вложенности структурируются, но снова получится только один срез по фичам. Если попытаться создать структуру с двумя срезами, по фичам и компонентам сразу, ее сложность и запутанность создаст больше проблем, чем пользы. А если у вас 3000 тест-кейсов? А если 10000?

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

Еще один подводный камень хранения тестов в папках ждет тех, кто планирует хранить в них автоматизированные тесты, написанные на разных языках программирования. Тут все просто: в Java тесты хранятся по полному имени пакет вроде io.qameta.allure, а в JavaScript или Python просто по имени пакета. Это значит, что при автоматической генерации тест-кейсов из автотестов, каждый фреймворк будет городить свои подструктуры в дереве и вся нормализация и базовая структура будет нарушена. Конечно, можно написать свою интеграцию для каждого фреймворка, но мы же стараемся упростить себе жизнь, верно?

Самое время задаться вопросом, при чем здесь принятие решений из заголовка статьи. Ответ прост: все перечисленные недостатки связаны с тем, что папочная организация хранения тест-кейсов заставляет команду тестирования с самого начала принимать решение о структуре тестов, а не просто хранить информацию о тестовых сценариях и их результатах. Мало будет просто "подумать наперед" придется рассчитывать, что будет с проектом и командой тестирования через год-два, а лучше через три. К сожалению, чаще всего прогнозы оказываются неверными: можно переоценить темпы роста и годами сидеть в структуре "на вырост" или, наоборот, недооценить их и оказаться в структуре, неудобной команде и коллегам.

Как эту задачу решали Ops'ы?

С ограничениями классического дерева разобрались, а как их обходить? На самом деле, с этой задачей уже сталкивались многие, и изобретать велосипед нет необходимости. Большинство систем, работающих с большими объемами данных или большим количеством объектов переходят на плоскую структуру с навигацией по признакам. Самый яркий из недавних примеров инструменты мониторинга типа Grafana и Graphite.

Давайте рассмотрим его повнимательнее и попробуем применить к тестированию. Админы и все те, кто работают в Ops к метрикам и данным относятся с большой щепетильностью и любовью. Просто потому, что о падении сервиса, сети или недоступности какой-то кластера вы захотите узнать раньше пользователя, так? Изначально весь мониторинг строился по классической иерархической структуре: дата-центр кластер машинка метрики (CPU, RAM, storage и прочее). Удобная и понятная система, которая работает, если не приходится в реальном времени отслеживать десяток метрик, которые не привязаны к физическим машинам. А метрики для Ops'ов очень важны.

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

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

Набор меток хранится в плоской структуре и свободно используется любой критерий поиска, фильтрации или группировки становится меткой

Чтобы получить отчет или анализ данных, нужно просто указать, по каким критериям срезы нас интересуют: нагрузка на CPU по инстанстам, разделенным по географии.

Такой метод управления данными позволяет не только фильтровать и делать выборки внутри структуры. Он предоставляет еще один уровень свободы в виде вышеупомянутой группировки: теперь можно спокойно сделать запрос к хранилищу вида "покажи статистику доступности всех машин, на которых крутится такой-то микросервис с группировкой по кластерам". Парсер проходится по всем машинам, забирает статистику доступности с тех, на которых стоит метка микросервиса и группирует их по кластерам.

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

В любой момент по запросу пользователю доступна любая аналитика и любой срез данных. Зайдите в дэшборды любой Ops-команды крупного сервиса, здесь найдутся отчеты по десятку метрик (uptime, загрузка ресурсов, количество пользователей и т.д.), нарезанных по множеству критериев (география, балансировка между серверами и пр.).

Да это же просто автоматизация папочек! скажете вы.

И это прекрасно это классическое решение проблемы масштабирования. Конечно, у системы с метками есть несколько минусы:

• Нельзя создать "скелет" из папок и оставить их пустыми. Классическая практика из начала статьи, которая позволяет на старте продумать архитектуру.

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

Тест-кейсы: дерево против меток

Хорошо, с админами все понятно. Они там сидят и целый день смотрят в метрики и крутят данные. А нам-то зачем?

Ответ прост: мир разработки, к сожалению или к счастью, уже давно ушел от жесткой структуры релизы ускоряются, сборки автоматизируются. На фоне этих изменений, мир тестирования в большинстве компаний выглядит немного архаично: на новые фичи готовится по пачке новых тест-кейсов для ручных тестов и автоматизации, они раскладываются по папкам, запускается в тестирование на неопределенный срок (от 1-2 дней до недели), собирается результат тестирования и отгружается обратно в разработку после полного завершения. Ничего не напоминает? Это же старая добрая каскадная разработка (waterfall, то бишь)! В 2021 году. Если послушать Баруха Садогурского в одном из подкастов, где он довольно убедительно рассказывает, что любой процесс это по сути agile, в котором "мы пытаемся отложить принятие решения максимально далеко, чтобы перед этим собрать побольше данных", станет понятно, почему весь мир разработки гонится за короткими итерациями и быстрыми релизами. Именно поэтому разработчики уже давно пишут софт итеративно, внедряя по одной фиче или паре фиксов на релиз, опсы отгружают эти релизы как можно скорее, которые перед этим тестируются. А как они тестируются?

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

Посмотрите на последние веяния в тестировании для DevOps заключаются в том, чтобы тестировать как можно меньше и как можно быстрее: это приводит к подходам вроде shift right и тестируйте как можно меньше. Практики, направленные на скорость, повторяемость и стабильность выполнения тестов, а не покрытие и оценку качества в широком смысле про это в свое время буду писать отдельные статьи. Поэтому, чтобы оставаться в мире, где тестирование отвечает за качество продукта, давайте вернемся к нашим папочкам и признакам. Создавая папочную структуру, мы изначально закладываем в хранилище тест-кейсов принятое решение о том, в каком виде хотим получать отчеты и видеть результаты. Проблема в том, что мы не знаем какие отчёты понадобятся в будущем.

Если вы не успеваете готовить отчеты для коллег и бизнеса, то действительно ли тестирование приносит максимальную пользу?

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

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

По сути, вместо одного статичного дерева, управление через признаки позволяет простым и понятным способом сделать генератор деревьев, основанный на нужных критериях, расширяемый и масштабируемый без лишних танцев с бубном. А как только мы получаем автоматически генерируемые выборки и группы, мы можем настроить автоматический live-репортинг и генерацию отчетов. Самый понятный пример JIRA, где можно по любому полю тикета построить график, тренд или дэшборд любого вида, собрать, отфильтровать или сгруппировать тикеты (могут понадобиться плагины!:)) в любую структуру прямо на митинге.

Согласитесь, звучит заманчиво: иметь гибкость JIRA-тикетов в управлении тест-кейсами. Останется только автоматизировать запуски на слияние веток и вот тестирование уже отвечает требованиям DevOps!

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

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

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

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

ArchUnit это бесплатная, простая и расширяемая библиотека для проверки архитектуры вашего Java кода для использования в любой простой среде модульного тестирования Java.То есть ArchUnit может проверять зависимости между пакетами и классами, уровенями и срезами, проверять циклические зависимости и многое другое.Он делает это путем анализа данного байт-кода Java и импорта всех классов в структуру кода Java.

ArchUnit позволяет вам реализовать правила для статических свойств архитектуры приложения в форме исполняемых тестов, таких как следующие:

• Проверки зависимостей пакетов

• Проверки зависимостей класса

• Проверки содержания классов и пакетов

• Проверки наследования

• Проверка аннотаций

• Проверка уровней

• Проверки цикла

Примечание переводчика. Эта заметка дополняет предыдущую на тему ArchUnit.

Начнем

Для поддержки ArchUnit JUnit 5, просто добавьте следующую зависимость из Maven Central:

pom.xml

XML

<dependency>    <groupId>com.tngtech.archunit</groupId>    <artifactId>archunit-junit5</artifactId>    <version>0.14.1</version>    <scope>test</scope></dependency>

build.gradle

Groovy

dependencies {   testImplementation 'com.tngtech.archunit:archunit-junit5:0.14.1' } } 

Проверки зависимостей пакетов

Java

class ArchunitApplicationTests {  private JavaClasses importedClasses;  @BeforeEach  public void setup() {        importedClasses = new ClassFileImporter()                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)                .importPackages("com.springboot.testing.archunit");    }  @Test  void servicesAndRepositoriesShouldNotDependOnWebLayer() {      noClasses()                .that().resideInAnyPackage("com.springboot.testing.archunit.service..")                .or().resideInAnyPackage("com.springboot.testing.archunit.repository..")                .should()                .dependOnClassesThat()                .resideInAnyPackage("com.springboot.testing.archunit.controller..")                .because("Services and repositories should not depend on web layer")                .check(importedClasses);    }}

Сервисы и репозитории не должны взаимодействовать с веб-уровнем.

Проверки зависимостей класса

class ArchunitApplicationTests {  private JavaClasses importedClasses;  @BeforeEach    public void setup() {        importedClasses = new ClassFileImporter()                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)                .importPackages("com.springboot.testing.archunit");    }    @Test    void serviceClassesShouldOnlyBeAccessedByController() {        classes()                .that().resideInAPackage("..service..")                .should().onlyBeAccessed().byAnyPackage("..service..", "..controller..")                .check(importedClasses);    }}

ArchUnit предлагает абстрактный API-интерфейс, похожий на DSL, который, в частности, может оценивать импортируемые классы.Доступ к сервисам должен осуществляться только контроллерами.

Две точки представляют любое количество пакетов (сравните AspectJ Pointcuts).

Соглашение об именовании

Java

class ArchunitApplicationTests {    private JavaClasses importedClasses;  @BeforeEach  public void setup() {    importedClasses = new ClassFileImporter()        importedClasses = new ClassFileImporter()                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)                .importPackages("com.springboot.testing.archunit");  }    @Test    void serviceClassesShouldBeNamedXServiceOrXComponentOrXServiceImpl() {        classes()                .that().resideInAPackage("..service..")                .should().haveSimpleNameEndingWith("Service")                .orShould().haveSimpleNameEndingWith("ServiceImpl")                .orShould().haveSimpleNameEndingWith("Component")                .check(importedClasses);    }    @Test    void repositoryClassesShouldBeNamedXRepository() {        classes()                .that().resideInAPackage("..repository..")                .should().haveSimpleNameEndingWith("Repository")                .check(importedClasses);    }    @Test    void controllerClassesShouldBeNamedXController() {        classes()                .that().resideInAPackage("..controller..")                .should().haveSimpleNameEndingWith("Controller")                .check(importedClasses);    }}

Общее правило это соглашение об именах.Например, все имена сервис классов должны заканчиваться на Service, Component и т. д.

Проверка аннотаций

Java

class ArchunitApplicationTests {  private JavaClasses importedClasses;  @BeforeEach  public void setup() {      importedClasses = new ClassFileImporter()              .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)              .importPackages("com.springboot.testing.archunit");  }  @Test  void fieldInjectionNotUseAutowiredAnnotation() {      noFields()              .should().beAnnotatedWith(Autowired.class)              .check(importedClasses);  }  @Test  void repositoryClassesShouldHaveSpringRepositoryAnnotation() {      classes()              .that().resideInAPackage("..repository..")              .should().beAnnotatedWith(Repository.class)              .check(importedClasses);  }  @Test  void serviceClassesShouldHaveSpringServiceAnnotation() {      classes()              .that().resideInAPackage("..service..")              .should().beAnnotatedWith(Service.class)              .check(importedClasses);  }}

API ArchUnit Lang может определять правила для членов классов Java.Это может быть актуально, например, если методы в определенном контексте необходимо аннотировать с помощью определенной аннотации или если типы возвращаемых данных реализуют определенный интерфейс.

Проверки уровней

class ArchunitApplicationTests {private JavaClasses importedClasses;@BeforeEach  public void setup() {        importedClasses = new ClassFileImporter()                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)                .importPackages("com.springboot.testing.archunit");    }    @Test    void layeredArchitectureShouldBeRespected() {layeredArchitecture()                .layer("Controller").definedBy("..controller..")                .layer("Service").definedBy("..service..")                .layer("Repository").definedBy("..repository..")                .whereLayer("Controller").mayNotBeAccessedByAnyLayer()                .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")                .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")                .check(importedClasses);    }}

В приложении Spring Boot уровень сервиса зависит от уровня репозитория, уровень контроллера зависит от уровня сервиса.

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

Полный исходный код примеров можно найти в моемрепозитории GitHub.

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

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

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

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

Это тем более важно, если мы работаем над монолитной кодовой базой, охватывающей множество различных областей бизнеса или ограниченных контекстов, если использовать жаргон Domain-Driven Design.

Как мы можем защитить нашу кодовую базу от нежелательных зависимостей?С тщательным проектированием ограниченных контекстов и постоянным соблюдением границ компонентов.В этой статье показан набор практик, которые помогают в обоих случаях при работе со Spring Boot.

Пример кода

Эта статья сопровождается примером рабочего кодана GitHub.

Видимость Package-Private

Что помогает с соблюдением границ компонентов?Уменьшение видимости.

Если мы используем Package-Private видимость для внутренних классов, доступ будут иметь только классы в одном пакете.Это затрудняет добавление нежелательных зависимостей извне пакета.

Итак, просто поместите все классы компонента в один и тот же пакет и сделайте общедоступными только те классы, которые нам нужны вне компонента.Задача решена?

Нет, на мой взгляд.

Это не работает, если нам нужны подпакеты в нашем компоненте.

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

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

Так что, да, package-private видимость помогает избежать нежелательных зависимостей, но само по себе это, в лучшем случае, неполноценное решение.

Модульный подход к ограниченным контекстам

Что мы можем с этим поделать?Мы не можем полагаться только на package-private видимость.Давайте рассмотрим подход к сохранению нашей кодовой базы чистой от нежелательных зависимостей с использованием интеллектуальной структуры пакета, package-private видимости, где это возможно, и ArchUnit в качестве средства обеспечения там, где мы не можем использовать package-private видимость.

Пример использования

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

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

Чтобы использовать язык Domain-Driven Design (DDD): компонент биллинга реализует ограниченный контекст, который предоставляет варианты использования биллинга.Мы хотим, чтобы этот контекст был как можно более независимым от других ограниченных контекстов.В остальной части статьи мы будем использовать термины компонент и ограниченный контекст как синонимы.

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

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

Классы API и внутренние классы

Давайте посмотрим на структуру пакета, который я предлагаю для нашего биллингового компонента:

billing api internal     batchjob    |    internal     database         api         internal

У каждого компонента и субкомпонента естьinternalпакет, содержащий, ну, внутренние классы, и дополнительныйapiпакет, содержащий, как вы угадали, классы API, которые предназначены для использования другими компонентами.

Такое разделение пакетов междуinternalиapiдает нам несколько преимуществ:

• Мы можем легко вкладывать компоненты друг в друга.

• Легко догадаться, что классы внутриinternalпакета нельзя использовать извне.

• Легко догадаться, что классы внутриinternalпакета можно использовать из его подпакетов.

• Пакеты apiиinternalдают нам инструмент для обеспечения соблюдения правил зависимостей с ArchUnit (подробнее об этомпозже).

• Мы можем использовать столько классов или подпакетов впакетеapiилиinternal, сколько захотим, при этом границы наших компонентов по-прежнему четко определены.

Если возможно, классы внутриinternalпакета должны быть package-private.Но даже если они являются public (и они должны быть public, если мы используем подпакеты), структура пакета определяет четкие и легко отслеживаемые границы.

Вместо того, чтобы полагаться на недостаточную поддержку Java для package-private видимости, мы создали архитектурно выразительную структуру пакета, которая может быть легко реализована с помощью инструментов.

Теперь давайте посмотрим на эти пакеты.

Инверсия зависимостей для предоставления доступа к Package-Private функциям

Начнем сdatabaseподкомпонента:

database api|    + LineItem|    + ReadLineItems|    + WriteLineItems internal     o BillingDatabase

+означает, что класс является public,oозначает, что он является package-private.

databaseКомпонент выставляет API с двумя интерфейсамиReadLineItemsиWriteLineItems, которые позволяют читать и записвысать строку заказа клиента из и в базу данных, соответственно.ТипLineItemдомена также является частью API.

Внутриdatabaseподкомпонент имеет класс,BillingDatabaseреализующий два интерфейса:

@Componentclass BillingDatabase implements WriteLineItems, ReadLineItems {  ...}

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

Обратите внимание, что это применение принципа инверсии зависимостей.

Вместо использованияapiпакета, зависящего отinternalпакета, использется инверсия зависимость.Это дает нам свободу делать вinternalпакете все, что мы хотим, пока мы реализуем интерфейсы вapiпакете.

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

Давайте также заглянем вbatchjobподкомпонент:

Подкомпонент batchjob не предоставляет API доступа к другим компонентам.У него просто есть классLoadInvoiceDataBatchJob(и, возможно, несколько вспомогательных классов), который ежедневно загружают данные из внешнего источника, преобразуют их и передают их в базу данных биллингового компонента черезWriteLineItemsинтерфейс:

@Component@RequiredArgsConstructorclass LoadInvoiceDataBatchJob {  private final WriteLineItems writeLineItems;  @Scheduled(fixedRate = 5000)  void loadDataFromBillingSystem() {    ...    writeLineItems.saveLineItems(items);  }}

Обратите внимание, что мы используем@ScheduledаннотациюSpring,чтобы регулярно проверять наличие новых элементов в биллинговой системе.

Наконец, содержимое компонента верхнего уровняbilling:

billing api|    + Invoice|    + InvoiceCalculator internal     batchjob     database     o BillingService

Компонент billingпредоставляет доступ к интерфейсу InvoiceCalculatorи доменному типуInvoice.Опять же, интерфейс InvoiceCalculatorреализован внутренним классом, который вызываетсяBillingServiceв примере.BillingServiceобращается к базе данных черезReadLineItemsAPI базы данных для создания счета-фактуры клиента из нескольких позиций:

@Component@RequiredArgsConstructorclass BillingService implements InvoiceCalculator {  private final ReadLineItems readLineItems;  @Override  public Invoice calculateInvoice(        Long userId,         LocalDate fromDate,         LocalDate toDate) {        List<LineItem> items = readLineItems.getLineItemsForUser(      userId,       fromDate,       toDate);    ...   }}

Теперь, когда у нас есть чистая структура, нам нужна инъекция зависимостей, чтобы связать все это вместе.

Соединяем все вместе с помощью Spring Boot

Чтобы связать все вместе с приложением, мы используем функцию Spring Java Config и добавляемConfigurationкласс вinternalпакеткаждого модуля:

billing internal     batchjob    |    internal    |        o BillingBatchJobConfiguration     database    |    internal    |        o BillingDatabaseConfiguration     o BillingConfiguration

Эти конфигурации говорят Spring внести набор компонентов Spring в контекст приложения.

Полкомпонент конфигурации databaseвыглядит следующим образом:

@Configuration@EnableJpaRepositories@ComponentScanclass BillingDatabaseConfiguration {}

С помощью аннотации @Configurationмы сообщаем Spring, что это класс конфигурации, который вносит компоненты Spring в контекст приложения.

Аннотация @ComponentScanговорит Spring, что нужно включить все классы ,которые находятся в том же пакете, что икласс конфигурации (или подпакет) и аннотированные с@Componentкак бины в контекст приложения.Это загрузит нашBillingDatabaseкласс, приведенный выше.

Вместо @ComponentScanмы могли бы также использовать@Beanаннотированные фабричные методы внутри@Configurationкласса.

Под капотом для подключения к базе данныхdatabaseмодуль использует репозитории Spring Data JPA.Мы включаем их с помощью аннотации @EnableJpaRepositories.

Конфигурация batchjobвыглядит также:

@Configuration@EnableScheduling@ComponentScanclass BillingBatchJobConfiguration {}

Только аннотация @EnableSchedulingдругая.Нам это нужно, чтобы включить аннотацию @Scheduledв нашем bean-компонентеLoadInvoiceDataBatchJob.

Наконец, конфигурация компонента верхнего уровняbillingвыглядит довольно скучно:

@Configuration@ComponentScanclass BillingConfiguration {}

С помощью аннотации @ComponentScanэта конфигурация гарантирует, что подкомпоненты@Configurationбудут обнаружены Spring и загружены в контекст приложения вместе с их bean-компонентами.

Благодаря этому у нас есть четкое разделение границ не только по измерению пакетов, но и по измерению Spring конфигураций.

Это означает, что мы можем настроить таргетинг на каждый компонент и подкомпонент отдельно, обращаясь к его@Configurationклассу.Например, мы можем:

• Загрузить только один (под) компонент в контекст приложения в рамкахинтеграционного теста SpringBootTest.

• Включить или отключить определенные (под) компоненты, добавиваннотацию @Conditional...к конфигурации этого подкомпонента.

• Заменить компоненты, внесенные в контекст приложения, на (под) компонент, не затрагивая другие (под) компоненты.

Однако у нас все еще есть проблема: классы вbilling.internal.database.apiпакете являются public, то есть к ним можно получить доступ извнеbillingкомпонента, что нам не нужно.

Давайте решим эту проблему, добавив в игру ArchUnit.

Обеспечение границ с помощью ArchUnit

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

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

Маркировка внутренних пакетов

Чтобы управлять нашимиinternalпакетами при создании правил архитектуры, нам нужно как-то пометить их как внутренние.

Мы могли бы сделать это по имени (то есть рассматривать все пакеты с именем internal как внутренние пакеты), но мы также можем отметить пакеты другим именем, для чего создадим аннотацию@InternalPackage:

@Target(ElementType.PACKAGE)@Retention(RetentionPolicy.RUNTIME)@Documentedpublic @interface InternalPackage {}

Затем во все наши внутренние пакеты мы добавляемpackage-info.javaфайл с этой аннотацией:

@InternalPackagepackage io.reflectoring.boundaries.billing.internal.database.internal;import io.reflectoring.boundaries.InternalPackage;

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

Проверка отсутствия доступа к внутренним пакетам извне

Теперь мы создаем тест, который проверяет, что классы в наших внутренних пакетах не доступны извне:

class InternalPackageTests {  private static final String BASE_PACKAGE = "io.reflectoring";  private final JavaClasses analyzedClasses =       new ClassFileImporter().importPackages(BASE_PACKAGE);  @Test  void internalPackagesAreNotAccessedFromOutside() throws IOException {    List<String> internalPackages = internalPackages(BASE_PACKAGE);    for (String internalPackage : internalPackages) {      assertPackageIsNotAccessedFromOutside(internalPackage);    }  }  private List<String> internalPackages(String basePackage) {    Reflections reflections = new Reflections(basePackage);    return reflections.getTypesAnnotatedWith(InternalPackage.class).stream()        .map(c -> c.getPackage().getName())        .collect(Collectors.toList());  }  void assertPackageIsNotAccessedFromOutside(String internalPackage) {    noClasses()        .that()        .resideOutsideOfPackage(packageMatcher(internalPackage))        .should()        .dependOnClassesThat()        .resideInAPackage(packageMatcher(internalPackage))        .check(analyzedClasses);  }  private String packageMatcher(String fullyQualifiedPackage) {    return fullyQualifiedPackage + "..";  }}

ВinternalPackages(), мы используем reflection библиотеку для сбора всех пакетов, аннотированных нашей@InternalPackageаннотацией.

Затем для каждого из этих пакетов мы вызываемassertPackageIsNotAccessedFromOutside().Этот метод использует API-интерфейс ArchUnit, подобный DSL, чтобы гарантировать, что классы, которые находятся вне пакета, не должны зависеть от классов, которые находятся внутри пакета.

Этот тест теперь завершится ошибкой, если кто-то добавит нежелательную зависимость к publicклассу во внутреннем пакете.

Но у нас все еще есть одна проблема: что, если мы переименуем базовый пакет (io.reflectoringв данном случае) в процессе рефакторинга?

Тогда тест все равно пройдет, потому что он не найдет никаких пакетов в (теперь несуществующем)io.reflectoringпакете.Если у него нет пакетов для проверки, он не может потерпеть неудачу.

Итак, нам нужен способ сделать этот тест безопасным при рефакторинге.

Обеспечение безопасного рефакторинга правил архитектуры

Чтобы сделать наш тестовый рефакторинг безопасным, мы проверяем наличие пакетов:

class InternalPackageTests {  private static final String BASE_PACKAGE = "io.reflectoring";  @Test  void internalPackagesAreNotAccessedFromOutside() throws IOException {    // make it refactoring-safe in case we're renaming the base package    assertPackageExists(BASE_PACKAGE);    List<String> internalPackages = internalPackages(BASE_PACKAGE);    for (String internalPackage : internalPackages) {      // make it refactoring-safe in case we're renaming the internal package      assertPackageIsNotAccessedFromOutside(internalPackage);    }  }  void assertPackageExists(String packageName) {    assertThat(analyzedClasses.containPackage(packageName))        .as("package %s exists", packageName)        .isTrue();  }  private List<String> internalPackages(String basePackage) {    ...  }  void assertPackageIsNotAccessedFromOutside(String internalPackage) {    ...  }}

Новый методassertPackageExists()использует ArchUnit, чтобы убедиться, что рассматриваемый пакет содержится в классах, которые мы анализируем.

Мы делаем эту проверку только для базового пакета.Мы не выполняем эту проверку для внутренних пакетов, потому что знаем, что они существуют.В конце концов, мы идентифицировали эти пакеты по@InternalPackageаннотации внутриinternalPackages()метода.

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

Вывод

В этой статье представлен оригинальный подход к использованию пакетов для модульного построения Java-приложения и сочетается его с Spring Boot как механизмом внедрения зависимостей и с ArchUnit для сбоя тестов, когда кто-то добавил недопустимую межмодульную зависимость.

Это позволяет нам разрабатывать компоненты с четкими API и четкими границами, избегая большого шара грязи.

Дайте мне знать свои мысли в комментариях!

Вы можете найти пример приложения, использующего этот подход,на GitHub.

Если вас интересуют другие способы работы с границами компонентов с помощью Spring Boot, вам может бытьинтересен проект moduliths.

Привет Хабр! Зачастую разработчика нанимают для того, чтобы он как профессионал решал проблемы бизнеса. Но иногда ко мнению разработчиков по вопросам, в которых они более компетентны, чем представители бизнеса, не прислушиваются. О том, что с этим можно сделать и зачем это нужно разработчику, я и хотел бы поговорить.

Счастье и удволетворенность работой

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

В мире разработки ПО (software development) есть ряд препятствий, которые не позволяют воспользоваться этим путем к получению удовольствия от работы. Например, разработчик, как профессионал своего дела, может считать, что поддерживаемость системы, проработанная архитектура и правильная организация процессов делают систему более устойчивой к изменениям, тем самым позволяя быстрее разрабатывать новую функциональность и адаптироваться под меняющийся рынок прямая польза для бизнеса. Но представители бизнеса могут считать это ненужной тратой ресурса времени разработчиков.

В чем проблема?

Проблема в том, что бизнес не всегда знает, что для него лучше. Представители бизнеса менеджеры, специалисты по продукту, аналитики и многие другие профессионалы намного лучше разработчика умеют отвечать на вопрос что делать? (произведение Н. Чернышевского не имеет к этому никакого отношения). Но никто не обладает большей экспертизой в разработке ПО чем разработчики (а также архитекторы, технические менеджеры и другие специалисты обладающие знаниями и hard skills в области разработки). Их задача предоставить бизнесу свою экспертизу, валидировать его идеи и отвечать на вопрос как делать?. Идея такого взаимодействия лежит в основе методологии Agile (https://agilemanifesto.org/).

Внимательный читатель заметит, как я прибегаю к приему *argumentum ad auctoritatem (аргумент к авторитету).* Но в мире мнений и субъективных суждений, в котором мы живем это хороший прием, и я советую прибегать в том числе и к нему для донесения профессионалом своей идеи.

Мнение профессионала о том, что полезно для бизнеса субъективно. Это мнение, которое, возможно, не является истиной в последней инстанции и, как любое мнение, может быть ошибочно errare humanum est. Тем не менее, я считаю что разработчику стоит бороться за те идеи, в которые он верит как профессионал.

Что можно попробовать сделать?

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

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

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

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

Кого и как убеждать?

Если с идеей разработчика согласны все, кто влияет на ее принятие, тогда она принимается и результатом становится однозначный успех. Но эта ситуация выглядит идеализированной, и, скорее всего, возникнут спорные ситуации, которые потребуют разрешения. Я считаю, что в случае разработки ПО есть две стороны, которые разработчик может убедить в правоте своих суждений. Первая горизонтальная это другие разработчики, так как невозможно внедрить практики, например TDD (разработка через тестирование) или code review, если это делает один человек в команде. Вторая вертикальная представители бизнеса, так как применение best practices, особенно когда их внедрение только начинаются, требует времени разработчиков.

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

А использование административного ресурса это как раз возможная необходимость разрешения вертикальных споров. Разработчику необходимо убедить представителей бизнеса в том, что его идея принесет пользу компании. Бизнесу нужна причина тратить ресурсы, поэтому нужно ясно объяснить, что внедрение best practices разработки это инвестиция. Здесь также инструментами убеждения являются все возможные приемы риторики, а также, возможно, работа с данными, поиск примеров и апелляция к авторитету.

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

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

Заключение

Эта статья глубоко субъективное мнение о том, как разработчику получать больше удовольствия от своей работы за счет проявления профессионализма и донесения до бизнеса субъективных идей, которые разработчик, как профессионал, считает верными. Статья во многом вдохновлена идеями Agile, книгой Clean Architecture Роберта Мартина, а также собственным опытом, переживаниями и опытом знакомых и коллег.