ДокументацияРасширенный
Как работает Некси
Что происходит между файлом, который вы пишете, и страницей в браузере: слои, которые пересекает запрос, кто что создает и что Nexy оставляет вашему приложению. Вам не нужна эта страница для запуска; позже он отвечает на вопросы «почему это так работает».
Слои
Browser
│
▼
Uvicorn ───── ASGI transport
│
▼
Middleware ── sessions, CORS, gzip, trusted hosts, your own
│
▼
Router ────── FBR | Modular | Custom ── picks the file that answers
│
▼
Renderer ──── HTML (Jinja2, Markdown, Node) or JSON
│
▼
Response| Слой | Ответственность | Нет |
|---|---|---|
| Uvicorn | принять соединение, говорить ASGI | знать, что такое страница |
| Промежуточное ПО | оформить запрос: сессия, CORS, gzip, доверенные хосты, перенаправление HTTPS, ваше | выбрать маршрут |
| Маршрутизатор | сопоставить URL-адрес с файлом с его макетами, зависимостями и страницами ошибок | производить контент |
| Рендерер | запустите страницу и преобразуйте ее результат в HTML или JSON | получить ваши данные |
| Клиент | Vite и ваш фреймворк: пакеты, гидратация, навигация по клиенту | ответить на запрос сервера |
Кто что строит
| Актер | Владеет | Не владеет |
|---|---|---|
| Некси | маршрутизация, серверный рендеринг, действия, компиляция .nexy, один источник |
компоненты, реакционная способность, данные |
| Vite | клиентские пакеты, сервер разработки, горячая перезагрузка | маршрутизация, рендеринг сервера, действия |
| Ваша структура | компоненты, реакционная способность, экосистема | маршрутизация, документ (Nexy запрашивает для него свой макет) |
| Ваша заявка | данные, аутентификация, авторизация, бизнес-правила | транспорт, рендеринг |
Правило таблицы: Nexy строит то, что ей принадлежит, и никогда не компилирует то, что компилирует Vite.
Система маршрутизации
Путь под src/routes/ становится URL-адресом по четырем правилам:
| Файл | URL-адрес |
|---|---|
blog/index.nexy |
/blog |
blog/[slug].nexy |
/blog/hello |
blog/[...parts].nexy |
/blog/a/b |
(marketing)/about.nexy |
/about |
Расширение никогда не появляется; index - маршрут к папке; папка в скобках группирует файлы без добавления сегмента.
Когда два объекта могут ответить на один и тот же URL-адрес, побеждает тот, кто зарегистрировался первым, и Nexy всегда регистрируется в следующем порядке:
- конечная точка Действия;
- статические файлы:
/public,/assets,/favicon.ico; - модульный
APIRouter(useRouter); - файловые маршруты, сначала наиболее конкретные: статические пути, затем динамические пути с наиболее фиксированными сегментами, а затем всеобъемлющие.
Два файловых маршрута одинаковой специфичности регистрируются в алфавитном порядке, поэтому [id].nexy отвечает перед [slug].nexy. Таким образом, модульный маршрут превосходит страницу с тем же путем. Это порядок приоритета, на который можно положиться, а не правило тай-брейка: дайте одному URL-адресу один файл.
Система просмотра
Расширение файла определяет, что это такое, а конфигурация проекта определяет, какие расширения активны.
| Расширение | Активен, когда | Составлено | Служил как |
|---|---|---|---|
.nexy |
режим сервера | Nexy: заголовок становится Python, разметка становится Jinja2 | страница |
.md |
всегда | Nexy: приправлено GitHub Markdown, идентификаторы заголовков, оглавление. | страница внутри ближайшего макета |
.mdx |
всегда | Vite, с React или Preact | компонентный маршрут |
.tsx |
useFF - это React, Solid или Preact |
Vite и структура | компонентный маршрут |
.vue |
useFF - это Vue |
Vite и Vue | компонентный маршрут |
.svelte |
useFF - это Svelte |
Vite и Svelte | компонентный маршрут |
.py |
всегда | Python | обработчик API: GET, POST, ... - это методы |
Файл, расширение которого неактивно, пропускается с предупреждением и не обслуживается. В клиентском режиме .nexy отклоняется до запуска сервера. См. Соглашения о файлах.
Жизненный цикл рендеринга
Три вопроса решают все, что замечает читатель:
| Вопрос | Ответ | Страница |
|---|---|---|
| Кто создает HTML? | сервер или браузер для клиентского маршрута | Рендеринг |
| Когда данные читаются? | при каждом запросе, при каждой регенерации или в браузере | ССР, ИСР |
| Когда прибудет JavaScript? | только для острова или для всего документа | Острова, CSR |
В режиме сервера сервер отображает каждую страницу, revalidate кэширует одну страницу на каждый URL-адрес, а острова добавляют JavaScript к одному компоненту. В клиентском режиме первый документ отображается в Node, а затем навигация происходит в браузере.
__nexy__/ содержит все сгенерированное: скомпилированные страницы, запись клиента, выходные данные сборки. Никогда не редактируйте его, никогда не фиксируйте его; удалите его, чтобы выполнить чистую сборку.
Интеграция с интерфейсом
Vite не заменяет Nexy. Vite объединяет и обслуживает клиентский код. Он не маршрутизирует запрос, не отображает страницу .nexy, не запускает действие и не владеет источником. Браузер обращается к одному источнику - Nexy - и в разработке Nexy проксирует конечные точки Vite через него, поэтому нет необходимости настраивать CORS.
Nexy не заменяет React. Nexy решает, какой компонент рендерится, когда и с какими реквизитами; фреймворк владеет моделью компонентов, реактивностью и экосистемой. Страница .nexy импортирует компонент как остров; в режиме клиента маршрут является компонентом.
Для маршрута компонента Python записывает только тонкий модуль-оболочку, указывающий на файл. Компиляция и рендеринг на стороне сервера - работа Vite.
Разработка и производство
nx dev проверяет nexyconfig.py, компилирует страницы, запускает Vite, если проект имеет интерфейсную структуру, и перезапускает сервер при сохранении. nx build выполняет ту же работу один раз заранее, а nx start обслуживает результат.
nx dev |
nx build затем nx start |
|
|---|---|---|
| Страницы | компилируется при сохранении | скомпилировано один раз, заранее |
| Код клиента | Vite сервер разработки с горячей перезагрузкой, стоящий за собственным происхождением Nexy | пакет в __nexy__/client/, предварительно обработанный HTML |
| Node.js | работает рядом с Python | не нужен для обслуживания |
| Ошибки | наложение в браузере, панель инструментов на каждой странице | страницы статуса без подробностей |
| Происхождение | один порт, 3000 |
один порт |
Что не меняется: те же правила маршрутизации, те же файлы подкачки, те же nexyconfig.py. Страница, которая ведет себя по-разному, является ошибкой, а не режимом.
Что Nexy оставляет вам
Nexy намеренно останавливается на границе вашего приложения:
| Беспокойство | Что предлагает Nexy | Что ты пишешь |
|---|---|---|
| Аутентификация | промежуточное программное обеспечение сеанса, AuthenticationMiddleware при включении |
логин, поиск пользователя, политика использования файлов cookie |
| Авторизация | dependencies.py, защита, наследование для каждой папки |
само правило |
| База данных | нет собственного ORM; nx new может формировать SQLModel, SQLAlchemy или Tortoise, nx migrate запускает Alembic или Aerich |
модели и запросы (Базы данных) |
| Интернационализация | ничего для ваших страниц; переведен только CLI | библиотека и сообщения (i18n) |
| Фоновые задания | ничего: ни очереди, ни планировщика | рабочий процесс |
| Электронная почта, платежи, поиск | ничего | услуга, которую вы выбираете |
Причина одна и та же для всех шести: фреймворк, который выбирает ваш ORM или вашу библиотеку аутентификации, решает то, что может решить только ваше приложение. Стоимость очевидна: для вас ничего не подключено, а в руководствах, приведенных в таблице, указано, куда подключать каждый из них.
Следующие шаги
- Структура проекта: каждая часть находится в проекте.
- Маршрутизация: файловые, модульные и пользовательские маршрутизаторы.
- Рендеринг: SSR, ISR, CSR и острова
- Интерфейс: Vite, стиль и сборка клиента