Лучшая система именования и организации файлов
Проклятие и дар React.js заключается в том, что он не самоуверен в том, как вы структурируете свои компоненты и файлы. Делайте, что хотите, и это сработает. Но с каждым новым проектом это проблема «чистого листа».
Эта статья написана с точки зрения человека, создающего (и, наконец, рефакторинга) интерфейса платформы для ведения блогов, предназначенной для энтузиастов пленочной фотографии. Помимо перечисления и отображения статей, приложение предоставляет административные элементы управления и полный набор редакторов форматированного текста, состоящий из 280 файлов и папок. Речь идет о приложении Analog.Cafe.
Предисловие 1: «глупые» и «умные» компоненты: не лучший способ сортировать файлы.
- app/ - components/ - containers/
Когда я начал работать над своим приложением после года интенсивных сборок Ruby on Rails для Archie.AI (довольно самоуверенный фреймворк), я упал на стену, пытаясь выяснить, как структурировать и назвать многочисленные файлы с помощью React. . В то время наиболее распространенным советом было разделить компоненты на чистые функции и компоненты с отслеживанием состояния.
Ожидается, что при использовании этого метода ваши компоненты неизбежно будут повторно использованы где-то еще. Хотя это может быть верно для многих проектов, я не могу понять, как это может быть применимо ко всем приложениям. Более того, разделение функциональности на части и размещение частей компонента, выполняющего ту же функцию, в разных углах вашей файловой системы контрпродуктивно и нелогично.
Поразмыслив, я придумал лучшую систему (см. Ниже).
Предисловие 2: стилизованные компоненты, это не CSS; они компоненты.
Styled-components - моя любимая библиотека, когда дело касается встраивания CSS в проекты React. Это очень хорошо.
Распространенной схемой его использования является разделение стилей на styles.js
, что напоминает файловую структуру, которая не так давно была у нас с более простыми рукописными файлами HTML.
Оказывается, это не очень хорошая идея. А именно потому, что этот метод создает третий тип компонентов (помимо уже упомянутых умных и тупых). Что еще хуже, у этого типа компонента есть совершенно отдельный организационный метод, который пытается имитировать конфликтующие парадигмы.
Я рекомендую рассматривать стилизованные компоненты так, как они есть - компоненты React.
Шаблон интерфейса.
Шаблон интерфейса - это напоминание о том, что мы создаем интерфейсное приложение, которое легче понять и структурировать, если рассматривать его как компиляцию элементов визуального интерфейса. Этот шаблон состоит из предложений по структуре файлов и папок, предпочтительным типам экспорта, методам комментирования и рекомендациям по размеру файлов.
Форма структуры файлов и папок.
- app/ - core/ - admin/ - user/ - constants.js - index.js - store.js - utils.js
Примечание: вы можете просмотреть всю структуру приложения для Analog.Cafe в этом репозитории.
Мое приложение разделено на три основных раздела: core/
admin/
и user/
. В вашем случае у вас может не быть никаких разделов, если приложение недостаточно велико. Затем вы можете структурировать свою папку app/
так же, как содержимое приведенных выше разделов (см. Ниже).
Приведенные выше четыре файла JavaScript не требуют пояснений, но с некоторыми оговорками. В этом примере они служат индексными файлами, в которых хранятся только самые основные и часто используемые экспорты: index.js
содержит основной компонент React оболочки для приложения, store.js
объединяет редукторы, найденные внутри трех вышеуказанных приложений. разделов и экспортирует хранилище Redux, а utils.js
и constants.js
содержат наиболее распространенные фрагменты функций JavaScripit и повторно используемые константы.
- core/ - components/ - constants/ - store/ - utils/
Внутри каждого раздела приложения есть четыре папки, которые по форме напоминают каталог app/
. Единственное отличие состоит в том, что эта форма вынуждает вас создавать больше файлов в ваших utils/
и constants/
папках, что лучше для организации и должно улучшить работу встряхивания дерева.
Если вы не разбиваете приложение на разделы, указанные выше папки можно поместить в папку app/
вместо core/
.
- constants/ - messages-.js - messages-article.js - routes-article.js - rules-submission.js - utils/ - actions-session.js - messages-profile.js
Обе папки constants/
и utils/
имеют похожие шаблоны именования файлов. Первое ключевое слово - это сообщения, маршруты, правила или действия. За ним следует тире и ключевое слово, описывающее определенную часть представления вашего приложения. Я понимаю, что это не самое надежное соглашение об именах, однако вы можете лучше понять его на практике. Основными целями должны быть последовательность и ясность.
Обратите внимание на файл с именем messages-.js, который содержит строки и объекты, обозначенные как сообщения, обращенные к пользователю, не назначенные какой-либо конкретной части представления приложения.
- store/ - actions-article.js - actions-submission.js - reducers-article.js - reducers-submission.js
Папка store/
предназначена для Redux. Он содержит пары файлов (действия и редукторы) для каждой части вашего приложения. Простой; все в одном месте.
- components/ - controls/ - icons/ - pages/ - routes/ - forms/ - vignettes/
components/
папка: я обнаружил, что перечисленные выше шесть типов компонентов являются достаточно всеобъемлющим способом организации приложения. Такие подпапки необходимы, чтобы быстро найти то, что вы ищете, и понять структуру приложения. В противном случае вы можете застрять с сотнями папок в этой части вашего приложения. Вот как я их различаю:
controls/
- Кнопки и массивы кнопок, модальные поля, ссылки, панели навигации, меню и т. д.
icons/
- Графические элементы, созданные с помощью React и предназначенные для того, чтобы оставаться частью приложения, например, встроенные SVG или CSS.
pages/
- Компоненты, которые должны занимать целую или значимую часть экранного пространства.
routes/
- Эта папка предназначена специально для компонентов маршрута React Router.
forms/
- Элементы ввода.
vignettes/
- Компоненты меньшего размера, которые больше нигде не нужны.
- controls/ - Card/ - index.js - components/ - CardFigure.js - CardHeader.js
Каждая из компонентных папок будет иметь имена, написанные в CamelCase, с необязательным index.js
в их корне, который будет связывать все вместе. При необходимости внутри можно разместить папку components/
, которая может содержать стилизованные компоненты или компоненты React.js, которые напрямую помогли бы составить основной компонент (в данном случае Card/
component).
Примечание 1. Здесь нет различия или правил между «умными» и «глупыми» компонентами, но «умные» компоненты, естественно, обычно оказываются в корне основного компонента в индексе. .js, который можно использовать в своих интересах.
Примечание 2: Вам ничего не мешает импортировать файлы из других разделов приложения; в большинстве случаев это требуется, и в этом нет ничего плохого. Не стесняйтесь требовать admin/
утилит в core/
компонентах.
Примечание 3. Вы могли заметить, что у подкомпонентов нет собственных папок. Это упрощает чтение и улучшает структуру папок. Их, конечно, можно было бы поместить в свои собственные папки, если бы они, в свою очередь, имели свои собственные подкомпоненты, но это было бы беспорядочно. Старайтесь, чтобы дерево файлов было как можно более плоским.
Предпочтительные типы экспорта.
Простое правило - предпочитать именованный экспорт, например export const function Name ()=>{}
в constants/
utils/
и store/
- это побудит вас правильно сбалансировать количество файлов в этих папках.
Однако все компоненты должны стремиться экспортировать только экспорт по умолчанию, за некоторыми исключениями, когда они могут содержать как экспорт по умолчанию, так и именованный экспорт в очень маленьких файлах. Это простое правило заставит вас создать больше компонентов (которые, кстати, намного проще назвать, чем более жестко структурированные файлы констант и utils), что, в свою очередь, приведет к создают ряд преимуществ с точки зрения окончательного размера пакета и удобочитаемости приложения (меньшее количество строк кода на файл).
Рекомендации по размеру файла.
Не более 300 строк в файле. Все, что больше этого, требует разделения.
Комментирующие практики.
Раньше я думал, что чем больше комментариев в коде, тем лучше. Пока я не узнал обратного. Обильные комментарии могут быть полезны при создании учебника, однако они, как правило, загрязняют файлы приложений и поощряют неправильные методы именования переменных. Так что, если код кажется трудным для понимания, его следует пересмотреть и исправить для более понятного наименования и стиля. Используйте такие инструменты, как Prettier в ваших интересах.
Напишите читаемый код вместо того, что вам нужно в руководстве.
Может показаться, что предстоит многое сделать, но на практике это может быть легко достигнуто и понятно всей команде. Взгляните на репо, которое уже использует этот метод, чтобы познакомиться. Вернитесь к этому тексту, чтобы получить подробную информацию и обоснование каждого выбора.
Как вы могли заметить, я ничего не сказал о том, где разместить тесты. Этот метод также не был опробован в большом количестве производственных систем, поэтому, возможно, я кое-что упустил или ошибся. В таких случаях вам, возможно, придется адаптироваться, и если у вас будет время, дайте мне знать, чтобы я мог улучшить это руководство.
🍻
Первоначально опубликовано на www.archie.ai.