Zmiany Admin API PrestaShop 9.2: kontrakty przewoźników i odpowiedzi

Klient API może przestać działać, nawet gdy wywoływany adres URL się nie zmienił. Wymagane pole może zostać opisane dokładniej, brakująca encja może teraz powodować jawny błąd albo wynik zapytania może przejść przez inną wewnętrzną ścieżkę mapowania. To kwestie kontraktu, które zasługują na ukierunkowane testy.

PrestaShop 9.2 RC1 zawiera prace nad domeną przewoźników i API oraz zmianę dotyczącą zapytań CQRS zwracających listy. Ten artykuł analizuje te konkretne zmiany i ich skutki dla integracji. Zakłada znajomość Admin API i nie powtarza podstaw uwierzytelniania ani API Platform.

Przegląd jest aktualny na 26 września 2026 r. RC1 pozostaje celem oceny; poniższe przykłady opisują metody testowania kontraktów, a nie zweryfikowane odpowiedzi działającego sklepu w tym projekcie.

Jeśli odpowiedź API zawiera niestandardowe pola, uwzględnij proces integracji modułu Extra Properties w przeglądzie kontraktu zamiast zakładać, że każde zarejestrowane pole powinno być udostępnione.

Obsługa przewoźników obejmuje rdzeń i moduł zasobów

Prace nad przewoźnikami w rdzeniu są powiązane z pracami nad zasobami w ps_apiresources. Scalony PR rdzenia wskazuje poprawki potrzebne do prawidłowego działania zasobów przewoźników, w tym skalarne argumenty zapytań, nowoczesny kontekst sklepu i sprawdzanie brakującego produktu. Zmiana domeny przewoźników i API nr 42022.

Dla twórców klientów bezpośrednią konsekwencją jest zapisywanie obu wersji. „Rdzeń 9.2” nie opisuje w pełni wykazu zasobów zainstalowanych w konkretnym sklepie. Przed przyjęciem operacji sprawdź wygenerowaną dokumentację tej instalacji i zweryfikuj jej dostępność autoryzowanym żądaniem w piaskownicy.

Nie kopiuj proponowanej ścieżki z dyskusji o zgłoszeniu, zakładając, że została wydana. Zmiana rdzenia może wspierać zasób pakowany osobno, a komentarz z przeglądu może opisywać wcześniejszą iterację. Używaj razem zainstalowanego schematu i odpowiadającej rewizji źródeł.

Zbuduj najmniejszy przydatny zestaw testowy przewoźników: znanego przewoźnika, produkt powiązany z właściwym sklepem i celowo nieistniejący identyfikator produktu. Początkowo utrzymuj proste reguły wysyłki, by nie mylić błędu walidacji domeny z regułą kwalifikowalności.

Wygenerowane schematy żądań są częścią kontraktu

Ten sam PR przewoźników zajmuje się dokumentacją treści żądań wywodzoną z poleceń: pominiętymi właściwościami, wymagalnością i kontekstem schematu dostarczanym przez zasoby. Dodaje też obsługę domyślnych wartości operacji przed mapowaniem i walidacją. Szczegóły schematów i wartości domyślnych.

To ważne dla generowanych klientów. Nieaktualny schemat może skłonić klienta do pominięcia informacji potrzebnych operacji lub błędnego reprezentowania zagnieżdżonych wartości. Ponowne wygenerowanie klienta bez sprawdzenia różnic może potem wprowadzić zmiany daleko wykraczające poza przyjmowaną operację.

Zapisz schemat bazowy i schemat wersji kandydującej z ich odpowiednich instalacji. Przejrzyj wymagane pola, dopuszczalność null, struktury elementów tablic i wartości domyślne. Potwierdź, które różnice wpływają na operacje rzeczywiście wywoływane przez klienta.

Udokumentowana wartość domyślna nie jest powodem do bezkrytycznego wysyłania null. Wartości pominięte, null i jawne mogą mieć różne znaczenia. Przetestuj każdy stan, który może wytworzyć aplikacja, i zapisz wynikowe zachowanie.

Dla operacji zapisu porównuj zapisaną encję z żądaniem, nie tylko z wynikiem HTTP. Żądanie może zostać przyjęte, podczas gdy wartość domyślna daje wynik inny niż oczekiwanie biznesowe klienta.

Brakujące encje i zakres sklepu wymagają przypadków negatywnych

Znaczący test kontraktu zawiera identyfikator, który nie może istnieć w zestawie testowym. Prace nad przewoźnikami sprawiają, że ustawianie odniesień dla nieznanego produktu jawnie zawodzi, zamiast po cichu nic nie robić. Zachowanie przy brakującym produkcie.

Klient powinien traktować to jako nieudaną operację biznesową. Rejestrowanie udanej synchronizacji wyłącznie dlatego, że zakończyło się żądanie transportowe, ukryłoby różnicę.

Przetestuj też rzeczywistą encję w nieodpowiednim kontekście sklepu. Prawidłowy identyfikator globalny nie dowodzi, że operacja jest prawidłowa w każdym sklepie. Użyj udokumentowanego mechanizmu zakresu zainstalowanej operacji i sprawdź wynikowe powiązanie lub wartość w zamierzonym sklepie.

Unikaj cichego zastępowania brakującego kontekstu domyślnym sklepem. Jeśli aplikacja wymaga operacji w jednym sklepie, sprawdź ten wymóg przed wysłaniem. Warunek wstępny po stronie klienta może zapobiec niejasnemu błędowi serwera i lepiej określić zamierzony zakres w logach.

Nie utożsamiaj pustego wyniku kwalifikowalności z błędem. Prawidłowe żądanie może poprawnie nie znaleźć żadnych kwalifikujących się przewoźników. Oddzielaj ten wynik od odmowy dostępu, nieprawidłowego produktu lub wyjątku serwera.

Mapowanie zapytań listowych nie oznacza nowej otoczki każdej odpowiedzi

Oddzielna zmiana wersji 9.2 opakowuje zwykłe wyniki listowe operacji CQRS niebędących kolekcjami pod wewnętrznym kluczem mapowania _queryResult. Wyniki asocjacyjne zachowują dotychczasowe zachowanie mapowania. PR wyjaśnia, że klucz pozwala przypisać wynik listowy do właściwości zasobu. Mapowanie wyników listowych nr 42011.

Kluczowe jest rozróżnienie między wewnętrznym wejściem mapowania a publiczną reprezentacją odpowiedzi. Nie każ każdemu klientowi API oczekiwać właściwości najwyższego poziomu _queryResult. Mapowanie zasobu i serializacja określają udostępnianą strukturę.

Dla rozszerzenia implementującego odpowiedni zasób sprawdź listę z elementami i pustą listę. Pusty wynik jest ważny, ponieważ kod często traktuje go jako brak danych lub nieoczekiwany typ. Klient powinien otrzymać udokumentowaną reprezentację w obu przypadkach.

Jeśli utrzymujesz migawki kontraktów, porównuj sparsowaną strukturę zamiast nieistotnego formatowania czy kolejności właściwości. Przydatna asercja sprawdza oczekiwany typ i wartości pola. Porównanie surowego tekstu może zawieść przez nieszkodliwe zmiany serializacji, pomijając niedopasowanie semantyczne gdzie indziej.

Ta zmiana jest ukierunkowanym usprawnieniem mapowania. Nie stanowi dowodu, że wszystkie operacje kolekcji lub wszyscy dotychczasowi klienci wymagają przepisania.

Udostępnienie Extra Properties dodaje wymiar kontraktu danych

Gdy integracja przyjmuje nowo zarejestrowaną właściwość, traktuj ją jako część kontraktu biznesowego. Określ właściciela, typ, znaczenie pustej wartości i zakres sklepu lub języka, zanim pozwolisz innemu systemowi ją zapisywać.

Nie wnioskuj o zewnętrznym formacie danych z administracyjnej etykiety pola. Sprawdź zainstalowany schemat zasobu i zweryfikowaną przykładową odpowiedź. Zachowaj przestrzeń nazw modułu i dokładną obsługiwaną reprezentację w mapowaniu klienta.

Pole może być dostępne w formularzu administracyjnym, podczas gdy integracja nie została skonfigurowana ani upoważniona do jego wykorzystania. Z kolei udostępniona wartość może dziedziczyć uprawnienia encji nadrzędnej zamiast mieć osobną politykę na poziomie pola. Sprawdź to zachowanie w bieżącej dokumentacji funkcji i instalacji.

Dla nowej właściwości dodaj przypadki pełnego cyklu: zapisz prawidłową wartość, odczytaj ją, wyczyść, jeśli jest to obsługiwane, odrzuć nieprawidłową wartość i sprawdź, że drugi sklep pozostaje niezmieniony. Oddzielaj te przypadki od zwykłych pól produktu, aby awarie wskazywały nową powierzchnię rozszerzenia.

Jeśli nie używasz Extra Properties, nie rozszerzaj danych zapisu klienta tylko dlatego, że wersja kandydująca może je udostępnić. Przyjmuj wyłącznie pola potrzebne kontraktowi biznesowemu.

Zbuduj mały proces porównywania kontraktów

Poniższy pomocniczy kod Python porównuje wykaz ścieżek i metod dwóch lokalnie zapisanych plików JSON OpenAPI. Nie pobiera danych sklepu, nie uwierzytelnia się ani nie weryfikuje zachowania operacji:

import json
from pathlib import Path

METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}

def operations(filename):
    document = json.loads(Path(filename).read_text(encoding="utf-8"))
    return {
        (method.upper(), path)
        for path, item in document.get("paths", {}).items()
        for method in item
        if method.lower() in METHODS
    }

before = operations("baseline-openapi.json")
after = operations("candidate-openapi.json")
print("Added:", sorted(after - before))
print("Removed:", sorted(before - after))

Użyj nazw plików eksportów schematów, które faktycznie zapisałeś. Niezmieniony wykaz nadal wymaga porównania schematów używanych operacji. Parametry żądań, schematy treści, schematy odpowiedzi i uprawnienia mogą się zmienić bez dodania lub usunięcia ścieżki.

Po statycznym porównaniu uruchom mały zestaw testów na syntetycznych rekordach: autoryzowany odczyt, prawidłowy zapis, nieprawidłowe dane wejściowe, brakująca encja, pusty wynik i właściwy zakres sklepu. Sprawdź trwały wynik każdego zapisu.

Nie zapisuj tokenów w danych testowych ani nie zatwierdzaj surowych odpowiedzi produkcyjnych w repozytorium. Ukrywaj identyfikatory tam, gdzie to właściwe, i używaj syntetycznych danych klientów, aby dowody kontraktu można było bezpiecznie udostępniać opiekunom.

Odróżniaj brak wsparcia od niezgodnego wsparcia

Jeśli operacja jest nieobecna w schemacie wersji kandydującej, zapisz ją jako niedostępną w tej parze wersji. Nie wysyłaj odgadniętego żądania i nie interpretuj błędu routingu jako dowodu, że nowa implementacja domeny jest uszkodzona.

Jeśli operacja istnieje, lecz odrzuca udokumentowane dane, zachowaj fragment schematu, oczyszczone żądanie i odpowiedź. To inna klasa problemu zgodności, którą można zgłosić z dokładnym niedopasowaniem kontraktu.

Dla generowanych klientów przechowuj rewizję wygenerowanego kodu obok eksportu schematu. W przeciwnym razie programista może testować obecny serwer starym klientem i przypisać serwerowi wybór serializacji klienta. Odtwórz problem minimalnym wspieranym żądaniem przed zmianą którejkolwiek strony.

Te rozróżnienia czynią raport migracji API użytecznym: niedostępna operacja, niedopasowanie schematu, usterka serializacji i błąd walidacji biznesowej wskazują różnych właścicieli.

Wydaj klienta dla nazwanej pary wersji

Deklaracja zgodności powinna wskazywać wersje rdzenia i modułu zasobów, przyjęte operacje i ograniczenia. Jeśli nowa operacja jest nieobecna, jawnie wyłącz zależną funkcję zamiast zawieść później w niepowiązanym procesie.

Gdy operacja zwraca niepewny wynik po przekroczeniu limitu czasu, uzgodnij go przed powtórzeniem zapisu o istotnych skutkach. Usprawnienia schematów wersji 9.2 nie usuwają trybów awarii systemów rozproszonych.

Główne zadanie programisty jest więc wąskie: sprawdź rzeczywisty kontrakt zasobu, przetestuj zmiany przewoźników i mapowania, od których zależysz, oraz zachowaj dowody, że założenia klienta nadal obowiązują. Jest to bardziej niezawodne niż traktowanie nowego wydania jako zaproszenia do ślepego wygenerowania wszystkiego od nowa.

Kontekst platformy bazowej znajdziesz w naszym przewodniku po Admin API PrestaShop 9; zastosuj powyższe kontrole właściwe dla wersji do ocenianej instalacji.

Wybierając rozszerzenie, przejrzyj moduły PrestaShop 9 firmy PrestaSuite i porównaj udokumentowaną obsługę wersji oraz wymagania integracji z własnymi wynikami testów.