競合する関数パラメーターを処理するパターンはありますか？

指定された開始日と終了日に基づいて、合計金額を月額に分割する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無視されているのかについて混乱する可能性があります。関数のドキュメントでこの動作を指定します。

さらに、私はそれが悪い先例を設定し、それ自体に関係してはならない（つまりSRPに違反する）APIに責任を追加すると感じます。追加のコンシューマーtotalが、numMonthsおよびからの計算など、より多くのユースケースをサポートする関数を必要としているとしmonthlyPaymentます。この関数は、時間とともにますます複雑になります。

私の好みは、関数をそのままにしておき、代わりに呼び出し元にendDate自分自身を計算させることです。しかし、私は間違っている可能性があり、それらが行った変更がAPI関数を設計するための許容可能な方法であるかどうか疑問に思っていました。

あるいは、このようなシナリオを処理するための一般的なパターンはありますか？APIで元の関数をラップする追加の高次関数を提供できますが、これはAPIを膨張させます。関数内で使用するアプローチを指定するフラグパラメーターを追加できます。

実装を見ると、ここで本当に必要なのは、1つではなく3つの異なる関数です。

元のもの：

function getPaymentBreakdown(total, startDate, endDate) 

終了日ではなく月数を提供するもの：

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

そして、毎月の支払いを提供し、終了日を計算するもの：

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

これで、オプションのパラメーターはなくなり、どの関数がどのように、どの目的で呼び出されるかが明確になるはずです。コメントで述べたように、厳密に型指定された言語では、関数のオーバーロードを利用して、3つの異なる関数を必ずしも名前ではなく署名によって区別することもできます。

異なる関数は、ロジックを複製する必要があるわけではないことに注意してください。内部で、これらの関数が共通のアルゴリズムを共有している場合、「プライベート」関数にリファクタリングする必要があります。

このようなシナリオを処理するための一般的なパターンはありますか

良いAPIデザインを記述する「パターン」（GoFデザインパターンの意味で）はないと思います。自己記述的な名前、より少ないパラメーターを持つ関数、直交（=独立）パラメーターを持つ関数を使用することは、読み取り可能、保守可能、および進化可能なコードを作成するための基本原則にすぎません。プログラミングのすべての良いアイデアが必ずしも「設計パターン」であるとは限りません。

さらに、私はそれが悪い先例を設定し、それ自体に関係してはならない（つまりSRPに違反する）APIに責任を追加すると感じます。追加のコンシューマーtotalが、numMonthsおよびからの計算など、より多くのユースケースをサポートする関数を必要としているとしmonthlyPaymentます。この関数は、時間とともにますます複雑になります。

正解です。

私の好みは、関数をそのまま保持し、代わりに呼び出し側にendDate自体を計算させることです。しかし、私は間違っている可能性があり、それらが行った変更がAPI関数を設計するための許容可能な方法であるかどうか疑問に思っていました。

呼び出し元のコードが無関係なボイラープレートで汚染されるため、これも理想的ではありません。

あるいは、このようなシナリオを処理するための一般的なパターンはありますか？

のような新しいタイプを導入しDateIntervalます。意味のあるコンストラクタを追加します（開始日+終了日、開始日+ numか月など）。これを、システム全体で日付/時刻の間隔を表すための共通通貨タイプとして採用します。

時々流fluentな表現がこれに役立ちます：

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を思い付くことができます。

もう1つの大きな利点は、オートコンプリートを備えた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)
  };
}

また、識別された共用体/代数データ型を使用してシステムを操作する場合は、たとえばとして渡すことができますTimePeriodSpecification。

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

そして、実際に実装するのに失敗するような問題は発生しません。