A1sCode — 28 дней • День 2: Архитектура A1sCode

Задачи дня

• Понять, зачем библиотека разбита на отдельные модули.
• Усвоить зоны ответственности и границы использования.
• Принять базовые соглашения по именованию функций.
• Разобраться с логированием и обработкой ошибок.
• Собрать минимальный «скелет» проекта с A1sCode.

Картина целиком

• A1sQ — работа с запросами: сборка, параметры, безопасная выгрузка.
• A1sO — операции над значениями и объектами (валидация, структуры).
• A1sS — строки: приведение, разбиение/склейка, очистка.
• A1sLog — логирование событий/ошибок, лаконичные сообщения.
• A1sJ — JSON: сериализация/десериализация, безопасные чтения.
• A1sX — XML: парсинг, выборки, преобразования.
• A1sArrays — операции с массивами: создание, объединение, уникальность.
• A1sLocks — блокировки/семафоры для критических участков.

Идея: маленькие функции с предсказуемыми именами. Минимальные зависимости между модулями.

Слои и границы

• Утилиты (S, O, Arrays) — не обращаются к БД; детерминированные операции.
• Интеграция с платформой (Q, X, J) — аккуратная работа с внешними форматами и СУБД.
• Инфраструктура (Log, Locks) — поперечные функции для всех слоёв.

Рекомендация: бизнес-код вызывает утилиты; доступ к данным изолируем в небольших точках через A1sQ.

Именование функций

• Глагол + Смысл: AsString, NumOrZero, RegexReplace, ToStruct.
• Булевы — читаемо: Empty, NotEmpty, HasKey.
• Без сюрпризов: вход == выход (типы и значения предсказуемы).
• Stable API: не меняем сигнатуры без необходимости; расширяем новыми функциями.

Логи и ошибки

• A1sLog.Info(Источник, Сообщение) — кратко фиксируем важные шаги.
• A1sLog.Warn(Источник, Предупреждение) — крайние случаи, не критично.
• A1sLog.Error(Источник, Ошибка) — фиксируем исключительные ситуации.
• В утилитах — не бросать исключения там, где можно вернуть безопасное значение.

// Пример: обёртка выполнения с логом
Функция ВыполнитьБезопасно(Операция, ОписаниеОперации = "") Экспорт
    Попытка
        Возврат Операция(); // ожидается процедурный объект или лямбда
    Исключение
        A1sLog.Error("Core", "Ошибка: " + ОписаниеОперации + "; " + ОписаниеОшибки());
        Возврат Неопределено;
    КонецПопытки;
КонецФункции
      

Паспорт модуля (YAML в комментариях)

Храним служебные сведения в шапке модуля — удобно для навигации и аудита.

// --- a1s:passport
// id: a1s-q
// name: A1sQ
// owner: Vadim Shchetinkin
// version: 0.9.0
// links:
//   - https://a1scode.ru
//   - https://a1scode.ru/docs/a1sq
// changelog:
//   - 2025-08-27: add ExecuteQSafe
// --- /a1s:passport
      

Скелет проекта с A1sCode

1. Общие модули: подключить A1sQ, A1sO, A1sS, A1sLog, A1sJ, A1sX, A1sArrays, A1sLocks.
2. Sandbox модуль для обучающих примеров и smoke-тестов.
3. Точки доступа к данным: маленькие процедуры, использующие A1sQ.
4. Логирование: A1sLog.Info на ключевых шагах.

// Sandbox: минимальная проверка архитектурного скелета
Процедура SmokeTest() Экспорт
    A1sLog.Info("Smoke", "Старт");

    // 1) Утилиты не зависят от БД
    Результат = A1sS.AsString(A1sO.NumOrZero(Неопределено)); // "0"
    A1sLog.Info("Smoke", "Утилиты OK: " + Результат);

    // 2) Доступ к данным — через A1sQ
    Таб = A1sQ.Unload("ВЫБРАТЬ 1 КАК One");
    A1sLog.Info("Smoke", "Строк: " + Таб.Количество());

    A1sLog.Info("Smoke", "Финиш");
КонецПроцедуры
      

Практика (15–30 минут)

1. Добавьте «паспорт» в один из модулей (как в примере).
2. Создайте SmokeTest() и выполните его.
3. Убедитесь, что логи фиксируются: старт → утилиты → запрос → финиш.
4. Разделите ваш код на «утилиты» и «точки доступа к данным».

Чек-лист

• □ Понимаю роли модулей A1sQ/O/S/Log/J/X/Arrays/Locks.
• □ Принял соглашения по именованию.
• □ Логи подключены и читаемы.
• □ Есть SmokeTest() и «паспорт» в шапке модуля.

Что дальше

Далее — блок по запросам: начнём с безопасной выгрузки и простых выборок.