При разработке сложных тиражируемых решений или крупных корпоративных систем на платформе 1С перед разработчиком неизбежно встает архитектурная задача. Как описать «костяк» (ядро) программы и четко определить требования к API для функций расширения? С одной стороны, не хочется превращать систему в «черный ящик» для сторонних разработчиков. С другой стороны, сложные схемы в тяжелых нотациях вроде BPWIN или UML часто быстро устаревают, а читать бесконечные простыни сухого программного кода без пояснений — сомнительное удовольствие.
В этой статье мы подробно разберем, как эффективно решить эту задачу. Мы проанализируем проверенные временем классические подходы, а также рассмотрим современные инструменты автоматизации документирования, визуализации и ведения архитектурных решений, которые применяются в современной экосистеме 1С.
Когда речь заходит о документировании структуры кода, у многих разработчиков возникает соблазн найти сложную графическую нотацию или автоматическую «вундервафлю». Однако практика разработки крупнейших библиотек, таких как Библиотека стандартных подсистем (БСП) от фирмы «1С», доказывает: лучшее решение — это структурированный, понятный русский текст с примерами кода.
Для описания ядра системы отлично подходит концепция «механизмов». Механизм — это логическая единица архитектуры, которая находится выше уровня отдельной процедуры или функции, но ниже уровня целой подсистемы метаданных. Описание механизма должно отвечать на три главных вопроса:
Проанализируем пример структуры такого описания для условного механизма скидок:
Механизм расчета скидок в чеке ККМ
==================================
1. Назначение
Обеспечивает автоматический расчет скидок при заполнении табличной части "Товары".
2. Архитектурный костяк (Core)
- Общий модуль "СкидкиКартыСервер" — содержит ядро расчета (процедура "РассчитатьСкидки").
- Регистр сведений "ДействующиеСкидки" — хранит правила и условия.
3. Точки расширения (API)
Для добавления собственных видов скидок необходимо:
1) Добавить элемент в предопределенный список условий.
2) Реализовать алгоритм расчета в переопределяемом модуле "СкидкиКартыПереопределяемый"
в процедуре "ПриРасчетеСобственнойСкидки".
Такой подход не требует изучения специализированного ПО и понятен любому новому программисту, пришедшему на проект.
Если для описания глобального «костяка» подходит обычный текст, то требования к конкретным программным интерфейсам (API) лучше всего документировать непосредственно в коде. В мире веб-разработки для этого используется JSDoc. В экосистеме 1С разработан аналогичный строгий стандарт документирования процедур и функций.
Современные инструменты разработки, такие как 1С:EDT и плагины для VS Code (например, на базе BSL Language Server), умеют «на лету» парсить стандартизованные комментарии. Разработчик получает всплывающие контекстные подсказки с описанием типов параметров и структуры возвращаемых значений при вызове функций.
Посмотрим на пример правильного оформления программного интерфейса (API) для расширения системы:
// Выполняет расчет индивидуальной скидки по дисконтной карте.
//
// Параметры:
// ДисконтнаяКарта - СправочникСсылка.ИнформационныеКарты - Ссылка на карту клиента.
// СуммаДоСкидки - Число - Исходная сумма документа для расчета.
// ПараметрыРасчета - Структура - Дополнительные параметры:
// * УчитыватьНакопления - Булево - Использовать ли историю покупок клиента.
// * Склад - СправочникСсылка.Склады - Место продажи.
//
// Возвращаемое значение:
// Число - Итоговая сумма предоставляемой скидки в валюте учета.
//
Функция РассчитатьИндивидуальнуюСкидку(Знач ДисконтнаяКарта, Знач СуммаДоСкидки, Знач ПараметрыРасчета) Экспорт
// Костяк базового расчета
Скидка = 0;
// Вызов переопределяемого метода (точка расширения)
СкидкиКартыПереопределяемый.ПриРасчетеСкидки(ДисконтнаяКарта, СуммаДоСкидки, ПараметрыРасчета, Скидка);
Возврат Скидка;
КонецФункции
Используя утилиты автоматизации (например, bsl2jsdoc или генераторы статических сайтов вроде Docusaurus), вы можете автоматически собрать все такие комментарии из ваших общих модулей и выгрузить их в виде красивого веб-сайта с документацией API. Это полностью решает проблему ручного обновления описания функций.
Иногда текстового описания недостаточно, и требуется визуализировать архитектуру системы. Традиционные UML-диаграммы классов часто оказываются избыточными и сложными для поддержки в 1С, так как платформа сама управляет объектной моделью метаданных.
Отличной альтернативой является международный стандарт визуализации ИТ-систем — C4 Model (Context, Containers, Components, Code). Рассмотрим, как уровни C4 адаптируются под архитектуру 1С:
Чтобы схемы не устаревали, рекомендуется использовать подход «Архитектура как код» (Architecture as Code). Схемы описываются обычным текстом с помощью инструмента PlantUML. Вы можете версионировать эти схемы в Git вместе с кодом вашей конфигурации. Посмотрим на пример текстового описания схемы PlantUML для нашего механизма:
@startuml
package "Ядро конфигурации (Core)" {
[Модуль расчета скидок] as CoreCalc
[Регистр правил] as RulesDB
}
package "Точки расширения (API)" {
[Переопределяемый модуль] as ExtensionAPI
}
CoreCalc --> RulesDB : Чтение настроек
CoreCalc ..> ExtensionAPI : Передача управления при расчете
@enduml
Этот код автоматически рендерится в наглядную графическую схему взаимодействия компонентов.
Часто описание «костяка» программы теряет актуальность из-за того, что архитектурные решения принимаются «на лету» в чатах или устно. Для фиксации правил проектирования и требований к API рекомендуется использовать практику ADR (Архив архитектурных решений).
Каждое важное решение по структуре кода оформляется в виде небольшого файла в формате Markdown и сохраняется в репозиторий проекта в папку docs/adr. Структура такого документа строго регламентирована:
ADR-003: Использование подписок на события для расширения логики проведения документов).ОбработкаПроведения»).Такой подход гарантирует, что правила разработки и требования к API не будут потеряны, а новые разработчики смогут быстро войти в проект, просто прочитав историю принятых решений.
Для эффективного описания структуры кода и требований к API в 1С не стоит искать сложные графические нотации. Наш практический опыт предлагает сбалансированный стек документирования:
Такой комплексный подход сделает ваш код понятным, а процесс его расширения — безопасным и прогнозируемым.