Czy istnieje wzorzec obsługi sprzecznych parametrów funkcji?

Mamy funkcję API, która dzieli całkowitą kwotę na kwoty miesięczne na podstawie danych dat rozpoczęcia i zakończenia.

// 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,
  };
}

Ostatnio konsument tego interfejsu API chciał określić zakres dat na inne sposoby: 1) podając liczbę miesięcy zamiast daty końcowej, lub 2) podając miesięczną płatność i obliczając datę końcową. W odpowiedzi zespół API zmienił funkcję na:

// 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),
  };
}

Wydaje mi się, że ta zmiana komplikuje interfejs API. Teraz rozmówca musi się martwić o ukryte heurystyki z realizacją danej funkcji w celu ustalenia, które parametry mają pierwszeństwo w wykorzystywane do obliczenia zakres dat (czyli w kolejności priorytetów monthlyPayment, numMonths, endDate). Jeśli osoba dzwoniąca nie zwraca uwagi na podpis funkcji, może wysłać wiele opcjonalnych parametrów i pomylić się, dlaczego endDatejest ignorowana. Określamy to zachowanie w dokumentacji funkcji.

Dodatkowo uważam, że stanowi zły precedens i dodaje obowiązki do API, którym nie powinien się zajmować (tj. Naruszać SRP). Załóżmy, że dodatkowi klienci chcą, aby funkcja obsługiwała więcej przypadków użycia, takich jak obliczanie totalna podstawie parametrów numMonthsi monthlyPayment. Ta funkcja z czasem będzie się komplikować.

Preferuję, aby funkcja pozostała taka, jaka była, a zamiast tego wymagać od osoby dzwoniącej obliczenia endDatesiebie. Jednak mogę się mylić i zastanawiałem się, czy wprowadzone przez nich zmiany były akceptowalnym sposobem zaprojektowania funkcji API.

Alternatywnie, czy istnieje wspólny wzorzec obsługi takich scenariuszy? Możemy zapewnić dodatkowe funkcje wyższego rzędu w naszym interfejsie API, które zawijają oryginalną funkcję, ale powoduje to powiększenie interfejsu API. Być może moglibyśmy dodać dodatkowy parametr flagi określający, które podejście należy zastosować w funkcji.

Widząc implementację, wydaje mi się, że tak naprawdę potrzebujesz tutaj 3 różnych funkcji zamiast jednej:

Oryginalny:

function getPaymentBreakdown(total, startDate, endDate) 

Ten, który podaje liczbę miesięcy zamiast daty końcowej:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

i ten zapewniający miesięczną płatność i obliczający datę końcową:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Teraz nie ma już żadnych parametrów opcjonalnych i powinno być całkiem jasne, która funkcja nazywa się w jaki sposób i w jakim celu. Jak wspomniano w komentarzach, w ściśle typowanym języku można również wykorzystać przeciążenie funkcji, rozróżniając 3 różne funkcje niekoniecznie według nazwy, ale według ich podpisu, w przypadku, gdy nie zaciemnia to ich celu.

Zauważ, że różne funkcje nie oznaczają, że musisz zduplikować dowolną logikę - wewnętrznie, jeśli funkcje te mają wspólny algorytm, należy przekształcić je w funkcję „prywatną”.

czy istnieje wspólny wzorzec obsługi takich scenariuszy

Nie sądzę, że istnieje „wzorzec” (w sensie wzorców projektowych GoF), który opisuje dobry projekt API. Używanie samoopisujących nazw, funkcje z mniejszą liczbą parametrów, funkcje z ortogonalnymi (= niezależnymi) parametrami, to tylko podstawowe zasady tworzenia czytelnego, łatwego do utrzymania i rozwijalnego kodu. Nie każdy dobry pomysł w programowaniu jest koniecznie „wzorcem projektowym”.

Dodatkowo uważam, że stanowi zły precedens i dodaje obowiązki do API, którym nie powinien się zajmować (tj. Naruszać SRP). Załóżmy, że dodatkowi klienci chcą, aby funkcja obsługiwała więcej przypadków użycia, takich jak obliczanie totalna podstawie parametrów numMonthsi monthlyPayment. Ta funkcja z czasem będzie się komplikować.

Masz dokładnie rację.

Preferuję, aby funkcja pozostała taka, jaka była, a zamiast tego wymagać od osoby dzwoniącej obliczenia samej daty końcowej. Jednak mogę się mylić i zastanawiałem się, czy wprowadzone przez nich zmiany były akceptowalnym sposobem zaprojektowania funkcji API.

Nie jest to również idealne, ponieważ kod wywołujący zostanie zanieczyszczony niepowiązaną płytą kotła.

Alternatywnie, czy istnieje wspólny wzorzec obsługi takich scenariuszy?

Wprowadź nowy typ, np DateInterval. Dodaj dowolne konstruktory, które mają sens (data początkowa + data końcowa, data początkowa + liczba miesięcy, cokolwiek.) Zaadoptuj to jako typ wspólnej waluty do wyrażania przedziałów dat / godzin w całym systemie.

Czasami pomagają w tym płynne wyrażenia:

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();

Mając wystarczająco dużo czasu na zaprojektowanie, możesz opracować solidny interfejs API, który działa podobnie do języka specyficznego dla domeny.

Inną dużą zaletą jest to, że środowiska IDE z funkcją autouzupełniania sprawiają, że czytanie dokumentacji API jest prawie nierealne, ponieważ jest intuicyjne ze względu na możliwości samodzielnego odkrywania.

Istnieją zasoby, takie jak https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ lub https://github.com/nikaspran/fluent.js na ten temat.

Przykład (wzięty z pierwszego łącza do zasobów):

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]

W innych językach używasz nazwanych parametrów . Można to emulować w Javscript:

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

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

Alternatywnie możesz również zerwać odpowiedzialność za określenie liczby miesięcy i pominąć tę funkcję:

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

A getpaymentBreakdown otrzyma obiekt, który zapewni podstawową liczbę miesięcy

Byłyby to funkcje wyższego rzędu zwracające na przykład funkcję.

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 jeśli miałbyś pracować z systemem z dyskryminowanymi związkami / algebraicznymi typami danych, możesz przekazać to jak, powiedzmy, a TimePeriodSpecification.

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

i wtedy nie wystąpiłby żaden problem, w którym można nie wdrożyć jednego i tak dalej.