[Перевод] Структурирование React-приложений
Материал, перевод которого мы сегодня публикуем, раскрывает подходы, применяемые его автором при структурировании React-приложений. В частности, речь здесь пойдёт об используемой структуре папок, об именовании сущностей, о местах, где располагаются файлы тестов, и о других подобных вещах.
Одна из наиболее приятных возможностей React заключается в том, что эта библиотека не принуждает разработчика к строгому соблюдению неких соглашений, касающихся структуры проекта. Многое в этом плане остаётся на усмотрение программиста. Этот подход отличается от того, который, скажем, принят во фреймворках Ember.js или Angular. Они дают разработчикам больше стандартных возможностей. В этих фреймворках предусмотрены и соглашения, касающиеся структуры проектов, и правила именования файлов и компонентов.
Лично мне нравится подход, принятый в React. Дело в том, что я предпочитаю контролировать что-либо сам, не полагаясь на некие «соглашения». Однако много плюсов есть и у того подхода к структурированию проектов, который предлагает тот же Angular. Выбор между свободой и более или менее жёсткими правилами сводится к тому, что именно ближе вам и вашей команде.
За годы работы с React я испробовал множество различных способов структурирования приложений. Некоторые из применённых мной идей оказались более удачными, чем другие. Поэтому здесь я собираюсь рассказать обо всём том, что хорошо показало себя на практике. Я надеюсь, что вы найдёте здесь что-то такое, что пригодится и вам.
Я не стремлюсь показать здесь некий «единственно правильный» способ структурирования приложений. Вы можете взять какие-то мои идеи и изменить их под свои нужды. Вы вполне можете со мной и не согласиться, продолжив работать так, как работали раньше. Разные команды создают разные приложения и используют разные средства для достижения своих целей.
Важно отметить, что если вы заглянете на сайт Thread, в разработке которого я участвую, и посмотрите на устройство его интерфейса, то вы обнаружите там места, в которых те правила, о которых я буду говорить, не соблюдаются. Дело в том, что любые «правила» в программировании стоит воспринимать лишь как рекомендации, а не как всеохватывающие нормативы, которые справедливы в любых ситуациях. И если вы думаете, что какие-то «правила» вам не подходят — вы, ради повышения качества того, над чем работаете, должны находить в себе силу отступать от этих «правил».
Собственно говоря, теперь, без лишних слов, предлагаю вам мой рассказ о структурировании React-приложений.
Не стоит слишком сильно беспокоиться о правилах
Возможно, вы решите, что рекомендация о том, что не стоит слишком волноваться о правилах, выглядит в начале нашего разговора странно. Но я имею в виду именно это, когда говорю, что главная ошибка, возникающая у программистов в плане соблюдения правил, заключается в том, что программисты придают правилам слишком большое значение. Это особенно справедливо в начале работы над новым проектом. В момент создания первого index.jsx попросту невозможно знать о том, что лучше всего подойдёт для этого проекта. По мере того, как проект будет развиваться, вы совершенно естественным образом выйдете на некую структуру файлов и папок, которая, вероятно, будет весьма неплохо для этого проекта подходить. Если же в ходе продолжения работы окажется, что сложившаяся структура в чём-то неудачна, её можно будет улучшить.
Если вы читаете это и ловите себя на мысли о том, что в вашем приложении нет ничего такого, о чём тут идёт речь, то это — не проблема. Каждое приложение своеобразно, не существует двух абсолютно одинаковых команд разработчиков. Поэтому каждая команда, работая над проектом, приходит к неким соглашениям относительно его структуры и методики работы над ним. Это помогает членам команды трудиться продуктивно. Не стремитесь к тому, чтобы, узнав о том, как кто-то что-то делает, немедленно вводить подобное и у себя. Не пытайтесь внедрить в свою работу то, что названо в неких материалах, да хотя бы и в этом, «наиболее эффективным способом» решения некоей задачи. Я всегда придерживался и придерживаюсь следующей стратегии относительно подобных рекомендаций. У меня есть собственный набор правил, но, читая о том, как в тех или иных ситуациях поступают другие, я выбираю то, что мне кажется удачным и подходящим мне. Подобное приводит к тому, что со временем мои методы работы совершенствуются. При этом у меня не случается никаких потрясений и не возникает желания переписывать всё с нуля.
Важные компоненты размещаются в отдельных папках
Подход к размещению файлов компонентов по папкам, к которому я пришёл, заключается в том, что те компоненты, которые в контексте приложения можно считать «важными», «базовыми», «основными», размещаются в отдельных папках. Эти папки, в свою очередь, размещаются в папке components. Например, если речь идёт о приложении для электронного магазина, то подобным компонентом можно признать компонент
- src/
- components/
- product/
- product.jsx
- product-price.jsx
- navigation/
- navigation.jsx
- checkout-flow/
- checkout-flow.jsx
При этом «второстепенные» компоненты, которые используются только некими «основными» компонентами, располагаются в той же папке, что и эти «основные» компоненты. Этот подход хорошо показал себя на практике. Дело в том, что благодаря его применению в проекте появляется некая структура, но уровень вложенности папок оказывается не слишком большим. Его применение не приводит к появлению чего-то вроде ../../../ в командах импорта компонентов, он не затрудняет перемещение по проекту. Этот подход позволяет построить чёткую иерархию компонентов. Тот компонент, имя которого совпадает с именем папки, считается «базовым». Другие компоненты, находящиеся в той же папке, служат цели разделения «базового» компонента на части, что упрощает работу с кодом этого компонента и его поддержку.
Хотя я и являюсь сторонником наличия в проекте некоей структуры папок, я считаю, что самое главное — это подбор хороших имён файлов. Папки, сами по себе, менее важны.
Использование вложенных папок для подкомпонентов
Один из минусов вышеописанного подхода заключается в том, что его применение может привести к появлению папок «базовых» компонентов, содержащих очень много файлов. Рассмотрим, например, компонент
Я, на самом деле, не особенно об этом беспокоюсь. Меня это устраивает в том случае, если файлы имеют продуманные имена, и если их легко можно найти (с помощью средств поиска файлов в редакторе). Если всё так и есть, то структура папок отходит на второй план. Вот твит на эту тему.
Однако если вы предпочитаете, чтобы ваш проект имел бы более разветвлённую структуру, нет ничего сложного в том, чтобы переместить подкомпоненты в их собственные папки:
- src/
- components/
- product/
- product.jsx
- ...
- product-price/
- product-price.jsxФайлы тестов располагаются там же, где и файлы проверяемых компонентов
Начнём этот раздел с простой рекомендации, которая заключается в том, что файлы тестов стоит размещать там же, где и файлы с кодом, который с их помощью проверяют. Я ещё расскажу о том, как я предпочитаю структурировать компоненты, стремясь к тому, чтобы они находились бы поблизости друг от друга. Но сейчас я могу сказать, что нахожу удобным размещать файлы тестов в тех же папках, что и файлы компонентов. При этом имена файлов с тестами идентичны именам файлов с кодом. К именам тестов, перед расширением имени файла, лишь добавляется суффикс .test:
- Имя файла компонента:
auth.js. - Имя файла теста:
auth.test.js.
У такого подхода есть несколько сильных сторон:
- Он облегчает поиск файлов тестов. С одного взгляда можно понять то, существует ли тест для компонента, с которым я работаю.
- Все необходимые команды импорта оказываются очень простыми. В тесте, для импорта тестируемого кода, не нужно создавать структуры, описывающие, скажем, выход из папки
__tests__. Подобные команды выглядят предельно просто. Например — так:import Auth from './auth'.
Если у нас имеются некие данные, используемые в ходе теста, например — нечто вроде моков запросов к API, мы помещаем и их в ту же папку, где уже лежит компонент и его тест. Когда всё, что может понадобиться, лежит в одной папке, это способствует росту продуктивности работы. Например, если используется разветвлённая структура папок и программист уверен в том, что некий файл существует, но не может вспомнить его имя, программисту придётся выискивать этот файл во множестве вложенных директорий. При предлагаемом подходе достаточно взглянуть на содержимое одной папки и всё станет ясно.
CSS-модули
Я — большой поклонник CSS-модулей. Мы обнаружили, что они отлично подходят для создания модульных CSS-правил для компонентов.
Я, кроме того, очень люблю технологию styled-components. Однако в ходе работы над проектами, в которой участвует много разработчиков, оказалось, что наличие в проекте реальных CSS-файлов повышает удобство работы.
Как вы уже, наверное, догадались, наши CSS-файлы располагаются, как и другие файлы, рядом с файлами компонентов, в тех же самых папках. Это значительно упрощает перемещение между файлами тогда, когда нужно быстро понять смысл того или иного класса.
Более общая рекомендация, суть которой пронизывает весь этот материал, заключается в том, что весь код, имеющий отношение к некоему компоненту, стоит держать в той же папке, в которой находится этот компонент. Прошли те дни, когда отдельные папки использовались для хранения CSS и JS-кода, кода тестов и прочих ресурсов. Использование сложных структур папок усложняет перемещение между файлами и не несёт в себе никакой очевидной пользы за исключением того, что это помогает «организовывать код». Держать в одной и той же папке взаимосвязанные файлы — это значит тратить меньше времени на перемещение между папками в ходе работы.
Мы даже создали Webpack-загрузчик для CSS, возможности которого соответствуют особенностям нашей работы. Он проверяет объявленные имена классов и выдаёт ошибку в консоль в том случае, если мы ссылаемся на несуществующий класс.
Почти всегда в одном файле размещается код лишь одного компонента
Мой опыт показывает, что программисты обычно слишком жёстко придерживаются правила, в соответствии с которым в одном файле должен находиться код одного и только одного React-компонента. При этом я вполне поддерживаю идею, в соответствии с которой не стоит размещать в одном файле слишком много компонентов (только представьте себе сложности именования таких файлов!). Но я полагаю, что нет ничего плохого в том, чтобы поместить в тот же файл, в котором размещён код некоего «большого» компонента, и код «маленького» компонента, связанного с ним. Если подобный ход способствует сохранению чистоты кода, если «маленький» компонент не слишком велик для того, чтобы помещать его в отдельный файл, то это никому не повредит.
Например, если я создаю компонент
const Price = ({ price, currency }) => (
{currency}
{formatPrice(price)}
)
const Product = props => {
// представьте, что здесь находится большой объём кода!
return (
В этом подходе хорошо то, что мне не пришлось создавать отдельный файл для компонента
Выделение отдельных папок для универсальных компонентов
Мы в последнее время пользуемся универсальными компонентами. Они, фактически, формируют нашу дизайн-систему (которую мы рассчитываем когда-нибудь опубликовать), но пока мы начали с малого — с компонентов вроде и
Подобные компоненты располагаются в собственной папке (src/components/generic). Это значительно упрощает работу со всеми универсальными компонентами. Они находятся в одном месте — это очень удобно. Со временем, по мере роста проекта, мы планируем разработать руководство по стилю (мы — большие любители react-styleguidist) для того чтобы ещё больше упростить работу с универсальными компонентами.
Использование псевдонимов для импорта сущностей
Сравнительно плоская структура папок в наших проектах способствует тому, что в командах импорта нет слишком длинных конструкций вроде ../../. Но совсем без них обойтись сложно. Поэтому мы использовали babel-plugin-module-resolver для настройки псевдонимов, которые упрощают команды импорта.
Сделать то же самое можно и с помощью Webpack, но благодаря использованию плагина Babel такие же команды импорта могут работать и в тестах.
Мы настроили это с помощью пары псевдонимов:
{
components: './src/components',
'^generic/([\\w_]+)': './src/components/generic/\\1/\\1',
}
Первый устроен чрезвычайно просто. Он позволяет импортировать любой компонент, начиная команду со слова components. При обычном подходе команды импорта выглядят примерно так:
import Product from '../../components/product/product'
Мы вместо этого можем записывать их так:
import Product from 'components/product/product'
Обе команды приводят к импорту одного и того же файла. Это очень удобно, так как позволяет не задумываться о структуре папок.
Второй псевдоним устроен немного сложнее:
'^generic/([\\w_]+)': './src/components/generic/\\1/\\1',
Мы используем здесь регулярное выражение. Оно находит команды импорта, которые начинаются с generic (знак ^ в начале выражения позволяет отобрать только те команды, которые начинаются с generic), и захватывает то, что находится после generic/, в группу. После этого мы используем захваченный фрагмент (\\1) в конструкции ./src/components/generic/\\1/\\1.
В результате мы можем пользоваться командами импорта универсальных компонентов такого вида:
import Button from 'generic/button'
Они преобразуются в такие команды:
import Button from 'src/components/generic/button/button'
Эта команда, например, служит для импорта JSX-файла, описывающего универсальную кнопку. Сделали мы всё это из-за того, что подобный подход значительно упрощает импорт универсальных компонентов. Кроме того, он сослужит нам хорошую службу в том случае, если мы решим изменить структуру файлов проекта (это, так как наша дизайн-система растёт, вполне возможно).
Тут мне хотелось бы отметить, что при работе с псевдонимами стоит соблюдать осторожность. Если у вас их всего несколько, и они предназначены для решения стандартных задач импорта — то всё нормально. Но если их у вас будет много — они могут принести больше путаницы, чем пользы.
Универсальная папка lib для утилит
Хотелось бы мне вернуть себе всё то время, которое я потратил на то, чтобы отыскать идеальное место для кода, который не является кодом компонентов. Я разделял это всё по разным принципам, выделяя код утилит, сервисов, вспомогательных функций. У всего этого так много названий, что все их я и не упомню. Теперь же я не пытаюсь выяснить разницу между «утилитой» и «вспомогательной функцией» для того чтобы подобрать подходящее место для некоего файла. Теперь я использую гораздо более простой и понятный подход: всё это попадает в единственную папку lib.
В долгосрочной перспективе размер этой папки может оказаться настолько большим, что придётся её как-то структурировать, но это совершенно нормально. Всегда легче оснастить что-то некоей структурой, чем избавляться от ошибок чрезмерного структурирования.
В нашем проекте Thread папка lib содержит около 100 файлов. Они разделены примерно поровну на файлы, содержащие реализацию неких возможностей, и на файлы тестов. Сложностей при поиске нужных файлов это не вызывало. Благодаря интеллектуальным системам поиска, встроенным в большинство редакторов, мне, практически всегда, достаточно ввести нечто вроде lib/name_of_thing, и то, что мне нужно, оказывается найденным.
Кроме того, у нас имеется псевдоним, который упрощает импорт из папки lib, позволяя пользоваться командами такого вида:
import formatPrice from 'lib/format_price'
Не пугайтесь плоских структур папок, при использовании которых одна папка может хранить множество файлов. Обычно такая структура — это всё, что нужно для некоего проекта.
Сокрытие библиотек сторонней разработки за собственными API
Мне очень нравится система мониторинга ошибок Sentry. Я часто пользовался ей при разработке серверных и клиентских частей приложений. С её помощью можно захватывать исключения и получать уведомлений об их возникновении. Это — отличный инструмент, который позволяет нам быть в курсе проблем, возникающих на сайте.
Всякий раз, когда я используют в своём проекте библиотеку стороннего разработчика, я думаю о том, как сделать так, чтобы, при необходимости, её можно было бы как можно легче заменить на что-то другое. Часто, как с той же системой Sentry, которая нам очень нравится, в этом необходимости нет. Но, на всякий случай, никогда не помешает продумать путь ухода от использования некого сервиса или путь смены его на что-то другое.
Лучшим решением подобной задачи является разработка собственного API, скрывающего чужие инструменты. Это — нечто вроде создания модуля lib/error-reporting.js, который экспортирует функцию reportError(). В недрах этого модуля используется Sentry. Но Sentry напрямую импортируется только в этом модуле и нигде больше. Это означает, что замена Sentry на другой инструмент будет выглядеть очень просто. Для этого достаточно будет поменять один файл в одном месте. До тех пор, пока общедоступный API этого файла остаётся неизменным, остальная часть проекта не будет даже знать о том, что при вызове reportError() используется не Sentry, а что-то другое.
Обратите внимание на то, что общедоступным API модуля называют экспортируемые им функции и их аргументы. Их ещё называют общедоступным интерфейсом модуля.
Использование PropTypes (либо таких средств, как TypeScript или Flow)
Когда я занимаюсь программированием, я думаю о трёх версиях самого себя:
- Джек из прошлого и код, который он написал (иногда — сомнительный код).
- Сегодняшний Джек, и тот код, который он пишет сейчас.
- Джек из будущего. Когда я думаю об этом будущем себе, я спрашиваю себя настоящего о том, как мне писать такой код, который облегчит мне в будущем жизнь.
Может, это прозвучит странновато, но я обнаружил, что полезно, размышляя о том, как писать код, задаваться следующим вопросом: «Как он будет восприниматься через полгода?».
Один из простых способов сделать себя настоящего и себя будущего продуктивнее заключается в указании типов свойств (PropTypes), используемых компонентами. Это позволит сэкономить время на поиск возможных опечаток. Это убережёт от ситуаций, когда, пользуясь компонентом, применяют свойства неправильных типов, или вовсе забывают о передаче свойств. В нашем случае хорошим напоминанием о необходимости использования PropTypes служит правило eslint-react/prop-types.
Если пойти ещё дальше, то рекомендуется описывать свойства как можно точнее. Например, можно поступить так:
blogPost: PropTypes.object.isRequired
Но гораздо лучше будет сделать так:
blogPost: PropTypes.shape({
id: PropTypes.number.isRequired,
title: PropTypes.string.isRequired,
// и так далее
}).isRequired
В первом примере выполняется минимально необходимая проверка. Во втором разработчику даётся гораздо больше полезных сведений. Они придутся очень кстати, например, в том случае, если некто забудет о некоем поле, используемом в объекте.
Сторонние библиотеки используются лишь тогда, когда они по-настоящему нужны
Этот совет сегодня, с появлением хуков React, актуален как никогда. Например, я занимался большой переделкой одной из частей сайта Thread и решил обратить особое внимание на использование сторонних библиотек. Я предположил, что используя хуки и некоторые собственные наработки, я смогу сделать много всего и без использования чужого кода. Моё предположение (что стало приятной неожиданностью), оказалось верным. Об этом можно почитать здесь, в материале про управление состоянием React-приложений. Если вас привлекают подобные идеи — учитывайте то, что в наши дни, благодаря хукам React и API Context, в реализации этих идей можно зайти очень далеко.
Конечно, некоторые вещи, вроде Redux, в определённых обстоятельствах необходимы. Я посоветовался бы не стремиться к тому, чтобы совершенно сторониться подобных решений (и не стоит ставить во главу угла уход от них в том случае, если вы уже ими пользуетесь). Но, если у вас возникает мысль о включении в проект новой библиотеки, вам стоит знать, что это далеко не всегда является единственным вариантом решения некоей задачи.
Неприятные особенности генераторов событий
Генератор событий — это паттерн проектирования, который позволяет наладить взаимодействие между парой компонентов, не связанных напрямую. Раньше я часто пользовался этим паттерном.
// первый компонент генерирует событие
emitter.send('user_add_to_cart')
// второй компонент принимает событие
emitter.on('user_add_to_cart', () => {
// делаем что-то полезное
})
Я объяснял использование этого паттерна тем, что при таком подходе компоненты могут быть полностью отделены друг от друга. Я оправдывал этот подход тем, что компоненты могут обмениваться данными исключительно с помощью механизма отправки и обработки событий. Неприятности мне принесло как раз то, что компоненты «отделены друг от друга». Хотя может показаться, что компоненты и являются самостоятельными сущностями, я сказал бы, что это не так. Они всего лишь имеют неявную зависимость друг от друга. «Неявной» эту зависимость я называю преимущественно из-за того, что я считал сильной стороной этого паттерна. А именно, речь идёт о том, что компоненты не знают о существовании друг друга.
Нечто подобное можно обнаружить в Redux. Компоненты напрямую друг с другом не общаются. Они взаимодействуют с дополнительной структурой, называемой действием. Логика того, что происходит при возникновении события, вроде user_add_to_cart, находится в редьюсере. В результате всем этим становится легче управлять. Кроме того, инструменты, используемые при разработке приложений с применением Redux, упрощают поиск действий и их источников. В результате те дополнительные структуры, которые используются в Redux при работе с событиями, оказывают положительное влияние на проект.
После того, как мне довелось поработать над многими проектами, полными генераторов событий, я обнаружил, что там регулярно происходит следующее:
- Некий код, ожидающий появления событий, удаляют. После этого генераторы событий отправляют эти события в пустоту.
- Некий код, отправляющий события, тоже могут удалить. В результате прослушиватели событий ожидают возникновения событий, которые ничто не генерирует.
- Некое событие, которое кто-то счёл неважным, удаляют. Это, так как событие было важным, серьёзно нарушает работу проекта.
Всё это плохо из-за того, что ведёт к неопределённости. Это ведёт к тому, что программист теряет уверенность в правильности устройства кода, над которым работает. Когда программист не знает о том, может ли он спокойно удалить некий фрагмент кода, вроде бы ненужный, этот фрагмент кода обычно не удаляется и в проекте накапливается «мёртвый» код.
В современных условиях я решал бы задачи, которые можно решить с помощью генераторов событий, используя API Context или свойства-коллбэки.
Упрощение тестирования с использованием специальных утилит
В итоге мне хотелось бы дать ещё один совет, касающийся тестирования компонентов (я, кстати, написал об этом учебный курс). Этот совет заключается в следующем: создайте набор вспомогательных функций, которые позволят упростить процесс тестирования компонентов.
Например, однажды я написал приложение, в котором статус аутентификации пользователя хранился в небольшом фрагменте контекста, который был нужен множеству компонентов. В каждом тесте я мог бы поступить так:
const wrapper = mount(
)
Я же написал небольшой вспомогательный механизм:
const wrapper = mountWithAuth(ComponentUnderTest, {
name: 'Jack',
userId: 1,
})
У такого подхода имеется множество сильных сторон:
- Каждый тест оказывается предельно понятным. При взгляде на тест сразу ясно — работает ли он в условиях, когда пользователь вошёл в систему, или в условиях, когда пользователь в неё не вошёл.
- Если реализация механизма аутентификации изменяется — я могу обновить
mountWithAuthи все мои тесты продолжат нормально работать. Всё дело в том, что логика аутентификации в моей системе размещается в одном месте.
Не опасайтесь того, что вы создадите слишком много подобных вспомогательных утилит в файле test-utils.js. То, что их у вас будет много — это вполне нормально. Такие утилиты упростят процесс тестирования ваших проектов.
Итоги
Здесь я поделился многим из своего опыта. Мои советы направлены на то, чтобы улучшить поддерживаемость кодовой базы, и, что важнее, сделать работу над растущими проектами приятнее. Хотя у каждой кодовой базы есть собственные старые проблемы, существуют приёмы, которые позволяют смягчить негативные воздействия этих проблем на проекты и не допустить появления новых. В начале материала я уже об этом говорил, но повторюсь снова: любые советы стоит рассматривать лишь как рекомендации. При применении чужих идей к конкретному проекту они преобразовываются в соответствии со спецификой этого проекта. Ведь все мы имеем разные мнения относительно структуры проектов и по-разному подходим к решению различных задач, касающихся разработки приложений.
Уважаемые читатели! Как вы структурируете ваши React-приложения?
