Skill v1.0.1

Automated scan100/100

steelmorgan/1c-agent-based-dev-framework/ssl-patterns

+1 new

──Details

PublishedJune 21, 2026 at 10:51 AM

Content Hashsha256:637bf0da617b9e2a...

Git SHAf0ac1fdfcab1

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 20.4 KB)

SKILL.md20.4 KBactive

SKILL.md · 340 lines · 20.4 KB

version: "1.0.1" name: ssl-patterns description: "MUST use WHEN используешь или расширяешь функциональность БСП (Библиотека стандартных подсистем). Provides каталог готовых функций ОбщегоНазначения и правила вызова подсистем без дублирования." uses_capabilities:

get_signature_help

alwaysApply: false

Паттерны работы с БСП (Библиотека стандартных подсистем)

Код БСП проверен на миллионах установок, обновляется централизованно, знаком другим разработчикам. Дублирование БСП — антипаттерн.

Сигнатуры функций БСП — через `get_signature_help`. У функций ОбщегоНазначения и
прочих модулей БСП много параметров и перегрузок; не угадывайте порядок и состав аргументов.
В точке вызова get_signature_help(uri, line, character) показывает параметры и перегрузки
вызываемого метода прямо по месту — без открытия определения модуля БСП. Применяйте при вызове
любой функции из каталога ниже, если не уверены в сигнатуре.

Правило 1: Модуль ОбщегоНазначения — основной «швейцарский нож»

Прежде чем писать свою реализацию, проверьте — возможно, в БСП уже есть готовая функция.

Функция	Когда использовать
`ЗначениеРеквизитаОбъекта()`	Вместо `Ссылка.Реквизит` (избегаем точечную нотацию)
`ЗначенияРеквизитовОбъекта()`	Несколько реквизитов одним вызовом
`СообщитьПользователю()`	Сообщение с привязкой к полю (вместо `Сообщить()`)
`МенеджерОбъектаПоСсылке()`	Вместо `Выполнить("Справочники." + Имя)`
`ПодсистемаСуществует()`	Условный вызов модулей
`ОбщийМодуль()`	Динамический вызов модуля БСП
`ЭтоСсылка()`	Валидация параметров
`СсылкаСуществует()`	Проверка перед обращением

bsl

// ПЛОХО: три обращения к БД через точку
Наименование = КонтрагентСсылка.Наименование;
ИНН = КонтрагентСсылка.ИНН;
Ответственный = КонтрагентСсылка.ОсновнойМенеджер;
 
// ПРАВИЛЬНО: одно обращение через БСП
РеквизитыКонтрагента = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
    КонтрагентСсылка,
    "Наименование, ИНН, ОсновнойМенеджер");

Правило 2: СтроковыеФункцииКлиентСервер — работа со строками

Модуль содержит оптимизированные функции, корректно обрабатывающие edge cases.

Функция	Когда использовать
`ПодставитьПараметрыВСтроку()`	Аналог `СтрШаблон()`, с дополнительными проверками
`СтрокаСЧисломПредметов()`	Склонение: «5 документов», «1 документ»
`ЕстьНедопустимыеСимволы()`	Валидация ввода
`ТолькоЦифрыВСтроке()`	Валидация ИНН, КПП
`РазложитьСтрокуВМассивПодстрок()`	Парсинг по разделителю

bsl

// Склонение: «1 документ», «2 документа», «5 документов»
ТекстОповещения = СтроковыеФункцииКлиентСервер.СтрокаСЧисломПредметов(
    КоличествоДокументов,
    НСтр("ru = 'документ, документа, документов'"));

Правило 3: ОбщегоНазначенияКлиентСервер — утилиты для обеих сред

Директива &НаКлиентеНаСервереБезКонтекста — доступен и на клиенте, и на сервере.

Функция	Описание
`ДополнитьМассив()`	Объединение двух массивов
`ДополнитьСтруктуру()`	Объединение двух структур
`СвойствоСтруктуры()`	Безопасное чтение свойства (значение по умолчанию если нет)
`ПроверитьПараметр()`	Валидация типа с информативной ошибкой

bsl

// Безопасный доступ с значением по умолчанию
ДатаНачала = ОбщегоНазначенияКлиентСервер.СвойствоСтруктуры(
    ПараметрыОтчёта, "ДатаНачала", НачалоГода(ТекущаяДатаСеанса()));

Правило 4: Стратегия поиска функций БСП

Алгоритм: LSP -> grep -> AI

LSP (если доступен): navigate_symbol("ЗначенияРеквизитовОбъекта")
Поиск по тексту: grep -r "Функция.*КурсВалюты" src/CommonModules/
AI-ассистент: «Есть ли в БСП функция для получения курса валюты на дату?»

Когда писать своё vs использовать БСП

Ситуация	Решение
В БСП есть подходящая функция	Используй БСП
В БСП есть похожая, но с лишним функционалом	Используй БСП — лишнее не мешает
Нужной функции нет в БСП	Пиши своё в стиле БСП
Конфигурация без БСП	Пиши своё

Правило 5: Работа с журналом регистрации через БСП

См. error-handling, правило 7.

Правило 6: РаботаСФайлами — вместо прямого ФайловаяСистема

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

bsl

ИмяВременногоФайла = ПолучитьИмяВременногоФайла("xlsx");
Попытка
    ТабличныйДокумент.Записать(ИмяВременногоФайла, ТипФайлаТабличногоДокумента.XLSX);
    // ... работа с файлом ...
Исключение
    // Обработка ошибки
КонецПопытки;
 
// Явное удаление
УдалитьФайлы(ИмяВременногоФайла);

Правило 7: Типовые паттерны БСП

Проверка заполнения (ОбработкаПроверкиЗаполнения)

bsl

Процедура ОбработкаПроверкиЗаполнения(Отказ, ПроверяемыеРеквизиты)
 
    Если НЕ ЗначениеЗаполнено(Контрагент) Тогда
        ОбщегоНазначения.СообщитьПользователю(
            НСтр("ru = 'Не заполнен контрагент.'"),
            ЭтотОбъект, "Контрагент",, Отказ);
    КонецЕсли;
 
    // Условное исключение реквизитов из проверки
    Если ВидОперации = Перечисления.ВидыОпераций.Услуга Тогда
        ОбщегоНазначенияКлиентСервер.УдалитьЗначениеИзМассива(
            ПроверяемыеРеквизиты, "Склад");
    КонецЕсли;
 
КонецПроцедуры

Получение данных для печати

bsl

Процедура Печать(МассивОбъектов, ПараметрыПечати, КоллекцияПечатныхФорм,
        ОбъектыПечати, ПараметрыВывода) Экспорт
 
    Если УправлениеПечатью.НужноПечататьМакет(КоллекцияПечатныхФорм, "Счёт") Тогда
 
        ТабличныйДокумент = Новый ТабличныйДокумент;
        ТабличныйДокумент.КлючПараметровПечати = "Документ.РеализацияТоваровУслуг.Счёт";
 
        УправлениеПечатью.ВывестиТабличныйДокументВКоллекцию(
            КоллекцияПечатныхФорм, "Счёт", НСтр("ru = 'Счёт на оплату'"),
            ТабличныйДокумент);
    КонецЕсли;
 
КонецПроцедуры

Правило 8: Не дублируйте функционал БСП

Что часто пишут сами	Что есть в БСП
Получение реквизита по ссылке	`ОбщегоНазначения.ЗначениеРеквизитаОбъекта()`
Подстановка в строку	`СтроковыеФункцииКлиентСервер.ПодставитьПараметрыВСтроку()`
Склонение слов	`СтроковыеФункцииКлиентСервер.СтрокаСЧисломПредметов()`
Отправка почты	`РаботаСПочтовымиСообщениями`
Курс валюты	`РаботаСКурсамиВалют.ПолучитьКурсВалюты()`
Длительная операция в фоне	`ДлительныеОперации.ВыполнитьФункцию()`
Хранение секретов / паролей	`БезопасноеХранилище.ПрочитатьДанные()`
Профили прав доступа	`ГруппыДоступаПользователей` / `ПрофилиГруппДоступа`
Регистрация внешней обработки	`СведенияОВнешнейОбработке()`

Правило 9: Модули «КлиентСервер» — разделение ответственности

Суффикс модуля	Среда	Пример
(без суффикса)	Сервер	`ОбщегоНазначения`
`Клиент`	Клиент	`ОбщегоНазначенияКлиент`
`КлиентСервер`	Обе среды	`ОбщегоНазначенияКлиентСервер`
`ПовтИсп`	Сервер, с кэшированием	`ОбщегоНазначенияПовтИсп`

Для клиентского кода формы — ищите сначала в *КлиентСервер, потом в *Клиент. Для серверного — в основном модуле (без суффикса). *ПовтИсп — для часто запрашиваемых справочных данных.

Правило 10: Длительные операции (ДлительныеОперации)

Используй подсистему ДлительныеОперации для любой серверной работы дольше ~3 сек. Не блокируй UI самодельным циклом ожидания.

bsl

// Запуск фоновой задачи
&НаСервере
Функция ЗапуститьОперацию(Параметры)
    ПараметрыФона = ДлительныеОперации.ПараметрыВыполненияВФоне(УникальныйИдентификатор);
    ПараметрыФона.НаименованиеФоновогоЗадания = НСтр("ru = 'Обработка данных'");
    Возврат ДлительныеОперации.ВыполнитьФункцию("ОбщийМодуль.ФункцияДляФона",
        ПараметрыФона, Параметры);
КонецФункции
 
// Подключение ожидания на клиенте
&НаКлиенте
Процедура ЗапуститьОперациюНаКлиенте()
    Операция = ЗапуститьОперацию(ПараметрыРасчёта);
    ПараметрыОжидания = ДлительныеОперацииКлиент.ПараметрыОжидания(ЭтотОбъект);
    ПараметрыОжидания.ВыводитьПрогресс = Истина;
    ДлительныеОперацииКлиент.ОжидатьЗавершение(Операция,
        Новый ОписаниеОповещения("ОперацияЗавершена", ЭтотОбъект), ПараметрыОжидания);
КонецПроцедуры
 
// Обработка результата
&НаКлиенте
Процедура ОперацияЗавершена(Операция, ДополнительныеПараметры) Экспорт
    Если Операция = Неопределено Тогда
        Возврат; // Отменена пользователем
    КонецЕсли;
    Если Операция.Статус = "Ошибка" Тогда
        СтандартныеПодсистемыКлиент.ОбработатьОшибкуФоновогоЗадания(Операция);
        Возврат;
    КонецЕсли;
    // Получить результат
    РезультатОперации = ПолучитьРезультатСервер(Операция.АдресРезультата);
КонецПроцедуры

Ключевые правила:

Передавай прогресс через ДлительныеОперации.СообщитьПрогресс() внутри фоновой процедуры.
Не храни состояние между шагами в глобальных переменных — используй параметры задания.
Реализуй идемпотентный перезапуск: повторный вызов с теми же параметрами должен давать тот же результат.

Правило 11: Безопасное хранилище (БезопасноеХранилище)

Никогда не храни пароли, токены и секреты в:

реквизитах объектов метаданных
константах конфигурации
журнале регистрации
системе контроля версий (конфиги, xml)

bsl

// Запись секрета
БезопасноеХранилище.Записать(ЭтотОбъект, Новый Структура("Пароль", ПарольПользователя));
 
// Чтение секрета
ДанныеХранилища = БезопасноеХранилище.ПрочитатьДанные(ЭтотОбъект);
Если ДанныеХранилища <> Неопределено Тогда
    Пароль = ДанныеХранилища.Пароль;
КонецЕсли;
 
// Удаление при удалении объекта
БезопасноеХранилище.Удалить(ЭтотОбъект);

В обработчике ПередУдалением объекта всегда вызывай БезопасноеХранилище.Удалить() — иначе «осиротевшие» записи накапливаются в хранилище.

Правило 12: Профили групп доступа (ПрофилиГруппДоступа)

При разработке подсистем с ролевым доступом — используй механизм профилей БСП вместо прямого назначения ролей.

bsl

// Пример описания профиля в ОписаниеПрофилейГруппДоступа()
Профиль = УправлениеДоступом.ОписаниеПрофиля();
Профиль.Идентификатор = "ИдентификаторПрофиля_UUID";
Профиль.Наименование   = НСтр("ru = 'Менеджер по продажам'");
Профиль.Роли.Добавить("РольМенеджерПродаж");
Профили.Добавить(Профиль);

Ключевые правила:

Идентификатор профиля — фиксированный UUID, не меняется при переименовании.
Для повышенных привилегий используй ПривилегированныйРежим() строго локально, сразу снимай после операции.
Проверку прав выполняй через УправлениеДоступом.ПроверитьДопустимостьДействия(), не через РольДоступна() напрямую — последнее не учитывает RLS.

Правило 13: Внешние обработки и расширения (СведенияОВнешнейОбработке)

Регистрация внешней обработки в БСП-базе требует функции СведенияОВнешнейОбработке() в основном модуле обработки.

bsl

// В модуле обработки
Функция СведенияОВнешнейОбработке() Экспорт
 
    СведенияОВнешнейОбработке = ДополнительныеОтчётыИОбработки.СведенияОВнешнейОбработке();
    СведенияОВнешнейОбработке.Вид = ДополнительныеОтчётыИОбработкиКлиентСервер
        .ВидОбработки().ДополнительнаяОбработка;
    СведенияОВнешнейОбработке.Наименование = НСтр("ru = 'Моя обработка'");
    СведенияОВнешнейОбработке.Версия       = "1.0";
    СведенияОВнешнейОбработке.БезопасныйРежим = Истина;
 
    // Описание команды
    Команда = СведенияОВнешнейОбработке.Команды.Добавить();
    Команда.Представление = НСтр("ru = 'Выполнить'");
    Команда.Идентификатор = "Выполнить";
    Команда.ИспользованиеКонтекста = ДополнительныеОтчётыИОбработкиКлиентСервер
        .ИспользованиеКонтекстаКоманды().ВПроцедуреВыполнитьКоманду;
 
    Возврат СведенияОВнешнейОбработке;
 
КонецФункции
 
// Точка входа для команды
Процедура ВыполнитьКоманду(Идентификатор, ПараметрыКоманды, ОбъектыНазначения) Экспорт
    // ... реализация ...
КонецПроцедуры

Поиск аналогов через Напарника

Если search_ssl_functions не дал результата — ask_ai_assistant (шаблон VALIDATE_BSL из buddy-prompting): передать фрагмент кода, получить рекомендации по замене на методы БСП. Также SEARCH_DOCS для документации по конкретному методу БСП.

depends_on: []

← v1.0.0 All versions v1.0.2 →