AIKraft/Skills/orpc-contract-first

orpc-contract-first

Руководство по внедрению паттернов oRPC contract-first в Dify frontend. Полезно при создании контрактов, интеграции TanStack Query, миграции legacy-кода и выборе стратегии вызовов (queryOptions или use-* хуки).

LALangGenius official Разработка ★ 157.9k

Что делает навык

Направляет разработку во 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).

Как работает

  1. Определите контракт в web/contract/console/{domain}.ts или web/contract/marketplace.ts, используя base.route().output().
  2. Добавьте .input(type<...>()) только если есть параметры запроса; для GET без параметров omit .input().
  3. Зарегистрируйте контракт в web/contract/router.ts, группируя по префиксу API (например, billing: {} ).
  4. В UI-компонентах используйте useQuery с consoleQuery.{domain}.{endpoint}.queryOptions(...) для стандартных случаев.
  5. Если 3+ точек вызова имеют одинаковые опции, вынесите их в локальный queryOptions helper, а не создавайте use-* хук.
  6. Для мутаций используйте mutationOptions; при сложной логике применяйте oRPC клиенты как mutationFn.

Примеры запросов агенту

Создай контракт для получения списка счетов в домене billing, используя GET запрос без параметров тела.
Напиши компонент React, который получает данные через consoleQuery.billing.invoices.queryOptions с кастомной select функцией.
Рефактори существующий useQuery хук, заменив его на прямой вызов queryOptions из клиента oRPC.

Что понадобится

  • Репозиторий Dify с доступом к структуре web/contract и web/service.
  • Настроенный TypeScript проект с подключенным TanStack Query.
  • Знание структуры папок web/contract/console и web/contract/marketplace.

Описание составлено по SKILL.md навыка, сверено 08.10.2026.

Как подключить

1Скачать навык
# возьмите папку навыка «orpc-contract-first» из репозитория: # https://github.com/langgenius/dify
2Положить папку с SKILL.md к навыкам ассистента
# положите папку навыка туда, где ассистент ищет skills: cp -r orpc-contract-first/ ~/.claude/skills/orpc-contract-first/

Навык — папка с файлом SKILL.md (описание + инструкции) и опциональными скриптами. Ассистент (Claude, Claude Code и совместимые) подхватывает его по описанию и следует шагам.