Esiste un modello per la gestione di parametri di funzioni in conflitto?

Abbiamo una funzione API che suddivide un importo totale in importi mensili in base alle date di inizio e fine indicate.

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

Di recente, un consumatore per questa API ha voluto specificare l'intervallo di date in altri modi: 1) fornendo il numero di mesi anziché la data di fine, oppure 2) fornendo il pagamento mensile e calcolando la data di fine. In risposta a ciò, il team API ha modificato la funzione nel modo seguente:

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

Sento che questo cambiamento complica l'API. Ora il chiamante ha bisogno di preoccuparsi per l'euristica nascosti con l'implementazione della funzione nel determinare quali parametri prendono preferenza nell'essere utilizzato per calcolare l'intervallo di date (ad esempio in ordine di priorità monthlyPayment, numMonths, endDate). Se un chiamante non presta attenzione alla firma della funzione, potrebbe inviare più parametri opzionali e confondersi sul motivo per cui endDateviene ignorato. Specifichiamo questo comportamento nella documentazione della funzione.

Inoltre, ritengo che costituisca un precedente negativo e aggiunga all'API delle responsabilità che non dovrebbe riguardare (ovvero la violazione di SRP). Supponiamo che altri utenti desiderino che la funzione supporti più casi d'uso, come il calcolo totaldai parametri numMonthse monthlyPayment. Questa funzione diventerà sempre più complicata nel tempo.

La mia preferenza è mantenere la funzione com'era e invece richiedere al chiamante di calcolarsi endDate. Tuttavia, potrei sbagliarmi e mi chiedevo se le modifiche apportate fossero un modo accettabile per progettare una funzione API.

In alternativa, esiste un modello comune per la gestione di scenari come questo? Potremmo fornire ulteriori funzioni di ordine superiore nella nostra API che racchiudono la funzione originale, ma questo gonfia l'API. Forse potremmo aggiungere un parametro flag aggiuntivo specificando quale approccio usare all'interno della funzione.

Vedendo l'implementazione, mi sembra che ciò di cui hai veramente bisogno qui siano 3 diverse funzioni invece di una:

Quello originale:

function getPaymentBreakdown(total, startDate, endDate) 

Quello che fornisce il numero di mesi anziché la data di fine:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

e quello che fornisce il pagamento mensile e calcola la data di fine:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Ora non ci sono più parametri opzionali e dovrebbe essere abbastanza chiaro quale funzione viene chiamata come e per quale scopo. Come menzionato nei commenti, in un linguaggio strettamente tipizzato, si potrebbe anche utilizzare il sovraccarico delle funzioni, distinguendo le 3 diverse funzioni non necessariamente dal loro nome, ma dalla loro firma, nel caso in cui ciò non offuschi il loro scopo.

Nota le diverse funzioni non significano che devi duplicare qualsiasi logica - internamente, se queste funzioni condividono un algoritmo comune, dovrebbe essere refactored a una funzione "privata".

esiste un modello comune per la gestione di scenari come questo

Non credo che esista un "modello" (nel senso dei modelli di progettazione GoF) che descrive una buona progettazione delle API. L'uso di nomi che descrivono se stessi, funzioni con meno parametri, funzioni con parametri ortogonali (= indipendenti), sono solo principi di base per la creazione di codice leggibile, mantenibile ed evolvibile. Non tutte le buone idee in programmazione sono necessariamente un "modello di progettazione".

Inoltre, ritengo che costituisca un precedente negativo e aggiunga all'API delle responsabilità che non dovrebbe riguardare (ovvero la violazione di SRP). Supponiamo che altri utenti desiderino che la funzione supporti più casi d'uso, come il calcolo totaldai parametri numMonthse monthlyPayment. Questa funzione diventerà sempre più complicata nel tempo.

Hai esattamente ragione.

La mia preferenza è mantenere la funzione com'era e invece richiedere al chiamante di calcolare endDate da soli. Tuttavia, potrei sbagliarmi e mi chiedevo se le modifiche apportate fossero un modo accettabile per progettare una funzione API.

Anche questo non è l'ideale, perché il codice chiamante verrà inquinato con una piastra caldaia non correlata.

In alternativa, esiste un modello comune per la gestione di scenari come questo?

Introdurre un nuovo tipo, ad esempio DateInterval. Aggiungi qualunque costruttore abbia senso (data di inizio + data di fine, data di inizio + num mesi, qualunque sia.). Adottare questo come tipi di valuta comune per esprimere intervalli di date / orari in tutto il sistema.

A volte le espressioni fluide aiutano su questo:

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

Dato il tempo sufficiente per progettare, puoi creare un'API solida che agisce in modo simile a un linguaggio specifico del dominio.

L'altro grande vantaggio è che gli IDE con il completamento automatico rendono quasi irrilevante la lettura della documentazione dell'API, poiché è intuitivo a causa delle sue capacità auto-individuabili.

Ci sono risorse là fuori come https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ o https://github.com/nikaspran/fluent.js su questo argomento.

Esempio (tratto dal primo collegamento di risorse):

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]

Bene, in altre lingue, useresti parametri denominati . Questo può essere emulato in Javscript:

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

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

In alternativa potresti anche rompere la responsabilità di specificare il numero del mese e lasciarlo fuori dalla tua funzione:

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

E getpaymentBreakdown riceverà un oggetto che fornirà il numero base di mesi

Quelli avrebbero una funzione di ordine superiore restituendo ad esempio una funzione.

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

E se dovessi lavorare con un sistema con sindacati / tipi di dati algebrici discriminati, potresti passare come, per esempio, a TimePeriodSpecification.

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

e quindi nessuno dei problemi si verificherebbe dove potresti non riuscire a implementarne effettivamente uno e così via.