Errors

---
name: errors
description: "Паттерны обработки исключений, транзакций и блокировок 1С - канонический паттерн транзакции, БлокировкаДанных, ТранзакцияАктивна, логирование, deadlock. Используй при написании кода с записью данных, транзакциями, Попытка/Исключение, блокировками и обработкой ошибок в массовой записи (цикл записи объектов)."
---

# Обработка ошибок, транзакции и блокировки

> Нормы кода — в `.claude/rules/1c-rules.md` (единственный источник правил).
> Здесь — развёрнутые паттерны и примеры «как именно».

## Приоритеты

🔴 КРИТИЧНО (нарушение = потеря данных): канонический паттерн транзакций; проверка ТранзакцияАктивна(); не гасить исключения бесследно (логировать при окончательной обработке или когда нужна диагностика).
🟡 ВАЖНО (нарушение = блокировки/производительность): минимизация времени транзакции; БлокировкаДанных перед чтением; единый порядок блокировки.
🟢 РЕКОМЕНДУЕТСЯ: структурированное логирование; понятные сообщения пользователю; поэлементная обработка массовых операций.

---

## ШАБЛОНЫ КОДА (копируй и адаптируй)

### Шаблон 1: Канонический паттерн транзакции
```bsl
НачатьТранзакцию();
Попытка
    // 1. Блокировка (если нужна)
    Блокировка = Новый БлокировкаДанных;
    ЭлементБлокировки = Блокировка.Добавить("Документ.Название");
    ЭлементБлокировки.УстановитьЗначение("Ссылка", СсылкаНаДокумент);
    Блокировка.Заблокировать();
    
    // 2. Операции с данными
    ДокументОбъект = СсылкаНаДокумент.ПолучитьОбъект();
    ДокументОбъект.Записать();
    
    // 3. Фиксация - ПОСЛЕДНЯЯ операция
    ЗафиксироватьТранзакцию();
Исключение
    // 4. Откат - ПЕРВАЯ операция в блоке Исключение
    ОтменитьТранзакцию();
    
    // 5. Логирование ПОСЛЕ отката
    ЗаписьЖурналаРегистрации(
        НСтр("ru = 'Операция'"),
        УровеньЖурналаРегистрации.Ошибка,
        Метаданные.Документы.Название,
        СсылкаНаДокумент,
        ОбработкаОшибок.ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()));
    
    ВызватьИсключение;
КонецПопытки;
```

### Шаблон 2: Обработка исключения с логированием
```bsl
Попытка
    // Опасная операция
    ВыполнитьОперацию();
Исключение
    ИнформацияОбОшибке = ИнформацияОбОшибке();
    
    ЗаписьЖурналаРегистрации(
        НСтр("ru = 'Имя события'"),
        УровеньЖурналаРегистрации.Ошибка,
        Метаданные.Объекта,
        СсылкаНаОбъект,
        ОбработкаОшибок.ПодробноеПредставлениеОшибки(ИнформацияОбОшибке));
    
    ВызватьИсключение; // Пробрасываем дальше
КонецПопытки;
```

### Шаблон 3: Блокировка данных перед чтением
```bsl
НачатьТранзакцию();
Попытка
    // СНАЧАЛА блокируем
    Блокировка = Новый БлокировкаДанных;
    ЭлементБлокировки = Блокировка.Добавить("РегистрНакопления.Название");
    ЭлементБлокировки.УстановитьЗначение("Измерение", Значение);
    ЭлементБлокировки.Режим = РежимБлокировкиДанных.Исключительный;
    Блокировка.Заблокировать();
    
    // ПОТОМ читаем
    Запрос = Новый Запрос("ВЫБРАТЬ ...");
    Результат = Запрос.Выполнить();
    
    // Обрабатываем и записываем
    // ...
    
    ЗафиксироватьТранзакцию();
Исключение
    ОтменитьТранзакцию();
    ЗаписьЖурналаРегистрации(...);
    ВызватьИсключение;
КонецПопытки;
```

---

## Подробные паттерны (reference)

**Не загружаются автоматически — открой нужный файл инструментом Read по теме задачи.**

| Тема | Файл |
|---|---|
| Транзакции: канонический паттерн, вложенные (ТранзакцияАктивна), минимизация времени, обработчики событий объекта | `references/transactions.md` |
| Блокировки: БлокировкаДанных, ЗаблокироватьДанныеДляРедактирования, таймауты и deadlock | `references/locks.md` |
| Исключения: Попытка/Исключение (логирование), ВызватьИсключение, массовые операции, внешние вызовы | `references/exceptions.md` |
| Логирование и сообщения пользователю: ЗаписьЖурналаРегистрации, формирование текста ошибки | `references/logging.md` |

---

## Чек-лист транзакций и обработки ошибок

Дополнение к общему «Чек-листу проверки кода» из `.claude/rules/1c-rules.md` — детализация для транзакций и исключений:

Используй этот список для проверки кода с транзакциями и обработкой ошибок:

### Транзакции
- [ ] `НачатьТранзакцию()` стоит НЕПОСРЕДСТВЕННО перед `Попытка`
- [ ] `ЗафиксироватьТранзакцию()` - ПОСЛЕДНЯЯ операция перед `Исключение`
- [ ] `ОтменитьТранзакцию()` - ПЕРВАЯ операция в блоке `Исключение`
- [ ] Логирование идёт ПОСЛЕ `ОтменитьТранзакцию()`
- [ ] Нет кода между `ЗафиксироватьТранзакцию()` и концом `Попытка`

### Обработка исключений
- [ ] Логирование — при окончательной обработке или когда нужна доп. диагностика; одно исключение не логируется повторно на разных уровнях
- [ ] Используется `ОбработкаОшибок.ПодробноеПредставлениеОшибки()` для журнала
- [ ] Используется `ОбработкаОшибок.КраткоеПредставлениеОшибки()` для пользователя
- [ ] Исключение либо пробрасывается (`ВызватьИсключение`), либо возвращается статус
- [ ] Нет "проглоченных" исключений (пустой блок `Исключение`)

### Блокировки
- [ ] `БлокировкаДанных` устанавливается ПЕРЕД чтением данных
- [ ] Используется `ЕСТЬNULL()` при работе с результатами LEFT JOIN
- [ ] Блокировки устанавливаются в едином порядке (по возрастанию ссылок)
- [ ] Время транзакции минимизировано (нет долгих операций внутри)

### Массовые операции
- [ ] Ошибка в одном элементе не останавливает обработку остальных
- [ ] Каждая ошибка логируется отдельно
- [ ] Есть итоговый отчёт об ошибках для пользователя

---