Как-то в общении с моим другом-разработчиком из одной крупной софтверной компании у нас зашёл разговор о взаимодействии распределённых команд. В его компании было множество достаточно изолированных команд, каждая из которых разрабатывала свой сервис. В ответ на мой вопрос, как команды расшаривают API, я получил ожидаемый ответ: Open API. Open API, безусловно, прекрасный инструмент, но у него есть ряд недостатков. 

Меня зовут Андрей Зяблин, я главный разработчик в «Магните». Расскажу о том, как распространять API нативным для Java способом и пользоваться им в объектно-ориентированном стиле без использования генераторов кода. 

Немного теории 

Классическая ситуация: одна команда разрабатывает REST API (поставщик), другая его потребляет (потребитель). Чтобы распространять API, и был придуман стандарт Open API, также известный как Swagger. Он представляет собой стандарт описания и документации для RESTful — набора правил, который позволяет разработчикам описывать и документировать функциональность своего API.

OpenAPI-спецификация представлена в формате JSON или YAML и содержит подробное описание методов, параметров, структуры данных и другой информации, необходимой для взаимодействия с API. 

OpenAPI — замечательный инструмент. Он позволяет распространять API между разработчиками, пишущими на различных языках и работающих в разных компаниях. Однако такое нужно далеко не всегда. Когда все команды разрабатывают на Java, возникает вопрос: так ли уж необходимо промежуточное звено в виде OpenAPI? Нельзя ли распространять API более нативным для Java способом и пользоваться им в объектно-ориентированном стиле без использования генераторов кода? 

Да, существуют современные технологии, которые позволяют это сделать. Ниже я продемонстрирую подход для команд, разрабатывающих REST-сервисы на Java и Spring — это очень распространённый стек.  

Как работает подход: рассмотрим на примере

Для демонстрации подхода воспроизведу ситуацию, описанную выше: когда есть поставщик API и его потребитель. Для этого потребуются два приложения:

• поставщик API – producer,

• потребитель API – consumer.

Producer будет распространять API через maven-репозитарий. Такой подход позволяет оперативно публиковать изменения, а также оперативно потреблять их без генерации кода. 

Подход подразумевает классическую структуру API, состоящую из двух основных частей: POJO-модели и интерфейсов, предоставляющих методы работы с этими моделями.

Распространяем модели — producer

Создадим многомодульный проект со следующими настройками для простоты. 

allprojects { 
    group = 'com.example.producer' 
    version = '0.0.1' 
    sourceCompatibility = '11' 
    repositories { 
        mavenCentral() 
        mavenLocal() 
    } 
} 

subprojects { 
    apply plugin: 'java' 
    apply plugin: 'org.springframework.boot' 
    apply plugin: 'io.spring.dependency-management' 
    dependencies { 
        implementation 'org.springframework.boot:spring-boot-starter-web' 
        compileOnly 'org.projectlombok:lombok' 
        annotationProcessor 'org.projectlombok:lombok' 
    } 
 
} 

Добавим модуль model, который будет содержать модели. Настроим его для публикации в локальный maven-репозитарий с использованием плагина maven-publish. 

apply plugin: 'maven-publish' 
 
jar { 
    enabled=true 
    archiveClassifier.set("") 
} 
 
bootJar { 
    enabled = false 
} 
 
publishing { 
    publications { 
        maven(MavenPublication) { 
            artifact jar 
        } 
    } 
    repositories { 
        mavenLocal() 
    } 
} 

Сама модель: 

package com.example.producer.model; 
 
import lombok.Builder; 
import lombok.Getter; 
import lombok.Setter; 
 
@Getter 
@Setter 
@Builder 
public class Employee { 
 
    private Long id; 
 
    private  String name; 
} 

Теперь опубликуем модель: 

gradle clean build publish 

Потребляем модели — consumer

Создадим проект consumer со следующими зависимостями. 

ext { 
    set('producerVersion', "0.0.1") 
} 

dependencies { 
    implementation "com.example.producer:model:${producerVersion}" 
} 

В принципе, на этом шаге модели из producer уже можно использовать, причём без всякой генерации кода.

Ну а где же API?

Конечно, распространение моделей — это хорошо, но это вещь достаточно тривиальная и древняя. А где же интерфейсы, где обещанный REST, спросите вы. Сейчас всё будет. Но для начала немного теории про технологии, которые позволяют это сделать. 

Spring Cloud OpenFeign

Spring Cloud OpenFeign (далее Feign) — декларативный клиент REST для приложений Spring Boot. Он позволяет создавать веб-сервисы без написания какого-либо кода, кроме создания интерфейса. Этой его особенностью мы и воспользуется, чтобы делиться API с окружающими. Одна из замечательных возможностей Feign — поддержка аннотаций Spring MVC. 

Создание REST-сервиса

Для этого воспользуемся ещё одной замечательной возможностью Spring – обнаруживать аннотации контроллеров в интерфейсах. 

Модуль Common API

Модуль будет содержать интерфейс, в котором мы определим не только сигнатуры методов, но и типы веб-запросов. По сути этот интерфейс представляет собой REST-API. Почему это вынесено в отдельный модуль, станет понятно позднее. 

dependencies { 
    implementation project(":model") 
} 

package com.example.producer.common.api; 
 
import com.example.producer.model.Employee; 
import java.util.List; 
import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.PathVariable; 
 
public interface EmployeeApi { 

    String path = "/employee"; 
 
    @GetMapping("findById/{id}") 
    Employee findById(@PathVariable Long id); 
 
    @GetMapping("findByName/{name}") 
    Employee findByName(@PathVariable String name); 
 
    @GetMapping("findAll") 
    List<Employee> findAll(); 
} 

Модуль API

Модуль представляет собой Spring Boot приложение, содержащее реализацию интерфейса EmployeeAPI. 

dependencies { 
    implementation project(":model") 
    implementation project(":common-api") 
} 

package com.example.producer.controller; 
 
import com.example.producer.common.api.EmployeeApi; 
import com.example.producer.model.Employee; 
import java.util.List; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 
 
@RestController 
@RequestMapping(EmployeeApi.path) 
public class EmployeeController implements EmployeeApi { 
 
    @Override 
    public Employee findById(Long id) { 
        return Employee.builder().id(id).name("test1").build(); 
    } 
 
    @Override 
    public Employee findByName(String name) { 
        return Employee.builder().id(1L).name(name).build(); 
    } 
 
    @Override 
    public List<Employee> findAll() { 
        return List.of(Employee.builder().id(1L).name("test3").build()); 
    } 
 
} 

Распространяем интерфейс

Теперь нужно опубликовать наш интерфейс в maven-репозитарии. Отсюда понятно, почему это вынесено в отдельный модуль. Добавим в Common API следующие настройки: 

apply plugin: 'maven-publish' 
 
jar { 
    enabled=true 
    archiveClassifier.set("") 
} 
 
bootJar { 
    enabled = false 
} 
 
publishing { 
    publications { 
        maven(MavenPublication) { 
            artifact jar 
        } 
    } 
    repositories { 
        mavenLocal() 
    } 
} 

И заново публикуем проект, увеличив версию.  

allprojects { 
    group = 'com.example.producer' 
    version = '0.0.2' 

gradle clean build publish 

Перенесём приложение на другой порт.

server: 
  port: 8096 

Полная структура приложения producer выглядит так: 

Потребляем интерфейс — consumer

Сделаем из consumer Spring Boot приложение. 

plugins { 
    id 'org.springframework.boot' version '2.6.2' 
    id 'io.spring.dependency-management' version '1.0.11.RELEASE' 
    id 'java' 
} 
 
group = 'com.example' 
version = '0.0.1-SNAPSHOT' 
sourceCompatibility = '11' 
 
configurations { 
    compileOnly { 
        extendsFrom annotationProcessor 
    } 
} 
 
repositories { 
    mavenLocal() 
    mavenCentral() 
} 
 
ext { 
    set('springCloudVersion', "2021.0.0") 
    set('producerVersion', "0.0.2") 
} 
 
dependencies { 
    implementation 'org.springframework.boot:spring-boot-starter-web' 
    implementation 'org.springframework.cloud:spring-cloud-starter-openfeign' 
    implementation 'io.github.openfeign:feign-jackson:9.3.1' 
    implementation "com.example.producer:model:${producerVersion}" 
    implementation "com.example.producer:common-api:${producerVersion}" 
    compileOnly 'org.projectlombok:lombok' 
    annotationProcessor 'org.projectlombok:lombok' 
    testImplementation 'org.springframework.boot:spring-boot-starter-test' 
} 
 
dependencyManagement { 
    imports { 
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}" 
    } 
} 

package com.example.consumer; 
 
import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication; 
 
@SpringBootApplication 
public class ConsumerApplication { 
 
    public static void main(String[] args) { 
        SpringApplication.run(ConsumerApplication.class, args); 
    } 
 
} 

Далее настроим Feign. 

@Configuration 
@RequiredArgsConstructor 
public class EmployeeConfig { 
  
    @Value("${producer.api.url}") 
    private String baseUrl; 
 
    private final ObjectMapper mapper; 
 
    @Bean 
    public EmployeeApi employeeApi() { 
        return Feign.builder() 
            .contract(new SpringMvcContract()) 
            .encoder(new JacksonEncoder(mapper)) 
            .decoder(new JacksonDecoder(mapper)) 
            .target(EmployeeApi.class, baseUrl.concat(EmployeeApi .path)); 
    } 
 
 
} 

Cоздадим контроллер для демонстрации использования producer API. 

@RestController 
@RequestMapping("employee") 
@RequiredArgsConstructor 
public class EmployeeController { 
 
    private final EmployeeApi employeeApi; 
 
    @GetMapping("findById/{id}") 
    public Employee findById(@PathVariable Long id) { 
        return employeeApi.findById(id); 
    } 
 
    @GetMapping("findAll") 
    public List<Employee> findAll() { 
        return employeeApi.findAll(); 
    } 
 
} 

В коде видна вся магия такого подхода. Мы общаемся с REST-сервис, просто вызывая методы объекта, как в классическом ООП. 

Настроим producer API URL.  

producer: 
  api: 
    url: http://localhost:8096 

Ну и перенесём приложение на другой порт. 

server: 
  port: 8097 

Проверка результатов

Запускаем оба приложения и наслаждаемся результатом. Ниже приведён результат вызова метода findAll приложения consumer.

А что с документацией?

С документацией проблема решается при помощи старого доброго javadoc. Настроим проект producer для генерации документации. Для удобства настройки плагина публикаций перенесём в отдельный файл в корне проекта — publish.gradle.

apply plugin: 'maven-publish' 
 
jar { 
    enabled=true 
    archiveClassifier.set("") 
} 
 
bootJar { 
    enabled = false 
} 
 
task packageJavadoc(type: Jar) { 
    from javadoc 
    classifier = 'javadoc' 
} 
 
publishing { 
    publications { 
        maven(MavenPublication) { 
            artifact jar 
            artifact tasks.packageJavadoc 
        } 
    } 
    repositories { 
        mavenLocal() 
    } 
} 

Здесь добавилась новая задача. 

task packageJavadoc(type: Jar) { 
    from javadoc 
    classifier = 'javadoc' 
} 

Теперь publish.gradle можно использовать в публикуемых модулях: 

apply from: '../publish.gradle' 

Задокументируем интерфейс.

** 
 * It's a great interface 
 */ 
public interface EmployeeApi { 

Поднимем версию и опубликуем модули. Далее настроим проект consumer. Добавим плагин idea. 

plugins { 
    id 'org.springframework.boot' version '2.6.2' 
    id 'io.spring.dependency-management' version '1.0.11.RELEASE' 
    id 'java' 
    id 'idea' 
} 

Настроим его. 

idea { 
    module { 
        downloadJavadoc = true 
    } 
} 

Сделаем реимпорт проекта. Теперь можем наслаждаться чтением документации. 

Безусловно, OpenAPI — очень мощный и удобный инструмент. Однако и описываемый подход имеет свои преимущества:  

• Нет необходимости кодогенерации: уходит зависимость от кодогенераторов.  

• API распротраняется в виде библиотек через репозитарии maven, поэтому для их подключения в клиенте не требуется дополнительных плагинов — это просто обычная зависимость maven. 

• Несколько проще поддерживать версионность по сравнению с Open API.