Пример контракта сервиса

Цель примера — изолировать код подсистемы от других частей приложения.

В проекте есть подсистема ПодсистемаРасчетЗарплаты. К ней за данными обращаются другие подсистемы. Для этого они используют контракт APIРасчетаЗарплаты, который объявлен в подсистеме.

Реализация этого контракта находится в этой же подсистеме в общем модуле РасчетЗарплаты.

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

Контракт будет иметь единственную реализацию, поэтому свойство контракта Множественный имеет значение Ложь.

ВидЭлемента: КонтрактСервиса
Ид: 090080db-f78f-4d6e-b4e5-0ed5dc39c6e4
ОбластьВидимости: ВПроекте
Имя: APIРасчетаЗарплаты
Окружение: КлиентИСервер
Обязательный: Истина
Множественный: Ложь

Значение свойства Обязательный равное Истина говорит о том, что одна реализация у этого контракта обязана быть. Это позволяет упростить использование этого контракта и не проверять перед использованием, существует ли его реализация.

Модуль контракта APIРасчетаЗарплаты.xbsl выглядит следующим образом.

// Импорт подсистемы Главная, чтобы к справочникам
// Организации и НачислениеЗарплаты обращаться по неквалифицированному имени.
импорт Главная

// Объявление типов, использующихся в параметрах методов.
структура СтруктураЗаписи 
    пер Поле1: Строка
    пер Поле2: Число
;

структура СтруктураПоказателей
    пер Поле1: Строка
    пер Поле2: Число
;

структура СтруктураЗаработка
    пер Поле1: Строка
    пер Поле2: Число
;

// Регистрирует значения оперативных показателей расчета зарплаты.
абстрактный метод ЗаписатьЗначенияОперативныхПоказателей(
   Движения: Массив<СтруктураЗаписи>, 
   Организация: Организации.Ссылка, 
   ОперативныеПоказатели: СтруктураПоказателей,
   ЗаписыватьДвижения = Ложь
)

// Регистрирует данные о сдельном заработке.
абстрактный метод ЗарегистрироватьСдельныйЗаработок(
   Движения: Массив<СтруктураЗаписи>, 
   Организация: Организации.Ссылка, 
   СдельныйЗаработок: СтруктураЗаработка
)

// Возвращает ссылку на заполненный документ начисления зарплаты 
// или создает новый.
абстрактный метод ДокументНачисленияЗарплаты(
   МесяцНачисления: ДатаВремя, 
   Организация: Организации.Ссылка, 
   Подразделение: Неопределено
): НачислениеЗарплаты.Ссылка?

// Процедура предназначена для создания документа отражения в бухучете
// из обработки РасчетЗарплаты.
абстрактный метод СоздатьДокументОтраженияВБухучете(
   Организация: Организации.Ссылка, 
   МесяцНачисления: ДатаВремя, 
   СтандартнаяОбработка: Булево
)

В нем объявлены четыре метода, из которых и состоит API подсистемы:

ЗаписатьЗначенияОперативныхПоказателей();
ЗарегистрироватьСдельныйЗаработок();
ДокументНачисленияЗарплаты();
СоздатьДокументОтраженияВБухучете().

Также в нем объявлены три типа данных, СтруктураЗаписи, СтруктураПоказателей и СтруктураЗаработка, которые используются в параметрах этих методов.

Описание общего модуля РасчетЗарплаты.yaml, который реализует контракт, выглядит следующим образом.

ВидЭлемента: ОбщийМодуль
Ид: d417a5cc-a09a-403f-9c39-0c5d0ffeb8a1
ОбластьВидимости: ВПроекте
Имя: РасчетЗарплаты
Окружение: КлиентИСервер
НастройкиТипа:
    Контракты:
        - APIРасчетаЗарплаты

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

// Импорт подсистемы Главная, чтобы к справочникам 
// Организации и НачислениеЗарплаты обращаться по неквалифицированному имени.
импорт Главная

// Регистрирует значения оперативных показателей расчета зарплаты.
@ВПроекте
@Реализация
метод ЗаписатьЗначенияОперативныхПоказателей(
   Движения: Массив<APIРасчетаЗарплаты.СтруктураЗаписи>,
   Организация: Организации.Ссылка,
   ОперативныеПоказатели: APIРасчетаЗарплаты.СтруктураПоказателей,
   ЗаписыватьДвижения = Ложь
)
    // Тело метода.
;

// Регистрирует данные о сдельном заработке.
@ВПроекте
@Реализация
метод ЗарегистрироватьСдельныйЗаработок(
   Движения: Массив<APIРасчетаЗарплаты.СтруктураЗаписи>, 
   Организация: Организации.Ссылка,
   СдельныйЗаработок: APIРасчетаЗарплаты.СтруктураЗаработка
)
    // Тело метода.
;

// Возвращает ссылку на заполненный документ начисления зарплаты 
// или создает новый.
@ВПроекте
@Реализация
метод ДокументНачисленияЗарплаты(
   МесяцНачисления: ДатаВремя,
   Организация: Организации.Ссылка,
   Подразделение: Неопределено
): НачислениеЗарплаты.Ссылка?
    // Тело метода.
    возврат Неопределено
;

// Процедура предназначена для создания документа отражения в бухучете 
// из обработки РасчетЗарплаты.
@ВПроекте
@Реализация
метод СоздатьДокументОтраженияВБухучете(
   Организация: Организации.Ссылка,
   МесяцНачисления: ДатаВремя,
   СтандартнаяОбработка: Булево
)
    // Тело метода.
;

Обращение к данным подсистемы расчета зарплаты из другой подсистемы выглядит следующим образом.

// Импорт подсистемы ПодсистемаРасчетЗарплаты, чтобы к модулю APIРасчетаЗарплаты
// обращаться по неквалифицированному имени.
импорт ПодсистемаРасчетЗарплаты

@НаСервере
метод Алгоритм()
    
    // Заполнить коллекцию движений.
    пер КоллекцияДвижений: Массив<APIРасчетаЗарплаты.СтруктураЗаписи>
    пер Запись = новый APIРасчетаЗарплаты.СтруктураЗаписи("строка", 2)
    КоллекцияДвижений.Добавить(Запись)
    
    // Найти организацию.
    пер Организация = Организации.НайтиПоКоду(8)
    
    // Заполнить структуру показателей.
    пер ОперативныеПоказатели = новый APIРасчетаЗарплаты.СтруктураПоказателей("показатель", 3)
    
    // Вызвать реализацию метода ЗаписатьЗначенияОперативныхПоказателей().
    пер СервисРасчета = APIРасчетаЗарплаты.ПолучитьСервис()    
    СервисРасчета.ЗаписатьЗначенияОперативныхПоказателей(
         КоллекцияДвижений,
         Организация,
         ОперативныеПоказатели,
         Истина
      )
;

Чтобы упростить обращения пространство имен подсистемы ПодсистемаРасчетЗарплаты импортируется в модуль.

Для обращения к типам данных, объявленным в контракте, используется имя контракта APIРасчетаЗарплаты.

Для получения реализации контракта используется его метод ПолучитьСервис().