БСП в 1С: как устроена библиотека стандартных подсистем и как ей пользоваться

Что такое БСП в 1С

БСП 1С — это библиотека, поставляемая «1С» отдельно от конфигураций и встраиваемая в них целиком или частями. Она закрывает функциональность, которая не относится к предметной области, но нужна почти каждому прикладному решению: пользователи и права, работа с файлами, дополнительные реквизиты и сведения, электронная почта, обмен данными, регламентные задания, журнал регистрации, версионирование объектов, печатные формы.

Для разработчика это означает две вещи. Первая: в типовой конфигурации значительная часть кода — не «код конфигурации», а код библиотеки, и относиться к нему нужно как к внешней зависимости. Вторая: перед тем как писать очередной helper, стоит проверить, нет ли готового решения в БСП, — иначе рядом с библиотечной функцией появится её самописный дубль, который придётся сопровождать вручную.

Отдельная особенность: БСП не описана в синтакс-помощнике платформы. Источник истины по сигнатурам — комментарии перед экспортными функциями в самих модулях библиотеки, а также поставляемая документация к версии БСП.

Как устроена библиотека: подсистемы и общие модули

Библиотека нарезана на подсистемы. Каждая подсистема — это связанный набор объектов метаданных: свои справочники и регистры, формы, обработчики и один или несколько общих модулей. Подсистемы можно внедрять выборочно, но у них есть зависимости, и «Базовая функциональность» нужна всегда.

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

Масштаб стоит представлять заранее. В выгрузке конфигурации «Управление торговлей» каталог CommonModules содержит 2872 общих модуля (библиотека плюс прикладной код конфигурации). Модуль ОбщегоНазначения в этой выгрузке — 11155 строк, ОбщегоНазначенияКлиентСервер — 4855 строк, СтандартныеПодсистемыСервер — 6320 строк. Без понимания правил именования ориентироваться в таком объёме невозможно, поэтому с них и начнём.

Принцип именования общих модулей БСП

Суффикс в имени общего модуля — это не украшение, а объявленный контракт. Он отражает свойства модуля в метаданных (Сервер, Клиент, Вызов сервера, Повторное использование возвращаемых значений) и статус его программного интерфейса.

• Без суффикса (ОбщегоНазначения, Пользователи) — серверный модуль: Сервер = Истина, клиент выключен, прямой вызов с клиента невозможен.
• Клиент (ОбщегоНазначенияКлиент) — только клиентский контекст: работа с формами, диалогами, оповещениями.
• КлиентСервер (ОбщегоНазначенияКлиентСервер) — доступен и на сервере, и на клиенте. Здесь лежат функции без обращения к базе: работа с коллекциями, строками, датами, проверки параметров.
• ВызовСервера (ОбщегоНазначенияВызовСервера) — серверный модуль с флагом Вызов сервера: его экспортные функции можно вызвать из клиентского кода, каждый вызов — обращение к серверу.
• ПовтИсп (СтандартныеПодсистемыПовтИсп) — включено повторное использование возвращаемых значений (на время сеанса или вызова). Результат кешируется по набору параметров, поэтому такие функции обязаны быть детерминированными и не иметь побочных эффектов.
• Переопределяемый (ОбщегоНазначенияПереопределяемый) — штатная точка расширения. Библиотека вызывает его процедуры сама, а внедренец пишет в них свой код. Именно сюда попадают ПриОпределенииОбщихПараметровБазовойФункциональности, ПриДобавленииОбработчиковУстановкиПараметровСеанса и подобные обработчики.
• Служебный (ПользователиСлужебный) — внутренняя реализация подсистемы. Его код заключён в область #Область СлужебныйПрограммныйИнтерфейс и предназначен только для самой библиотеки.
• Локализация, УТ и подобные — модули адаптации: локализованная или конфигурационная надстройка над подсистемой.

Суффиксы комбинируются: РаботаСФайламиСлужебныйКлиентСервер — служебный модуль, доступный в обоих контекстах, РаботаСФайламиСлужебныйПовтИсп — служебный с кешированием. Читать имя нужно слева направо: подсистема, затем статус интерфейса, затем контекст исполнения.

ОбщегоНазначения: серверные функции, которые нужны чаще всего

Модуль ОбщегоНазначения — самый используемый модуль библиотеки. Его главная прикладная ценность — чтение реквизитов по ссылке одним запросом, без чтения объекта целиком.

// Один реквизит по ссылке
ДатаДок = ОбщегоНазначения.ЗначениеРеквизитаОбъекта(СсылкаДок, "Дата");

// Несколько реквизитов за один запрос — возвращается структура
Реквизиты = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
    СсылкаДок, "Дата, Номер, Контрагент, Проведен");

Если Реквизиты.Проведен Тогда
    Сообщить(Реквизиты.Контрагент);
КонецЕсли;

// Таблица значений в массив структур
МассивСтрок = ОбщегоНазначения.ТаблицаЗначенийВМассив(Товары);

Разница между чтением реквизита и чтением объекта критична в циклах и обработках больших выборок: подробный разбор с замерами — в статье о ЗначениеРеквизитаОбъекта и ЗначенияРеквизитовОбъекта. Про преобразование табличной части в массив структур и его применение — в статье о ТаблицаЗначенийВМассив.

ОбщегоНазначенияКлиентСервер: коллекции, строки и даты

В ОбщегоНазначенияКлиентСервер собраны функции, которым не нужна база данных, поэтому один и тот же вызов работает и в модуле формы, и в серверной процедуре.

// Обернуть значение в массив (типовой параметр отбора)
Отбор.Вставить("Организация",
    ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве(Организация));

// Убрать дубли из массива
Уникальные = ОбщегоНазначенияКлиентСервер.СвернутьМассив(МассивКонтрагентов);

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

// Строка в дату: пустая строка даёт Дата(1, 1, 1)
ДатаЗначение = ОбщегоНазначенияКлиентСервер.СтрокаВДату(СтрокаИзФайла);

Такие функции экономят не столько строки, сколько ошибки: ЗначениеВМассиве убирает ручное создание массива под каждый отбор, СвойствоСтруктуры — проверку Свойство() перед каждым обращением. Детальные разборы: ЗначениеВМассиве и работа с массивами, структуры и соответствия в БСП, преобразование строки в дату.

Модули подсистем: пользователи, файлы, дополнительные реквизиты

Кроме универсальных модулей, у каждой подсистемы есть свой программный интерфейс. Три подсистемы встречаются в прикладных задачах чаще прочих.

// Пользователи: текущий пользователь сеанса
Автор = Пользователи.АвторизованныйПользователь(); // может быть внешним пользователем
Автор = Пользователи.ТекущийПользователь();        // только СправочникСсылка.Пользователи

Если Пользователи.ЭтоПолноправныйПользователь() Тогда
    // ветка для администратора
КонецЕсли;

// РаботаСФайлами: содержимое присоединённого файла
Данные = РаботаСФайлами.ДвоичныеДанныеФайла(СсылкаНаФайл);

// УправлениеСвойствами: значения дополнительных реквизитов объектов
Значения = УправлениеСвойствами.ЗначенияСвойств(МассивОбъектов);

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

Как быстро найти нужную функцию БСП

Синтакс-помощник здесь не поможет, поэтому работает другой порядок действий:

1. Определить подсистему по задаче: файлы — РаботаСФайлами, доп. реквизиты — УправлениеСвойствами, пользователи — Пользователи, общее — ОбщегоНазначения.
2. Открыть модуль без суффикса или с суффиксом КлиентСервер и смотреть только область #Область ПрограммныйИнтерфейс: всё, что вне её, — не для прикладного кода.
3. Прочитать комментарий перед функцией: в БСП он оформлен по стандарту и содержит описание параметров и тип возвращаемого значения. Это и есть замена справки.
4. Если модуль неизвестен — искать по глобальному поиску конфигуратора или по выгрузке в файлы: имена функций в библиотеке говорящие, поиск по фрагменту («Реквизит», «Массив», «Файл») почти всегда попадает в цель.

Полезный приём при поиске по выгрузке: искать строку Экспорт вместе с ключевым словом. Экспортная функция в модуле без суффикса Служебный — это публичный интерфейс, на который можно опираться.

Как узнать версию БСП в конкретной базе

Версия библиотеки определяет, какие функции доступны: интерфейс БСП между версиями меняется, и код, написанный под 3.1, может не запуститься на более ранней. Номер версии возвращает функция ВерсияБиблиотеки модуля СтандартныеПодсистемыСервер.

Версия = СтандартныеПодсистемыСервер.ВерсияБиблиотеки();
Сообщить("Версия БСП: " + Версия); // например, "3.1.10.х"

// Сравнение версий — штатной функцией библиотеки
Если ОбщегоНазначенияКлиентСервер.СравнитьВерсии(Версия, "3.1.5.0") >= 0 Тогда
    // ветка для новых версий
КонецЕсли;

Внутри функция читает описания подсистем и берёт версию подсистемы СтандартныеПодсистемы, поэтому результат — именно версия библиотеки, а не версия конфигурации. Второй способ, без кода: посмотреть версию подсистемы «Стандартные подсистемы» в свойствах конфигурации или в справке «О программе» типового решения.

Чего нельзя делать с библиотекой

БСП — внешняя зависимость с собственным циклом обновления. Из этого следуют жёсткие ограничения.

• Нельзя править модули библиотеки. При обновлении БСП модуль приедет в новой редакции, и правка либо потеряется, либо превратится в конфликт объединения, который придётся разбирать вручную по каждому обновлению. Нужное поведение добавляется через модули с суффиксом Переопределяемый или через расширение конфигурации.
• Нельзя вызывать модули с суффиксом Служебный. Это внутренняя реализация: сигнатуры и сам факт существования функции меняются между версиями без предупреждения. Если нужная возможность есть только в служебном модуле — значит, её публичный аналог либо в другом модуле, либо в другой версии библиотеки.
• Нельзя обращаться к неэкспортным процедурам и к коду вне области #Область ПрограммныйИнтерфейс, даже если технически вызов проходит.
• Нельзя переносить куски кода библиотеки в свои модули. Копия перестаёт обновляться вместе с БСП и со временем начинает вести себя иначе, чем оригинал.
• Нельзя класть в ПовтИсп-модули функции с побочными эффектами. Результат кешируется, и повторный вызов просто не выполнится.

Частые ошибки при работе с БСП

• Вызов серверного модуля с клиента. ОбщегоНазначения — серверный модуль без флага «Вызов сервера»; с клиента доступны ОбщегоНазначенияКлиент, ОбщегоНазначенияКлиентСервер и ОбщегоНазначенияВызовСервера.
• Правка модуля библиотеки «на пару строк». Конфигурация снимается с поддержки или получает вечный конфликт при обновлении БСП.
• Вызов служебного модуля, найденного поиском. Работает сегодня и падает после обновления библиотеки.
• Чтение объекта ради одного реквизита. Ссылка.ПолучитьОбъект() в цикле вместо ЗначенияРеквизитовОбъекта — типовая причина медленной обработки.
• Функция с побочным эффектом в ПовтИсп-модуле. Второй вызов вернёт закешированный результат, и действие не выполнится.
• Самописный дубль библиотечной функции. Свой «СвернутьМассив» рядом с библиотечным — лишний код и расхождение в поведении на граничных случаях.
• Код под чужую версию БСП. Перед использованием редкой функции стоит сверить версию библиотеки в базе.

Частые вопросы про БСП в 1С