Kas yra JSON? Paprastas vadovas su pavyzdžiais

JSON (JavaScript Object Notation) yra paprastas tekstinis formatas struktūriniams duomenims aprašyti – pavyzdžiui, klientui, užsakymui ar produktų sąrašui – kaip vardus, susietus su reikšmėmis. Jį lengva skaityti žmonėms, o programoms lengva generuoti ir analizuoti. Kai programėlės ir paslaugos keičiasi duomenimis internete, JSON yra kur kas dažniausiai naudojamas formatas.

Kodėl JSON svarbus kuriant su DI

JSON sutiksite nuolat, net jei niekada nerašote kodo:

• API. Kai jūsų programėlės ekranai įkelia duomenis iš savo serverio arba serveris kviečia mokėjimų, el. pašto ar DI paslaugą, duomenys dažniausiai keliauja kaip JSON. Žr. kas yra API.
• Nustatymų failai. Daugelis projektų konfigūracijos failų yra JSON – pavyzdžiui, package.json, kuriame išvardytos JavaScript projekto priklausomybės.
• Duomenų bazės. Postgres gali saugoti JSON stulpelyje (jsonb tipas) duomenis, kurie netelpa į įprastas eilutes ir stulpelius. Žr. kas yra Postgres.
• DI išvestis. Kai norite, kad DI modelis grąžintų ką nors, ką gali panaudoti programa – žymių sąrašą, ištrauktus sąskaitos faktūros laukus – dažniausiai prašote JSON.
• Klaidų pranešimai ir žurnalai. Daugelis klaidų ateina kaip JSON, o jų skaitymas dažnai yra greičiausias būdas sužinoti, kas nutiko.

Mokėjimas skaityti JSON leidžia patikrinti, ką iš tikrųjų gavo jūsų programėlė, pastebėti trūkstamą lauką ir tiksliai aprašyti problemas savo DI kūrimo įrankiui.

Kasdienė analogija

Pagalvokite apie popierinę formą: Vardas: ____, Telefonas: ____, Naujienlaiškis: ☐ taip ☐ ne. Kiekvienas įrašas yra etiketė su reikšme šalia. JSON yra ta forma, užrašyta tekstu griežtu išdėstymu, kurį kompiuteris gali perskaityti nespėliodamas. Kaip ir formose, JSON gali turėti skyrius skyriuose (adreso blokas su gatve, miestu ir pašto kodu) ir sąrašus (keli telefono numeriai).

Kaip atrodo JSON

Štai vienas rezervavimas JSON formatu:

{
  "id": 5001,
  "customer": "Lena Park",
  "service": "Haircut",
  "startsAt": "2026-10-03T14:00:00Z",
  "price": 35.5,
  "paid": false,
  "notes": null,
  "extras": ["beard trim", "hot towel"],
  "contact": {
    "email": "lena@example.com",
    "phone": "+44 20 7946 0000"
  }
}

Kaip tai skaityti:

• Riestiniai skliaustai { } apgaubia objektą – vardų ir reikšmių porų rinkinį.
• Kiekviena pora yra "vardas": reikšmė, atskirta kableliais.
• Laužtiniai skliaustai [ ] apgaubia masyvą – sutvarkytą sąrašą.
• Objektai ir masyvai gali būti vienas kito viduje, kaip contact ir extras.

Šeši reikšmių tipai

JSON turi tik šešis reikšmių tipus. Šis nedidelis sąrašas yra didelė priežastis, kodėl jis veikia visur.

Datos tipo nėra. Datos rašomos kaip eilutės, paprastai ISO 8601 formatu, kaip parodyta aukščiau (2026-10-03T14:00:00Z, kur Z reiškia UTC). Susitarus dėl to formato, išvengiama visos laiko juostų klaidų kategorijos.

Griežtos taisyklės (iš kur kyla klaidos)

JSON yra mažiau atlaidus, nei atrodo. Visi šie pavyzdžiai yra neteisingi:

{ name: "Lena" }            ← raktas be dvigubų kabučių
{ 'name': 'Lena' }          ← vienos kabutės
{ "a": 1, "b": 2, }         ← galutinis kablelis
{ "a": 1 "b": 2 }           ← trūksta kablelio
{ "a": 1 // comment }       ← komentarai neleidžiami

Dauguma „Unexpected token“ klaidų, kurias pamatysite, yra viena iš šių. JSON tikrintuvas ar formatuoklis parodys tiksliai eilutę.

Darbo pavyzdys: JSON per programėlę

Klientas grožio salono programėlėje rezervuoja kirpimą. Štai kur atsiranda JSON:

1. Rezervavimo forma išsiunčia programėlės serveriui:

{ "service": "Haircut", "startsAt": "2026-10-03T14:00:00Z", "name": "Lena Park" }

1. Serveris išsaugo rezervavimą duomenų bazėje ir atsako su statusu 201 Created bei:

{ "id": 5001, "status": "confirmed" }

1. Jei laikas jau užimtas, jis gali atsakyti su statusu 409 Conflict ir:

{ "error": "slot_taken", "message": "That time was just booked. Please pick another." }

Puslapis perskaito status ar error ir parodo tinkamą žinutę. Jei puslapis vietoj to rodytų tuščią ekraną, naršyklės kūrėjo įrankiai (Network skirtukas) parodytų šį JSON – dažnai greičiausia užuomina, kas nutiko.

Pagrindiniai terminai

Dažni klaidingi įsitikinimai

• „JSON yra JavaScript.“ Jis kilęs iš JavaScript sintaksės, bet nepriklauso nuo kalbos; Python, Java, C#, Go ir kitos skaito jį.
• „Skaičiai kabutėse yra gerai.“ "35" yra eilutė, o ne skaičius. Jų maišymas sukelia klaidų, pavyzdžiui, "35" + "5" tampa "355". Pinigus dažnai geriau saugoti sveikais centais (3550), kad išvengtumėte apvalinimo problemų.
• „JSON yra saugus, nes tai tik duomenys.“ JSON gali nešti bet ką, įskaitant paslaptis. Nedėkite API raktų į JSON, kuris siunčiamas naršyklei.
• „Viską dėkite į JSON stulpelį.“ Patogu lanksčiems papildomiems duomenims, bet duomenys, pagal kuriuos ieškote, filtruojate ar jungiate, paprastai turi būti įprastuose stulpeliuose.
• „DI visada grąžina teisingą JSON.“ Modeliai gali pridėti papildomo teksto ar pažeisti formatą. Daugelis tiekėjų siūlo struktūruoto išvesties režimą; jūsų kodas vis tiek turėtų patikrinti, ką gauna.

Ko paklausti savo DI kūrimo įrankio

• „Parodyk pavyzdį, koks JSON grąžinamas šiam galiniam taškui.“
• „Grąžink klaidas kaip JSON su error kodu ir žmogui suprantama message.“
• „Saugok datas kaip ISO 8601 eilutes UTC ir konvertuok į vietinį laiką tik ekrane.“
• „Saugok kainas kaip sveikus centus.“
• „Tikrink gaunamą JSON serveryje ir atmesk užklausas su trūkstamais arba neteisingo tipo laukais.“
• „Kai kviečiate DI modelį, prašykite JSON tiksliai tokios formos ir prieš naudodami patikrinkite.“

JSON Mythex

Mythex rašyti JSON rankiniu būdu nereikia – aprašote, ko norite, o agentas parašo kodą, kuris jį siunčia ir skaito. Vis dėlto verta jį atpažinti: kai kas nors sugenda, įklijavus JSON klaidą į pokalbį, agentui duodama tiksli užuomina. Dokumentacijos REST API backend receptas nuo pat pradžios prašo „aiškių JSON klaidų“, o integruoti bet kokį API receptas apima išorinių paslaugų kvietimą. Platesniam vaizdui žr. REST vs GraphQL ir kaip ištaisyti DI sukurtą programėlę.

Klausimai