Loading documentation...
Preparing Ring content
Концепции, ценность и типичные сценарии клонирования — меньше кода.
Концепции, ценность и типичные сценарии клонирования — меньше кода.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Используйте вкладки Основатель / Разработчик в боковой панели документации. Основатели: как валидация защищает бизнес-данные. Разработчики: полный справочник паттернов Zod с примерами из кодовой базы.
Каждый API-вызов к вашему Ring-клону: это контракт. Клиент обещает корректно сформированные данные, сервер обещает обработать их безопасно. Валидация данных: способ Ring Platform обеспечить этот контракт, отклоняя некорректный ввод до того, как он испортит записи, создаст фантомные заказы или обойдёт верификацию платежей.
| Слой | Что ловит | Кто отвечает |
|---|---|---|
| Граница маршрута | Отсутствующие поля, неверные типы, некорректный JSON | Схемы Zod в обработчиках /app/api/** |
| Граница сервиса | Нарушения бизнес-правил (неверная роль, отсутствие владения) | Доменные сервисы в features/*/services/ |
| Граница базы данных | Нарушения ограничений (NOT NULL, UNIQUE, CHECK) | Ограничения PostgreSQL в data/schema.sql |
Каждый слой даёт узкую гарантию. Ни один слой не заменяет остальные.
Без валидации некорректный API-запрос может:
Трёхслойная валидация Ring Platform ловит это до попадания в базу.
Когда вы ringize деплой, вы наследуете валидацию, которая:
RBAC, confidential-тиры, чеклист hardening API и layout-level auth-гейты.
Контракт JSONB-документов, schema.sql SSOT и паттерны DatabaseService.
Верификация HMAC webhook, идемпотентные order references и settlement-потоки.
Конвенции Server Action, паттерны доступа к БД и обработка ошибок.
Используйте вкладки Основатель / Разработчик в боковой панели документации. Основатели: как валидация защищает бизнес-данные. Разработчики: полный справочник паттернов Zod с примерами из кодовой базы.
Каждый API-вызов к вашему Ring-клону: это контракт. Клиент обещает корректно сформированные данные, сервер обещает обработать их безопасно. Валидация данных: способ Ring Platform обеспечить этот контракт, отклоняя некорректный ввод до того, как он испортит записи, создаст фантомные заказы или обойдёт верификацию платежей.
| Слой | Что ловит | Кто отвечает |
|---|---|---|
| Граница маршрута | Отсутствующие поля, неверные типы, некорректный JSON | Схемы Zod в обработчиках /app/api/** |
| Граница сервиса | Нарушения бизнес-правил (неверная роль, отсутствие владения) | Доменные сервисы в features/*/services/ |
| Граница базы данных | Нарушения ограничений (NOT NULL, UNIQUE, CHECK) | Ограничения PostgreSQL в data/schema.sql |
Каждый слой даёт узкую гарантию. Ни один слой не заменяет остальные.
Без валидации некорректный API-запрос может:
Трёхслойная валидация Ring Platform ловит это до попадания в базу.
Когда вы ringize деплой, вы наследуете валидацию, которая:
RBAC, confidential-тиры, чеклист hardening API и layout-level auth-гейты.
Контракт JSONB-документов, schema.sql SSOT и паттерны DatabaseService.
Верификация HMAC webhook, идемпотентные order references и settlement-потоки.
Конвенции Server Action, паттерны доступа к БД и обработка ошибок.
Используйте вкладки Основатель / Разработчик в боковой панели документации. Основатели: как валидация защищает бизнес-данные. Разработчики: полный справочник паттернов Zod с примерами из кодовой базы.
Каждый API-вызов к вашему Ring-клону: это контракт. Клиент обещает корректно сформированные данные, сервер обещает обработать их безопасно. Валидация данных: способ Ring Platform обеспечить этот контракт, отклоняя некорректный ввод до того, как он испортит записи, создаст фантомные заказы или обойдёт верификацию платежей.
| Слой | Что ловит | Кто отвечает |
|---|---|---|
| Граница маршрута | Отсутствующие поля, неверные типы, некорректный JSON | Схемы Zod в обработчиках /app/api/** |
| Граница сервиса | Нарушения бизнес-правил (неверная роль, отсутствие владения) | Доменные сервисы в features/*/services/ |
| Граница базы данных | Нарушения ограничений (NOT NULL, UNIQUE, CHECK) | Ограничения PostgreSQL в data/schema.sql |
Каждый слой даёт узкую гарантию. Ни один слой не заменяет остальные.
Без валидации некорректный API-запрос может:
Трёхслойная валидация Ring Platform ловит это до попадания в базу.
Когда вы ringize деплой, вы наследуете валидацию, которая:
RBAC, confidential-тиры, чеклист hardening API и layout-level auth-гейты.
Контракт JSONB-документов, schema.sql SSOT и паттерны DatabaseService.
Верификация HMAC webhook, идемпотентные order references и settlement-потоки.
Конвенции Server Action, паттерны доступа к БД и обработка ошибок.
Атакующий шлёт поддельный webhook «payment completed». Ring сначала валидирует HMAC-подпись: при несовпадении webhook отклоняется до изменения статуса заказа.
Валидация: не только забота разработчика. Она напрямую защищает выручку, доверие пользователей и compliance-позу. Каждый Ring-клон поставляет эти гарды включёнными по умолчанию.
Никогда не используйте body as any, чтобы обойти TypeScript при вызове сервисных функций. Если сервис ожидает конкретный тип, создайте схему Zod, которая валидирует форму, затем приведите валидированный вывод: parsed.data as Parameters<typeof service>[0]. Валидация Zod делает приведение безопасным.
Платёжные webhook (WayForPay, Stripe) приходят в разных форматах. z.preprocess нормализует сырое тело до валидации, но для HMAC-верифицированных webhook никогда не трансформируйте значения (HMAC использует Object.values() на сыром payload):
Для webhook с несколькими wire-форматами (например Web Vitals metrics) z.preprocess может нормализовать в каноническую форму:
Когда правила зависят от значений полей (например, требования к metadata различаются по типу conversation), используйте superRefine:
Для больших TypeScript enums (например NotificationType с 27 значениями) извлекайте значения в runtime для Zod:
Маршруты аналитики используют Next.js 16 after(), чтобы ответить сразу, пока записи в БД идут в фоне. Это убирает ~50 мс блокирующей задержки на каждый analytics-вызов:
Обработка платёжных webhook сочетает валидацию формы Zod с верификацией HMAC-подписи:
Zod гарантирует, что payload содержит обязательные поля (orderReference, merchantSignature, amount и т.д.) до любой обработки.
Пересчитайте HMAC-MD5 из значений payload с помощью merchant secret key. Сравните с merchantSignature. При несовпадении отклоните.
Разберите префикс orderReference, чтобы определить тип заказа (store, membership, news promotion) и направить в нужный обработчик.
Обработчики проверяют существующий статус заказа до обновления: дублирующие webhook безопасно игнорируются.
Все маршруты /api/mcp/v1/* используют схемы Zod с .passthrough() для прямой совместимости. Это позволяет MCP-клиентам слать дополнительные поля без поломки, при этом обязательные поля всё равно валидируются:
| Анти-паттерн | Почему опасно | Замена |
|---|---|---|
body as any | Обходит всю проверку типов | Zod safeParse + типизированный вывод |
Ручные цепочки if | Легко пропустить крайние случаи | Один вызов schema.safeParse() |
| Мутация parsed body | Побочные эффекты ломают предсказуемость | Spread в новый объект |
| Нет валидации на маршруте | Сервис получает мусор | Zod на границе маршрута |
as Record<string, unknown> при чтении БД | Скрывает несовпадения типов | schema.safeParse(dbResult.data) |
Сессии Auth.js v5, role enum SSOT и multi-provider setup.
Атакующий шлёт поддельный webhook «payment completed». Ring сначала валидирует HMAC-подпись: при несовпадении webhook отклоняется до изменения статуса заказа.
Валидация: не только забота разработчика. Она напрямую защищает выручку, доверие пользователей и compliance-позу. Каждый Ring-клон поставляет эти гарды включёнными по умолчанию.
Никогда не используйте body as any, чтобы обойти TypeScript при вызове сервисных функций. Если сервис ожидает конкретный тип, создайте схему Zod, которая валидирует форму, затем приведите валидированный вывод: parsed.data as Parameters<typeof service>[0]. Валидация Zod делает приведение безопасным.
Платёжные webhook (WayForPay, Stripe) приходят в разных форматах. z.preprocess нормализует сырое тело до валидации, но для HMAC-верифицированных webhook никогда не трансформируйте значения (HMAC использует Object.values() на сыром payload):
Для webhook с несколькими wire-форматами (например Web Vitals metrics) z.preprocess может нормализовать в каноническую форму:
Когда правила зависят от значений полей (например, требования к metadata различаются по типу conversation), используйте superRefine:
Для больших TypeScript enums (например NotificationType с 27 значениями) извлекайте значения в runtime для Zod:
Маршруты аналитики используют Next.js 16 after(), чтобы ответить сразу, пока записи в БД идут в фоне. Это убирает ~50 мс блокирующей задержки на каждый analytics-вызов:
Обработка платёжных webhook сочетает валидацию формы Zod с верификацией HMAC-подписи:
Zod гарантирует, что payload содержит обязательные поля (orderReference, merchantSignature, amount и т.д.) до любой обработки.
Пересчитайте HMAC-MD5 из значений payload с помощью merchant secret key. Сравните с merchantSignature. При несовпадении отклоните.
Разберите префикс orderReference, чтобы определить тип заказа (store, membership, news promotion) и направить в нужный обработчик.
Обработчики проверяют существующий статус заказа до обновления: дублирующие webhook безопасно игнорируются.
Все маршруты /api/mcp/v1/* используют схемы Zod с .passthrough() для прямой совместимости. Это позволяет MCP-клиентам слать дополнительные поля без поломки, при этом обязательные поля всё равно валидируются:
| Анти-паттерн | Почему опасно | Замена |
|---|---|---|
body as any | Обходит всю проверку типов | Zod safeParse + типизированный вывод |
Ручные цепочки if | Легко пропустить крайние случаи | Один вызов schema.safeParse() |
| Мутация parsed body | Побочные эффекты ломают предсказуемость | Spread в новый объект |
| Нет валидации на маршруте | Сервис получает мусор | Zod на границе маршрута |
as Record<string, unknown> при чтении БД | Скрывает несовпадения типов | schema.safeParse(dbResult.data) |
Сессии Auth.js v5, role enum SSOT и multi-provider setup.
Атакующий шлёт поддельный webhook «payment completed». Ring сначала валидирует HMAC-подпись: при несовпадении webhook отклоняется до изменения статуса заказа.
Валидация: не только забота разработчика. Она напрямую защищает выручку, доверие пользователей и compliance-позу. Каждый Ring-клон поставляет эти гарды включёнными по умолчанию.
Никогда не используйте body as any, чтобы обойти TypeScript при вызове сервисных функций. Если сервис ожидает конкретный тип, создайте схему Zod, которая валидирует форму, затем приведите валидированный вывод: parsed.data as Parameters<typeof service>[0]. Валидация Zod делает приведение безопасным.
Платёжные webhook (WayForPay, Stripe) приходят в разных форматах. z.preprocess нормализует сырое тело до валидации, но для HMAC-верифицированных webhook никогда не трансформируйте значения (HMAC использует Object.values() на сыром payload):
Для webhook с несколькими wire-форматами (например Web Vitals metrics) z.preprocess может нормализовать в каноническую форму:
Когда правила зависят от значений полей (например, требования к metadata различаются по типу conversation), используйте superRefine:
Для больших TypeScript enums (например NotificationType с 27 значениями) извлекайте значения в runtime для Zod:
Маршруты аналитики используют Next.js 16 after(), чтобы ответить сразу, пока записи в БД идут в фоне. Это убирает ~50 мс блокирующей задержки на каждый analytics-вызов:
Обработка платёжных webhook сочетает валидацию формы Zod с верификацией HMAC-подписи:
Zod гарантирует, что payload содержит обязательные поля (orderReference, merchantSignature, amount и т.д.) до любой обработки.
Пересчитайте HMAC-MD5 из значений payload с помощью merchant secret key. Сравните с merchantSignature. При несовпадении отклоните.
Разберите префикс orderReference, чтобы определить тип заказа (store, membership, news promotion) и направить в нужный обработчик.
Обработчики проверяют существующий статус заказа до обновления: дублирующие webhook безопасно игнорируются.
Все маршруты /api/mcp/v1/* используют схемы Zod с .passthrough() для прямой совместимости. Это позволяет MCP-клиентам слать дополнительные поля без поломки, при этом обязательные поля всё равно валидируются:
| Анти-паттерн | Почему опасно | Замена |
|---|---|---|
body as any | Обходит всю проверку типов | Zod safeParse + типизированный вывод |
Ручные цепочки if | Легко пропустить крайние случаи | Один вызов schema.safeParse() |
| Мутация parsed body | Побочные эффекты ломают предсказуемость | Spread в новый объект |
| Нет валидации на маршруте | Сервис получает мусор | Zod на границе маршрута |
as Record<string, unknown> при чтении БД | Скрывает несовпадения типов | schema.safeParse(dbResult.data) |
Сессии Auth.js v5, role enum SSOT и multi-provider setup.