Правила создания общих модулей

#std469

Область применения: управляемое приложение, мобильное приложение, обычное приложение.

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

1.2. При разработке общих модулей следует выбирать один из четырех контекстов выполнения кода:

Тип общего модуля Пример наименования Вызов сервера Сервер Внешнее соединение Клиент
(обычное приложение)
Клиент
(управляемое приложение)
1. Серверный ОбщегоНазначения (или ОбщегоНазначенияСервер)

 

+

+

+

 

2. Серверный для вызова с клиента ОбщегоНазначенияВызовСервера

+

+

 

 

3. Клиентский ОбщегоНазначенияКлиент (или ОбщегоНазначенияГлобальный)

 

 

 

+

+

4. Клиент-серверный ОбщегоНазначенияКлиентСервер

 

+

+

+

+

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

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

Серверные общие модули называются по общим правилам именования объектов метаданных.
Например: РаботаСФайламиFilesOperations.

В отдельных случаях для предотвращения конфликта имен со свойствами глобального контекста может быть добавлен постфикс "Сервер" (англ. "Server").
Например: РегламентныеЗаданияСервер, ScheduledJobsServer.

2.2. Серверные общие модули для вызова с клиента содержат серверные процедуры и функции, доступные для использования из клиентского кода. Они составляют клиентский программный интерфейс сервера приложения.
Такие процедуры и функции размещаются в общих модулях с признаком:

Серверные общие модули для вызова с клиента называются по общим правилам именования объектов метаданных и должны именоваться с постфиксом "ВызовСервера" (англ. "ServerCall").
Например: РаботаСФайламиСлужебныйВызовСервераFilesOperationsInternalServerCall.

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

См. также: Ограничение на установку признака «Вызов сервера» у общих модулей, Обеспечение совместимости библиотек

2.3. Клиентские общие модули содержат клиентскую бизнес-логику (функциональность, определенную только для клиента) и имеют признаки:

Исключение составляют случаи, когда клиентские процедуры и функции должны быть доступны только в режиме управляемого приложения (только в режиме обычного приложения или только в режиме внешнего соединения). В таких случаях, допустима иная комбинация двух этих признаков.

Клиентские общие модули именуются с постфиксом "Клиент" (англ. "Client").
Например: РаботаСФайламиКлиентFilesOperationsClient.

См. также: минимизация кода, выполняемого на клиенте

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

Общие модули этого вида именуются с постфиксом "КлиентСервер" (англ. "ClientServer").
Например: РаботаСФайламиКлиентСерверFilesOperationsClientServer.

В то же время, как только возникает необходимость ветвить код в клиент-серверных общих модулях на серверный и клиентский, то не следует использовать для этого инструкции препроцессора. Вместо этого, функциональность, различную для клиента и для сервера, рекомендуется реализовывать по общим правилам в модулях соответствующего типа – см. пп. 2.1 и 2.3. Такое явное разделение клиентской и серверной бизнес-логики продиктовано соображениями повышения модульности прикладного решения, упрощения контроля со стороны разработчика над клиент-серверным взаимодействием и снижением риска ошибок из-за принципиальных отличий требований к разработке клиентского и серверного кода (необходимость минимизации кода, выполняемого на клиенте, разной доступностью объектов и типов платформы и др.). При этом нужно иметь в виду неизбежное увеличение числа общих модулей в конфигурации.

Подробнее см.: Использование директив компиляции и инструкций препроцессора

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

3.1. Имена общих модулей рекомендуется строить по общим правилам именования объектов метаданных. Название общего модуля должно совпадать с названием подсистемы или отдельного механизма, процедуры и функции которой он реализует. Рекомендуется избегать в названиях общих модулей таких общих слов как "Процедуры", "Функции", "Обработчики", "Модуль", "Функциональность" и т.п. и применять их только в исключительных случаях, когда они более полно раскрывают назначение модуля.

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

3.2. Дополнительно к общим модулям могут быть добавлены уточняющие постфиксы.

3.2.1. Для глобальных модулей добавляется постфикс "Глобальный" (англ. "Global"), в этом случае постфикс "Клиент" добавлять не следует.
Например: РаботаСФайламиСлужебныйГлобальныйFilesOperationsInternalGlobal.

3.2.2. Модули, выполняющиеся в привилегированном режиме, имеющие признак Привилегированный, именуются с постфиксом "ПолныеПрава" (англ. "FullAccess").
Например: РаботаСФайламиСлужебныйПолныеПраваFilesOperationsInternalFullAccess.

3.2.3. Модули, предназначенные для реализации на сервере или на клиенте функций с повторным использованием возвращаемых значений (на время вызова или на время сеанса), именуются с постфиксом "ПовтИсп" (англ. "Cached") и "КлиентПовтИсп" (англ. "ClientCached") соответственно.
Например: РаботаСФайламиСлужебныйКлиентПовтИспFilesOperationsInternalClientCached.

См. также: Обеспечение совместимости библиотек

3.2.4. Серверные и клиентские модули библиотечных конфигураций (которые предназначены не для самостоятельного использования, а для разработки других конфигураций) с процедурами и функциями, допускающие изменение своей реализации, именуются с постфиксами "Переопределяемый" (англ. "Overridable") и "КлиентПереопределяемый" (англ. "ClientOverridable").
Например: РаботаСФайламиКлиентПереопределяемыйFilesOperationsClientOverridable.

См. также: Переопределяемые и поставляемые объекты библиотеки

3.2.5. В локализуемых конфигурациях, на базе которых выпускаются национальные прикладные решения для различных стран или регионов, модули, реализующие национальную специфику, именуются с постфиксами "Локализация" (англ. "Localization") и "КлиентЛокализация" (англ. "ClientLocalization").
Например: ЭлктроннаяПодписьСлужебныйЛокализация, ElectonicSignatureInternalLocalization.

См. также