Как организовать API?

Question

Я разрабатываю API, и я хотел бы, чтобы он был простым в использовании. Итак, если у меня есть клиенты, выписки и платежи. Имеет ли смысл иметь такие объекты, как: Customer, CustomerHandler, Statement, StatementHandler, Payment, PaymentHandler? Таким образом, когда разработчик хочет что-то сделать с клиентами, которых он / она знает, чтобы создать CustomerHandler, тогда все возможные функции, которые он хотел бы выполнить с клиентом, находятся внутри обработчика.

Методы, такие как:

• CustomerHandler:

  • AddCustomer (клиент)
  • GetCustomer (CUSTOMERID)
  • GetCustomerCount ()

• StatementHandler:

  • GetStatement (StatementId)
  • GetStatementCount (CUSTOMERID)

• PaymentHandler:

  • GetPaymentsByCustomer (CUSTOMERID)
  • GetPayment (PaymentID)
  • GetPaymentCountByCustomer (CUSTOMERID)

Таким образом, если разработчик хочет работать над получением платежей, он / она знает, что он идет в PaymentHandler. Мой коллега подумал, что такие функции, как GetPayments (customerID) принадлежат к классу, который управляет клиентом. Таким образом, это будет как Customer.GetPayments () AS Payments. Но если у меня есть какой-то другой объект, такой как Worker, будет Worker.GetPayments () AS Payments. Итак, я вижу логику с обоими подходами. Первый группирует вещи так, что, независимо от того, от кого поступает платеж, вы получаете все это из одного класса, имея такие функции, как GetPaymentsByCustomer (CustomerID) и GetPaymentsByWorker (WorkerID). Таким образом, не нужно сталкиваться с различными объектами обработчика или менеджера для получения платежей. Оба подхода имеют смысл для меня, а вы? Или мы оба вместе, и есть лучший способ сделать это? Заранее спасибо!

Answer 1

Если вы разрабатываете API, то, возможно, вы могли бы попробовать написать несколько макетов с точки зрения ваших предполагаемых пользователей. Реализуйте несколько вариантов использования, даже если это просто на белой доске, и посмотрите, какой подход более ценен.

В вашем примере платежей как Работник, так и Клиент могут реализовать интерфейс Payable. Если бы вам позже пришлось добавить объект, который можно было бы «оплатить», вы бы просто реализовали тот же интерфейс. Если у вас есть обработчик платежей и вам нужно добавить новый тип вещей, которые можно было бы оплатить, вам придется изменить обработчик, добавив новый метод. Со временем это может стать громоздким, я полагаю. Конечно, вы могли бы использовать комбинацию из двух и иметь утилиту-обработчик, которая выполняла роль передней панели вашей платежной системы.

Answer 2

Вы в значительной степени описываете два способа (шаблоны) для доступа к данным:

• активная запись - http://martinfowler.com/eaaCatalog/activeRecord.html
• картограф данных - http://martinfowler.com/eaaCatalog/dataMapper.html

Пожалуйста, получите книгу Мартина Фаулера Шаблоны архитектуры корпоративных приложений и ознакомьтесь со всеми плюсами и минусами. В частности, если вы пытаетесь представить свои объекты и API-интерфейсы как веб-сервисы, вы можете использовать подход отображения данных (как вы предлагаете).

Активная запись очень популярна, потому что она проще. Решите для себя, что лучше всего соответствует вашим потребностям.

Answer 3

В дебатах «где это принадлежит» я обычно решаю, где что-то принадлежит, основываясь на том, что оно возвращает. Если у вас есть метод GetPayments (), который возвращает список объектов Payment, он должен быть в PaymentHandler.

Это действительно довольно субъективная вещь, но выполнение по типу возврата гарантирует, что все, что создает объекты Payment, будет в PaymentHandler, объекты Customer в CustomerHandler и т. Д.

Это может немного упростить ситуацию, когда вам нужно будет внести изменения позже, и, как вы упомянули, пользователям вашего API очень легко определить, какой обработчик им нужно вызывать - если им нужен клиент, они будут работать с CustomerHandler.

Это также устраняет путаницу, если у вас есть гипотетический метод, такой как GetPayments (customerId, workerId), который будет получать платежи для клиента и работника. Используя ваше предложение коллег, неясно, куда пойдет этот метод, поскольку он включает в себя платежи, клиентов и работников. Категоризация по типу возврата почти всегда понятна, поскольку функция возвращает только одну вещь.