Как создать библиотеку в 1С: от общего модуля до переиспользуемой подсистемы

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

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

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

Что считать библиотекой в контексте 1С

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

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

Проектирование: границы, имена и структура модулей

До открытия конфигуратора определите, что войдёт в библиотеку, а что останется в прикладных объектах. Признак библиотечного кода — он не зависит от конкретного документа или справочника и может использоваться повторно. Например, функция «СформироватьПечатнуюФорму» относится к документу, а «ПодготовитьТабличныйДокументКОтправке» — кандидат в библиотеку.

Выберите префикс для имён модулей — обычно 2–4 символа, отражающие проект или организацию: АИТ_ОбщегоНазначения, МП_РаботаСПочтой. Префикс защищает от конфликтов имён при обновлении типовой конфигурации и сразу показывает происхождение кода. Внутри библиотеки принято разделять модули по ролям: клиентский, серверный, повторного использования.

• ИмяБиблиотеки — серверный модуль с основным программным интерфейсом;
• ИмяБиблиотекиКлиент — клиентские процедуры (диалоги, открытие форм);
• ИмяБиблиотекиВызовСервера — тонкий слой для обращения к серверу из клиентского кода;
• ИмяБиблиотекиПовтИсп — функции, результаты которых кэшируются на время сеанса.

Создание общего модуля: пошаговая инструкция

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

1. 1
   Откройте конфигуратор и дерево конфигурации, ветка «Общие» → «Общие модули».
2. 2
   Нажмите «Добавить» и задайте имя с префиксом, например АИТ_РаботаСоСтроками.
3. 3
   В свойствах модуля включите флаги «Сервер» и «Вызов сервера»; снимите «Клиент (управляемое приложение)», если модуль серверный.
4. 4
   Откройте модуль и добавьте область «ПрограммныйИнтерфейс» с экспортными процедурами и функциями.
5. 5
   Разместите вспомогательный код в области «СлужебныеПроцедурыИФункции» без слова «Экспорт».
6. 6
   Сохраните конфигурацию (F7) и выполните синтаксическую проверку модуля.

Ключевой момент — флаги компиляции. Флаг «Сервер» означает, что код исполняется на сервере 1С; «Вызов сервера» разрешает обращение к модулю из клиентского контекста. Ошибка в расстановке флагов — частая причина сообщений вида «Процедура или функция с указанным именем не определена» при работающей проверке конфигурации.

Пример минимального содержимого модуля:

#Область ПрограммныйИнтерфейс

// Удаляет из строки недопустимые символы.
//
// Параметры:
//   ИсходнаяСтрока - Строка - обрабатываемое значение.
//
// Возвращаемое значение:
//   Строка - очищенная строка.
//
Функция ОчиститьСтроку(ИсходнаяСтрока) Экспорт
Возврат СокрЛП(СтрЗаменить(ИсходнаяСтрока, Символы.НПП, ""));
КонецФункции

#КонецОбласти

Флаги компиляции и контексты исполнения

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

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

Программный интерфейс и соглашения о коде

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

Внутренние алгоритмы помещайте в область СлужебныеПроцедурыИФункции без ключевого слова Экспорт. Так вы сохраняете свободу рефакторинга: менять внутреннюю реализацию можно, не опасаясь сломать вызывающий код. Если служебная функция всё же должна быть видна другим модулям библиотеки, но не прикладному коду, некоторые команды используют отдельный модуль с суффиксом «Служебный».

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

Объединение модулей в подсистему и поставку библиотеки

Когда модулей несколько, создайте подсистему: ветка «Общие» → «Подсистемы», команда «Добавить». В свойствах подсистемы укажите синоним, картинку и включите в состав общие модули, а при необходимости — роли, функциональные опции и XDTO-пакеты библиотеки. Подсистема даёт навигацию в панели разделов и служит логической границей при выгрузке.

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

Сравнение вариантов

Общие модули внутри конфигурации

Подходит для одного проекта. Минимальные накладные расходы, но перенос в другую конфигурацию выполняется вручную.

Отдельная подсистема с поставкой

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

Расширение конфигурации

Подходит, когда библиотека дополняет типовое решение без изменения его кода. Ограничение: не все объекты доступны в расширениях.

Проверка результата и типичные ошибки

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

Контрольные точки

Как проверить результат

Компиляция модулей

Норма

Проверка конфигурации завершается без ошибок в ветке общих модулей

Тревожный признак

Сообщения «переменная не определена» или «процедура не обнаружена»

Вызов из клиентского кода

Норма

Функция выполняется, данные возвращаются на клиент

Тревожный признак

Ошибка «вызов сервера запрещён» — не установлен соответствующий флаг

Права пользователя

Норма

Обычный пользователь выполняет сценарий без ошибок доступа

Тревожный признак

«Нарушение прав доступа» — код требует привилегированного режима или настройки ролей

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

Частые вопросы о библиотеках в 1С

Чем общий модуль отличается от модуля менеджера объекта?

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

Можно ли вызывать функции библиотеки из внешней обработки?

Да, если модули развёрнуты в той же конфигурации и у них установлены подходящие флаги компиляции. Вызов выглядит как обычное обращение: ИмяМодуля.ИмяФункции(). В безопасном режиме внешних обработок доступ к общим модулям может быть ограничен настройками защиты.

Сколько общих модулей допустимо в одной библиотеке?

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

Как обновить библиотеку в базе, где она уже встроена?

Через сравнение и объединение конфигураций с файлом поставки новой версии. Перед объединением сверьте список изменённых объектов, чтобы не перезаписать локальные доработки, и проверьте обратную совместимость программного интерфейса.

Нужен ли для библиотеки режим совместимости?

Библиотека наследует режим совместимости конфигурации, в которую встроена. Если планируется встраивание в разные конфигурации, пишите код, не опирающийся на возможности только самой новой платформы, либо явно документируйте минимальную версию.

Можно ли оформить библиотеку как расширение конфигурации?

Да, во многих случаях это удобный вариант: расширение не меняет типовую конфигурацию и легко отключается. Ограничения — не все виды объектов и механизмов доступны в расширениях, а заимствованные общие модули нельзя изменять произвольно, только дополнять.