Внутренний DDD Внешний API — концепция дизайна внешнего API

автор:Ли Чжэнинженер-кунар

Присоединился к Qunar в феврале 2017 года. В настоящее время основное внимание уделяется управлению службой домена и стандартизации возможностей домена на основе управления API. Приверженность решению сложных бизнес-задач посредством доменизации, моделирования и восприятия. Ожидайте использовать драйвер DDD, чтобы уменьшить сложность системы и повысить эффективность команды.

предисловие

Внутренний DDD и внешний API — это концепция дизайна архитектуры ремоделирования бизнеса, запущенная группой исследований и разработок бизнес-группы по продаже авиабилетов Qunar.com в третьем квартале 2020 года. В третьем квартале 2020 года Qunar добился определенного прогресса в области стандартизации API, основанного на прошлом, и эта статья предназначена в основном для того, чтобы поделиться с вами этим опытом.

Что такое внутренний DDD и внешний API?Это практический принцип использования DDD в качестве концепции дизайна предметной области и дизайна микросервисов в области бизнес-исследований и разработок, а также простое для понимания изложение использования API для взаимодействия между доменами.

1 Краткая история разработки Qunar API

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

wikiQunar — наиболее традиционный инструмент-носитель API для Qunar.Все публичные платформы, появившиеся ранее в компании, такие как платежный центр, предоставляют стандартные API через вики. Преимущество вики в том, что она обладает относительно высокой степенью свободы, не стеснена различными нормами, может быть модифицирована по желанию, может быть очень персонализирована под требования определенных читателей интерфейса, естественная безопасность лучше, а не -Сотрудники компании не имеют разрешения на доступ. Недостатков больше. Например, поскольку нет определенной спецификации интерфейса, которую можно было бы ограничить, интерфейс определяется различными способами, и существуют различные очень персонализированные соглашения. Одни и те же соглашения представлены по-разному, и некоторые имеют тенденцию давать Вложенные презентации, а некоторые, как правило, дают модульные презентации Синхронизация между определениями интерфейса и интерфейсами зависит от спецификаций и сознания инженеров, и вики очень легко не соответствует коду.

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

Второе решение, которое играет вспомогательную роль в Qunar, этоYAPI, Предысторией роста YAPI является архитектура разделения клиентской и серверной части, которая началась в 2016 году. Разделение фронтенда и бэкэнда делает фронтенд-инжиниринг более независимым. YAPI также стал проектом Qunar с открытым исходным кодом в 2018 году. Являясь интерфейсной платформой, разработанной фронтенд-студентами, YAPI по-прежнему остается одним из краеугольных камней API-решений Qunar. Роль YAPI можно выразить одним предложением: «совместно поддерживать определение интерфейса и соединять интерфейс и сервер».

Разницу между YAPI и Wiki можно представить на следующем рисунке:

Чтобы предотвратить синхронизацию определений интерфейса с интерфейсом (документация и код не синхронизируются), одноклассники бэкэнда ввели в код режим Annotation для использования аннотаций.swagger, и сделал некоторые расширения на основе maven на основе swagger, чтобы спецификации, написанные swagger, могли обновлять изменения интерфейса для платформы YAPI с помощью команд maven и изменений статуса проекта, таких как публикация, и устранять несоответствие между документом интерфейса и реализация интерфейса проблема.

swagger -> YAPI добился определенных результатов, но поскольку проектов, использующих swagger для написания документов API, относительно немного, и мало кто знает, что существует инструмент swagger -> YAPI, метод swagger -> YAPI не продвигался внутри компании. , чтобы использовать.

Две причины, по которым Qunar продвигает стандартизацию API

В 2020 году из-за эпидемии Qunar.com начала активную кампанию по «обучению внутренних навыков», которая включает ремоделирование бизнес-DDD в основных областях бизнеса, экономию затрат на оборудование и рефакторинг внутреннего API.

При этом мы сталкиваемся с некоторыми трудностями:

1, вызов DDD и должны быть реконструированы вне поля через интерфейс, то интерфейс обеспечивает гораздо более подходящее его между полем и вне поля? 10? 30? 50? Если API предоставляет слишком много, это означает, что не хватает стандартов API, достаточно высокого качества?

2. Стоимость оборудования включает в себя стоимость узлов физической машины и виртуальной машины, автономный журнал, стоимость журнала в реальном времени, так сколько узлов виртуальной машины физической машины является более подходящим? Насколько уместны автономный журнал и вывод журнала в реальном времени системы? Эта часть очень зависит от количества системных API и объема предоставленного доступа к API.

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

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

3 Теоретическая основа стандартизации API

Теоретическая основа стандартизации API исходит из концепции интерфейса между системами, предложенной Джеффом Безосом в 2002 году, и эта концепция постепенно обогащалась до концепции, называемой зрелостью SOA.

Вот как Безос выражает идею взаимодействия с системами Amazon:

2002年，贝索斯突然向全公司发布了一道指令。

- С сегодняшнего дня все команды предоставляют данные и различные функции в виде сервисного интерфейса.

- Связь между командами должна осуществляться через интерфейс.

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

- Конкретная технология реализации не указана, допустимы HTTP, Corba, PubSub и пользовательские протоколы.

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

- Несоблюдение вышеуказанных правил влечет за собой увольнение.

Модель зрелости SOA, разработанная на основе вышеупомянутого решения Джеффа Безоса, имеет четкие требования к стандартизации API, в том числе:

Подробная спецификация, определяющая интерфейсы, методы, параметры, типы и описания
определить критерии оценки,
Поддержка подключаемых модулей средств разработки: IDEA, распознавание спецификаций подключаемых модулей eclipse.
Издательская система поддерживает API

Из приведенной выше серии требований к API нам нужно, чтобы API имел следующие характеристики:

Спецификации понятны
Легкий доступ к ассамблее
простой в использовании синтаксис
Исполнением легко управлять
Платформа проста в применении

Есть и общий принцип: все функции основаны на существующей инфраструктуре Qunar, и колеса повторяться не будут.

В итоге получается общее решение по стандартизации Qunar API:

Которые, платформа хранения API YAPI готова, слегка модифицирована для поддержки этой службы API, требует стандартизации, дерево платформы управления приложениями готово, существующая система, в которой сеть называется Portal, платформа управления доменом приложения готова, только для вас Необходимо сделать этот расширенный шлюз и открытая платформа легко доступна, это сделала обе системной интеграции. Можно сказать, что только qdoc-аннотация и qdoc-maven-плагин - вновь созданные плагины, инструменты.

4 Специальная реализация процесса стандартизации API

4.1 Спецификация проста для понимания

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

Следующие условия регулируются Комитетом по разработке спецификаций:

область (домен/группа)

Для общей системной границы бизнеса домен (домен) содержит несколько приложений (коды приложений), а внешние интерфейсы домена доступны через коды приложений, которые принадлежат той части, которая открыта для внешнего мира. Примечание. Области можно сопоставить с узлами третьего/четвертого уровня дерева приложений.

Приложение (AppCode)

Приложение относится к коду приложения в системе Qunar, а код приложения — это приложение. Существует особый случай, когда набор кода (один проект git) развертывает несколько кодов приложений, которые мы считаем несколькими приложениями.

услуга

Под одним и тем же кодом приложения может предоставляться несколько услуг. Будут разные представления для разных реализаций службы (dubbo/http).

Для dubbo хорошо понятно, что сервисному интерфейсу соответствует сервис.
Для http, основанного на идее Spring MVC (restful), каждому сервису соответствует контроллер. (Для этого требуются разные контроллеры, чтобы различать функциональную группу).

интерфейс

Это функциональное измерение самого лучшего зернистости и является настоящим подмножеством обслуживания. Различные реализации услуг (Dubbo / http) будут иметь разные формы выражения.

Для dubbo это метод, предоставляемый услугой.
Для http это RequestMapping (метод), предоставляемый контроллером.

параметр

Параметры являются важной частью интерфейса. Будут разные представления для разных реализаций службы (dubbo/http).

Для dubbo хорошо понятно, что достаточно входных параметров сигнатуры метода на основе java, и содержимого в RpcContext (за исключением особых случаев, эквивалентных QTraceContext).
Для http параметр состоит из четырех частей, первая часть передается списком параметров в URL-адресе, а вторая часть помещается в http-данные POST. Обычно эти две части основаны на Spring MVC и могут быть определены с помощью @RequestParam. Третья часть — это информация cookie (заголовок запроса), а четвертая часть эквивалентна QTraceContext.

Тип (тип)

И входные, и выходные параметры должны быть идентифицированы по типу. Тип — это описательное определение структуры. Будут разные представления для разных реализаций службы (dubbo/http).

Для dubbo очевидно, что типом здесь является определение типа Java. В то же время необходимо пояснить особый случай объекта: для объекта он представляет собой произвольную структуру, которая не разрешена в типе, а фактический тип (определение конкретного класса или определение схемы json) соответствующего объекта должен быть идентифицированы.
Для http входными параметрами обычно являются базовые типы или JSON-подобные типы (включая коллекции и т. д., которые описываются в json), а выходные параметры описываются в json. http — это слабая система определения типов, которая не подходит для документов, поэтому мы оговариваем, что типы входных и выходных параметров определяются в схеме json.

После стандартизации терминов мы начали формулировать аннотации и аннотации, соответствующие терминам.В первом выпуске мы сначала стандартизировали соответствующие аннотации:

Домен (@QDomainDoc)

Приложение (@QAppcodeDoc) Сервис (@QServiceDoc) Интерфейс (@QInterfaceDoc) Имеются аннотации параметров и возможность удаления возвращаемого значения Параметры (@QParamDocs)
Параметр (@qparamdoc) Модель Параметр (@qparammodel) аннотация (@qparammodelproperty) Тип модели модели (@qtypeatoc) эквивалентен @requestParam. Не реализован в настоящее время и будет поддерживать описание кода состояния значения возвращаемого значения (@QReponses) в будущем. Описание кода состояния значения возврата (@QResponse) описание возвращаемого значения данных Описание данных возврата Данные значения (@QRESPONSONSEDOCS). @QRESPONSEDOC) Exception (@QExceptiondoc) Расширения (@qextensiondoc)

Для каждой соответствующей аннотации мы также дадим инструкции по использованию соответствующего параметра аннотации:

Сервис (@QServiceDoc) описывает назначение сервиса:

Как видите, нормативные термины и аннотации, данные QDoc, полностью учитывают инженерный контекст, обычно используемый студентами Qunar, например, домен и код приложения, которые обычно используются в инженерном контексте Qunar.Когда вы видите эти слова, вы можете подумайте о том, для чего он используется. Эти термины, которые близки к словарю, обычно используемому инженерами, делают понимание спецификации QDoc очень простым. Вы можете понять ее, не читая большой раздел инструкций. Стоимость обучения низкая, и вы может использовать его быстро. В этом основное различие между спецификациями, сформулированными Qunar.com, и сторонними API-инструментами, такими как swagger2.0, swagger3.0 и smart-doc. спецификация OpenAPI3.0 очень важная причина.

Когда определение канонического компонента API на основе аннотаций будет завершено, следующим шагом будет разработка соответствующих инструментов, подключаемых модулей и доступа к инструментам.

4.2 Легкий доступ к компонентам

Чтобы облегчить доступ бизнес-инженерам, QDoc не позволяет бизнес-инженерам-разработчикам иметь дополнительный объем разработки в процессе доступа к QDoc.Метод добавления пакета jar и подключаемого модуля maven Шаги доступа очень просты:

Этапы доступа к сервису

Чтобы получить доступ к службе QDOC, вам необходимо представить соответствующий плагин Maven в POM для завершения выпуска QDOC;
Если вы хотите использовать Annotation для написания документации по API, вам потребуется пакет qdoc-annotation для завершения написания;
Введение конкретной зависимости: (плагин Maven)

<plugin>
    <groupId>com.qunar.fd</groupId>
    <artifactId>qdoc-maven-plugin</artifactId>
    <version>${qdoc.maven.version}</version>
</plugin>
QDoc Annotation
 
<dependency>
    <groupId>com.qunar.fd</groupId>
    <artifactId>qdoc-annotation</artifactId>
    <version>${qdoc.annotation.version}</version>
    <scope>provided</scope>
</dependency>

4.3 Синтаксис прост в использовании

Синтаксис QDoc разделен на две части: одна часть — это синтаксис на стороне проекта git, другая часть — это синтаксис на стороне кода API, и эти две части вместе составляют стандартизированный API Qunar.

Грамматика инженерной стороны Git выглядит следующим образом, QDomainDoc и QAPPCodedoc используются таким образом.

Другие аннотации из QDomainDoc и QAPPCodedoc и код API объединяют, но ненавязчивые приложения:

  @QInterfaceDoc(
            type = "dubbo",
            define = "给用户发送短信验证码,dubbo接口",
            desc = "校验手机号是否为用户所有,给用户发送短信验证码",
            scene = "给用户发送短信验证码",
            notice = "内网使用",
            since = "发送短信验证码,产品需求引入",
            authors = "fanrong.zhao",
            url = "dubbo_send"
    )
    @QParamDocs({
            @QParamDoc(name = "paramV1", value = "第一个参数", paramType = "form", dataType = "String", notice = "必须是string类型的", paramExample = "username"),
            @QParamDoc(name = "paramV2", value = "第二个参数", required = false, paramType = "form", dataType = "Boolean", notice = "必须是boolean类型的", paramExample = "true")
    })
    @QResponses({
            @QResponse(code = -1, message = "系统异常"),
            @QResponse(code = 200, message = "成功")
    })
    @QResponseDocs({
            @QResponseDoc(bindValueName = "data", description = "第一个参数", bindValueType = "object", propertys = {
                    @QProperty(type = "String", name = "name", desc = "描述1"),
                    @QProperty(type = "int", name = "age", desc = "描述2"),
                    @QProperty(type = "com.qunar.fd.qdoc.qdocexample.vo.ExampleResultVO",name = "food",desc = "描述3")
            }),
    })
    public ApiResponseV2<Food> example0(@RequestParam String paramV1,@RequestParam boolean paramV2) {
        return null;
    }

По отзывам инженеров Qunar.com, которые уже используют его, написание API через аннотации для API средней сложности занимает всего 5 минут.

4.4 Выполнением легко управлять

Инструмент Qunar.com QDoc в основном поддерживает два метода синхронизации API: синхронизацию команд maven и синхронизацию системы публикации. Синхронизация команд maven с одной стороны может удовлетворить требования Design2doc, а с другой более гибкая, так же наследует наработки Qunar.com в swagger-YAPI Синхронизация через систему публикации - основная работа этого QDoc. Работа в этом направлении решает все проблемы с рассинхронизацией интерфейсов с Мастер-версией, включая создание интерфейсов, обновления, откаты и т.д.

Мы видим, что:

Этапы активации услуги

Открытие системы публикации

В дереве приложений Qunar есть список услуг под соответствующим кодом приложения.В списке услуг [QDoc] нажмите Активация, чтобы завершить активацию интеграции дерева приложений.
Интеграция выпуска CM

В издательской системе Qunar соответствующий appcode открывается через маркет услуг.

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

За три простых шага мы завершили интеграцию QDoc и системы публикации.

4.5 Платформа проста в применении

Перед работой дела, независимо от того, как, если нет взаимодействия хорошая поддержка платформы, то для пользователя тоже очень болезненная, крокодивная система приложений также сложно популярность. Наш окончательный выбор, YAPI встроен в платформу управления приложениями, а AppCode, связанный с управлением, предоставляя менеджерам опыт управления командой One-Stop.

YAPI может обратиться к версии с открытым исходным кодомhellosean1025.github.io/yapi/

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

Конечно, после того, как мы установили систему управления API для измерения домена, мы можем, кстати, предоставить наш API через зрелую систему шлюза Qunar.com:

До сих пор Qunar представила весь процесс от аннотаций API в коде до доменного API открытой платформы с помощью инструмента QDoc.

Итак, с какими трудностями мы столкнулись в проекте?

5 трудностей реализации стандартизации API

1. Откуда берутся ресурсы для развития?

Этот проект инициирован техническим директором по бизнес-исследованиям и разработкам бизнес-группы Qunar.com, занимающейся продажей авиабилетов. Непосредственной команды для поддержки ресурсов нет. Необходимые ресурсы подключаются и разрабатываются через CM, платформу YAPI, разработку инструментов и бизнес. пилотные проекты.В нем участвуют инженеры из всех команд компании.В проекте используется метод управления проектами с открытым исходным кодом внутри компании.Создается проектная команда, создается единый независимый проект, и ресурсы каждой команды объединяются в команда для завершения проекта Завершение проекта также является большой проблемой для руководителей проектов.

2. Сначала проектируйте или сначала кодируйте

В качестве начального этапа проекта невозможно одновременно поддерживать Design First и Code First.В результате исследований мы обнаружили, что Design First больше подходит для разработки интерфейсов, не относящихся к предметной области, таких как интерфейс и интерфейс. внутренний интерфейс совместной отладки Этот вид интерфейса поддержки Он не является универсальным, он будет переработан по мере изменения страницы и обычно не используется повторно. Code First лучше подходит для поддержки высококачественных интерфейсов для долгосрочной поддержки измерения предметной области. Первоначальная цель нашей работы по стандартизации API на этот раз состоит в том, чтобы помочь ремоделировать бизнес DDD, чтобы сделать хорошую работу по стандартизированному обслуживанию интерфейса измерения предметной области. Поэтому мы решили сначала поддерживать метод подготовки интерфейса Code First.

3. Аннотация или комментарии

До того, как мы сделали QDoc, инструменты стандартизации API, которые в определенной степени использовались в компании, включали swagger2.0, swagger3.0 и smart-doc. должно быть более очевидным.Существует больше инженеров, которые используют метод аннотирования smart-doc.Хотя метод аннотирования имеет слишком много аннотаций над кодом API, это вызовет проблему неприглядного кода.Однако, поскольку значительно больше пользователей используют метод аннотаций, мы решили сначала поддерживать QDoc.Метод аннотаций. Это не означает, что QDoc не будет поддерживать комментарии в будущем.

4. Поддержка полной спецификации OpenAPI3.0 или части спецификации OpenAPI3.0.

Эта проблема возникает из-за того, что у нас уже есть довольно зрелая платформа YAPI, исходный код которой мы открыли в 2018 году. Соответствуем ли мы требованиям к интерфейсу YAPI? Должен ли он полностью соответствовать требованиям спецификации OpenAPI3.0, наш ответ отрицательный. Платформа постоянно развивается, у YAPI тоже будут старые времена, когда YAPI состарится, мы также сделаем выбор в других платформах, поддерживающих спецификацию OpenAPi3.0, а knife4j теперь является API в пределах нашего поля зрения.

6 Итоги проекта

DDD и API наконец встречаются. Был получен доступ к основному домену, домену поддержки и API общего домена.

Стандартизация API основного домена эффективно защищает домен от вторжений
API общего домена способствует реализации платформы общего домена.
API домена поддержки сокращает объем разработки

Нет повторения колеса, все формируется по ситуации:

7 Резюме и последующие планы по проекту

Из предыдущего введения мы видим, что конструкция API Qunar иерархична: самый внутренний слой — это API измерения AppCode, внешний слой — измерение бизнес-интерфейса, а внешний слой — измерение домена, которое можно открыть. через шлюз.Интерфейс настроен на открытую платформу, чтобы сформировать управление интерфейсом и использование интерфейса различных размеров.

В последующем необходимо сделать следующие вещи в управлении интерфейсом измерения AppCode:

Завершить плагин соответствия интерфейса IDEA;
поддержка режима аннотации;
Поддержка генерации клиент-серверного кода;
Измерение интерфейса в области исследования: есть ли лучшая альтернатива, чем YAPI, knife4j был в поле зрения;
Более важно то, что благодаря развитию стандартизации API идея DDD может быть обратно продвинута для создания всестороннего и глубокого понимания различных областей бизнеса.

END