Go-сервисы расширения проекта
Отдельная серверная логика рядом с сайтом: публичный HTTP, закрытый RPC и события без пересборки ядра.

Один сервис — две среды
Go-сервис живёт в sites/app/services/<name>, запускается отдельным процессом и общается с ядром через bnx-extension-bus/v1. Тот же каталог работает в локальной песочнице bnxdev и на сервере под bnxcore.
Это не модуль страницы: сервис не рисует HTML. Он нужен для внешних API, прикладной логики, закрытых вызовов между сервисами и проектных HTTP-методов. При изменении перезапускается только затронутый сервис.
Какой механизм выбрать
Начинайте с самого узкого механизма, который решает задачу.
От задачи до работающего сервиса
Понятный путь: определить задачу, выбрать способы связи, проверить безопасность и подготовить выпуск.
Сформулируйте задачу
Опишите, какой результат должен выдавать сервис, какие данные он получает и что происходит при ошибке.
Выберите способ связи
Публичный веб-адрес (HTTP) подходит для внешних запросов, закрытый вызов между сервисами (RPC) — для работы внутри проекта, а события — для реакции на изменения.
Определите границы доступа
Откройте для браузера только необходимые методы. Служебные операции и секретные данные должны оставаться внутри проекта.
Реализуйте обработчики
Добавьте нужную логику и убедитесь, что каждый объявленный метод или событие имеет соответствующий обработчик.
Проверьте локально
Запустите сервис в песочнице, выполните успешный и ошибочный запросы и убедитесь, что закрытые методы недоступны извне.
Подготовьте публикацию
Соберите сервис для операционной системы и архитектуры сервера, пройдите предварительную проверку и затем выпустите проект.
Создание price_sync через системное меню
Откройте нужный проект в Studio и выберите в системном меню Файл → Расширения ядра.
- Нажмите Создать Go-микросервис.
- Введите имя
price_sync. - Подтвердите создание. 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 подходит внешнему клиенту и доступен только методам с public: true. RPC связывает сервисы, когда вызывающей стороне нужен результат или ошибка. Событие уведомляет подписчиков и не ждёт подтверждения.
События шины v1 не являются очередью с гарантированной доставкой: потерянное сообщение не отправляется повторно автоматически. Критичное изменение данных оформляйте как RPC с ограничением времени и уникальным operation_id, защищающим от повторной операции.
Закрытый 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.
Проверка готовности
Готовность подтверждается результатами сборки и фактического запуска, а не только наличием файлов.