SDK / kontrakty i rozszerzenia

Integruję narzędzie przez kontrakty

Chcesz, aby Twoje narzędzie rozumiało dokumenty wytwarzane przez Junexis. Zacznij od jednego dokumentu, jego wersji i wskazanego schematu. Nie trzeba implementować dostawcy Storage ani odczytywać wszystkich formatów platformy.

1. Wybierz producenta i odbiorcę

Przykład dokumentu	Kto go wytwarza?	Kto go odczytuje?
Manifest dostawcy	Autor dostawcy lub generator SDK	Walidator, zestaw zgodności i narzędzia obsługujące dostawców
Raport zgodności	Narzędzie SDK	Automatyzacja autora oraz mechanizm publikacji dostawcy
Metadane Registry	Registry	Klient paczek lub dostawców
Plan aktualizacji	Narzędzie cyklu życia instalacji	Narzędzie prezentujące albo wykonujące obsługiwany plan

Każdy format ma odrębny kontrakt. Prawidłowy manifest dostawcy nie jest poprawnym manifestem pakietu aplikacyjnego.

2. Odczytaj rzeczywisty manifest

Poniżej dokument wygenerowany dla pierwszego dostawcy. Wskazuje wersję kontraktu, tożsamość, publiczną paczkę, ABI i zdolności:

{
  "schemaVersion": "junexis.provider/0.1",
  "id": "Junexis.Example.Memory",
  "version": "0.1.0",
  "abiVersion": "junexis.storage.runtime/0.1",
  "factoryType": "Junexis.Example.Memory.MemoryStorageProvider",
  "resourceKind": "storage",
  "capabilities": [
    "read",
    "write",
    "health"
  ],
  "sdk": {
    "packageId": "Junexis.Storage.Runtime.Abstractions",
    "version": "0.1.0"
  },
  "artifact": {
    "assembly": "Junexis.Example.Memory.dll",
    "targetFramework": "net10.0"
  }
}

Otwórz dokument JSON · Otwórz schemat 0.1

Ten dokument opisuje tylko dostawcę. Nie zawiera jego haseł ani konfiguracji połączenia z bazą. Zdolności read, write, health deklarują zakres, który trzeba potwierdzić oddzielną próbą.

3. Zweryfikuj strukturę przed odczytem

Dokument JSON→Wersja kontraktu→Właściwy schemat→Odczyt obsługiwanych danych

Rozpoznaj schemaVersion i ustal, czy odbiorca obsługuje tę wersję.
Wybierz odpowiadający jej schemat z indeksu kontraktów.
Zastosuj walidator zgodny z dialektem danego schematu. Ten przykład używa JSON Schema 2020-12.
Zwróć czytelną diagnostykę dla dokumentu odrzuconego. Nie interpretuj go jako innej wersji tylko dlatego, że część pól wygląda znajomo.
Po walidacji wykonaj kontrole wymagane przez właściwy kontrakt operacji.

To opis integracji własnego odbiorcy. SDK nie dostarcza tu jednej biblioteki klienckiej dla każdego języka programowania.

4. Zobacz dokument odrzucany

Przykładowy błąd: do powyższego manifestu dopisano pole:

"undeclaredField": true

Schemat manifestu 0.1 ma additionalProperties: false, więc odrzuca cały dokument z tym dodatkowym polem. Otwórz pełny błędny dokument.

Oba przykłady sprawdzono lokalnym narzędziem walidacji schematów SDK: dokument poprawny przyjęto, a dokument z dodatkowym polem odrzucono. To test struktury, nie próba wykonania dostawcy.

5. Oddziel trzy wyniki

Wynik	Co potwierdza?	Czego nie potwierdza?
Dokument zgodny ze schematem	Właściwa struktura dla konkretnej wersji.	Zgodności z plikiem projektu, prawdziwości deklaracji i działania kodu.
Walidacja i zgodność dostawcy	Kontrole SDK, tożsamość, wymagania wersji i zadeklarowane zdolności.	Wykonania operacji w docelowym środowisku.
Zaliczone próby wykonawcze	Zachowanie objęte konkretnymi testami.	Wszystkich przypadków, trwałości ani gotowości produkcyjnej.

Walidacja schematu dokumentu podpisanego nie zastępuje weryfikacji podpisu i polityki zaufania. Analogicznie poprawny schemat planu aktualizacji nie oznacza, że plan został wykonany.

Twój pierwszy wynik

Twoje narzędzie potrafi przyjąć manifest obsługiwanej wersji i wyjaśnić, dlaczego odrzuciło drugi dokument. Masz jawny kontrakt wejścia, zamiast polegać na przypadkowej zgodności pól.

Dalej wybierz właściwą rodzinę w indeksie kontraktów. Jeśli chcesz dostarczyć implementację zamiast samego odbiorcy dokumentów, przejdź do pierwszego dostawcy.

Wróć do wyboru drogi Rola SDK w platformie

Twoja droga