Cosa c'è di sbagliato in un endpoint che restituisce HTML anziché dati JSON?

Quando ho iniziato a studiare PHP (circa 5 o 6 anni fa) ho appreso dell'Ajax e ho attraversato "le fasi":

1. Il server restituisce dati HTML e si mette dentro una di DOM innerHTML
2. Si impara a conoscere i formati di trasferimento di dati come XML (e si dice "oooh, quindi è quello per cui viene utilizzato) e quindi JSON.
3. Si restituisce JSON e si crea l'interfaccia utente utilizzando il codice JavaScript vanilla
4. Passa a jQuery
5. Informazioni su API, intestazioni, codici di stato HTTP, REST , CORS e Bootstrap
6. Apprendi SPA e framework di frontend ( React , Vue.js e AngularJS ) e lo standard API JSON.
7. Riceverai un codice legacy aziendale e dopo averlo ispezionato, scoprirai che fanno ciò che è descritto nel passaggio 1.

Mentre lavoravo con questa base di codice legacy, non ho nemmeno pensato che potesse restituire HTML (voglio dire, siamo professionisti ora, giusto?), Quindi ho avuto difficoltà a cercare l'endpoint JSON che restituiva i dati che le chiamate Ajax popolano. Non è stato fino a quando ho chiesto "al programmatore" che mi ha detto che stava restituendo HTML e che veniva aggiunto direttamente al DOM con innerHTML.

Certo, questo era difficile da accettare. Ho iniziato a pensare ai modi per refactificare questo negli endpoint JSON, pensando alle unità di test degli endpoint e così via. Tuttavia, questa base di codice non ha test. Non uno solo. Ed è oltre 200k linee. Naturalmente uno dei miei compiti include la proposta di approcci per testare il tutto, ma al momento non lo stiamo ancora affrontando.

Quindi, in nessun angolo, mi chiedo: se non abbiamo alcun test, quindi non abbiamo motivi particolari per creare questo endpoint JSON (poiché non è "riutilizzabile": restituisce letteralmente dati che si adattano solo a quella parte del applicazione, ma penso che questo fosse già implicito poiché ... restituisce dati HTML).

Che cosa esattamente è sbagliato nel fare questo?

Cosa c'è di sbagliato in un endpoint che restituisce HTML anziché dati JSON?

Niente. Ogni applicazione ha requisiti diversi e può darsi che l'applicazione non sia stata progettata per essere una SPA.

Può darsi che questi splendidi framework che hai citato (Angular, Vue, React, ecc ...) non fossero disponibili al momento dello sviluppo, o non fossero cose aziendali "approvate" da usare nella tua organizzazione.

Ti dirò questo: un endpoint che restituisce HTML riduce la tua dipendenza dalle librerie JavaScript e riduce il carico sul browser dell'utente poiché non sarà necessario interpretare / eseguire il codice JS per creare oggetti DOM: l'HTML è già lì, si tratta solo di analizzare gli elementi e renderli. Ovviamente, questo significa che stiamo parlando di una quantità ragionevole di dati. 10 megabyte di dati HTML non sono ragionevoli.

Ma dal momento che non c'è nulla di sbagliato nel restituire HTML, ciò che stai perdendo non usando JSON / XML è fondamentalmente la possibilità di usare il tuo endpoint come API. E qui sta la domanda più grande: deve davvero essere un'API?

Correlati: è corretto restituire HTML da un'API JSON?

JSON e HTML soddisfano due diversi scopi semantici.

Se stai popolando una pagina web con dati, usa JSON. Se si sta creando una pagina Web da porzioni di pagine Web, utilizzare HTML.

Potrebbero sembrare che siano la stessa cosa, ma non lo sono affatto. Per prima cosa, quando si crea una parte di una pagina Web utilizzando HTML restituito dal server, si lavora sul lato server. Quando si associano dati a una pagina Web, si lavora sul lato client.

Inoltre, devi fare attenzione con HTML per non legare strettamente a una pagina specifica. L'intero punto del rendering delle pagine parziali in questo modo è che i parziali siano riutilizzabili e , se si rende il parziale troppo specifico, non si comporrà in altre pagine. JSON non ha questo problema, perché sono solo dati, non struttura della pagina web.

Il problema principale è che accoppia strettamente il server al client, che deve conoscere la struttura HTML. Inoltre, rende gli endpoint più difficili da riutilizzare in nuovi modi o nuove applicazioni.

La restituzione di dati semplici e il rendering del client diminuisce l'accoppiamento e aumenta la flessibilità e la testabilità: è possibile eseguire test unitari sul client per dati fittizi ed eseguire test unitari sul server per testare i dati desiderati.

Penso che tu l'abbia un po 'indietro. Tu dici:

non abbiamo alcun test, quindi non abbiamo motivi particolari per creare questo endpoint JSON

Un motivo per utilizzare un endpoint corretto sarebbe quello di poterlo testare. Direi che non avere test è un'ottima ragione per iniziare a scriverne. Cioè, se c'è qualche logica che sarebbe adatta a testare.

200k righe di codice sono molte da refactoring e sono probabilmente difficili da mantenere. Rompere alcuni endpoint e testarli potrebbe essere un buon punto di partenza.

Un altro motivo potrebbe essere quello di separare il server dal client. Se, in un lontano futuro, la progettazione dell'applicazione o il layout cambiano, è più facile lavorare con un formato dati adeguato rispetto all'output HTML. In un mondo ideale, dovresti solo cambiare il client e non toccare affatto il server.

Esistono 3 modi (almeno?) Per creare una pagina Web:

• Genera l'intero lato server della pagina.
• Restituisce una pagina di ossa nude dal server più codice (JavaScript) e fa in modo che la pagina recuperi i suoi dati e li renda nel lato client HTML.
• Restituisce una pagina parziale più codice e fai in modo che il codice recuperi blocchi pre-renderizzati di HTML che possono essere rilasciati nella pagina.

Il primo va bene. Anche il secondo va bene. È l'ultimo il problema.

Il motivo è semplice: ora hai diviso la costruzione della pagina HTML in parti completamente disconnesse. Il problema è di manutenzione. Ora hai due entità separate incaricate di gestire i dettagli dell'interfaccia utente. Quindi devi mantenere CSS e altri dettagli simili sincronizzati tra i due pezzi separati. Hai cambiato la larghezza della barra laterale? Grande. Ora il frammento HTML che ritorna causa lo scorrimento orizzontale perché i suoi presupposti sulla larghezza della barra laterale non sono più validi. Hai cambiato il colore di sfondo per quel blocco? Bene, ora il colore del carattere del tuo frammento HTML si scontra perché ha assunto un colore di sfondo diverso e qualcuno ha dimenticato di testare quell'endpoint.

Il punto è che ora hai diviso le conoscenze che dovrebbero essere centralizzate in un unico posto (vale a dire la logica di presentazione), e questo rende più difficile assicurarsi che tutti i pezzi si incastrino correttamente. Usando un'API JSON, puoi invece mantenere tutta quella logica solo nel front-end, oppure puoi tenerli tutti nei tuoi modelli lato server se, per cominciare, rendi i tuoi dati in HTML. Si tratta di mantenere la conoscenza / logica della presentazione in un unico posto, in modo che possa essere gestita in modo coerente e come parte di un singolo processo. HTML / CSS / JS è abbastanza difficile da mantenere dritto senza scomporlo in molti piccoli pezzi.

Le API JSON hanno anche l'ulteriore vantaggio di rendere i dati completamente disponibili indipendentemente dalla logica di presentazione. Ciò consente a più presentatori diversi , come un'app mobile e una pagina Web, di utilizzare gli stessi dati. In particolare, consente di consumare i dati senza browser (come app mobili o cron job notturni); questi consumatori potrebbero anche non essere in grado di analizzare l'HTML. (Questo ovviamente si basa necessariamente su una situazione in cui i dati sono gli stessi tra i diversi consumatori, o uno può usare un sottoinsieme dell'altro.) La necessità di questa capacità dipende dai requisiti della tua specifica applicazione, tuttavia, durante la gestione della presentazione la logica è necessaria a prescindere. Dirò che se lo implementerai in anticipo, sarai meglio preparato per la crescita futura.

Direi che non c'è nulla di sbagliato nel fatto che il server restituisca un frammento HTML e l'interfaccia utente lo assegni a .innerHTML di qualche elemento. Questo è, a mio avviso, il modo più semplice per sviluppare codice JavaScript asincrono. Il vantaggio è che il meno possibile viene fatto utilizzando JavaScript e il più possibile in un ambiente back-end controllato. Ricorda che il supporto JavaScript nei browser varia ma il tuo back-end ha sempre la stessa versione dei componenti di back-end, il che significa che fare il più possibile nel back-end significherà il minor numero possibile di incompatibilità di versione.

Ora, a volte vuoi qualcosa di più di un semplice frammento HTML. Ad esempio, un codice di stato e un frammento HTML. Quindi è possibile utilizzare un oggetto JSON con due membri, statusCode e HTML di cui il secondo può essere assegnato a .innerHTML di alcuni elementi dopo aver verificato statusCode. Quindi, usare JSON e usare innerHTML non sono affatto approcci esclusivi alternativi; possono essere usati insieme.

Usando JSON puoi anche avere più frammenti HTML nella stessa risposta che vengono assegnati al .innerHTML di più elementi.

In sintesi: utilizzare .innerHTML. Rende il tuo codice compatibile con il maggior numero possibile di versioni del browser. Se hai bisogno di più, usa JSON e .innerHTML insieme. Evita XML.

Non c'è nulla di sbagliato in linea di principio . La domanda è: cosa vuoi ottenere?

JSON è perfetto per la trasmissione di dati. Se invece invii HTML e ti aspetti che il client estragga i dati dall'HTML, questa è spazzatura.

D'altra parte, se si desidera trasmettere HMTL che verrà reso come HTML, quindi inviarlo come HTML - invece di comprimere l'HTML in una stringa, trasformando la stringa in JSON, trasmettendo JSON, decodificandolo dall'altra parte , ottenere una stringa ed estrarre l'HTML dalla stringa.

E proprio ieri mi sono imbattuto in un codice che ha inserito due elementi in un array, ho trasformato l'array in JSON, ho inserito il JSON in una stringa, ho inserito la stringa in un array, ho trasformato l'intero array in JSON, l'ho inviato al client, che ha decodificato JSON, ottenne un array contenente una stringa, prese la stringa, estrasse il JSON dalla stringa, decodificò il JSON e ottenne un array con due elementi. Non farlo.

Tutto dipende dallo scopo dell'API, ma in genere ciò che descrivi è una violazione abbastanza forte della separazione delle preoccupazioni :

In un'applicazione moderna, il codice API dovrebbe essere responsabile dei dati e il codice client dovrebbe essere responsabile della presentazione.

Quando la tua API restituisce HTML, stai accoppiando strettamente i tuoi dati e la tua presentazione. Quando l'API restituisce HTML, l'unica cosa che puoi fare (facilmente) con quell'HTML è visualizzarla come parte di una pagina più grande. Da un altro punto di vista, l'unica cosa utile per l'API è fornire HTML alla tua pagina. Inoltre, hai diffuso il codice HTML sia nel codice client che in quello del server. Questo può rendere la manutenzione un mal di testa.

Se la tua API restituisce JSON, o qualche altra forma di dati puri, diventa molto più utile. L'app esistente può comunque consumare tali dati e presentarli in modo appropriato. Ora, tuttavia, altre cose possono usare l'API per accedere agli stessi dati. Anche in questo caso, la manutenzione è più semplice: tutto l'HTML risiede in un'unica posizione, quindi se si desidera ridisegnare l'intero sito, non è necessario modificare l'API.

L'HTML è legato a uno specifico design e utilizzo.

Con HTML, se si desidera modificare il layout di pagina, è necessario modificare la modalità di generazione dell'html dalla chiamata del server. Di solito, ciò richiede un programmatore back-end. Ora hai programmatori back-end, che per definizione non sono i tuoi migliori scrittori html, gestendo questi aggiornamenti.

Con JSON, se il layout della pagina cambia, la chiamata al server JSON esistente non deve necessariamente cambiare affatto. Invece, il tuo sviluppatore front-end, o anche il progettista, aggiorna il modello per produrre il diverso HTML desiderato dagli stessi dati di base.

Inoltre, JSON può diventare la base per altri servizi. Potresti avere ruoli diversi che devono vedere gli stessi dati di base in modi diversi. Ad esempio, potresti avere un sito Web del cliente che mostra i dati su un prodotto in una pagina dell'ordine e una pagina di vendita interna per i rappresentanti che mostra gli stessi dati in un layout molto diverso, forse accanto ad altre informazioni non disponibili per i clienti generali. Con JSON, la stessa chiamata al server può essere utilizzata in entrambe le viste.

Infine, JSON può ridimensionare meglio. Negli ultimi anni abbiamo esagerato con i framework javascript sul lato client. Penso che sia il momento di fare un passo indietro e iniziare a pensare a quale javascript stiamo usando e come influenza le prestazioni del browser ... specialmente sui dispositivi mobili. Detto questo, se stai gestendo un sito abbastanza grande da richiedere una server farm o un cluster, anziché un singolo server, JSON può ridimensionare meglio. Gli utenti ti daranno il tempo di elaborazione nei loro browser gratuitamente e, se ne approfitti, puoi ridurre il carico del server in una distribuzione di grandi dimensioni. JSON usa anche meno larghezza di banda, quindi di nuovo, se sei abbastanza grandee usarlo in modo appropriato, JSON è notevolmente più economico. Certo, può anche peggiorare, se finisci per alimentare librerie da 40 KB per analizzare 2 KB di dati in 7 KB di HTML, quindi di nuovo: paga essere consapevole di ciò che stai facendo. Ma esiste il potenziale per JSON di migliorare prestazioni e costi.

Non c'è nulla di sbagliato in un tale endpoint se soddisfa i suoi requisiti. Se è necessario sputare HTML che un consumatore noto può analizzare in modo efficace, certo, perché no?

Il problema è che, nel caso generale, si desidera che gli endpoint emettano un payload ben formato ed effettivamente analizzabile da un parser standard. E per analizzare effettivamente, intendo, analizzare in modo dichiarativo.

Se il tuo client è costretto a leggere il payload e fa leva su di esso da informazioni aperte con loop e istruzioni if, non è effettivamente analizzabile. E l'HTML, essendo il suo modo di essere, è molto perdonato nel non aver bisogno di essere ben formato.

Ora, se ti assicuri che il tuo html sia conforme a xml, allora sei d'oro.

Detto questo, ho un problema significativo con questo:

Ti dirò questo: un endpoint che restituisce HTML riduce la tua dipendenza dalle librerie JavaScript e riduce il carico sul browser dell'utente poiché non sarà necessario interpretare / eseguire il codice JS per creare oggetti DOM: l'HTML è già lì, si tratta solo di analizzare gli elementi e renderli. Ovviamente, questo significa che stiamo parlando di una quantità ragionevole di dati. 10 megabyte di dati HTML non sono ragionevoli.

È una cattiva idea, non importa come la tagli. Decenni di esperienza industriale collettiva ci hanno mostrato che, in generale, è una buona idea separare i dati (o il modello) dalla sua visualizzazione (o vista).

Qui si stanno unendo i due allo scopo di eseguire rapidamente il codice JS. E questa è una micro ottimizzazione.

Non l'ho mai vista come una buona idea se non in sistemi molto banali.

Il mio consiglio? Non farlo HC SVNT DRACONES , YMMV , ecc.

JSON è solo una presentazione testuale di dati strutturati. Un client deve naturalmente disporre di un parser per elaborare i dati, ma praticamente tutte le lingue hanno funzioni di parser JSON. È molto più efficiente utilizzare il parser JSON che utilizzare il parser HTML. Ci vuole poco ingombro. Non così con un parser HTML.

In PHP, basta usare json_encode($data)ed è il client dall'altra parte per analizzarlo. E quando recuperi i dati JSON da un servizio Web, usi semplicemente $data=json_decode($response)e puoi decidere come utilizzare i dati come faresti con le variabili.

Supponendo di sviluppare un'app per un dispositivo mobile, perché è necessario il formato HTML quando le app mobili utilizzano raramente il browser Web per analizzare i dati? Molte app mobili utilizzano JSON (il formato più comune) per lo scambio di dati.

Considerando che i cellulari sono spesso su piani misurati, perché vuoi usare HTML che richiede molta più larghezza di banda di JSON?

Perché usare HMTL quando HTML è limitato nel suo vocabolario e JSON può definire i dati? {"person_name":"Jeff Doe"}è più informativo di quello che l'HTML può fornire sui suoi dati poiché definisce solo la struttura per i parser HTML, non i dati.

JSON non ha nulla a che fare con HTTP. È possibile inserire JSON in un file. Puoi usarlo per le configurazioni. Il compositore utilizza JSON. Puoi usarlo anche per salvare semplici variabili nei file.

È difficile classificare un diritto o un errore. IMO, le domande che farò sono: " dovrebbe " o " può fare con meno? ".

Ogni endpoint dovrebbe cercare di comunicare con il minor contenuto possibile. Il rapporto segnale-rumore è in genere codici HTTP <JSON <XHTML. Nella maggior parte delle situazioni, è bene scegliere il protocollo meno rumoroso.

Sono diverso dal punto di vista del caricamento del browser client da parte di @machado, poiché con i browser moderni questo non è un problema. La maggior parte di essi è in grado di gestire abbastanza bene i codici HTTP e le risposte JSON. E anche se al momento non hai test, la manutenzione a lungo termine di un protocollo meno rumoroso sarebbe più economica di quella sopra.