Gibt es ein Muster für den Umgang mit widersprüchlichen Funktionsparametern?

Wir haben eine API-Funktion, die einen Gesamtbetrag basierend auf den angegebenen Start- und Enddaten in monatliche Beträge aufteilt.

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

Kürzlich wollte ein Verbraucher für diese API den Datumsbereich auf andere Weise angeben: 1) durch Angabe der Anzahl der Monate anstelle des Enddatums oder 2) durch Angabe der monatlichen Zahlung und Berechnung des Enddatums. In Reaktion darauf hat das API-Team die Funktion folgendermaßen geändert:

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

Ich glaube, diese Änderung erschwert die API. Nun muss der Anrufer Sorge um die versteckte Heuristik mit der Umsetzung der Funktion bei der Bestimmung , welche Parameter nehmen Präferenz verwendet wird , um den Datumsbereich (dh nach der Reihenfolge ihrer Priorität zu berechnen monthlyPayment, numMonths, endDate). Wenn ein Aufrufer die Funktionssignatur nicht beachtet, sendet er möglicherweise mehrere der optionalen Parameter und ist verwirrt, warum endDatediese ignoriert werden. Dieses Verhalten legen wir in der Funktionsdokumentation fest.

Außerdem habe ich das Gefühl, dass dies einen schlechten Präzedenzfall darstellt und der API Verantwortlichkeiten hinzufügt, mit denen sie sich nicht befassen sollte (dh die SRP verletzen). Angenommen, zusätzliche Verbraucher möchten, dass die Funktion mehr Anwendungsfälle unterstützt, z. B. das Berechnen totalaus den Parametern numMonthsund monthlyPayment. Diese Funktion wird mit der Zeit immer komplizierter.

Ich bevorzuge es, die Funktion so zu belassen, wie sie war, und stattdessen den Anrufer aufzufordern, sich endDateselbst zu berechnen . Ich kann mich jedoch irren und habe mich gefragt, ob die vorgenommenen Änderungen eine akzeptable Möglichkeit zum Entwerfen einer API-Funktion darstellen.

Gibt es alternativ ein allgemeines Muster für den Umgang mit solchen Szenarien? Wir könnten zusätzliche Funktionen höherer Ordnung in unserer API bereitstellen, die die ursprüngliche Funktion umschließen, aber dies bläht die API auf. Möglicherweise könnten wir einen zusätzlichen Flag-Parameter hinzufügen, der angibt, welcher Ansatz innerhalb der Funktion verwendet werden soll.

In Anbetracht der Implementierung scheint es mir, dass Sie hier wirklich drei verschiedene Funktionen anstelle von einer benötigen:

Das Original:

function getPaymentBreakdown(total, startDate, endDate) 

Derjenige, der die Anzahl der Monate anstelle des Enddatums angibt:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

und derjenige, der die monatliche Zahlung vornimmt und das Enddatum berechnet:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Jetzt gibt es keine optionalen Parameter mehr und es sollte ziemlich klar sein, welche Funktion wie und zu welchem ​​Zweck aufgerufen wird. Wie in den Kommentaren erwähnt, könnte man in einer streng getippten Sprache auch eine Funktionsüberladung verwenden, die die drei verschiedenen Funktionen nicht unbedingt anhand ihres Namens, sondern anhand ihrer Signatur unterscheidet, falls dies ihren Zweck nicht verschleiert.

Beachten Sie, dass die verschiedenen Funktionen nicht bedeuten, dass Sie eine Logik duplizieren müssen. Wenn diese Funktionen intern einen gemeinsamen Algorithmus verwenden, sollte dieser in eine "private" Funktion umgestaltet werden.

Gibt es ein allgemeines Muster für den Umgang mit solchen Szenarien?

Ich glaube nicht, dass es ein "Muster" (im Sinne der GoF-Designmuster) gibt, das ein gutes API-Design beschreibt. Die Verwendung selbstbeschreibender Namen, Funktionen mit weniger Parametern und Funktionen mit orthogonalen (= unabhängigen) Parametern sind nur Grundprinzipien für die Erstellung von lesbarem, wartbarem und entwickelbarem Code. Nicht jede gute Idee in der Programmierung ist notwendigerweise ein "Entwurfsmuster".

Außerdem habe ich das Gefühl, dass dies einen schlechten Präzedenzfall darstellt und der API Verantwortlichkeiten hinzufügt, mit denen sie sich nicht befassen sollte (dh die SRP verletzen). Angenommen, zusätzliche Verbraucher möchten, dass die Funktion mehr Anwendungsfälle unterstützt, z. B. das Berechnen totalaus den Parametern numMonthsund monthlyPayment. Diese Funktion wird mit der Zeit immer komplizierter.

Du bist genau richtig.

Ich bevorzuge es, die Funktion so zu belassen, wie sie war, und stattdessen den Aufrufer aufzufordern, das Enddatum selbst zu berechnen. Ich kann mich jedoch irren und habe mich gefragt, ob die vorgenommenen Änderungen eine akzeptable Möglichkeit zum Entwerfen einer API-Funktion darstellen.

Dies ist auch nicht ideal, da der Anrufercode durch nicht zugehörige Kesselschilder verschmutzt wird.

Gibt es alternativ ein allgemeines Muster für den Umgang mit solchen Szenarien?

Führe einen neuen Typ ein, wie DateInterval. Fügen Sie die Konstruktoren hinzu, die Sinn machen (Startdatum + Enddatum, Startdatum + Anzahl Monate, was auch immer). Übernehmen Sie dies als die gängigen Währungstypen für die Angabe von Datums- / Uhrzeitintervallen in Ihrem System.

Manchmal helfen dabei fließende Ausdrücke:

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

Wenn Sie genügend Zeit zum Entwerfen haben, können Sie eine solide API entwickeln, die einer domänenspezifischen Sprache ähnelt.

Der andere große Vorteil besteht darin, dass IDEs mit automatischer Vervollständigung das Lesen der API-Dokumentation fast unangenehm machen , da sie aufgrund ihrer selbsterkennbaren Funktionen intuitiv sind.

Es gibt Ressourcen wie https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ oder https://github.com/nikaspran/fluent.js zu diesem Thema.

Beispiel (entnommen aus dem ersten Ressourcenlink):

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]

In anderen Sprachen würden Sie benannte Parameter verwenden . Dies kann in Javscript emuliert werden:

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

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

Alternativ können Sie auch die Verantwortung für die Angabe der Monatsanzahl aufheben und diese aus Ihrer Funktion ausschließen:

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

Und getpaymentBreakdown würde ein Objekt erhalten, das die Basisanzahl der Monate liefert

Diese würden eine Funktion höherer Ordnung zurückgeben, zum Beispiel eine Funktion.

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

Und wenn Sie mit einem System mit diskriminierten Gewerkschaften / algebraischen Datentypen arbeiten würden, könnten Sie es wie folgt übergeben: a TimePeriodSpecification.

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

und dann würde keines der Probleme auftreten, wenn Sie eines nicht implementieren könnten und so weiter.