From 605a40752a32ea2d7d45fd89e78fbf2cb7a802d4 Mon Sep 17 00:00:00 2001 From: Nik Samokhvalov <nik@samokhvalov.info> Date: Fri, 15 Dec 2017 18:36:13 +0300 Subject: [PATCH] Manual about agents --- docs/ru/agent.md | 76 ++++++++++++++++++++++++++++++++++++++++ src/Agent/AgentTrait.php | 4 +-- 2 files changed, 78 insertions(+), 2 deletions(-) diff --git a/docs/ru/agent.md b/docs/ru/agent.md index e69de29..ae36ee5 100644 --- a/docs/ru/agent.md +++ b/docs/ru/agent.md @@ -0,0 +1,76 @@ +# Агенты + +Тяжеловесные или отложенные операции на сайте удобно выполнять в фоновом режиме, иногда с определённой периодичностью, +иногда практически моментально. Помочь в этом может [система очередей](http://ruhighload.com/index.php/2009/05/15/%D0%BE%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C-%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B9-%D1%87%D1%82%D0%BE-%D1%8D%D1%82%D0%BE-%D0%B8-%D0%B7%D0%B0%D1%87%D0%B5%D0%BC/). +Но в некоторых случаях, когда не требуется шардирование и отказоустойчивость подсистемы выполнения отложенных операций, +можно воспользоваться штатной технологией «Битрикса» — [агентами](http://dev.1c-bitrix.ru/learning/course/?COURSE_ID=43&LESSON_ID=3436). +К сожалению, эта технология имеет сырое API, но Console Jedi предоставляет свой API, покрывающий весь цикл работы с агентами. + +## Жизненный цикл + +### Настройка + +Переведите [выполнение агентов на cron](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=2943&LESSON_PATH=3913.4776.4620.4978.2943), +если ещё не сделали этого. В Console Jedi этот процесс автоматизирован, поэтому, в отличии от официального руководства, +достаточно выполнить команду: + +```bash +vendor/bin/jedi agent:on-cron +``` + +### Создание + +PHP-класс агента либо должен наследовать класс `\Notamedia\ConsoleJedi\Agent\Agent`, либо подключать трейт +`\Notamedia\ConsoleJedi\Agent\AgentTrait`, позволяющие объекту класса работать в режиме агента. + +Вот и всё, больше не требуется никаких операций. И самое главное — не нужно создавать в классе статичные методы, как это +рекомендует официальная документация «Битрикса», — Console Jedi умеет превращать объекты (с конструктором и публичными +нестатичными методами) в формат, ожидаемый «Битриксом». + +### Регистрация + +В момент, когда потребуется зарегистрировать в «Битриксе» новый агент, воспользуйтесь специальным строителем +`\Notamedia\ConsoleJedi\Agent\AgentTask`. + +Давайте зарегистрируем агент модуля `vasya.tester`, при выполнении которого будет создаваться объект `TestAgent` с аргументами `arg1` +(строка) и `true` (булевый тип) и вызываться метод объекта `execute` с аргументом `100500` (строка): + +```php +use Notamedia\ConsoleJedi\Agent\AgentTask; +use Vendor\Module\TestAgent; + +AgentTask::builder() + ->setClass(TestAgent::class) + ->setConstructorArgs(['arg1', true]) + ->setCallChain([ + ['execute' => [100500]] + ]), + ->setModule('vasya.tester') + ->create(); +``` + +> За подробным описанием методов строителя агентов обратитесь к PHPDoc-комментариям в классе `AgentTask`. + +### Выполнение + +Добавьте в `crontab` вызов команды, которая производит выполнение готовых к работе агентов: + +```bash +vendor/bin/jedi agent:execute +``` + +## Продление жизни агента + +Если время выполнения агента превышает 10 минут, необходимо периодически в процессе его работы выполнять пинг, чтобы +«Битрикс» не считал его зависшим. Например: + +```php +public function execute($param1) +{ + // Начало выполнения тяжёлых операций + + $this->pingAgent(20, ['execute' => [$param1]]); + + // Завершение выполнения +} +``` \ No newline at end of file diff --git a/src/Agent/AgentTrait.php b/src/Agent/AgentTrait.php index 2a266b6..b046895 100644 --- a/src/Agent/AgentTrait.php +++ b/src/Agent/AgentTrait.php @@ -77,7 +77,7 @@ public static function agent() * { * // start a heavy (big) cycle * - * $this->pingAgent(20, ['executeAgent => [$param1, $param2]]); + * $this->pingAgent(20, ['executeAgent' => [$param1, $param2]]); * * // end of cycle * } @@ -119,7 +119,7 @@ protected function pingAgent($interval, array $callChain) * { * // main logic * - * return $this->getAgentName(['executeAgent => [$param1, $param2]]); + * return $this->getAgentName(['executeAgent' => [$param1, $param2]]); * } * ``` *