Публичные контракты, как обеспечить их согласованность

Изменение контрактов

Изменение контрактов

Нужно что-то предпринять

Нужно что-то предпринять

Как сделать так,
чтобы такое больше не повторялось

Экосистема Sungero

Экосистема Sungero

Экосистема Sungero

Проблема. В каждом сервисе своя реализация клиента StorageServiceClientProxy

Проблема. В каждом сервисе своя реализация клиента StorageServiceClientProxy

Постановка задачи

Постановка задачи

Инструменты
RPC
REST

REST vs RPC

Где расположить контракты?
Как осуществить доступ сервисов к контрактам?

Где расположить контракты?
Как осуществить доступ сервисов к контрактам?

В какой момент выполнять генерацию?

В какой момент выполнять генерацию?

Где расположить код клиента?

Где расположить код клиента?
Где расположить код клиента?

Где расположили код клиента

Детали реализации

DescriptionController.cs
[Route("[controller]")]
[ApiController]
public class DescriptionController : ControllerBase {
[OpenApiOperation("GetDescription")]
[ProducesResponseType(typeof(ConversionDescription), 200)]
[ProducesResponseType(401)]
[ProducesResponseType(403)]
[HttpGet("{pluginName}/{binaryDataId}")]
public ActionResult
GetDescription(
string pluginName, Guid binaryDataId) { // код... }

FileController.cs
[Route("[controller]")]
[ApiController]
public class FileController : ControllerBase {
[OpenApiOperation("SaveFile")]
[ProducesResponseType(401)]
[ProducesResponseType(403)]
[HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[FileUploadOperation]
public async Task SaveFile() { // код... }

Процессор

Конфигурация Nswag.json
"runtime": "NetCore22",
"documentGenerator": { "webApiToOpenApi": {
"defaultUrlTemplate": "api/{controller}/{id?}",
"infoTitle": "PreviewStorage", "infoVersion": "1.0.0",
"documentName": "v1","allowNullableBodyParameters": true,
"output": "../../api-docs/PreviewStorage_swagger.json",
"outputType": "OpenApi3",
"assemblyPaths": [
"../../bin/$(Configuration)/PreviewStorage/netcoreapp2.2/PreviewStorage.dll“ ], } },
"codeGenerators": { "openApiToCSharpClient": { "input": "../../api-docs/PreviewStorage_swagger.json",
"namespace": "PreviewStorage.WebApiProxy",
"generateClientInterfaces": true,
"useHttpRequestMessageCreationMethod": true,
“httpClientType": "System.Net.Http.HttpClient",
"additionalNamespaceUsages": [ "PreviewService.Common.Model“ ],
"output": "../PreviewStorage.WebApiProxy/PreviewStorageProxy.g.cs",
"className": "{controller}PreviewStorageProxy",
"operationGenerationMode": "SingleClientFromOperationId“ } } }

Как добавили поддержку JWT

Как добавили поддержку JWT

Как добавили поддержку JWT

Как добавили поддержку JWT

Вывод

Вывод

Версионирование

Изменение
контрактов
Команда сервиса поставщика сама исправляет сервисы потребители.
Без версионирования
Варианты решения

Изменение
контрактов
Плохо работает:
Разные репозитории
Нет компетенций
Варианты решения

Изменение
контрактов
Команда сервиса поставщика оставляет предыдущую версию контрактов
Варианты решения

Версионирование

Версионирование

Версионирование

Версионирование

Когда вводить новую версию

Тестирование контрактов

Consumer driven contracts

Спасибо за внимание!
Разработчик Directum
в г. Уфа Романюк Антон
[e-mail]

REST + gRPC

Настройка csproj

Как CDC можно встроить в CI

Процессор
public class FileUploadOperationAttribute : OpenApiOperationProcessorAttribute {
public FileUploadOperationAttribute() : base(typeof(FileUploadOperationProcessor)) { } }
public class FileUploadOperationProcessor : IOperationProcessor {
public bool Process(OperationProcessorContext context) {
var parameters = context.OperationDescription.Operation.Parameters;
parameters.Add(new OpenApiParameter() {
Name = "stream", Kind = OpenApiParameterKind.Body,
Schema = new JsonSchema { Type = JsonObjectType.String, Format = "binary" },
IsRequired = true, Description = "Файл.",
});
return true; } }

WSDL
Language, platform, and transport independent (REST requires use of HTTP)
Works well in distributed enterprise environments (REST assumes direct point-to-point communication)
Standardized
Provides significant pre-build extensibility in the form of the WS* standards
Built-in error handling
Automation when used with certain language products

Версионирование

https://servicesblog.redhat.com/2019/01/31/comparing-openapi-with-grpc/
https://docs.microsoft.com/en-us/aspnet/core/grpc/comparison?view=aspnetcore-3.1
https://blog.maddevs.io/introduction-to-grpc-6de0d9c0fe61
https://github.com/Azure/openapi-diff
https://www.davidkaya.com/with-openapi-against-breaking-changes/
https://github.com/grpc/grpc-web/issues/517 не подойдет для передачи больших файлов
https://developers.google.com/protocol-buffers/docs/techniques?hl=en#large-data сообщения не больше 1 мб
https://app.swaggerhub.com/help/integrations/api-auto-mocking