Чи існує схема обробки конфліктуючих параметрів функції?

У нас є функція API, яка розбиває загальну суму на щомісячні суми залежно від дати початку та закінчення.

// JavaScript

function convertToMonths(timePeriod) {
  // ... returns the given time period converted to months
}

function getPaymentBreakdown(total, startDate, endDate) {
  const numMonths = convertToMonths(endDate - startDate);

  return {
    numMonths,
    monthlyPayment: total / numMonths,
  };
}

Нещодавно споживач цього API хотів вказати діапазон дат іншими способами: 1) шляхом надання кількості місяців замість дати закінчення, або 2) шляхом надання щомісячного платежу та підрахунку дати закінчення. У відповідь на це команда API змінила функцію на наступну:

// JavaScript

function addMonths(date, numMonths) {
  // ... returns a new date numMonths after date
}

function getPaymentBreakdown(
  total,
  startDate,
  endDate /* optional */,
  numMonths /* optional */,
  monthlyPayment /* optional */,
) {
  let innerNumMonths;

  if (monthlyPayment) {
    innerNumMonths = total / monthlyPayment;
  } else if (numMonths) {
    innerNumMonths = numMonths;
  } else {
    innerNumMonths = convertToMonths(endDate - startDate);
  }

  return {
    numMonths: innerNumMonths,
    monthlyPayment: total / innerNumMonths,
    endDate: addMonths(startDate, innerNumMonths),
  };
}

Я думаю, що ця зміна ускладнює API. Тепер абонент повинен турбуватися про евристиках захованих з реалізацією функції у визначенні того, які параметри приймають перевагу в даний час використовується для розрахунку діапазону дат (тобто в порядку пріоритету monthlyPayment, numMonths, endDate). Якщо абонент не звертає уваги на підпис функції, він може надіслати кілька необов'язкових параметрів і заплутатися в тому, чому endDateйого ігнорують. Ми вказуємо цю поведінку в документації щодо функцій.

Крім того, я вважаю, що це створює поганий прецедент і додає API відповідальності, з якою він не повинен стосуватися себе (тобто порушує SRP). Нехай додаткові споживачі хочуть функції для підтримки більшого числа випадків використання, наприклад, обчислення totalвід numMonthsі monthlyPaymentпараметрів. Ця функція з часом буде ускладнюватися.

Моя перевага - зберегти функцію такою, якою вона була, і замість цього вимагати від абонента розрахувати endDateсебе. Однак я можу помилитися і мені було цікаво, чи внесені ними зміни є прийнятним способом розробити функцію API.

Як варіант, чи існує загальна модель для обробки подібних сценаріїв? Ми могли б надати додаткові функції вищого порядку в нашому API, які містять оригінальну функцію, але це роздуває API. Можливо, ми могли б додати додатковий параметр прапора, який визначає, який підхід використовувати всередині функції.

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

Оригінальний:

function getPaymentBreakdown(total, startDate, endDate) 

Той, що містить кількість місяців замість дати закінчення:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

і той, що забезпечує щомісячний платіж та обчислює дату закінчення:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Тепер вже немає додаткових параметрів, і повинно бути досить зрозуміло, яка функція називається як і з якою метою. Як зазначалося в коментарях, строго набраною мовою можна було також використовувати функцію перевантаження, виділяючи 3 різні функції не обов'язково за своїм ім'ям, а за їх підписом, якщо це не заплутує їх призначення.

Зауважте, що різні функції не означають, що вам потрібно дублювати будь-яку логіку - якщо всередині цих функцій спільний алгоритм, він повинен бути відновлений до "приватної" функції.

чи існує загальна модель для обробки подібних сценаріїв

Я не думаю, що існує "модель" (в сенсі моделей дизайну GoF), яка описує хороший дизайн API. Використання самостійно описуючих імен, функцій із меншою кількістю параметрів, функцій з ортогональними (= незалежними) параметрами - лише основні принципи створення читабельного, підтримуваного та еволюційного коду. Не кожна гарна ідея в програмуванні обов'язково є «дизайнерською схемою».

Крім того, я вважаю, що це створює поганий прецедент і додає API відповідальності, з якою він не повинен стосуватися себе (тобто порушує SRP). Нехай додаткові споживачі хочуть функції для підтримки більшого числа випадків використання, наприклад, обчислення totalвід numMonthsі monthlyPaymentпараметрів. Ця функція з часом буде ускладнюватися.

Ви абсолютно правильні.

Моя перевага полягає в тому, щоб зберегти функцію такою, якою вона була, і замість цього вимагати, щоб абонент сам розрахував endDate. Однак я можу помилитися і мені було цікаво, чи внесені ними зміни є прийнятним способом розробити функцію API.

Це також не ідеально, оскільки код абонента буде забруднений незв'язаною плитою котла.

Як варіант, чи існує загальна модель для обробки подібних сценаріїв?

Введіть новий тип, як DateInterval. Додайте сенси конструкторів (дата початку + кінцева дата, дата початку + число місяців тощо). Прийміть це як типи загальної валюти для вираження інтервалів дат / разів у всій вашій системі.

Іноді в цьому допомагають вільні вирази:

let payment1 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byPeriod(months(2));

let payment2 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byDateRange(saleStart, saleEnd);

let monthsDue = forTotalAmount(1234)
                  .calculatePeriod()
                  .withPaymentsOf(12.34)
                  .monthly();

Виділивши достатньо часу для розробки, ви можете створити надійний API, який діє аналогічно мові, що залежить від домену.

Інша велика перевага полягає в тому, що IDE з автозаповненням змушують майже не зважати на читання документації API, як це інтуїтивно зрозуміло завдяки можливостям самовідкриття.

Там є такі ресурси, як https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ або https://github.com/nikaspran/fluent.js з цієї теми.

Приклад (взятий із першого посилання на ресурс):

let insert = (value) => ({into: (array) => ({after: (afterValue) => {
  array.splice(array.indexOf(afterValue) + 1, 0, value);
  return array;
}})});

insert(2).into([1, 3]).after(1); //[1, 2, 3]

Ну, в інших мовах ви б використовували названі параметри . Це можна наслідувати у Javscript:

function getPaymentBreakdown(total, startDate, durationSpec) { ... }

getPaymentBreakdown(100, today, {endDate: whatever});
getPaymentBreakdown(100, today, {noOfMonths: 4});
getPaymentBreakdown(100, today, {monthlyPayment: 20});

Як альтернативу, ви також можете зламати відповідальність за вказівку кількості місяця та виключити її зі своєї функції:

getPaymentBreakdown(420, numberOfMonths(3))
getPaymentBreakdown(420, dateRage(a, b))
getPaymentBreakdown(420, paymentAmount(350))

І getpaymentBreakdown отримає об'єкт, який забезпечить базову кількість місяців

Це буде функція вищого порядку, повертаючи, наприклад, функцію.

function numberOfMonths(months) {
  return {months: (total) => months};
}

function dateRange(startDate, endDate) {
  return {months: (total) => convertToMonths(endDate - startDate)}
}

function monthlyPayment(amount) {
  return {months: (total) => total / amount}
}


function getPaymentBreakdown(total, {months}) {
  const numMonths= months(total);
  return {
    numMonths, 
    monthlyPayment: total / numMonths,
    endDate: addMonths(startDate, numMonths)
  };
}

І якби ви працювали із системою з дискримінаційними типами даних союзів / алгебраїчних даних, ви могли б передати її як, скажімо, a TimePeriodSpecification.

type TimePeriodSpecification =
    | DateRange of startDate : DateTime * endDate : DateTime
    | MonthCount of startDate : DateTime * monthCount : int
    | MonthlyPayment of startDate : DateTime * monthlyAmount : float

і тоді жодна з проблем не виникне там, де ви не зможете реально реалізувати її тощо.