Пишем хорошие компоненты, которые захочется переиспользовать, а плохие — не пишем

Привет! Меня зовут Антон Крылов, я фронтенд-разработчик в Авито — занимаюсь профилями. До Авито я работал тимлидом и видел много хорошего и плохого кода. В этой статье — мои наблюдения и размышления на тему, как сделать компонент, который приятно использовать и который не придётся переписывать через время.

Прежде чем говорить о том, как написать хороший компонент, давайте поговорим о том, как делать точно не нужно.

Плохой компонент — сложный

Компонент можно назвать сложным, если:

1. У него нет тестов. Такой компонент без будет тяжело использовать извне, а расширять — ещё сложнее. 

2. Он делает слишком много. Я встречал компоненты на 1000–2000 строк, которые умеют всё. Но чтобы что-то поправить в таком компоненте, может понадобиться целый спринт.

3. Он Overengineered. Разработчики часто грешат добавлением искусственных сложностей в код. Например: 

• useEffect вместо useCallback. Я периодически встречаю такой кейс, когда в одном месте обрабатываются действия после изменения state, которое происходит где-то глубоко в компонентах фильтра. Почитайте, почему это не лучшее решение.

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

• Лишние слои абстракции. Иногда их плодят, чтобы весь код переиспользовался как можно больше, а в итоге потребности в переиспользовании нет. 

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

Плохой компонент — неконсистентный

Это компонент, чьё состояние или пропсы не соответствуют ожидаемому поведению. 

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

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

export interface TextFieldProps extends
Omit<React.HTMLProps<HTMLInputElement>,
'onChange'> {
	...
	errorText?: string;
	validation?: (value: string) => boolean;
	...
}

Но такое решение — неконсистентное. Если по ошибке передать в TextField только один из пропов, ничего работать не будет.

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

export interface TextFieldProps extends
Omit<React.HTMLProps<HTMLInputElement>,
'onChange'> {
	...
	validationProps?: {
	errorText: string;
	validation: (value: string) => boolean;
	},
	...
}

Лучшее решение для консистентности — пользоваться правилом «single prop — single logic» — на каждый проп должна быть своя логика:

export interface TextFieldProps extends
Omit<React.HTMLProps<HTMLInputElement>,
'onChange'> {
	...
	validation: (value: string) => string;
	...
}

Другие признаки плохого компонента

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

Отображение на флагах. Проблема в том, что рано или поздно количество флагов разрастётся. И тогда будет тяжело разобраться, что происходит в коде.

return isCreateForm ? <CreateForm /> : <EditForm />

Если без флагов никак не обойтись — делайте маппинг.

const forms = {
	createForm: CreateForm,
	editForm: EditForm
};

interface Props {
	formName: keyof typeof forms;
}

const Form = ({ formName }: Props) => {
	const Component = forms[formName];

	return <Component />
}

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

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

function TextField({
	withoutImplicitFocus,
	disabled,
	onFocus,
	hasLowerCase,
	hasAutoSelectAfterSubmit,
	onChange: onChangeProp,
	hasAutoSelect = true,
	selector = DEFAULT_SELECTOR,
	inputSize = "l",
	priority = 0,
	dataE2e = selector || DEFAULT_SELECTOR,
	dataTestId = selector || DEFAULT_SELECTOR,
	handleEnter = selectOnEnter,
	transformValueOnChange = transformToUppercase,
	onKeyDown = noop,
	useSuperFocus = useSuperFocusDefault,
	useFocusAfterError = useFocusAfterErrorDefault,
	useSuperFocusOnKeydown = useSuperFocusOnKeydownDefault,
	useSuperFocusAfterDisabled = useSuperFocusAfterDisabledDefault,
	someJSX,
	...textFieldProps
}: Props)

Чтобы избежать Props Hell, можно разбить компонент на более мелкие или использовать контекст.

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

Функциональные требования хорошего компонента

Функциональные требования к компонентам говорят о том, что они должны уметь делать и как должны выглядеть. 

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

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

Нефункциональные требования хорошего компонента

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

Вот какие нефункциональные характеристики есть у компонентов:

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

Коробочность — насколько просто пользоваться компонентом извне. Допустим, у нас есть компонент Table, который принимает только URL. Передавать данные таблицы через URL неудобно — это плохое решение для внешнего API. Но это может быть и хорошим решением — например, для CRUD-таблицы, где все данные ± однотипны.

interface Props {
	entryUrl: string;
}

const Table = ({ entryUrl }: Props) => {
	const { rows, headers } = useDataFromUrl(entryUrl);
	…
}

Зависимость — насколько компонент зависим от других компонентов. Если у компонента много зависимостей, он менее гибкий и более хрупкий.

Явность — насколько глубоко нужно знать бизнес-логику или быть погружённым в проект, чтобы работать с компонентом. Допустим, у нас есть компонент PrimaryButton. Для того, чтобы понять, что происходит, нужны знания о дизайн-системе: например, что из себя представляет variant='primary'

const PrimaryButton = ({ children }: Props) => {
	return (
		<Button variant='primary'>{children}</Button>
	)
}

Если хочется сделать код более явным, лучше избегать таких ситуаций. Например, вместо variant='primary' можно использовать более очевидный вариант — прокинуть код цвета:

const PrimaryButton = ({ children }: Props) => {
	return (
		<Button color='#f00'>{children}</Button>
	)
}

Функциональность — сколько возможностей предоставляет компонент. Например, у нас есть компонент BasicForm, который и отрисовывает форму, и умеет отправлять данные по нажатию Submit.

function BasicForm() {
  const form = useForm({
    onSubmit: (values) => {
      alert(JSON.stringify(values, null, 2));
      console.log('values', values);
    },
    children: [
      {
        label: 'First Name',
        name: 'firstName',
        component: 'Input',
        value: '',
      },
      {
        component: 'Submit',
        text: 'submit',
      },
    ],
  });
  return <Form form={form} />;
}

Хороший компонент — соответствует запросам

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

Допустим, у нас есть UI-кит. Рассмотрим, как характеристики будут меняться в зависимости от ситуации.

Ситуация 1: UI-кит используется во многих проектах. Так обычно и бывает: чаще всего наборы компонентов используются в большом количестве проектов. 

Тогда возникают такие нефункциональные требования:

• Переопределение стилей должно быть возможным только на уровне темы — для единообразия и согласованности дизайна.

• В наборе должно быть как можно меньше зависимостей — чтобы UI-кит меньше весил.

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

  

Ситуация 2: UI-кит используется в ограниченном количестве проектов. Допустим, мы точно знаем, что набор не будет использоваться в множестве проектов.

Тогда нефункциональные характеристики поменяются:

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

• Функциональности должно быть больше, чтобы на уровне конкретного проекта приходилось делать как можно меньше.

• Явность API не так важна — важнее функциональность. 

Как написать хороший компонент

У хорошего компонента характеристики соответствуют сценарию его использования. Давайте разберёмся, как влиять на нефункциональные требования, чтобы «подгонять» их под запросы для каждого конкретного компонента. 

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

Использовать Dependency Injection (DI), если нужны гибкость и независимости. Dependency Injection позволяет вынести создание объектов и управление их зависимостями за пределы класса — это делает код более гибким и расширяемым.

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

Вернёмся к примеру с компонентом TextField. В нём много потенциальных мест для использования Dependency Injection. Например, вместо пропса handleEnter можно прокинуть функцию, а вместо useSuperFocus — хук.

function TextField({
	withoutImplicitFocus,
	disabled,
	onFocus,
	hasLowerCase,
	hasAutoSelectAfterSubmit,
	onChange: onChangeProp,
	hasAutoSelect = true,
	selector = DEFAULT_SELECTOR,
	inputSize = "l",
	priority = 0,
	dataE2e = selector || DEFAULT_SELECTOR,
	dataTestId = selector || DEFAULT_SELECTOR,
	// вместо пропса ниже можно прокинуть функцию
	handleEnter = selectOnEnter,
	transformValueOnChange = transformToUppercase,
	onKeyDown = noop,
	// вместо пропса ниже можно использовать хук
	useSuperFocus = useSuperFocusDefault,
	useFocusAfterError = useFocusAfterErrorDefault,
	useSuperFocusOnKeydown = useSuperFocusOnKeydownDefault,
	useSuperFocusAfterDisabled = useSuperFocusAfterDisabledDefault,
	someJSX,
	...textFieldProps
}: Props)

Dependency Injection в React осуществляет функция inject. Подробнее об этом можно почитать в GitHub-репозитории react-ioc.

Также могут пригодиться:

• Расширение vscode-dependency-cruiser для VS Code — для генерации графа зависимостей из любого JS-файла

• Библиотека inversify-react — для внедрения зависимостей в компоненты в React-приложениях

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

Например, можно оставить общее поведение формы BasicForm (из примера выше) в хуках:

import { useForm } from "react-hook-form";

export default function App() {
  const { register, handleSubmit } = useForm({ shouldUseNativeValidation: true });

  const onSubmit = async (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName", { required: "Please enter your first name." })} />
      <input type="submit" />
    </form>
  );
}

В такой ситуации можно легко сделать хоть 1000 таких форм — каждый раз переписывать их не придётся.

TL;DR

1. Плохой компонент — сложный и неконсистентный.

2. У компонентов есть характеристики — нефункциональные требования:

• гибкость;

• коробочность;

• зависимость;

• явность;

• функциональность.

3. У хорошего компонента характеристики соответствуют запросам и требованиям.

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

• тесты;

• Dependency Injection;

• DSL-like подход.

Полезные ресурсы

Моя статья на русском: Гайд по написанию и рефакторингу компонентов, которые хочется переиспользовать →

Статьи на английском:

• You Might Not Need An Effect →

• Don't useEffect as callback →

• 5 Common mistakes to avoid when using react Hooks → 

GitHub-репозитории:

• Использование функции inject в React →

• Расширение vscode-dependency-cruiser для VS Code — для генерации графа зависимостей из любого JS-файла →

• Библиотека inversify-react — для внедрения зависимостей в компоненты в React-приложениях →

Предыдущая статья: Разработка — всё? Действительно ли нас всех заменят роботы?