hexarc pact

Hexarc Pact

Hexarc Pact предоставляет инструмент для разоблачения и потребления веб-API для проектов .NET/TypeScript.

Разработайте свой проект .NET Web API с PACT, чтобы сохранить единый источник истины для метаданных API и употреблять его в экосистеме .NET (микросервисы, настольные и мобильные приложения) или в Интернете через TypeScript.

Упаковка	Платформа	Версия	Загрузки
Hexarch.Pact.Protocol	.NET 7.0+
Hexarch.Pact.AspNetCore	.NET 7.0+
Hexarch.Pact.Client	.NET 7.0+
Hexarch.Pact.Tool	.NET 7.0+
@hexarc/pact-tool	Машинопись

Что в договоре?

• Функции
• Типовая система
• Правила аннотации API
  • Дополнительные атрибуты
• Демонстрация API
• Как использовать
  • Разоблачить схему PACT API (.NET WEB API Service)
  • Потребляйте схему PACT API (.net Client Application)
• Благодарности
• Лицензия

Функции

• Безопасные интеграции API за секунды.
• Без течения информации о информации. Потребляйте точный API, как он спроектирован.
• Код сначала. Не нужно описывать ваш протокол API во внешнем IDL/DSL.
• Заряжено в продвинутых типах. Не только простые DTOS, но и перечисления, дженерики, тегированные профсоюзы и т. Д.

Типовая система

Система типа PACT основана на типах .NET CLR с некоторыми сделанными на заказ для лучшего опыта разработки.

Что внутри системы типа PACT:

• Примитивные типы (включая Guid и DateTime )
• Семантика типа значения/ссылки
• Коллекции и дженерики (не только простые массивы и словари)
• Полная поддержка аннотаций типа ссылок (NRT)
• Enums (на основе строк и на основе чисел)
• Tagged Uniions (через hexarc.serialization.union)
• КУТУ (через hexarc.serialization.tuple)

Правила аннотации API

Схема PACT API предназначена для того, чтобы иметь RPC-подобную семантику. При этом открытый API должен следовать этим правилам:

• Контроллеры API должны быть отмечены стандартными атрибутами ApiController и Route .
• Атрибут маршрута должен иметь только постоянный путь строкового пути без шаблона (например, [Route("Entities")] ).
• Методы API должны быть отмечены одним из поддерживаемых глаголов HTTP ( HttpGet или HttpPost ). Атрибуты глагола могут содержать путь конечной точки. Другие не поддерживаются в данный момент.
  • Методы HttpGet могут иметь параметры запроса, которые должны быть связаны через атрибут FromQuery .
  • Методы HttpPost должны иметь только один параметр, который является корпусом запроса.
• Путь метода API может быть указан в атрибуте глагола HTTP или в атрибуте Route . Если путь метода не указан в атрибуте глагола HTTP, он будет взят из Route One или исключение будет поднято.

Дополнительные атрибуты

PACT предоставляет некоторые полезные атрибуты для аннотации API:

• PactIgnoreAttribute может применяться к контроллерам API или методам, которые будут исключены из схемы API.
• PactScopeAttribute может быть применен к контроллерам API, которые должны быть выделены в специфическую область в схеме API.

Демо -сервер API

Демо-сервер API можно найти по адресу https://hexarc-demo-api.herokuapp.com/.

Схема PACT API выставлена ​​по адресу https://hexarc-demo-api.herokuapp.com/pact/schema.

Чтобы сгенерировать клиент API, используйте инструкцию ниже.

Как использовать

Узнайте, как использовать PACT для разоблачения и потребления типичного веб -API.

Разоблачить схему PACT API

1. Установите пакет Hexarc.Pact.AspNetCore в проекте .net Web API:

dotnet add package Hexarc.Pact.AspNetCore

2. Добавьте генерацию схемы PACT в методе Startup.ConfigureServices :

 public void ConfigureServices ( IServiceCollection services )
{
    services . AddControllers ( ) ;

    // Register the Pact schema generation.
    services . AddPactGeneration ( ) ;
}

3. Включите промежуточное программное обеспечение PACT в методе Startup.Configure :

 public void Configure ( IApplicationBuilder app )
{
    // Enable the Pact middleware to expose the generated API schema.
    app . UsePact ( ) ;

    app . UseRouting ( ) ;
    app . UseEndpoints ( endpoints => endpoints . MapControllers ( ) ) ;
}

4. Реализуйте контроллер API в соответствии с правилами аннотации PACT:

 [ ApiController , Route ( "Misc" ) ]
public sealed class MiscController : ControllerBase
{
    [ HttpGet ( nameof ( Ping ) ) ]
    public String Ping ( [ FromQuery ] String message ) => $ "Hello, { message } " ;
}

5. Запустите приложение и откройте адрес YOUR_API_HOST/pact/schema чтобы обеспечить создание схемы PACT API.

Потреблять схему PACT API

1. Установите пакет Hexarc.Pact.Client в проекте .NET:

dotnet add package Hexarc.Pact.Client

2. Установите инструмент Hexarc.Pact.Tool в проекте:

dotnet tool install Hexarc.Pact.Tool

Вам может потребоваться настроить манифест инструментов .NET перед установкой инструмента Hexarc.Pact.Tool :

dotnet new tool-manifest

3. Добавьте конфигурацию pact.json в проект с желаемыми настройками генерации клиента API:

{
   "schemaUri" : " YOUR_API_HOST/pact/schema " ,
   "clientClassName" : " DemoClient " ,
   "clientClassNamespace" : " DemoNamespace " ,
   "outputDirectory" : " Generated "
}

где

• schemaUri - Ссылка на схему PACT API
• clientClassName - Имя для сгенерированного класса клиента API
• clientClassNamespace - Пространство имен, куда поместить сгенерированный класс клиента API
• outputDirectory - выходной каталог для сгенерированных источников

4. Создайте клиент API через инструмент PACT CLI:

dotnet pact

Эта команда должна выполняться в той же папке с конфигурацией pact.json .

5. Сгенерированный клиент API будет доступен для доступа к серверу API:

 var client = new DemoClient ( new HttpClient { BaseAddress = new Uri ( "YOUR_API_HOST" ) } ) ;
var pong = await client . Misc . Ping ( "World" ) ;
Console . WriteLine ( pong ) ; // Prints "Hello, World" to the output. 

Благодарности

Построен с инструментами JetBrains для проектов с открытым исходным кодом.

Лицензия

MIT © MAX Koverdyaev