orpc-contract-first
Руководство по внедрению паттернов oRPC contract-first в Dify frontend. Полезно при создании контрактов, интеграции TanStack Query, миграции legacy-кода и выборе стратегии вызовов (queryOptions или use-* хуки).
Что делает навык
Направляет разработку во frontend-части Dify, обеспечивая подход oRPC contract-first, где контракт в web/contract/* является единственным источником истины. Оптимизирует использование TanStack Query, минимизируя абстракции и сохраняя строгую типизацию TypeScript. Помогает выбирать между direct queryOptions, вспомогательными хелперами и кастомными use-* хуками в зависимости от сложности сценария.
Когда применять
- Создание новых контрактов API в директории web/contract с правильной структурой input/output.
- Интеграция запросов в UI через consoleQuery или marketplaceQuery с использованием queryOptions.
- Миграция legacy-кода на использование стандартных паттернов oRPC без создания лишних обёрток.
- Выбор стратегии вызовов: определение, когда использовать queryOptions напрямую, а когда создавать helper для общих опций.
- Настройка инвалидации кэша и управления состоянием мутаций с использованием правильных ключей (.key vs .queryKey).
Как работает
- Определите контракт в web/contract/console/{domain}.ts или web/contract/marketplace.ts, используя base.route().output().
- Добавьте .input(type<...>()) только если есть параметры запроса; для GET без параметров omit .input().
- Зарегистрируйте контракт в web/contract/router.ts, группируя по префиксу API (например, billing: {} ).
- В UI-компонентах используйте useQuery с consoleQuery.{domain}.{endpoint}.queryOptions(...) для стандартных случаев.
- Если 3+ точек вызова имеют одинаковые опции, вынесите их в локальный queryOptions helper, а не создавайте use-* хук.
- Для мутаций используйте mutationOptions; при сложной логике применяйте oRPC клиенты как mutationFn.
Примеры запросов агенту
Что понадобится
- Репозиторий Dify с доступом к структуре web/contract и web/service.
- Настроенный TypeScript проект с подключенным TanStack Query.
- Знание структуры папок web/contract/console и web/contract/marketplace.
Описание составлено по SKILL.md навыка, сверено 08.10.2026.
Как подключить
SKILL.md к навыкам ассистентаНавык — папка с файлом SKILL.md (описание + инструкции) и опциональными скриптами. Ассистент (Claude, Claude Code и совместимые) подхватывает его по описанию и следует шагам.