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

Привет! Я Никита Щербо, разработчик в компании Битрикс24.

Сегодня поделюсь с вами небольшим кейсом — расскажу, как мы с помощью ИИ нагенерили простых примеров для обучения сотрудников работе с Service Locator.

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

Итак, мы все давно знаем, что ИИ может генерить и код, и тесты, и документацию. У нас была обратная задача — имея код, документацию и тесты, создать простые и понятные примеры использования инструмента.

У меня в команде 30 человек — много новичков, которые пришли к нам из «Битрикс24 // Университет», есть те, кто уже давно работали с Service Locator, но не интересовались тем, как устроен механизм. Мы решили организовать общий митап для команды и показать, как можно использовать это решение в наших задачах.

Но оказалось, что простых и понятных примеров у нас нет. Вытаскивать их из кода внутреннего продукта было нереально — без контекста они не имели смысла.

Тесты для Service Locator, которые мы год назад также писали с ИИ, не были предназначены для чтения человеком, толку от них для новичков не было.

Оставалось одно — скормить ИИ все, что было, и попросить нагенерировать примеров на простых и понятных сущностях, как в учебниках по программированию — машинки, зверюшки и т.д.

Вот как это было:

1. Закинули в нейросеть имеющуюся информацию и объяснили задачу.

Что мы отдали ИИ:

• Папку с кодами самого Service Locator

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

• Набор тестов, который покрывал весь технический функционал Service Locator.

Дальше буквально за несколько итераций мы создали 9 файлов с понятными учебными примерами на каждый случай использования Service Locator. На первом примере ИИ с моими подсказками научился выдавать нужный результат, а все остальные уже генерил самостоятельно.

В результате получили простые примеры, на уровне букваря, на абстрактных, но вполне понятных сущностях — тех самых машинках и зверюшках.

2. С помощью ИИ-агентов собрали реальные примеры для ряда случаев

Здесь понадобились мои знания — я как разработчик, знаю, как Service Locator применяется внутри наших продуктов. Также я использовал наши внутренние инструменты на базе ИИ-агентов. Агенты знают, где какой код лежит, и могут использовать этот контекст. Они помогли найти нужные примеры в исходных кодах нашего продукта.

Реальные примеры я добавил не ко всем случаям — где-то это было избыточно или невозможно.

3. Результат: получили 9 файлов с понятными примерами, которые иллюстрируют все варианты применения Service Locator.

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

Пример с отправкой СМС

Это практически стандартный пример, типовая задача, понятная любому разработчику. Этот пример нейросеть придумала полностью сама, он понятно объясняет, как написать код, который отправляет смс с помощью Service Locator.

Мы в продукте реализуем эту задачу другим способом, но этот пример я оставил для обучения новичков.

// --- 1. Объявление классов --- /** * Класс-конфигурация (Зависимость). * Хранит API ключ, необходимый для работы. */ class ApiKeyConfig { public string $key = 'SECRET_KEY_999'; } /** * Реализация сервиса (SmsSender). * Зависит от ApiKeyConfig, который должен прийти в конструктор. */ class SmsSender { private ApiKeyConfig $config; public function __construct(ApiKeyConfig $config) { $this->config = $config; } public function send(string $msg): void { echo "SMS: '{$msg}' (используя ключ {$this->config->key})" . PHP_EOL; } } // --- 2. Конфигурация ServiceLocator --- $serviceLocator = ServiceLocator::getInstance(); // Регистрируем сервис отправки // В 'constructorParams' явно указываем, что нужно передать в конструктор SmsSender. $serviceLocator->addInstanceLazy(SmsSender::class, [ 'className' => SmsSender::class, 'constructorParams' => [ new ApiKeyConfig(), ], ]); // --- 3. Использование --- // Запрашиваем сервис по интерфейсу. $service = $serviceLocator->get(SmsSender::class); $service->send('Привет, Битрикс!');

Смешанные зависимости

Это один из самых сильных примеров — нейросеть описала в нем самую главную возможность Service Locator, реализацию смешанных зависимостей. Если бы мне нужно было придумать такой пример, пришлось писать бы большое количество кода, придумывать классы, но ИИ все сделал за меня.

// --- 1. Разные типы зависимостей --- // A. Конкретный класс (Локатор создаст сам) class HttpClient { public function getName(): string { return 'CurlClient'; } } // B. Абстрактный класс (Нужна регистрация) abstract class AbstractCache { abstract public function getName(): string; } // Может быть использовано class RedisCache extends AbstractCache { public function getName(): string { return 'Redis'; } } class MemcacheCache extends AbstractCache { public function getName(): string { return 'Memcache'; } } // C. Интерфейс (Нужна регистрация) interface LoggerInterface { public function getName(): string; } class FileLogger implements LoggerInterface { public function getName(): string { return 'FileLog'; } } // D. Главный класс (Локатор создаст сам, подтянув зависимости) class AppManager { public function __construct( public HttpClient $http, // Сам найдет public AbstractCache $cache, // Возьмет из конфига public LoggerInterface $log // Возьмет из конфига ) { } } // --- 2. Конфигурация --- $serviceLocator = ServiceLocator::getInstance(); // Регистрируем ТОЛЬКО абстракции и интерфейсы $serviceLocator->addInstanceLazy(AbstractCache::class, ['className' => MemcacheCache::class]); $serviceLocator->addInstanceLazy(LoggerInterface::class, ['className' => FileLogger::class]); // AppManager и HttpClient регистрировать НЕ НУЖНО. // --- 3. Использование --- $app = $serviceLocator->get(AppManager::class); echo "HTTP: {$app->http->getName()}, Cache: {$app->cache->getName()}, Log: {$app->log->getName()}" . PHP_EOL;

Циклические зависимости

Это распространенная проблема, но и ее важно показать на понятном примере. Тут ИИ, честно сказать, удивил — привел в пример не что-нибудь, а философскую проблему яйца и курицы! Достаточно понятно для любого человека объяснил проблему замкнутого круга.

// --- 1. Классы с циклом --- class Chicken { // Курица зависит от Яйца public function __construct(public Egg $egg) {} } class Egg { // Яйцо зависит от Курицы public function __construct(public Chicken $chicken) {} } // --- 2. Использование --- $serviceLocator = ServiceLocator::getInstance(); try { echo "Пытаемся получить Курицу...\n"; // Мы не регистрируем классы, так как они конкретные. // Локатор начнет создавать Chicken -> увидит Egg -> начнет создавать Egg -> увидит Chicken... // И тут он поймет, что Chicken уже в процессе создания. $chicken = $serviceLocator->get(Chicken::class); } catch (CircularDependencyException $e) { echo "\nПоймано исключение!\n"; echo "Тип ошибки: " . get_class($e) . "\n"; echo "Сообщение: " . $e->getMessage() . "\n"; // Обычно сообщение выглядит так: // "Cyclic dependency detected for service: Chicken -> Egg -> Chicken" }

Что мы получили в итоге

Прежде всего, ИИ помог быстрее сгенерировать примеры — это факт.

Я бы придумал их часа за полтора, но вопрос в качестве — вряд ли они были бы простыми, насущными, как пример с смс или курицей и яйцом. Я давно и безнадежно профдеформирован, для меня простые вещи уже не очевидны, а очевидные — не просты). Я больше усилий потратил бы на поиск действительно понятных примеров на уровне учебника.

Но гораздо интереснее, сколько времени, а главное — нервов, мы сэкономили нашим новичкам. Конечно, можно построчно изучать код продукта и разбираться в работе сервиса в течение нескольких дней. Но лучше действовать последовательно и начинать с простого. Если говорить про онбординг ребят, которые пришли к нам после нашего же Битрикс24//Университет, то им мы сэкономили несколько дней, показав простые примеры использования Service Locator.

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