C'è questo momento in cui stai felicemente refactoring del tuo back-end e poi raggiungi un metodo endpoint. Improvvisamente un'ondata di ansia albe su di te. Questo endpoint viene utilizzato? Tutti quei campi in questo DTO sono usati sul frontend? Dove si interromperà il frontend quando rinominerò questo campo? Con tutte queste domande non è insolito arrendersi e interrompere ulteriormente il refactoring.

Non perdere la speranza. Esistono modi per mantenere il tipo di codice client verificato rispetto all'API del server. Ti mostrerò un modo semplice che è completamente indipendente dallo stack del server. Si basa su strumenti basati sulla specifica OpenAPI (precedentemente Specifica Swagger).

L'idea generale è la seguente: generare un client Typescript da una descrizione OpenAPI degli endpoint del server. Non è necessario scrivere personalmente le specifiche dell'API. Ci sono plugin che lo generano per te per qualsiasi stack di server popolare .

Passiamo a un esempio concreto.
Userò Spring Boot per il lato server. Per il frontend ho scelto il mio amato React .

Dobbiamo iniziare dal back-end. Per cominciare, devi aggiungere queste dipendenze al tuo progetto Spring Boot pom.xml:

e configuralo inserendo questa configurazione nel tuo pacchetto root

Fatto ciò, sarà disponibile un nuovo endpoint: /v2/api-docs. Serve questo enorme JSON che descrive tutti i tuoi endpoint. Contiene tutte le informazioni necessarie per generare un client completo e completamente tipizzato.

Gli strumenti per farlo sono forniti dal progetto openapi-generator . Ci sono opzioni per eseguirlo direttamente , tramite Docker o un pacchetto npm . Se hai già installato JRE, l'ultima opzione sarebbe la più semplice:

Alcune note qui. Stiamo usando l' generateattività dal @openapitools/openapi-generator-clipacchetto. Con -idefiniamo da dove ottenere le specifiche API e con -gscegliamo typescript-fetchil modello per il nostro client generato da tutti quelli disponibili (incluso uno per Angular ovviamente). L'ultima opzione ( -o) specifica la directory di output per i file generati

Prendiamo ora questo semplice controller Spring:

La convalida javax e l'annotazione spavalda utilizzate qui hanno un impatto sulla specifica API generata. Dai un'occhiata al frammento corrispondente del JSON generato:

Da esso viene prodotto il seguente dattiloscritto:

Come puoi vedere i campi contrassegnati @NotNullsono generati come campi obbligatori (1). Il testo “Cognome utente” da the @ApiModelPropertyè utilizzato nella documentazione aggiuntiva di lastName(2). Un'altra cosa da notare qui: il nome enum Typescript viene generato in base al nome del campo ( User.roles), non al nome enum di Java. Questo perché il suo nome non è incluso da nessuna parte nel JSON in /v2/api-docs.

Oltre al modello generato, sono disponibili anche metodi corrispondenti a tutti gli endpoint. In questo caso, c'è UserResourceApiclasse con allUsersUsingGETmetodo.

Se osservi attentamente il nome generato del metodo, noterai che deriva direttamente dal nome del metodo Java. Questo è un po' controintuitivo. Le modifiche ai percorsi degli endpoint non richiedono modifiche al codice sul lato client. Le modifiche apparentemente interne ai nomi dei metodi del server che implementano gli endpoint introducono modifiche sostanziali nel client generato.

Avendo tutto questo fuori mano, vediamo come appare l'utilizzo del client generato:

Impostare prima l'URL di base per tutte le chiamate API (1), quindi creare un'istanza del wrapper API per la risorsa (2). Infine, chiama endpoint specifici (3) utilizzando metodi completamente tipizzati.

Questo è tutto. Ora hai un modo per assicurarti che il tuo codice client sia completamente coerente con l'API back-end.

Riepilogo

Con questa configurazione puoi utilizzare il compilatore Typescript per verificare che stai chiamando gli URL dell'endpoint API corretti, passando i parametri corretti e interpretando correttamente la risposta. Questo può davvero aumentare la fiducia nella tua base di codice.

Questa semplice configurazione funzionerà bene per un piccolo progetto, ma non è sufficiente per i team più grandi. La soluzione definitiva sarebbe generare e pubblicare un pacchetto client npm dattiloscritto sul server CI/CD come parte della creazione del back-end. Ma questo merita un post sul blog separato. Tuttavia, puoi sempre iniziare con questa semplice soluzione e poi passare a una pipeline più avanzata in un secondo momento.