--- title: "Apache Avro: sopimus moduulien välillä" url: "https://hurukan.com/fi/blog/apache-avro-sopimus-moduulien-valilla" description: "Jokainen moduulien välinen tapahtuma on sopimus. Avro kirjoittaa sen dataan, ja skeemamuutoksesta tulee ehdotus, jonka ihminen hyväksyy." --- # Apache Avro: sopimus moduulien välillä 2\. syyskuuta 2026·3 min lukuaika·Toimitus Kaksi insinööriä takaapäin kuvattuna yhteisen pöydän ääressä hiljaisessa toimistossa, heidän välissään suuri seinänäyttö, jossa abstrakti sinertävänharmaa kaavio lomakkeesta ja sen versioista, tulostettu arkki toisen käden alla, yksi sininen tilavalo näytön kehyksessä Kauppatiimi lisää tilaukseen alennusprosentin. Se on pieni muutos, josta sovittiin kokouksessa, ja tilauksia luova moduuli alkaa lähettää sitä samana iltapäivänä. Talousmoduuli, joka on lukenut tilauksia kaksi vuotta, ei tunne kenttää ja lakkaa hyväksymästä viestiä. Kukaan ei aikonut muuttaa sopimusta. Sopimus oli olemassa, sitä ei vain ollut kirjoitettu mihinkään muualle kuin kahteen koodinpätkään, jotka ennen olivat samaa mieltä. Järjestelmässä, joka on rakennettu tapahtumia vaihtavista moduuleista, jokainen tapahtuma on sopimus. Apache Avro on yksi muodoista, jotka kirjoittavat tuon sopimuksen itse dataan, ja syy siihen, miksi se on Hurukanin rakenteilla olevan [datakerroksen](https://hurukan.com/fi/system/data) suunnitelmassa, liittyy vähemmän tavuihin kuin siihen, mitä tapahtuu, kun sopimusta on muutettava. ## Skeema kulkee datan mukana Avro-tietue on tiivis binäärinen rivi. Yksinään sitä ei voi lukea: kenttien nimet, tyypit ja järjestys eivät ole tavuissa. Ne ovat skeemassa, joka on kirjoitettu JSON-muodossa, ja [spesifikaatio](https://avro.apache.org/docs/1.12.0/specification/) määrittelee pienen joukon tyyppejä sen kirjoittamiseen: null, boolean, int, long, float, double, bytes, string sekä yhdistetyt record, enum, array, map, union ja fixed. Kentällä voi olla oletusarvo, ja juuri se oletusarvo tekee muutoksesta myöhemmin selviytyvän. Nykyinen julkaisu on 1.12.2 ([projektin blogi](https://avro.apache.org/blog/), tarkistettu 21. lokakuuta 2026). Skeema saavuttaa lukijan kahdella tavalla. Tiedostossa Object Container File -muoto sijoittaa skeeman otsikkoon, jota seuraavat synkronointimerkillä erotetut tietuelohkot, joten vuosia myöhemmin löydetty tiedosto selittää yhä itsensä. Viestiväylällä, jossa skeeman lähettäminen jokaisen tapahtuman mukana olisi tuhlausta, spesifikaation yksittäisen objektin koodaus (single-object encoding) sijoittaa jokaisen tietueen eteen kahden tavun merkin ja kahdeksan tavun sormenjäljen skeemasta; rekisteri säilyttää skeeman tuon sormenjäljen alla. Laajalti käytetty Confluentin rekisteri tekee saman omalla kehystyksellään: taikatavu ja neljän tavun skeematunniste ennen Avro-tavuja ([Confluentin dokumentaatio](https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/index.html)). Kummallakin tavalla lukija ei koskaan arvaa. Sillä on kirjoittajan skeema ja omansa, ja loppu on sääntöjä. ## Tulkinta: miten lukija kohtaa kirjoittajan, jota se ei ole koskaan nähnyt Spesifikaatio määrittelee, mitä tapahtuu, kun kirjoittajan ja lukijan skeemat eroavat. Kentät sovitetaan nimen mukaan. Kenttä, jonka kirjoittaja lähetti mutta jota lukijalla ei ole, ohitetaan. Kenttä, jota lukija odottaa mutta jota kirjoittaja ei lähettänyt, täytetään lukijan oletusarvosta, ja jos oletusarvoa ei ole, luku epäonnistuu selkeällä syyllä. Jotkin tyypit voidaan korottaa matkalla: int voidaan lukea longina, long floatina tai doublena, float doublena, ja string ja bytes voidaan lukea toisinaan. Union sovitetaan lukijan puolen ensimmäiseen yhteensopivaan haaraan. Kirjoitettuina nuo säännöt ovat alennuskentän koko kuri. Lisää se oletusarvolla, ja talousmoduuli jatkaa lukemista ohittaen kentän, kunnes se opetetaan käyttämään sitä. Lisää se ilman oletusarvoa ja poista vanha kenttä samassa muutoksessa, ja yrityksen vanhin lukija pysähtyy. Säännöt eivät ole neuvoja; ne ratkaisevat, minkä version aamusta saat. ## Skeemamuutos ehdotuksena Hurukanissa suunnitelma on, että tapahtumaskeema on ontologian objekti siinä missä muutkin: sillä on omistaja, versiot ja paikka rekisterissä. Se muuttaa alennuskentän iltapäivän koodimuutoksesta lyhyeksi, kirjatuksi poluksi. **Agentti ehdottaa.** Kauppamoduuli tarvitsee uuden kentän; agentti luonnostelee skeemamuutoksen oletusarvoineen, tyyppeineen ja perusteluineen ja nimeää moduulit, jotka lukevat tätä tapahtumaa. **Rekisteri tarkistaa.** Ehdotettu versio testataan lukijoiden skeemoja vasten yllä olevien tulkintasääntöjen mukaan. Muutos, joka pysäyttäisi olemassa olevan lukijan, hylätään ennen kuin kukaan näkee sen, ja lukija nimetään. **Omistaja hyväksyy.** Yhteensopiva muutos on silti muutos moduulien väliseen sopimukseen. Tapahtuman omistaja, ihminen, hyväksyy sen, ja vasta sitten tuottajat alkavat kirjoittaa uutta versiota. **Rekisteri säilyttää sen.** Hyväksyntä, versio ja aika kirjoitetaan rekisteriin, joten vuotta myöhemmin kysymykseen «milloin alennukset ilmestyivät tilauksiin, ja kuka sen salli» on vastaus. Se on sama polku, jonka jokainen järjestelmän muutos kulkee: agentti ehdottaa, ihminen päättää, järjestelmä kirjaa. Laajempi ajatus on tekstissä [nykytila ja rekisteri](https://hurukan.com/fi/blog/nykytila-ja-rekisteri-kaksi-muistia). ## Mihin Avro ei ole tarkoitettu Avro kantaa tapahtumia hyvin ja lukee kokonaisia tietueita hyvin. Se on huono asettelu kysymykselle, jonka superäly useimmin esittää — muutama kenttä miljoonan rivin yli — koska jokainen kenttä on jokaisen toisen tiellä. Siksi suunnitelmassa Avro-tapahtumat kootaan erissä sarakkeiksi, kun ne on hyväksytty. Se, mikä muoto kuuluu minnekin, esitetään tekstissä [Parquet ja Avro: tapahtuma ja rekisteri](https://hurukan.com/fi/blog/parquet-ja-avro-tapahtuma-ja-rekisteri). Avro esiintyy myös paikassa, johon harva katsoo: taulumuoto Apache Iceberg kirjoittaa manifestinsa, luettelot taulun muodostavista datatiedostoista, Avro-tiedostoina ([Icebergin spesifikaatio](https://iceberg.apache.org/spec/)). Rivimuoto, joka kantaa tapahtumia moduulien välillä, kantaa myös rekisterin kirjanpitoa. ## Mikä jää ihmisille Agentti voi luonnostella skeeman, ajaa yhteensopivuustarkistuksen ja nimetä lukijat. Se ei voi päättää, että kenttä, johon talousmoduuli luotti, saa poistua, että oletusarvo nolla on tosi väite vanhoista tilauksista tai että lukijan saa antaa epäonnistua. Ne ovat päätöksiä liiketoiminnan merkityksestä, ja Hurukanissa ne tekee tapahtuman omistaja ja ne kirjataan ylös. ## Testi, jonka voit tehdä tänään Valitse yksi viesti, joka liikkuu kahden järjestelmänne välillä. Selvitä, missä sen kentät on määritelty. Jos vastaus on «lähettävässä koodissa» ja «vastaanottavassa koodissa», teillä on kaksi määritelmää eikä sopimusta. Kysy sitten, kuka hyväksyisi kentän lisäämisen siihen, nimeltä. Jos nimeä ei ole, seuraavan kentän lisää se, joka sitä ensimmäisenä tarvitsee, ja sen huomaa se, jolta se rikkoo jotain. [Datakerroksen](https://hurukan.com/fi/system/data) sivu kuvaa, missä tuon sopimuksen on tarkoitus asua Hurukanissa; [yleiskatsaus](https://hurukan.com/fi) näyttää moduulit sen ympärillä. - Apache Avro - skeemarekisteri - tapahtumasopimukset - skeeman evoluutio - datakerros ## Lue lisää - [Yksi identiteetti ihmisille ja agenteille: kuka saa tehdä mitä](https://hurukan.com/fi/blog/yksi-identiteetti-ihmisille-ja-agenteille) - [Nykytila ja rekisteri: yrityksen käyttöjärjestelmän kaksi muistia](https://hurukan.com/fi/blog/nykytila-ja-rekisteri-kaksi-muistia)