Регламент именования правил Phiremock

phiremock_rules_naming_protocol.md

Регламент именования правил Phiremock

Уровень 1: сервис

Следует кратко указать имя сервиса в имени раздела.

Например, https://partners.delivery-club.ru это партнёрское API Delivery Club. Значит папка будет называться partners_delivery_club.

Запрещено указывать URL сервиса, т.к. он может значительно различаться между prod, stage, dev версиями проекта, а также может со временем меняться.

Запрещено указывать api, т.к. любой сервис это итак API.

Все правила, относящиеся к конкретному сервису, должны содержать соответствующий префикс в URL правила в request.url.matches или request.url.isEqualTo.

Например, в правиле POST_orders_dryRun.json будет

{
  "request": {
    "method": "POST",
    "url": {
      "isEqualTo": "/partners_delivery_club/orders/dryRun"
    }
  }
}

Уровень 2: группа запросов

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

Например, order, а внутри — запросы создания заказа, получения списка заказов, получения информации по одному заказу.

Сложность заключается в том, что критерием объединения endpoint могут быть разные признаки.

Например, запросы товаров и стоп-листа можно объединить в группу menu, если ориентироваться на критерий формирования доступного к заказу объёма ассортимента.

Рекомендуется объединять запросы в одну группу на основании схожести пути. Например, /orders/dryRun и /orders/feed начинаются с orders.

При большом количестве похожих запросов или вариантов правил можно создавать вложенные группы.

В имени группы следует использовать плейсхолдеры также, как и в имени правила(см. уровень 4).

Proxy

Proxy-правила(т.е. правила, которые делают редирект запроса на другой внешний сервис) должны объединяться отдельной категорией proxy на подходящем уровне.

Например, если делается proxy каких-то запросов к заказам orders, то proxy должен быть внутри orders.

Уровень 3: правило запроса

Следует указать HTTP-метод и полный путь в имени JSON-файла.

• HTTP-метод указывается заглавными буквами;
• слеш / заменяется на _;
• плейсхолдеры должны заключаться в %;
• camelCase не изменяется.

Например,

POST /orders/dryRun/ —> POST_orders_dryRun.json GET /orders/{orderUuid} -> GET_orders_%orderUuid%.json

Полный путь может дублироваться с группами запросов(см. уровень 2). Например, /partners_delivery_club/orders/POST_orders_dryRun.json. Однако не следует убирать "orders" из имени правила: оно всегда должно полностью описывать метод, в какой бы категории не находилось.

Уровень 4: приоритет правила

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

Например,

GET_orders_%orderUuid%__060__not_found.json
GET_orders_%orderUuid%__070__cancelled.json
GET_orders_%orderUuid%__080__delivered.json
GET_orders_%orderUuid%__090__picked_up.json
GET_orders_%orderUuid%__100__confirmed.json

Уровень 5: вариант запроса

Следует кратко указать в качестве суффикса вариант запроса после двойного подчёркивания __ в имени JSON-файла. Если есть приоритет правила, то вариант запроса всегда должен идти после него(см. пример для уровня 4).

Например, POST /orders/dryRun, который реализует вариант с недоступным товаром 3010, может быть назван POST_orders_dryRun__unavailable_offer_3010.json