# Backend Версия источника: 4880e8b4372c96001c2e052be28b68a95d31252b Синхронизировано: 2026-11-09T11:15:07.649Z Источник: https://github.com/sergey-from-riders/vibecoding-base/tree/4880e8b4372c96001c2e052be28b68a95d31252b ## Оглавление - [Границы backend](#backend-boundaries) - [Go context](#backend-go-context) - [Обработка ошибок](#backend-errors) - [Ограничение параллелизма](#backend-bounded-concurrency) - [Async I/O](#backend-async) - [Валидация типов](#backend-typed-boundaries) - [Читаемость кода](#backend-readable-code) # Границы backend ## Коротко Обработчик переводит запрос в вызов приложения, а доменная логика остаётся переиспользуемой. ## Плохо ```text HTTP-обработчик сам считает скидку, делает SQL и отправляет письмо. ``` ## Хорошо ```text Обработчик → сервис заказа → хранилище. Отправка связана с сохранённым событием. ``` ## Почему Логику можно проверять без запуска HTTP и повторно использовать в worker. ## Когда применять Это инженерное правило справочника, а не требование протокола. Первоисточник описывает подход или механизм; конкретный процесс выбирается проектом. Количество слоёв соразмерно задаче. Требование ровно одного вызова сервиса не является свойством Go. ## Как проверить - Можно ли проверить правило скидки отдельно от сети? ## Человек Определяет бизнес-правила и границы ответственности сервисов. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Можно ли проверить правило скидки отдельно от сети? ## Источники - [Organizing a Go module - The Go Programming Language](https://go.dev/doc/modules/layout) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/go/rules/boundaries.md) --- # Go context ## Коротко Запрос к БД или внешнему сервису должен завершаться при отмене родительской работы. ## Плохо ```go // В HTTP-обработчике: срок запроса потерян. ctx := context.Background() err := db.QueryRowContext(ctx, query, orderID).Scan(&title) if err != nil { return err } ``` ## Хорошо ```go ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second) defer cancel() err := db.QueryRowContext(ctx, query, orderID).Scan(&title) if err != nil { return err } ``` ## Почему Зависшие операции занимают соединения и ресурсы. ## Когда применять Фрагмент функции, возвращающей error: db — *sql.DB, r — *http.Request, query — параметризованный SELECT одной строки. Две секунды — пример, а не норматив. В Go передавайте context явно; фоновая задача должна иметь собственного владельца и срок жизни. ## Как проверить - Отмените запрос и проверьте завершение зависимых операций. ## Человек Задаёт бюджет времени запроса и правила отмены работы. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Отмените запрос и проверьте завершение зависимых операций. ## Источники - [Canceling in-progress operations - The Go Programming Language](https://go.dev/doc/database/cancel-operations) - [sql package - database/sql - Go Packages](https://pkg.go.dev/database/sql#Rows) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/go/rules/go-context.md) --- # Обработка ошибок ## Коротко Сохраняйте причину ошибки внутри системы и возвращайте безопасное объяснение наружу. ## Плохо ```go func persist(order Order) (*Order, error) { result, _ := saveOrder(order) return result, nil } ``` ## Хорошо ```go func persist(order Order) (*Order, error) { result, err := saveOrder(order) if err != nil { return nil, fmt.Errorf("save order: %w", err) } return result, nil } ``` ## Почему Игнорирование ошибки создаёт ложный успех. ## Когда применять Не используйте panic для ожидаемой ошибки запроса. Преобразование внутренних причин в HTTP выполняется на границе. ## Как проверить - Сбой хранилища не возвращает успешный ответ? ## Человек Определяет, какие ошибки можно показать пользователю и когда нужна эскалация. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Сбой хранилища не возвращает успешный ответ? ## Источники - [Working with Errors in Go 1.13 - The Go Programming Language](https://go.dev/blog/go1.13-errors) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/go/rules/errors.md) --- # Ограничение параллелизма ## Коротко Каждая запущенная задача должна иметь предел, отмену и понятное завершение. ## Плохо ```text На каждый файл запускается новая goroutine без лимита. ``` ## Хорошо ```text Очередь с ограничением размера. Пул работников. Отмена и ожидание завершения. ``` ## Почему Неограниченная параллельность может исчерпать память и соединения. ## Когда применять Размер пула выбирают измерением. Для общего изменяемого состояния нужны синхронизация и race-проверка. ## Как проверить - Проверьте всплеск нагрузки, остановку и утечку goroutine. ## Человек Задаёт допустимую нагрузку и приоритеты задач. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Проверьте всплеск нагрузки, остановку и утечку goroutine. ## Источники - [Effective Go - The Go Programming Language](https://go.dev/doc/effective_go#channels) - [Data Race Detector - The Go Programming Language](https://go.dev/doc/articles/race_detector) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/go/rules/bounded-concurrency.md) --- # Async I/O ## Коротко В async-коде используйте асинхронный ввод-вывод или выносите блокирующую работу. ## Плохо ```python async def handler(): time.sleep(5) ``` ## Хорошо ```python async def handler(): await asyncio.sleep(5) ``` ## Почему Один блокирующий вызов может задержать другие запросы процесса. ## Когда применять Для Python asyncio. CPU-задачи обычно требуют процессов или выделенного worker; to_thread не делает произвольную CPU-работу параллельной в обычной сборке с GIL. ## Как проверить - Параллельный лёгкий запрос остаётся отзывчивым? ## Человек Определяет требования к задержке и пропускной способности. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Параллельный лёгкий запрос остаётся отзывчивым? ## Источники - [Coroutines and tasks — Python 3.14.10 documentation](https://docs.python.org/3.14/library/asyncio-task.html) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/python/rules/async.md) --- # Валидация типов ## Коротко Типы помогают разработчику, а проверка входа защищает работающую систему. ## Плохо ```text quantity = payload["quantity"] charge(quantity * price) ``` ## Хорошо ```text quantity = validated_request.quantity # Целое число в разрешённом диапазоне. ``` ## Почему Аннотация типа сама по себе не проверяет входящий JSON. ## Когда применять Для Python/FastAPI подходят модели Pydantic; конкретная версия фиксируется зависимостями проекта. ## Как проверить - Проверьте строку, отрицательное число и слишком большое значение. ## Человек Определяет допустимые значения и поведение при неверном вводе. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Проверьте строку, отрицательное число и слишком большое значение. ## Источники - [Models](https://docs.pydantic.dev/latest/concepts/models/) - [Request Body - FastAPI](https://fastapi.tiangolo.com/tutorial/body/) Уровень: Обязательно. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/python/rules/typed-boundaries.md) --- # Читаемость кода ## Коротко Разделяйте независимые обязанности и сохраняйте объяснения неочевидных решений. ## Плохо ```text Удалить полезные комментарии, чтобы уложиться в 5%. ``` ## Хорошо ```text Разделить независимые задачи. Оставить комментарий о причине ограничения. ``` ## Почему Формальный лимит строк не доказывает простоту программы. ## Когда применять Порог сложности может быть локальным сигналом ревью. Размер файла и доля комментариев не универсальные стандарты. ## Как проверить - Можно ли назвать одну ответственность модуля и объяснить его зависимости? ## Человек Проверяет понятность бизнес-смысла и согласует существенные изменения архитектуры. ## Агент Реализует правило в коде сервиса и проверяет ошибку, отмену и граничные входные данные. Контроль результата: - Можно ли назвать одну ответственность модуля и объяснить его зависимости? ## Источники - [Effective Go - The Go Programming Language](https://go.dev/doc/effective_go) Уровень: Рекомендуется. Проверено: 2026-11-09. Изменено: 2026-11-09. [Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/4880e8b4372c96001c2e052be28b68a95d31252b/registry/standards/backend/python/rules/readable-code.md)