Есть ли шаблон для обработки конфликтующих параметров функции?

У нас есть функция 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. Возможно, мы могли бы добавить дополнительный параметр флага, определяющий, какой подход использовать внутри функции.

Видя реализацию, мне кажется, что вам действительно нужно 3 разные функции вместо одной:

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

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

и тогда ни одна из проблем не возникнет, если вы не сможете реализовать ее и так далее.