Có một mẫu để xử lý các tham số chức năng xung đột?

Chúng tôi có chức năng API chia tổng số tiền thành số tiền hàng tháng dựa trên ngày bắt đầu và ngày kết thúc cụ thể.

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

Gần đây, một người tiêu dùng cho API này muốn chỉ định phạm vi ngày theo các cách khác: 1) bằng cách cung cấp số tháng thay vì ngày kết thúc hoặc 2) bằng cách cung cấp khoản thanh toán hàng tháng và tính ngày kết thúc. Để đáp ứng điều này, nhóm API đã thay đổi chức năng như sau:

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

Tôi cảm thấy sự thay đổi này làm phức tạp API. Bây giờ người gọi cần phải lo lắng về các chẩn đoán ẩn với thực hiện của chức năng trong việc xác định các thông số chụp ưu tiên trong được sử dụng để tính toán phạm vi ngày (tức là bởi thứ tự ưu tiên monthlyPayment, numMonths, endDate). Nếu một người gọi không chú ý đến chữ ký hàm, họ có thể gửi nhiều tham số tùy chọn và bị nhầm lẫn về lý do tại sao endDatebị bỏ qua. Chúng tôi chỉ định hành vi này trong tài liệu chức năng.

Ngoài ra, tôi cảm thấy nó thiết lập một tiền lệ xấu và thêm trách nhiệm cho API mà nó không nên quan tâm (ví dụ như vi phạm SRP). Giả sử người tiêu dùng bổ sung muốn chức năng hỗ trợ nhiều trường hợp sử dụng hơn, chẳng hạn như tính toán totaltừ numMonthsvà monthlyPaymenttham số. Chức năng này sẽ ngày càng phức tạp hơn theo thời gian.

Sở thích của tôi là giữ chức năng như cũ và thay vào đó yêu cầu người gọi endDatetự tính toán . Tuy nhiên, tôi có thể sai và tự hỏi liệu những thay đổi họ thực hiện có phải là một cách chấp nhận được để thiết kế một hàm API hay không.

Ngoài ra, có một mô hình chung để xử lý các tình huống như thế này? Chúng tôi có thể cung cấp thêm các hàm bậc cao hơn trong API bao bọc hàm ban đầu, nhưng điều này làm mờ API. Có lẽ chúng ta có thể thêm một tham số cờ bổ sung chỉ định cách tiếp cận nào được sử dụng bên trong hàm.

Nhìn thấy việc thực hiện, nó cho tôi thấy những gì bạn thực sự yêu cầu ở đây là 3 chức năng khác nhau thay vì một:

Bản gốc:

function getPaymentBreakdown(total, startDate, endDate) 

Người cung cấp số tháng thay vì ngày kết thúc:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

và người cung cấp khoản thanh toán hàng tháng và tính ngày kết thúc:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Bây giờ, không còn tham số tùy chọn nào nữa, và rõ ràng chức năng này được gọi là như thế nào và cho mục đích gì. Như đã đề cập trong các ý kiến, trong một ngôn ngữ được gõ chính xác, người ta cũng có thể sử dụng chức năng quá tải chức năng, phân biệt 3 chức năng khác nhau không nhất thiết phải bằng tên của họ, nhưng bằng chữ ký của họ, trong trường hợp điều này không làm xáo trộn mục đích của họ.

Lưu ý các hàm khác nhau không có nghĩa là bạn phải sao chép bất kỳ logic nào - bên trong, nếu các hàm này chia sẻ một thuật toán chung, thì nó sẽ được cấu trúc lại thành hàm "riêng tư".

Có một mô hình chung để xử lý các tình huống như thế này không

Tôi không nghĩ có một "mẫu" (theo nghĩa của các mẫu thiết kế GoF) mô tả thiết kế API tốt. Sử dụng tên tự mô tả, các hàm có ít tham số hơn, các hàm có tham số trực giao (= độc lập), chỉ là các nguyên tắc cơ bản để tạo mã có thể đọc, duy trì và có thể phát triển. Không phải mọi ý tưởng tốt trong lập trình đều nhất thiết phải là "mẫu thiết kế".

Ngoài ra, tôi cảm thấy nó thiết lập một tiền lệ xấu và thêm trách nhiệm cho API mà nó không nên quan tâm (ví dụ như vi phạm SRP). Giả sử người tiêu dùng bổ sung muốn chức năng hỗ trợ nhiều trường hợp sử dụng hơn, chẳng hạn như tính toán totaltừ numMonthsvà monthlyPaymenttham số. Chức năng này sẽ ngày càng phức tạp hơn theo thời gian.

Bạn chính xác.

Sở thích của tôi là giữ chức năng như cũ và thay vào đó yêu cầu người gọi tự tính toán endDate. Tuy nhiên, tôi có thể sai và tự hỏi liệu những thay đổi họ thực hiện có phải là một cách chấp nhận được để thiết kế một hàm API hay không.

Điều này cũng không lý tưởng, bởi vì mã người gọi sẽ bị ô nhiễm với tấm nồi hơi không liên quan.

Ngoài ra, có một mô hình chung để xử lý các tình huống như thế này?

Giới thiệu một loại mới, như DateInterval. Thêm bất cứ điều gì các nhà xây dựng có ý nghĩa (ngày bắt đầu + ngày kết thúc, ngày bắt đầu + tháng tháng, bất cứ điều gì.). Chấp nhận đây là loại tiền tệ chung để thể hiện khoảng thời gian ngày / lần trong toàn hệ thống của bạn.

Đôi khi những biểu hiện trôi chảy giúp ích cho việc này:

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

Dành đủ thời gian để thiết kế, bạn có thể đưa ra một API vững chắc hoạt động tương tự như ngôn ngữ dành riêng cho tên miền.

Ưu điểm lớn khác là các IDE có tính năng tự động hoàn thành hầu như không phù hợp để đọc tài liệu API, vì nó trực quan do khả năng tự khám phá của nó.

Có các tài nguyên ngoài đó như https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ hoặc https://github.com/nikaspran/fluent.js về chủ đề này.

Ví dụ (lấy từ liên kết tài nguyên đầu tiên):

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]

Vâng, trong các ngôn ngữ khác, bạn sẽ sử dụng các tham số được đặt tên . Điều này có thể được mô phỏng trong Javscript:

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

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

Thay vào đó, bạn cũng có thể phá vỡ trách nhiệm chỉ định số tháng và loại bỏ chức năng này:

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

Và getpaymentBreakdown sẽ nhận được một đối tượng cung cấp số tháng cơ sở

Những hàm này sẽ trả về hàm bậc cao hơn, ví dụ hàm.

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

Và nếu bạn đang làm việc với một hệ thống với các loại dữ liệu đại số / đại số bị phân biệt đối xử, bạn có thể chuyển nó vào như, giả sử, a TimePeriodSpecification.

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

và sau đó không có vấn đề nào xảy ra khi bạn không thể thực hiện một và cứ thế.