Как передать параметры запроса REST методу Java?

Question

Мы строим Java SDK, чтобы упростить доступ к одной из наших услуг, предоставляющих API REST. Этот SDK будет использоваться сторонними разработчиками.

Одна из проблем заключалась в том, чтобы найти хороший способ представления необязательных параметров каждого запроса.

Допустим, мы имеем покоя конечной точки: GET /photos , который имеет несколько необязательных параметров: sortBy, pageSize, pageNumber и т.д.

Одно решение было бы принять Map<String,String> в качестве параметра метода апи, который представляет, что вызов отдыха.

interface RestService { 
    public List<Photo> getPhotos(Map<String,String> parameters); 
} 

Есть несколько проблем с этим решением:

• Подпись метода дает разработчику никакой информации о названиях необязательных параметров, доступных для данного метода (а также допустимые значения). Ему нужно будет проконсультироваться с документацией REST api, и в идеале мы хотели бы избежать необходимости.
• Разработчик создаст несколько карт с параметрами методов, которые он вызовет, жестко кодируя имена и значения параметров во всем мире. Это означает, что если они когда-либо изменятся, это будет хлопот, чтобы исправить их.

Другим решением было бы использовать объект Options, который будет содержать информацию о дополнительных параметрах. Мы могли бы даже использовать шаблон строителя для создания этого объекта.

Это как метод подписи будет выглядеть следующим образом:

interface RestService { 
    public List<Photo> getPhotos(PhotosOptions options); 
} 

Разработчик теперь знает, какие доступны дополнительные параметры и могут легко построить PhotosOptions так:

PhotosOptions options = PhotosOptions.builder().sortBy(DESC).pageSize(200).build(); 
List<Photo> photos = getPhotos(options); 

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

Какое здесь самое лучшее решение? Создайте объект Option (и его построитель) для каждой комбинации? Наследование здесь не совсем помогает, потому что у меня есть всевозможные комбинации параметров.

Answer 1

Лучший способ это объект варианты использования, как вы показали:

interface RestService { 
    public List<Photo> getPhotos(PhotosOptions options); 
} 

Это очень сложный способ и требует, чтобы напечатать много писем, вы будете иметь много классов и других задницы боли.

Но я считаю, что этот способ лучше других, потому что он обеспечивает сильную подпись методов, делает ваш SDK более детерминированным. Если вы правильно отделите свои классы по пакетам, вы увидите, что это лучший способ.

Пользователи скажут вам спасибо.

У меня был тот же вопрос некоторое время назад, после нескольких попыток я выбрал этот метод, и теперь я счастлив.