Забезпечення зворотної сумісності бібліотек

Методична рекомендація (корисна порада)

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. Інший приклад приховування деталей реалізації бібліотеки від споживача. Припустімо:

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

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