Обеспечение обратной совместимости библиотек

Методическая рекомендация (полезный совет)

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

Например, версии библиотеки 2.0.1, 2.0.2 и 2.0.5 должны быть обратно совместимы. Однако допустимо, если следующая редакция 2.1 будет содержать существенные изменения, нарушающие это правило.

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

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

1.1. В целях обеспечения обратной совместимости следует

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

1.2. К программному интерфейсу библиотеки относятся те ее объекты метаданных, которые предназначены для использования в прикладном коде:

• имена и состав параметров экспортных процедур и функций общих модулей, модулей объектов, менеджеров, наборов записей и т.п., которые размещены в разделе «программный интерфейс»;
• имена и состав параметров всех экспортных процедур и функций переопределяемых общих модулей;
• имена объектов метаданных (включая их реквизиты, табличные части и пр.), к которым допускается непосредственное обращение из прикладного кода или из запросов.

Программный интерфейс библиотеки является самостоятельным предметом проектирования.

1.3. Рекомендуется размещать программный интерфейс библиотеки только в ее общих модулях, а не в модулях объектов, менеджеров, наборов записей и т.п.

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

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

• Общие модули ОбменСообщениями и ОбменСообщениямиКлиент – программный интерфейс подсистемы «Обмен сообщениями»
• Общий модуль ОбменСообщениямиСлужебный – служебные процедуры и функции подсистемы, которые не предназначены для использования в коде конфигурации-потребителя.

Такое размещение программного интерфейса в отдельных общих модулях позволяет

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

1.5. Обратную совместимость не нарушает расширение программного интерфейса библиотеки, например:

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

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

• Общий модуль ВнешниеЗадачиПереопределяемыйВызовСервера переименован в ВнешниеЗадачиВызовСервераПереопределяемый. Необходимо заменить все обращения к этому модулю в коде конфигурации.
• Процедура УстановитьПроизвольныйЗаголовокПриложения общего модуля СтандартныеПодсистемыКлиент переименована в УстановитьРасширенныйЗаголовокПриложения. Необходимо заменить все обращения к этой процедуре в коде конфигурации.
• Отчет СправкаПоИсполнительскойДисциплине удален. Вместо него следует использовать одноименный вариант отчета Задачи. Необходимо заменить все обращения к этому отчету в коде и в метаданных конфигурации.
• В общий модуль ЗащитаПерсональныхДанныхПереопределяемый добавить процедуру ДополнитьДанныеОрганизацииОператораПерсональныхДанных, перенеся ее определение из поставки библиотеки.
• Хранение предмета взаимодействий перенесено из реквизита документа в реквизит Предметрегистра сведений ПредметыПапкиВзаимодействий. Необходимо заменить все обращения к реквизиту Предмет документов взаимодействий на реквизит Предметрегистра сведений .

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

2.1. При необходимости переименовать (или удалить) экспортную функцию (процедуру) следует оставить старую реализацию функции, пометив ее как устаревшую с помощью комментария вида:

// Устарела: Следует использовать функцию ПересчитатьПоКурсу
// …
Функция ПересчитатьИзВалютыВВалюту(Сумма, ВалютаНач, ВалютаКон, ПоКурсуНач, ПоКурсуКон, ПоКратностьНач = 1, ПоКратностьКон = 1) Экспорт

и разместить новую версию функции с новым именем (в данном примере - ПересчитатьПоКурсу). Как правило, реализация старой версии функции при этом заменяется на вызов новой версии функции.

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

2.2. При необходимости пересмотреть состав параметров экспортных функций (процедур) следует использовать опциональные параметры, которые добавляются в конец списка формальных параметров.
Например:

Функция ПересчитатьИзВалютыВВалюту(Сумма, ВалютаНач, ВалютаКон, ПоКурсуНач, ПоКурсуКон, ПоКратностьНач = 1, ПоКратностьКон = 1) Экспорт

При этом в случае большого числа параметров рекомендуется более радикально пересмотреть их состав и действовать согласно п. 2.1.

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

Например, вместо «прямого» запроса к библиотечному регистру из прикладного кода:

Запрос = Новый Запрос;
Запрос.Текст = "ВЫБРАТЬ
| ОбластиДанных. Представление 
|ИЗ
| РегистрСведений.ОбластиДанных КАК ОбластиДанных
|ГДЕ
| ОбластиДанных.ОбластьДанных = &ОбластьДанных";
Запрос.УстановитьПараметр("ОбластьДанных", ПараметрыСеанса.ОбластьДанныхЗначение);
ТаблицаОбластейДанных = Запрос.Выполнить().Выгрузить();
ИмяПриложения = ?(ТаблицаОбластейДанных.Количество() = 0, "", ТаблицаОбластейДанных.Получить(0).Получить(0));

следует предусмотреть в библиотеке экспортную функцию, которая специально предназначена для использования в прикладном коде:

ИмяПриложения = РаботаВМоделиСервиса.ИмяПриложения();

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

2.4. Другой пример скрытия деталей реализации библиотеки от потребителя. Допустим:

• в первой версии библиотеки потребителям предоставлялась экспортная функция общего модуля с повторным использованием возвращаемых значений;
• но в следующей версии библиотеки это проектное решение пересмотрено в пользу «обычного» общего модуля, куда эта функция была перенесена (аналогично, если в обратную сторону).

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