К содержимому
BuildNexus
Один сервис — две среды
Архитектура

Один сервис — две среды

Go-сервис живёт в sites/app/services/<name>, запускается отдельным процессом и общается с ядром через bnx-extension-bus/v1. Тот же каталог работает в локальной песочнице bnxdev и на сервере под bnxcore.

Это не модуль страницы: сервис не рисует HTML. Он нужен для внешних API, прикладной логики, закрытых вызовов между сервисами и проектных HTTP-методов. При изменении перезапускается только затронутый сервис.

Все способы расширения

Какой механизм выбрать

Начинайте с самого узкого механизма, который решает задачу.

Задача
Подход
Визуальный блок страницы
HTML, стили, данные раздела
Обычный модуль
Сложный интерфейс из нескольких блоков
Один владелец состояния и серверная отрисовка
Lego-композиция
Короткий compute или refresh
Логика одного модуля
Серверный JavaScript
API, предметная логика, RPC
Изолированный процесс проекта
Go-сервис
Возможности не хватает всей платформе
Нужен общий контракт ядра
Изменение платформы

От задачи до работающего сервиса

Понятный путь: определить задачу, выбрать способы связи, проверить безопасность и подготовить выпуск.

01

Сформулируйте задачу

Опишите, какой результат должен выдавать сервис, какие данные он получает и что происходит при ошибке.

02

Выберите способ связи

Публичный веб-адрес (HTTP) подходит для внешних запросов, закрытый вызов между сервисами (RPC) — для работы внутри проекта, а события — для реакции на изменения.

03

Определите границы доступа

Откройте для браузера только необходимые методы. Служебные операции и секретные данные должны оставаться внутри проекта.

04

Реализуйте обработчики

Добавьте нужную логику и убедитесь, что каждый объявленный метод или событие имеет соответствующий обработчик.

05

Проверьте локально

Запустите сервис в песочнице, выполните успешный и ошибочный запросы и убедитесь, что закрытые методы недоступны извне.

06

Подготовьте публикацию

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

Создание price_sync через системное меню

Откройте нужный проект в Studio и выберите в системном меню Файл → Расширения ядра.

  1. Нажмите Создать Go-микросервис.
  2. Введите имя price_sync.
  3. Подтвердите создание. Studio подготовит каркас и сразу проверит его сборку.

Вставлять JSON в какой-либо файл не нужно. После создания файлы появятся в каталоге app/services/price_sync/ текущего сайта. Полный путь от корня репозитория — sites/app/services/price_sync/:

app/services/price_sync/
├── service.json
├── main.go
├── go.mod
├── README.md
└── bin/
  • service.json — настройки запуска, методы и подписки;
  • main.go — обработчики и подписки;
  • go.mod — зависимости Go;
  • README.md — описание сервиса;
  • bin/ — исполняемые файлы для разных платформ.

Затем откройте созданный service.json. В его разделе methods перечисляются методы сервиса и указывается, можно ли вызывать их из браузера. Ниже показан только фрагмент файла — остальные поля сохраняются:

"methods": {
  "get_price": {
    "public": true,
    "description": "Цена по SKU"
  },
  "reserve": {
    "public": false,
    "description": "Резерв товара"
  }
}

Безопасное значение по умолчанию: если браузер не должен вызывать метод, оставляйте public: false.

Типизированный публичный метод

Обработчик обязан проверить JSON и поля предметной области до выполнения операции. Цена ниже демонстрационная: в рабочем сервисе значение приходит из реального источника.

bus.Handle("get_price", func(_ context.Context, payload json.RawMessage) (any, error) {
    var input struct {
        SKU string `json:"sku"`
    }
    if err := json.Unmarshal(payload, &input); err != nil {
        return nil, fmt.Errorf("invalid payload: %w", err)
    }
    input.SKU = strings.TrimSpace(input.SKU)
    if input.SKU == "" {
        return nil, errors.New("sku is required")
    }
    return map[string]any{
        "sku": input.SKU,
        "price_kopecks": 12500,
    }, nil
})

После сборки публичный маршрут вызывается так:

POST /api/extensions/price_sync/get_price
Content-Type: application/json

{"sku":"BNX-SITE"}

public: true открывает HTTP-маршрут, но не заменяет проверку личности, проверку прав, ограничения частоты и защиту от повторов.

HTTP, RPC и события — три разных контракта
Шина расширений

HTTP, RPC и события — три разных контракта

HTTP подходит внешнему клиенту и доступен только методам с public: true. RPC связывает сервисы, когда вызывающей стороне нужен результат или ошибка. Событие уведомляет подписчиков и не ждёт подтверждения.

События шины v1 не являются очередью с гарантированной доставкой: потерянное сообщение не отправляется повторно автоматически. Критичное изменение данных оформляйте как RPC с ограничением времени и уникальным operation_id, защищающим от повторной операции.

Lego-композиция интерфейса

Закрытый RPC и событие

RPC: ответ обязателен

callCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

var result struct {
    Reserved bool `json:"reserved"`
    Left     int  `json:"left"`
}
err := bus.Call(callCtx, "inventory", "reserve", map[string]any{
    "sku": input.SKU,
    "qty": input.Qty,
    "operation_id": input.OperationID,
}, &result)

Метод inventory.reserve остаётся public: false. Обрабатывайте остановленный сервис, превышение времени ожидания и повтор того же operation_id.

Событие: получатели необязательны

if err := bus.Publish("catalog.updated", map[string]any{
    "sku": input.SKU,
    "operation_id": input.OperationID,
}); err != nil {
    fmt.Fprintln(os.Stderr, "publish catalog.updated:", err)
}

bus.Subscribe("catalog.updated", func(
    _ context.Context, source string, payload json.RawMessage,
) {
    // Быстрая, безопасная для параллельного выполнения обработка.
})

stdout зарезервирован протоколом шины. Диагностические и прикладные сообщения пишите только в stderr.

Проверка готовности

Готовность подтверждается результатами сборки и фактического запуска, а не только наличием файлов.

Проверка
Готово, когда
Файлы
service.json, main.go и go.mod прочитаны
Каркас целый, изменения точечные
Контракт
Методы и подписки объявлены
Имена совпадают с Handle и Subscribe
Сборка
Проверены все результаты сборки
built: true, поле error пусто
Запуск
Сервис зарегистрирован в среде выполнения
Нет цикла падений и перезапусков
Доступ
Публичный метод вызван по HTTP
Закрытый метод не виден в /api/extensions
Публикация
Известны система и архитектура сервера
Есть подходящий исполняемый файл, предварительная проверка пройдена
Визуальная композиция

Нужен блок страницы, а не серверный процесс?

Соберите сложный интерфейс с серверной отрисовкой из независимых модулей и оставьте данные у одного владельца состояния.