К содержимому
BuildNexus

Что выполняется сейчас

Серверный 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 и фактический формат ответа.

Проверочный список перед выпуском

  1. Пути к сценариям объявлены в manifest.json.
  2. compute не зависит от сети и быстро работает на пустых данных.
  3. refresh_hosts содержит только необходимые внешние хосты.
  4. Каждый fetch и head проверяет ok.
  5. Первый запуск и устаревший кеш имеют понятное состояние в интерфейсе.
  6. Ошибки пишутся через bnx.log без секретов и полного пользовательского ответа.
  7. Большие данные отправлены в импорт, а не в файловый кеш блока.
  8. Страница проверена с пустым списком, ошибкой внешнего сервиса и мобильной шириной.

Готовые рабочие образцы в поставке ядра: js_price_box для compute и js_downloads_box для связки refresh, кеша и compute.