Go JSON v2: verificați contractul cu aplicațiile care vă folosesc API-ul

După o migrare JSON, un serviciu scris în Go poate trece de compilare și totuși poate întrerupe o integrare folosită de clienți. Schimbarea importului se vede ușor în cod. Mai greu se vede dacă răspunsul păstrează sensul pe care îl așteaptă aplicația de la celălalt capăt.

În articolul publicat pe 4 noiembrie, echipa Go prezintă encoding/json/v2 ca API stabil, disponibil în Go 1.27. Data articolului nu este data lansării compilatorului. Pentru un serviciu existent, recomandarea este să identificați mai întâi locurile în care schimbați date JSON cu alte aplicații. Adoptarea unor valori implicite noi merită judecată prin efectul asupra acelor aplicații.

Compilarea și compatibilitatea cu alte aplicații

Compilatorul verifică relațiile dintre tipuri și apeluri. Nu poate afla ce așteaptă programul care importă răspunsurile dumneavoastră într-un tabel. De aceea, verificarea codului și verificarea unei integrări au criterii diferite.

Ghidul oficial de migrare precizează că trecerea la v2 este opțională. Pachetul encoding/json rămâne acoperit de promisiunea de compatibilitate Go. Ghidul descrie și posibilitatea de a folosi noul API cu un comportament compatibil cu versiunea anterioară. Puteți planifica schimbarea fără să tratați vechiul import ca pe o urgență.

În estimarea muncii, separați modificarea codului de identificarea celor care depind de el. Un import se poate înlocui repede. Găsirea persoanei care întreține o integrare veche poate dura mai mult decât modificarea serviciului. Acceptarea lucrării ar trebui să acopere ambele aspecte.

Faceți o listă a cererilor primite, a răspunsurilor trimise și a documentelor salvate pentru a fi citite ulterior de altă versiune. Stabiliți cine răspunde de fiecare legătură. Un mesaj intern, ale cărui aplicații se schimbă împreună, permite o altă abordare decât un API public folosit de clienți necunoscuți.

Ce înseamnă o colecție goală

Documentația pentru Go 1.27.0 descrie valorile implicite noi pentru colecții. O valoare nil de tip slice, în afara reprezentării speciale pentru octeți, este trimisă ca tablou gol. O valoare nil de tip map devine un obiect gol. Cu valorile implicite anterioare, rezultatul este null.

Luați ca exemplu ilustrativ câmpul "items": null și comparați-l cu "items": []. Sunt forme de date alese pentru explicație, nu rezultate ale unui program executat pentru acest articol. O aplicație ipotetică poate interpreta prima formă ca „datele nu au fost încă încărcate”, iar a doua ca „datele au fost încărcate, dar lista este goală”. Alta poate refuza null, deoarece așteaptă un tablou.

Pentru a doua aplicație, noua valoare implicită poate fi mai potrivită. Pentru prima, schimbarea poate elimina o informație. Stabiliți sensul câmpului înainte să schimbați reprezentarea. Dacă starea „neîncărcat” are un rol în produs, exprimați-o deliberat în modelul de date.

Verificați diferența și în aplicația care primește răspunsul. Două documente pot produce aceeași structură Go într-un test de pe server, dar rezultate diferite într-o aplicație mobilă. Unde este practic, folosiți cititorul JSON al aplicației respective și exemple din care au fost eliminate datele clienților.

Cererile primite cer o decizie proprie

Documentația v2 pentru versiunea aleasă descrie și respingerea implicită a numelor repetate într-un obiect și a secvențelor UTF-8 nevalide. Aceste reguli mai stricte sunt utile. Ele pot modifica însă lista cererilor acceptate de un serviciu existent.

Un obiect ilustrativ care conține de două ori numele role arată dificultatea: componenta care verifică accesul și cea care citește mai departe datele ar putea interpreta diferit valoarea. Decideți ce reprezentări admiteți și păstrați aceeași interpretare între componente. O opțiune de compatibilitate nu demonstrează că o cerere ambiguă este lipsită de risc.

Pentru o integrare existentă, aflați dacă partenerul trimite asemenea date. Dacă da, conveniți cum vor fi refuzate și cum va corecta partenerul cererile. Existența unei opțiuni globale nu justifică păstrarea automată a tuturor comportamentelor vechi. Niciun cititor JSON mai strict nu înlocuiește verificarea securității întregului serviciu.

Schimbați separat comportamentele vizibile

Documentația v1 pentru Go 1.27.0 include DefaultOptionsV1 în encoding/json. Aceasta este baza de compatibilitate pe care ghidul o descrie pentru apelurile noului API. Puteți separa astfel adoptarea API-ului de modificarea datelor acceptate sau trimise. Verificați opțiunile în documentația versiunii folosite, fără să preluați nume din exemplele experimentului anterior.

O ordine practică este să păstrați întâi comportamentul cunoscut, apoi să alegeți o singură legătură între aplicații. Notați ce se schimbă în răspunsuri și în tratarea erorilor. Verificați aplicațiile care depind de ea și pregătiți revenirea la comportamentul anterior. Un răspuns HTTP reușit nu dovedește că aplicația destinatară a putut folosi conținutul.

Stabiliți dinainte ce eroare justifică revenirea și cine ia decizia. Uneori revenirea înseamnă vechiul import; alteori este suficientă restabilirea configurației de compatibilitate pentru legătura afectată.

Când este suficientă o schimbare directă

Un serviciu nou sau o aplicație mică, ale cărei componente sunt publicate împreună, poate trece direct la v2 cu verificări bine alese. Dacă aplicațiile destinatare așteaptă deja noile reprezentări, un mecanism permanent de compatibilitate poate aduce mai multă întreținere decât valoare.

Efortul merită proporționat cu efectul unei erori și cu numărul celor implicați. Păstrați compatibilitatea unde depind de ea integrări vechi și adoptați deliberat noile valori în proiectele noi. Serviciul AL+ de dezvoltare software la comandă poate fi relevant când aceste legături fac parte dintr-un proiect mai amplu.

Migrarea este încheiată când aplicațiile vizate acceptă comportamentul convenit. Simplul import nou nu poate demonstra acest lucru.