orpc-contract-first
Umowy API z typami — implementuj oRPC w frontendu Dify bez błędów
Instalacja
Wybierz klienta i sklonuj repozytorium do odpowiedniego katalogu skilli.
Instalacja
O skillu
Skill do tworzenia i zarządzania kontraktami oRPC w warstwie API frontendu Dify. Automatycznie aktywuje się podczas definiowania nowych umów API, dodawania endpointów serwisów, integracji TanStack Query z typowanymi kontraktami lub migracji starych wywołań serwisów. Wymusza strukturę wejścia {params, query, body}, zagnieżdżanie tras po prefiksach API i import typów bezpośrednio z plików — bez barrel files. Obejmuje wszystkie prace w katalogach web/contract i web/service.
Jak używać
Utwórz nowy plik kontraktu w katalogu web/contract/console/{domena}.ts. Zaimportuj base z ../base oraz type z @orpc/contract, następnie zdefiniuj trasę zawierającą path, method, input i output zgodnie ze schematem {params, query?, body?}.
Zarejestruj kontrakt w pliku web/contract/router.ts, importując go bezpośrednio z pliku domeny (bez barrel files). Zagnieżdż trasę pod odpowiednim prefixem API — na przykład wszystkie trasy /billing/* powinny znaleźć się w obiekcie billing: {}.
Utwórz hook w pliku web/service/use-{domena}.ts, który będzie korzystać z consoleQuery.{grupa}.{kontrakt}.queryKey() do generowania kluczy zapytań oraz consoleClient.{grupa}.{kontrakt}() do wykonywania wywołań API.
Dla parametrów ścieżki użyj notacji {paramName} w polu path i dopasuj je w obiekcie params. Upewnij się, że struktura wejścia zawsze odpowiada formatowi {params, query?, body?}.
Importuj typy z @/types/ i używaj helpera type
() do definiowania typów. Wyeksportuj typ ConsoleInputs z routera, aby zapewnić pełną typizację w całej aplikacji. Jeśli migrujesz stare wywołania serwisów, zastąp je nowymi hookami oRPC i upewnij się, że wszystkie trasy są zagnieżdżone w routerze zgodnie z prefixami API.