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

Содержание руководства
- Что выполняется сейчас
- Файлы и подключение
- Контекст ctx
- Функции bnx
- Пример 1. Цена, скидка и склонение
- Пример 2. Обработка карточек
- Пример 3. Данные сущности
- Внешние адреса и безопасность
- Пример 4. JSON API
- Пример 5. Файл релизов
- Пример 6. Параметры и резервные адреса
- Кеш, расписание и отказоустойчивость
- Возврат данных в шаблон
- Ограничения и выбор подхода
- Отладка и проверка
Что выполняется сейчас
Серверный JavaScript добавляет модулю вычисления без изменения и пересборки ядра на Go. Сейчас движок выполняет два хука.
| Хук | Когда работает | Для чего подходит | Сеть |
|---|---|---|---|
compute(ctx) | При каждой серверной отрисовке раздела | Расчёты, фильтрация, подготовка подписей и данных шаблона | Нет |
refresh(input) | В фоне по расписанию | Получение публичных данных из внешних сервисов и сохранение кеша | Да, через bnx.fetch и bnx.head |
Обычная схема работы: refresh заранее получает внешние данные и складывает объект в кеш, compute быстро читает ctx.cache и готовит значения, а шаблон показывает результат посетителю.
Файлы и подключение
Сценарии хранятся внутри модуля. Путь объявляется в manifest.json относительно папки модуля; выход через ../ запрещён.
modules/my_module/
├── manifest.json
├── server/
│ ├── compute.js
│ └── refresh.js
└── templates/{
"name": "my_module",
"version": "1.0.0",
"runtime": {
"js": {
"compute": "server/compute.js",
"refresh": "server/refresh.js",
"refresh_every_minutes": 60,
"refresh_hosts": ["api.example.ru", "*.cdn.example.ru"]
}
}
}computeиrefreshуказывают файлы с одноимёнными функциями.refresh_every_minutesвключает автоматический запуск; без этого поля фонового расписания нет. Минимальный период — 5 минут.refresh_hostsограничивает внешние хосты. Шаблон*.example.ruразрешает поддомены, но не самexample.ru.
После правки серверного сценария пересобирать ядро не нужно. Убедитесь только, что страница действительно использует этот тип модуля.
Контекст ctx
Функция compute(ctx) получает один объект контекста.
| Поле | Содержимое |
|---|---|
ctx.settings | Итоговые настройки: значения по умолчанию из контракта плюс параметры раздела. |
ctx.section | Исходные поля конкретного раздела из редактора. Записи списка находятся в ctx.section.objects. |
ctx.record | Текущая запись на детальной странице или null. |
ctx.scope | Область вызова: раздел, список или детальная страница. |
ctx.lang | Текущий язык. |
ctx.page_name | Системное имя страницы. |
ctx.module | Объект с типом и версией модуля. |
ctx.cache | Последний успешный результат refresh или пустой объект. |
Как читать поле с учётом значения редактора
function compute(ctx) {
var product = ctx.section.product ||
ctx.settings.product ||
'Товар';
return { product_name: product };
}Если читать только ctx.settings.product, значение по умолчанию контракта может скрыть введённое редактором значение. Для пользовательских полей сначала проверяйте ctx.section.
Глобальные переменные между вызовами не сохраняются. Считайте compute чистой функцией: весь необходимый вход находится в ctx.
Функции bnx
Объект bnx — единственный поддерживаемый канал к возможностям ядра. Набор функций зависит от хука.
| Функция | Результат | Где доступна |
|---|---|---|
bnx.t(key, vars) | Перевод из языкового пакета модуля; неизвестный ключ возвращается как есть | compute, refresh |
bnx.money(number) | Денежная сумма в формате проекта | оба хука |
bnx.plural(number, forms) | Нужная форма из массива «один, несколько, много» | оба хука |
bnx.date(value, format) | Дата; поддерживаются dd d MM M MMMM yyyy HH mm ss | оба хука |
bnx.hash(algo, text) | Hex-хеш sha256, sha1 или md5 | оба хука |
bnx.log(level, message, fields) | Структурированная запись в журнал ядра | оба хука |
bnx.url(name, params) | URL именованного маршрута | только compute |
bnx.records(source, query) | Записи зарегистрированной сущности, не более 500 за вызов | только compute |
bnx.fetch(url) | Безопасный HTTP GET и тело ответа | только refresh |
bnx.head(url) | Статус, тип и размер ресурса без загрузки тела | только refresh |
Ошибка источника в bnx.records не должна уронить страницу: ядро вернёт пустой список и запишет предупреждение. Перед использованием проверьте, что сущность зарегистрирована.
Пример 1. Цена, скидка и склонение
Задача: посчитать сумму со скидкой и вывести корректную подпись количества. Числа возвращаем числами, а готовые подписи — отдельными строками.
function compute(ctx) {
var price = Number(ctx.section.price) || 0;
var quantity = Number(ctx.section.quantity) || 1;
var discount = Number(ctx.section.discount) || 0;
var subtotal = price * quantity;
var total = subtotal * (100 - discount) / 100;
var unit = bnx.plural(quantity, [
bnx.t('unit_one'),
bnx.t('unit_few'),
bnx.t('unit_many')
]);
return {
subtotal: subtotal,
total: total,
total_label: bnx.money(total),
quantity_label: quantity + ' ' + unit,
has_discount: discount > 0
};
}<p>{{ quantity_label }}</p>
<s v-if="has_discount">{{ subtotal }}</s>
<strong>{{ total_label }}</strong>Ключи возвращённого объекта становятся значениями шаблона. Не форматируйте число пробелами вручную, если оно ещё участвует в сравнении или расчёте.
Пример 2. Обработка карточек
Записи, добавленные редактором в списочный раздел, находятся в ctx.section.objects. Их можно отфильтровать и дополнить вычисляемыми полями.
function compute(ctx) {
var source = ctx.section.objects || [];
var cards = source
.filter(function (item) {
return item.is_active !== '0';
})
.map(function (item, index) {
var text = String(item.text || '');
return {
number: index + 1,
title: item.title || 'Без названия',
note: text.slice(0, 120),
url: item.url || '#',
featured: item.featured === '1'
};
});
return {
cards: cards,
cards_count: cards.length,
has_cards: cards.length > 0
};
}<article v-for="card in cards">
<span>{{ card.number }}</span>
<h3>{{ card.title }}</h3>
<p>{{ card.note }}</p>
</article>Флажки из данных проекта могут приходить строками '1' и '0'. Не полагайтесь на обычную проверку истинности строки '0'.
Пример 3. Данные сущности
bnx.records читает зарегистрированные сущности проекта. Это полезно, когда модулю нужна небольшая подборка существующих данных, а не собственные записи раздела.
function compute(ctx) {
var posts = bnx.records('publications', { limit: 5 }) || [];
var latest = posts.map(function (post) {
return {
title: post.title,
date_label: bnx.date(post.date, 'dd.MM.yyyy'),
url: bnx.url('publication', { slug: post.slug })
};
});
return {
latest: latest,
latest_count: latest.length,
empty_message: latest.length ? '' : bnx.t('no_publications')
};
}За один вызов возвращается не более 500 записей. Большие выборки, сложную фильтрацию и постоянные связи лучше описывать декларативным источником в module.compose.json: декларация отвечает на вопрос «какие данные нужны», а JavaScript — «что из них вычислить».
Внешние адреса и безопасность
Внешний адрес можно открыть только из фонового refresh. Функция bnx.fetch(url) выполняет HTTP GET, а bnx.head(url) получает сведения о ресурсе без загрузки тела. В compute этих функций нет.
Белый список хостов
"refresh_hosts": [
"api.example.ru",
"downloads.example.ru",
"*.cdn.example.ru"
]- Точное имя разрешает только этот хост.
*.cdn.example.ruразрешает его поддомены, но неcdn.example.ru.- Пустой список разрешает любой публичный адрес, однако для рабочего модуля безопаснее перечислить нужные хосты.
- Разрешение проверяется заново после каждого перенаправления.
Какие адреса принимаются
Разрешены схемы https:// и http://. Адреса с логином или паролем, localhost, loopback, private, link-local и зарезервированные IP блокируются. DNS проверяется до подключения, поэтому домен не может незаметно привести запрос во внутреннюю сеть сервера.
Формат ответа и лимиты
var res = bnx.fetch(url);
// res.ok, res.error, res.status, res.body,
// res.content_type, res.final_url, res.json()var info = bnx.head(url);
// info.ok, info.error, info.status, info.length,
// info.content_type, info.final_url- 20 секунд на один запрос;
- до 20 запросов за один прогон
refresh; - до 8 МиБ на один ответ;
- до 60 секунд на весь прогон;
- не более трёх перенаправлений по умолчанию.
Неуспех возвращается объектом с ok: false, а не выбрасывает исключение. Всегда проверяйте ok до чтения тела. Текущий интерфейс поддерживает только GET/HEAD без пользовательских заголовков и тела. API, которому нужны Bearer-токен, POST или секрет в адресе, подключайте через отдельную серверную интеграцию; секреты в URL намеренно запрещены.
Пример 4. JSON API
Пример получает курсы из публичного JSON API, проверяет ответ и оставляет в кеше только необходимые поля.
// server/refresh.js
var URL = 'https://api.example.ru/rates/latest.json';
function refresh(input) {
var res = bnx.fetch(URL);
if (!res.ok) {
bnx.log('warn', 'Не удалось получить курсы', {
url: URL,
error: res.error
});
return {};
}
var payload = res.json();
if (!payload || !payload.rates) {
bnx.log('warn', 'API вернул неожиданный JSON', {
content_type: res.content_type
});
return {};
}
return {
usd: Number(payload.rates.USD) || 0,
eur: Number(payload.rates.EUR) || 0,
source_url: res.final_url,
updated_at: bnx.date(new Date(), 'dd.MM.yyyy HH:mm')
};
}// server/compute.js
function compute(ctx) {
var data = ctx.cache || {};
return {
usd_label: data.usd ? bnx.money(data.usd) : 'Нет данных',
eur_label: data.eur ? bnx.money(data.eur) : 'Нет данных',
updated_at: data.updated_at || '',
is_loading: !data.updated_at
};
}res.json() возвращает null, если тело не является корректным JSON. Возврат пустого объекта при ошибке сохраняет предыдущий успешный кеш.
Пример 5. Файл релизов
Перед показом ссылок на большие файлы можно запросить метаданные через HEAD, не загружая архив в память.
var BASE = 'https://downloads.example.ru';
function refresh(input) {
var manifestRes = bnx.fetch(BASE + '/manifest.json');
if (!manifestRes.ok) {
bnx.log('warn', 'Манифест недоступен', {
error: manifestRes.error
});
return {};
}
var manifest = manifestRes.json();
if (!manifest || !manifest.file) return {};
var fileUrl = BASE + '/files/' +
encodeURIComponent(manifest.file);
var fileInfo = bnx.head(fileUrl);
if (!fileInfo.ok) {
bnx.log('warn', 'Файл релиза недоступен', {
url: fileUrl,
error: fileInfo.error
});
return {};
}
return {
version: String(manifest.version || ''),
file_url: fileInfo.final_url,
file_size: fileInfo.length,
file_type: fileInfo.content_type,
checksum: String(manifest.sha256 || ''),
checked_at: bnx.date(new Date(), 'dd.MM.yyyy HH:mm')
};
}length равен -1, если сервер не прислал Content-Length. Сравнивайте размер только при значении 0 или больше. Все обращения fetch и head расходуют общий лимит в 20 запросов.
Пример 6. Параметры и резервные адреса
Параметры запроса
Значения, попадающие в URL, обязательно кодируйте через encodeURIComponent.
function refresh(input) {
var city = 'Москва';
var url = 'https://weather.example.ru/current' +
'?city=' + encodeURIComponent(city) +
'&lang=ru';
var res = bnx.fetch(url);
if (!res.ok) return {};
var data = res.json();
return {
city: city,
temperature: Number(data.temperature),
condition: String(data.condition || '')
};
}Несколько публичных зеркал
function refresh(input) {
var urls = [
'https://api-1.example.ru/status.json',
'https://api-2.example.ru/status.json'
];
for (var i = 0; i < urls.length; i++) {
var res = bnx.fetch(urls[i]);
if (!res.ok) {
bnx.log('warn', 'Зеркало недоступно', {
url: urls[i], error: res.error
});
continue;
}
var data = res.json();
if (data && data.status) {
return {
status: data.status,
source: res.final_url,
checked_at: bnx.date(new Date(), 'HH:mm')
};
}
}
return {};
}Оба хоста нужно внести в refresh_hosts. Возврат {} после отказа всех зеркал оставит прошлый кеш. Если вместо этого вернуть заранее заданные значения, они заменят кеш; такой выбор должен быть осознанным и заметным пользователю.
Кеш, расписание и отказоустойчивость
Результат refresh сохраняется в data/module-cache/<модуль>.json. База данных для этого не нужна. При следующей отрисовке объект доступен как ctx.cache.
- Первый запуск: кеш пуст, поэтому шаблон должен иметь состояние «данные обновляются».
- Успешный запуск: новый объект полностью становится актуальным кешем.
- Ошибка сценария или возврат пустого объекта: предыдущие успешные данные сохраняются.
- После неудачи следующий запуск всё равно планируется.
Почему расписание может не работать
На обычном хостинге ядро не является постоянно работающим демоном. Планировщик хостинга должен регулярно обращаться к /health; без задания cron очередь фоновых обновлений не крутится.
Показывайте давность данных
function compute(ctx) {
var cache = ctx.cache || {};
return {
rows: cache.rows || [],
checked_at: cache.checked_at || '',
has_cache: Array.isArray(cache.rows),
cache_message: cache.checked_at
? 'Проверено ' + cache.checked_at
: 'Данные ещё не получены'
};
}Кеш модуля рассчитан на десятки отображаемых записей. Тысячи товаров, историю изменений и данные, которые нужно искать и редактировать, загружайте через импорт в сущности или базу.
Основное размещение — ваш VPS. Для подключения достаточно IP-адреса, логина и пароля от VPS. Studio установит необходимые компоненты и будет управлять сервисами: отдельно заходить на сервер и устанавливать панель управления не требуется. Как подключить VPS в Studio.
Если сложно подключить сервер через мастер или вручную, выберите облако BuildNexus или обратитесь в техническую поддержку за настройкой вашего VPS или хостинга — 2 500 ₽ разово.
Возврат данных в шаблон
compute возвращает обычный объект. Строки, числа, булевы значения, массивы и вложенные объекты доходят до шаблона и могут использоваться в условиях и циклах.
function compute(ctx) {
var rows = (ctx.section.objects || []).map(function (item) {
return {
title: item.title,
note: String(item.text || '').slice(0, 120)
};
});
return {
heading: rows.length ? 'Материалы' : 'Пока пусто',
rows: rows,
rows_count: rows.length,
has_rows: rows.length > 0,
meta: { page: ctx.page_name, lang: ctx.lang }
};
}<section>
<h2>{{ heading }}</h2>
<p v-if="!has_rows">Добавьте первую запись.</p>
<article v-for="row in rows">
<h3>{{ row.title }}</h3>
<p>{{ row.note }}</p>
</article>
</section>Не возвращайте функции, DOM-объекты или циклические структуры. Имена вычисляемых ключей делайте отличимыми от полей редактора, чтобы шаблон было проще сопровождать.
Ограничения и выбор подхода
Ограничения compute
Нет сети, файловой системы, window, document, DOM, import и require. Код выполняется в ограниченном времени и памяти, поэтому не размещайте в нём большие обходы, тяжёлую сортировку и работу, результат которой можно подготовить заранее.
Когда JavaScript не нужен
- Прямое поле раздела можно вывести токеном шаблона.
- Список из сущности, фильтр, сортировку и лимит лучше сначала описать декларативным источником.
- Коллекцию проекта подключайте через
records_collection. - Интерактивность после загрузки страницы реализуйте браузерным Vue-компонентом.
- Стандартную форму подключайте через
runtime.action.kind = 'form'.
Когда выбирать другой механизм
- POST, авторизация заголовком, вебхуки и секретные ключи — отдельная серверная интеграция.
- Тысячи товаров из прайса — импорт, а не
refresh. - Запись и изменение сущностей — поддерживаемый API или действие модуля, не
compute. - Постоянное состояние — коллекция или база, не глобальная переменная сценария.
Практическое правило: декларация выбирает данные, refresh заранее получает внешний снимок, compute быстро вычисляет представление, шаблон выводит его, а браузерный код отвечает только за взаимодействие.
Данные и коллекции · Шаблоны и Vue-HTML · Все способы расширения
Отладка и проверка
Диагностическая запись
bnx.log('info', 'Расчёт блока завершён', {
module: ctx.module.type,
page: ctx.page_name,
rows: rows.length
});| Симптом | Что проверить |
|---|---|
| Ключ в шаблоне пуст | Возвращает ли его compute, нет ли опечатки и используется ли нужный модуль. |
| Поле редактора игнорируется | Читайте ctx.section.field перед ctx.settings.field. |
| Список не выводится | Возвращается ли массив; списочный ли это модуль; есть ли записи в ctx.section.objects. |
bnx.records пуст | Зарегистрирована ли сущность, корректно ли её имя, что записано в журнале ядра. |
bnx.fetch отсутствует | Он доступен только внутри refresh. |
| Внешний запрос отклонён | Схему, refresh_hosts, публичность DNS/IP, редирект, размер и HTTP-статус. |
refresh не запускается | Есть ли refresh_every_minutes и обращается ли cron хостинга к /health. |
JSON равен null | Посмотрите content_type, body и фактический формат ответа. |
Проверочный список перед выпуском
- Пути к сценариям объявлены в
manifest.json. computeне зависит от сети и быстро работает на пустых данных.refresh_hostsсодержит только необходимые внешние хосты.- Каждый
fetchиheadпроверяетok. - Первый запуск и устаревший кеш имеют понятное состояние в интерфейсе.
- Ошибки пишутся через
bnx.logбез секретов и полного пользовательского ответа. - Большие данные отправлены в импорт, а не в файловый кеш блока.
- Страница проверена с пустым списком, ошибкой внешнего сервиса и мобильной шириной.
Готовые рабочие образцы в поставке ядра: js_price_box для compute и js_downloads_box для связки refresh, кеша и compute.