Nome classe postfixed versione per REST api

Question

Nome classe postfixed versione per REST api

#1 da (1 voti)
#2 da (0 voti)
#3 da (0 voti)

1

Sto lavorando su un'API REST basata su Spring con varianti v1 e v2:

/api/v1/dates
/api/v2/dates

Corrispondentemente, ci sono i pacchetti v1 e v2 nel codebase:

com.company.api.v1
com.company.api.v2

È una buona pratica assegnare nomi di classi postfix con il numero di versione come di seguito:

DatesControllerV1.java (nel pacchetto v1)
DatesControllerV2.java (nel pacchetto v2)

Preferisco non versione postfixing nel nome della classe come:

i nomi dei pacchetti dovrebbero dirti già la versione ridondante;
Semplicemente non mi piace il carattere numerico nel nome della classe.

Tuttavia, non la versione postfixing (cioè lo stesso nome di classe ma in pacchetti diversi) aumenterà la probabilità di utilizzare la classe sbagliata accidentalmente a causa del completamento / importazione automatica IDE da parte di sviluppatori incuranti.

Ho provato a cercare un repo github che abbia una struttura di base in codice simile e vediamo come si comportano con esso. Ma non è stato possibile trovarne uno sfortunatamente.

Mi chiedo quale approccio pensi sia migliore e il motivo. Mi chiedo anche se ci sia un approccio migliore (per l'attuale configurazione del codice base) rispetto a questi due?

Aggiorna

Con l'aiuto di Azuaron e CormacMulhall, mi sono reso conto che in realtà non ho altre opzioni per migliorare la mia situazione attuale, dato che entrambe le API v1 e v2 risiedono nella stessa base di codice e non posso cambiare questa configurazione.

Per coloro che sono alla ricerca del modo corretto di farlo (con diverse versioni di API), vedi la risposta di Azuaron di seguito.

java coding-standards naming rest spring-mvc

posta GJ. 19.08.2016 - 03:06

fonte

3 risposte

Leggi altre domande sui tag java coding-standards naming rest spring-mvc

Archivio principale guasto su github con richieste pull Come disegnare immagini ad alta risoluzione sul lato client?

score 1 · Answer 1

Devo ammettere che il mio cuore si è contratto di stress quando ho letto "... ci sono pacchetti v1 e v2 nel codice base ..." In genere, le API con versione sono, beh, versioni di il tuo codice e non vivere fianco a fianco nella tua base di codice.

Come ho fatto prima è forking il repository. La V1 resta in attesa di correzioni di bug fino a quando non siamo in grado di portare tutti su V2 e V2 è dove vanno a finire tutte le nuove funzionalità. Quindi, in produzione, distribuisci entrambi codebases (su server diversi o side-by-side) e i tuoi punti di routing dell'URL all'istanza appropriata.

Questo ti dà i seguenti vantaggi:

L'unico modo in cui qualcuno scrive codice contro l'API sbagliata è se sono nel repository sbagliato (a quel punto, non c'è molto altro che puoi fare per quel programmatore).
Non devi preoccuparti della retrocompatibilità nelle classi non condivise "condivise" (utilità, servizio, DAO, cosa hai).
Una distribuzione di una API non influisce sull'altra.
Onestamente? Fornisce un motivo di business dimostrabile per abbandonare v1 il prima possibile (puoi chiudere il vecchio server) che può essere chiaramente spiegato ai non sviluppatori.

Lo svantaggio è che il codebase non è condiviso, quindi i cambiamenti in uno che sono "necessari" nell'altro devono essere portati. Non vedo questo come un grosso problema. Non dovrebbe accadere così tanto (le nuove funzionalità vanno in v2, non v1, in base alla progettazione) e qualsiasi modifica che debba realmente essere condivisa può essere estratta in librerie o altri servizi.

score 0 · Answer 2

Penso che dipenda da "Li vedi come due versioni di essenzialmente stesso concetto O le vedi come due concetti diversi"?

Se vedi due concetti diversi, sarebbe sicuramente meglio nominarli separatamente (come SavingsAccount contro CheckingAccount).

Ho odiato le versioni. Ma, in realtà, ho dovuto morderlo e fare versioni nelle mie librerie c ++, per aiutare meglio i miei utenti. Ho usato spazi dei nomi.

Ero solito chiedere ai miei utenti (mostrarli con codice di esempio) per usare la dichiarazione appropriata "using namespace proj_lib_v1".

L'evoluzione del codice diventa un po 'dura anche se a volte. Metterei tutti i tuoi pacchetti in spazi dei nomi diversi (tante volte quante sono le versioni). Ero solito estrarre tutte le classi di helper e metterle in un namespace diverso (non esposto agli utenti).

score 0 · Answer 3

Bene, alcune delle tue opzioni potrebbero dipendere dalla flessibilità che hai nel dichiarare i tuoi URL (non sono del tutto familiare con tutte le opzioni disponibili in primavera).

Prima di tutto, se non hai alcuna flessibilità, suggerirei di utilizzare la specifica del nome della classe, a meno che i tuoi URL non siano mappati direttamente sulla struttura del tuo pacchetto, in quanto sarebbe più semplice fare le cose logicamente. I tuoi utenti API utilizzeranno l'URL e non la classe. I manutentori dovrebbero davvero conoscere la differenza prima di aggirarsi nel codice.

Se hai la possibilità di specificare URL per i metodi, come in alcuni pacchetti di annotazioni, allora potresti avere la stessa classe per fornire entrambe le versioni. Oppure potrebbe esserci un modo magico in primavera per farlo nel file web.xml (o in un file di mappatura simile).

L'API dell'URL è la cosa più importante in REST. La struttura dei pacchetti e delle classi dovrebbe essere spiegata in package.xml (o altra documentazione in-code) o seguire l'URL logicamente.