Инструментарий | English

Apache ServiceComb Toolkit — это набор инструментов для разработки микросервисов на основе контрактов.

Вкладчики: Этот проект нуждается в поддержке. Если вы готовы помочь в поддержке проекта, пожалуйста, свяжитесь с нами, и мы добавим вас в группу коммитеров для продолжения поддержки проекта.

Пользователи: Этот проект нуждается в поддержке. В то время как мы ищем постоянного поддерживателя, мы рекомендуем вам избегать использования этого проекта, чтобы избежать проблем, которые могут не получить техническую поддержку.

1 Введение

1.1 Цели* Предоставление возможностей для преобразования и проверки контрактов, кода и документации, чтобы помочь пользователям быстро создавать микросервисные проекты на основе популярных микросервисных фреймворков и моделей программирования, снижая стоимость входа в микросервисы и позволяя пользователям сосредоточиться на разработке бизнес-приложений, повышая эффективность рефакторинга и разработки устаревших систем.

1.2 Особенности

Извлечение контрактов из устаревших приложений

В приложениях, разработанных на основе моделей SpringMVC/POJO/JAX-RS, можно автоматически извлечь файлы контрактов, соответствующие стандарту OpenAPI.
Создание микросервисных проектов на основе контрактов

Ввод контрактов, соответствующих стандарту OpenAPI, позволяет автоматически создать микросервисные проекты на основе ServiceComb/SpringCloud/Swagger, а также на основе моделей SpringMVC/POJO/JAX-RS или SpringBoot.
Проверка соответствия контрактов и кода

Проверка соответствия реального кода приложения (например, данных и API-интерфейсов) с описанными в контракте.
Проверка стиля и совместимости контрактов

Проверка стиля проверяет, соответствует ли контракт стандарту OAS 3.0.2 и собственным правилам; проверка совместимости проверяет совместимость двух версий OAS.
Создание документации на основе контрактов и кода

Введите контракт сервиса, соответствующий стандартам OpenAPI, для автоматического создания документации в формате HTML.

1.3 Применение

Для компаний, интегрирующих приложения нескольких поставщиков

Проблема: Различия в данных поставщиков, стандартах услуг, языках программирования, привычках и фреймворках усложняют интеграцию и управление. Решение: Используя единые стандарты описания интерфейсов (контракты), можно автоматически создать проекты микросервисов на основе выбранных фреймворков с помощью инструментов. Это позволяет координировать работу нескольких команд разработчиков, снижая затраты на коммуникацию и избегая путаницы в будущем.
Быстрое преобразование устаревших систем в микросервисы

Проблема: Пользователи должны изучить микросервисы и связанные фреймворки перед тем, как начать разработку проектов микросервисов, что увеличивает издержки обучения.

Решение: Используя инструменты, можно анализировать устаревшие приложения, извлекать контракты и автоматически создавать проекты микросервисов на основе выбранных фреймворков. Это позволяет сосредоточиться на разработке бизнес-логики и уменьшает издержки обучения микросервисным фреймворкам.

2 Проектирование

2.1 Основная архитектура

2.2 Принцип работы

3 Быстрый старт

3.1 Сборка инструмента и плагинов из исходного кода

Требования к среде:

# Получение последнего исходного кода toolkit из github
$ git clone https://github.com/apache/servicecomb-toolkit.git
$ cd toolkit
```# Сборка и упаковка
```shell
$ mvn clean install

3.2 Конфигурация плагина toolkit-maven-plugin

3.2.1 Настройка

Конфигурация плагина toolkit-maven-plugin в файле pom Maven проекта

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Источник входных данных. Установите значение code для анализа текущего кода; установите значение contract для анализа файлов контрактов в указанной директории. Если не указано, значение по умолчанию — code -->
        <sourceType>code</sourceType>
        <!-- Тип сгенерированных файлов контрактов. Если не указано, значение по умолчанию — yaml -->
        <contractFileType>yaml</contractFileType>
        <!-- Тип сгенерированных документов. Если не указано, значение по умолчанию — html -->
        <documentType>html</documentType>
        <!-- Корневая директория для сгенерированных файлов контрактов и документов. Если не указано, значение по умолчанию — директория target в текущей директории команды, сгенерированные микросервисные проекты находятся в директории project, файлы контрактов — в contract, а документы — в document -->
        <outputDirectory>/target</outputDirectory>
        <!-- Путь к файлам контрактов для анализа. Эффективно при sourceType = contract, и обязательно для указания -->
        <contractLocation>/contract</contractLocation>
        <!-- Директория для проверки файлов контрактов. Эффективно при sourceType = contract, и обязательно для указания -->
        <sourceContractPath>/target/contract</sourceContractPath>
    </configuration>
</plugin>
```-- Директория для образцов файлов контрактов, обязательно для указания -->
         <destinationContractPath>/contract</destinationContractPath>
         <!-- Конфигурация сгенерированных микросервисных проектов -->
         <service>
             <!-- Тип микросервиса, можно сгенерировать provider/consumer/all, значение по умолчанию — all -->
             <serviceType>all</serviceType>
             <!-- GroupId микросервиса, пользовательский выбор, значение по умолчанию — domain.orgnization.project -->
             <groupId>domain.orgnization.project</groupId>
             <!-- ArtifactId микросервиса, пользовательский выбор, значение по умолчанию — sample -->
             <artifactId>sample</artifactId>
             <!-- ArtifactVersion микросервиса, пользовательский выбор, значение по умолчанию — 0.1.0-SNAPSHOT -->
             <artifactVersion>0.1.0-SNAPSHOT</artifactVersion>
             <!-- PackageName микросервиса, пользовательский выбор, значение по умолчанию — domain.orgnization.project.sample -->
             <packageName>domain.orgnization.project.sample</packageName>
             <!-- Фреймворк микросервиса, пользовательский выбор. Установите значение SpringCloud, чтобы создать проект стиля микросервисов SpringCloud. Значение по умолчанию — ServiceComb -->
             <microServiceFramework>ServiceComb</microServiceFramework>
             <!-- Идентификатор предоставляемого сервиса. В сценарии, где присутствуют только потребители услуг (serviceType=consumer), необходимо задать это значение -->
             <providerServiceId>servicecomb-provider</providerServiceId>
             <!---- Идентификатор сервиса, значение по умолчанию — значение artifactId -->
              <serviceId>servicecomb-consumer</serviceId>
          </service>
          <!-- Указание дополнительных значений свойств, которые могут быть использованы шаблоном mustache. Используется только при генерации кода, когда goal — generate -->
          <additionalProperties>
              <prop1>value</prop1>
              <prop2>value</prop2>
              .  .  .
              <propN>value</propN>
          </additionalProperties>
      </configuration>
  </plugin>
  ```#### 3.2.2 Команды
 ```shell
 # Создание контрактов, документации и микросервисного проекта
 mvn toolkit:generate ```# Проверка согласованности кода и контрактов
mvn toolkit:verify

3.2.2.1 Разбор кода, создание микросервисного проекта, OpenAPI-спецификаций контрактов, документации

Конфигурационные параметры (если не указан <configuration>, используются значения по умолчанию) Пример:

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Источник ввода. Значение "code" указывает на разбор текущего кода; значение "contract" указывает на разбор файлов контрактов в указанной директории. Если не указано, используется значение "code" по умолчанию -->
        <sourceType>code</sourceType>
        <!-- Корневая директория для создания контрактов, документации, если не указана, используется директория target в текущей директории -->
        <outputDirectory>./target</outputDirectory>
        <!-- Конфигурация для создания микросервисного проекта -->
        <service>
            <!-- Тип микросервиса, может быть "provider", "consumer", "all", значение по умолчанию "all" -->
            <serviceType>all</serviceType>
        </service>
    </configuration>
</plugin>

Запуск команды

mvn toolkit:generate

Создание контрактов из кода поддерживает следующие аннотации (уровень класса) для написания RESTful-интерфейсов

RestController, RestSchema, RpcSchema, RequestMappingПри создании контрактов из кода, методы RESTful-интерфейсов должны быть открытыми (public). Конфигурационные параметры (если не указаны явно <configuration>, используются значения по умолчанию).

Пример:

<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Тип входных данных. Значение `code` указывает на анализ текущего кода; значение `contract` указывает на анализ файлов контрактов в указанной директории. Если не указано, значение по умолчанию — `code` -->
        <sourceType>contract</sourceType>
        <!-- Путь к файлам контрактов, действует при значении `sourceType` равном `contract`, и должно быть обязательно указано -->
        <contractLocation>./contract</contractLocation>
        <!-- Корневая директория для генерации файлов контрактов и документов, если не указана, значение по умолчанию — директория `target` в текущей директории, где выполняется команда. Микросервисные проекты создаются в директории `project`, файлы контрактов — в `contract`, а документы — в `document` -->
        <outputDirectory>./target</outputDirectory>
        <!-- Конфигурация для генерации микросервисного кода -->
        <service>
            <!-- Тип микросервиса, может быть `provider`, `consumer`, или `all`. Значение по умолчанию — `all` -->
            <serviceType>provider</serviceType>
        </service>
    </configuration>
</plugin>

Запуск команды

mvn toolkit:generate
```#### 3.2.2.3 Проверка согласованности кода и контрактов

Конфигурационные параметры
Пример:
```xml
<plugin>
    <groupId>org.apache.servicecomb.toolkit</groupId>
    <artifactId>toolkit-maven-plugin</artifactId>
    <version>0.3.0-SNAPSHOT</version>
    <configuration>
        <!-- Источник ввода. Значение "code" указывает на анализ текущего кода; значение "contract" указывает на анализ файлов контрактов в указанной директории. Если не указано, по умолчанию используется "code" -->
        <sourceType>code</sourceType>
        <!-- Директория с образцами файлов контрактов, обязательный параметр -->
        <destinationContractPath>./contract</destinationContractPath>
    </configuration>
</plugin>

Запуск команды

mvn toolkit:verify

3.3 Использование toolkit cli-инструмента#### 3. 3. 0 Получение

Если вы используете официальную версию (>=0. 2. 0), после распаковки бинарного пакета вы можете использовать скрипты внутри пакета
- В среде Linux и Mac, используйте cli.sh
- В среде Windows, используйте cli.cmd
Если вы собираете из исходного кода, вы можете поместить cli/scripts/cli.* и cli/target/bin/toolkit-cli-{version}.jar в одну директорию, а затем выбрать соответствующий скрипт в зависимости от вашей среды. Все приведенные ниже примеры демонстрируются с использованием скрипта cli.sh в окружении Linux.

$ ./cli.sh help

3. 3. 1 Процесс генерации микросервиса

$ ./cli.sh codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC

codegenerate параметры команды:

-m, --microservice-framework : Указывает фреймворк микросервиса, поддерживается ServiceComb
Пример: -m ServiceComb
-p, --programming-model : Указывает модель программирования, доступны JAX-RS, POJO, SpringMVC, SpringBoot
Пример: -p SpringMvc
-i, --input : Указывает файл контракта, соответствующий стандарту OpenAPI, поддерживает форматы yaml и json, а также указание локальных и сетевых файлов
Пример: -i http://petstore.swagger.io/v2/swagger.json
-o, --output : Указывает путь для сохранения сгенерированного кода проекта
Пример: -o ./project
--group-id : Указывает group id для сгенерированного проекта
Пример: --group-id com.demo
--artifact-id : Указывает artifact id для сгенерированного проекта
Пример: --artifact-id springmvc-example
--artifact-version : Указывает artifact version для сгенерированного проекта
Пример: --artifact-version 1.0.0* --api-package : Указывает пакет API для сгенерированного проекта
Пример: --api-package com. demo. api
--model-package : Указывает пакет model для сгенерированного проекта
Пример: --model-package com. demo. model
-t, --service-type : Указывает тип микросервиса для сгенерированного проекта. Доступны значения provider, consumer, all
Пример: --service-type provider
--properties : Указывает дополнительные свойства, которые могут быть использованы в шаблоне Mustache
Пример: --properties applicationId=app,providerServiceId=provider

3. 3. 2 Генерация документации по контракту

$ . /cli. sh docgenerate -i swagger. yaml -o . /document

docgenerate Параметры команды:

-i, --input : Указывает файл контракта, следующий за стандартом OpenAPI, поддерживает форматы YAML и JSON, поддерживает указание локальных и сетевых файлов
Пример: -i http://petstore. swagger. io/v2/swagger. json
-o, --output : Путь для вывода документации
Пример: -o . /document
-f, --format : Указывает стиль документации, поддерживает Swagger-UI
Пример: -f swagger-ui#### 3.3.3 Проверка стиля контракта

$ ./cli.sh checkstyle -r style-check-rules.yaml -f oas.yaml
или
$ ./cli.sh cs -r style-check-rules.yaml -f oas.yaml

checkstyle Параметры команды

-r, --rules-file : Файл правил.
-f, --file : Файл спецификации OpenAPI v3 в формате yaml.

См. правила проверки стиля

3.3.4 Проверка совместимости контракта

$ ./cli.sh checkcompatibility left-oas.yaml right-oas.yaml
или
$ ./cli.sh cc left-oas.yaml right-oas.yaml

checkcompatibility Параметры команды

<files> : Два файла спецификации OpenAPI v3 в формате yaml

См. правила проверки совместимости

3.4 Примеры использования

Примеры использования плагина можно найти здесь

4 Общение в сообществе

Отправка проблем
Чат на gitter
Почтовый список: подписаться просмотреть

5 Участие в разработке

Подробности см. в руководстве по отправке pull request

OSCHINA-MIRROR/apache-ServiceComb-Toolkit

Инструментарий | English

1 Введение

1.2 Особенности

1.3 Применение

2 Проектирование

2.1 Основная архитектура

2.2 Принцип работы

3 Быстрый старт

3.1 Сборка инструмента и плагинов из исходного кода

3.2 Конфигурация плагина toolkit-maven-plugin

3.2.1 Настройка

3.2.2.1 Разбор кода, создание микросервисного проекта, OpenAPI-спецификаций контрактов, документации

3.3 Использование toolkit cli-инструмента#### 3. 3. 0 Получение

3. 3. 1 Процесс генерации микросервиса

3. 3. 2 Генерация документации по контракту

3.3.4 Проверка совместимости контракта

3.4 Примеры использования

4 Общение в сообществе

5 Участие в разработке

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/apache-ServiceComb-Toolkit .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Инструментарий | English

1 Введение

1.2 Особенности

1.3 Применение

2 Проектирование

2.1 Основная архитектура

2.2 Принцип работы

3 Быстрый старт

3.1 Сборка инструмента и плагинов из исходного кода

3.2 Конфигурация плагина toolkit-maven-plugin

3.2.1 Настройка

3.2.2.1 Разбор кода, создание микросервисного проекта, OpenAPI-спецификаций контрактов, документации

3.3 Использование toolkit cli-инструмента#### 3. 3. 0 Получение

3. 3. 1 Процесс генерации микросервиса

3. 3. 2 Генерация документации по контракту

3.3.4 Проверка совместимости контракта

3.4 Примеры использования

4 Общение в сообществе

5 Участие в разработке

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/apache-ServiceComb-Toolkit