Գնահատել նախագիծը
← Բոլոր հրապարակումները

Protobuf սխեմաների ճիշտ էվոլյուցիան ScalaPB-ով և fs2grpc-ով

Երբ API-ները սահմանվում են Interface Description Language-ներով, սխեմաները կարող են զարգանալ ավելի ամուր և անվտանգ, քան JSON-ի վրա հիմնված հաղորդագրությունների դեպքում։ Հաղորդագրության դաշտեր ավելացնելը/հեռացնելը լիովին անվտանգ է, թե ոչ, կախված է մի քանի գործոններից։ Անդրադառնանք հաղորդակցության տարբեր եղանակներին և մտածենք, թե որն ընտրել։

9 րոպե
ScalaProtobufgRPC

Սխեմայով առաջնորդվող պարադիգմը լայն ժողովրդականություն է վաստակել հաղորդակցության բազմաթիվ մոդելներում։ Երբ API-ները սահմանվում են Interface Description Languages-ով, սխեմաները կարող են զարգանալ ավելի ամուր և անվտանգ, քան JSON-ի վրա հիմնված հաղորդագրությունների դեպքում։ Մի շարք գործոններից կախված՝ հաղորդագրության դաշտեր ավելացնելը/հեռացնելը կարող է լիովին անվտանգ լինել կամ, տեղակայումից հետո, խախտել երկուական համատեղելիությունը։ gRPC սերվիսները, event sourcing-ը և Akka Cluster-ի ակտորների հաղորդակցությունը կարող են պահանջել սխեմայի էվոլյուցիայի տարբեր քաղաքականություն. ընտրությունը կարող է նաև տարբերվել կոնկրետ wire արձանագրությունից կախված։ Անդրադառնանք հաղորդակցության տարբեր եղանակներին և մտածենք, թե երբ ընտրել backward, forward կամ full համատեղելիություն։

Տեխնոլոգիա

Այս հոդվածի ուշադրության կենտրոնում Google Protocol Buffers-ն է, AKA Protobuf՝ gRPC սերվիսների լռելյայն հիմքում ընկած արձանագրությունը և հաղորդագրությունների վրա հիմնված հաղորդակցության հզոր տարբերակ։ gRPC հաղորդակցության ոճն ունի սխեմայի փոփոխություններ թույլատրելու, պարտադիր դաշտերի և լռելյայն արժեքների իր սեփական մոտեցումը։ Եթե backend-ներ եք կառուցում Scala-ով, ScalaPB-ը թույլ է տալիս .proto պայմանագրից case class-եր գեներացնել նախագծի կոմպիլյացիայի ընթացքում։ Այս գեներացված տիպերը կարելի է ավելի ամուր դարձնել լրացուցիչ անոտացիաներով, որոնց կանդրադառնանք ստորև։

Հաղորդակցության ոճ

gRPC

Սերվիսից սերվիս սինխրոն հաղորդակցության այս ձևը շարունակում է ժողովրդականություն ձեռք բերել։ Դասական REST պայմանագրերը անհարմար են զարգացնելու համար. և դա դեռ չհիշատակելով ավելի լավ արտադրողականությունն ու streaming-ի աջակցությունը։ Լրացուցիչ խնդիր է սերվիսի կիրառման դեպքերը HTTP բայերով (POST/PUT/DELETE և այլն)՝ ռեսուրսների URL-ների հետ միասին արտահայտելը, որոնք հաճախ վատ են համապատասխանում իրական դեպքերին։ gRPC-ն լուծում է այս խնդիրները։ gRPC աշխարհում սովորաբար խոսում ենք client-ների և server-ների մասին։ Սովորաբար server սերվիսը իր պայմանագրի սեփականատերն է protobuf ֆայլերի տեսքով, որոնցից ScalaPB-ով կարելի է case class-եր գեներացնել**։** Այնուհետև fs2grpc-ը կարող է արտադրել Cats Effect-ի վրա կառուցված բարակ client շերտ, իսկ CI-ը այս ամբողջ կոդը կարող է փաթեթավորել տարբերակավորված .jar արտեֆակտի մեջ, որը server-ը հրապարակում է։ Client սերվիսներն այնուհետև կախված են այս գեներացված արտեֆակտներից։

Հաղորդագրություններ (Messaging)

Ասինխրոն, հաղորդագրությունների վրա հիմնված հաղորդակցությունը շատ առավելություններ է բերում, ինչպիսիք են անջատվածությունը (decoupling), առաքման երաշխիքները, event sourcing-ը, command sourcing-ը և այլն։ Այն կարելի է կառուցել Kafka-ի, Pulsar-ի կամ այլ ենթակառուցվածքային լուծումների վրա։ Kafka-ի դեպքում այս մոդելը հաճախ լրացվում է արտաքին Schema Registry-ով, որն օգնում է կառավարել սխեմաների համատեղելիությունը producer-ների և consumer-ների միջև։ Կենտրոնանանք հետևյալ երկու ինտեգրացիոն մոդելների վրա.

  • 1 Producer – բազմաթիվ consumer-ներ
    Սերվիսը հրապարակում է իր իրադարձությունները (events), և consumer-ները կարող են միանալ կամ հեռանալ՝ դրանք կարդալու և մշակելու համար։ Սովորաբար սխեմայի փոփոխությունները ղեկավարում է producer-ը։
  • 1 Consumer – բազմաթիվ producer-ներ
    Սերվիսը կարդում է հրամանները (commands) թոփիքից, որին կարող են հրապարակել հնարավոր client սերվիսները։ Այստեղ սխեման թարմացնում է consumer-ը, ինչը այն նմանեցնում է gRPC server-ին։
  • Նույն տիպի ակտորների միջև հաղորդակցություն
    Այս սցենարը բնորոշ է այն մոդելներին, որտեղ նույն տիպի ակտորները հաղորդագրություններ են ուղարկում միմյանց, օրինակ՝ Akka Cluster-ի ներսում։ Մանրամասն չենք անդրադառնա դրան։ Բավական է ասել, որ այն պահանջում է full համատեղելիություն, որպեսզի rolling update-ի ընթացքում ակտորները կարողանան հաղորդագրություններ փոխանակել և՛ նոր, և՛ հին տարբերակներով։

Համատեղելիության ռեժիմների համառոտ ուղեցույց

Այժմ վերը նշված Protobuf-ի կիրառությունները թարգմանենք թույլատրելի գործողությունների ցանկերի, ինչպիսիք են դաշտեր ավելացնելը/հեռացնելը, ընտրովիությունը (optionality) փոխելը և այլն։ Սկզբում՝ համատեղելիության ռեժիմների կարճ հիշեցում.

  • backward – ամենահայտնի ռեժիմը։ Տվյալների consumer-ները պետք է կարողանան սպառել տվյալների օբյեկտների ավելի հին տարբերակները։
  • forward – կիրառվում է, երբ consumer-ն ունի սխեմայի ավելի հին տարբերակ, բայց պետք է հասկանա ավելի նոր տարբերակով սերիալիզացված տվյալները։
  • full – ամենախիստ սահմանափակումը, որը պահանջում է և՛ backward, և՛ forward համատեղելիություն։

gRPC

Հարցումների (requests) համար խորհուրդ է տրվում պահպանել backward համատեղելիություն։ Server-ը սխեման թարմացնում է առաջինը՝ առանց անհանգստանալու դեռևս հին սխեմաներով client-ների հարցումների մասին, իսկ client-ներն այնուհետև աստիճանաբար թարմացնում են իրենց սխեմաները։ Պատասխանների (responses) համար պետք է ռեժիմը forward-ն է, որպեսզի client-ները դեռ կարողանան մշակել server-ից եկող նոր հաղորդագրությունները։ Նկատի ունեցեք, որ no_box wrapper-ը մանրամասն բացատրվում է ստորև՝ Ընտրովիություն բաժնում։

ռեժիմ հաղորդակցություն սցենար մեթոդ
BACKWARD gRPC հարցումներ հարցմանը ավելացնել ընտրովի դաշտ ավելացնել proto-ում
BACKWARD gRPC հարցումներ հարցման պարտադիր դաշտը դարձնել ընտրովի հեռացնել no_box (հատուկ ScalaPB-ին)
BACKWARD gRPC հարցումներ հարցման ընտրովի դաշտը դարձնել պարտադիր խախտող
BACKWARD gRPC հարցումներ հարցումից հեռացնել ընտրովի դաշտ հեռացնել proto-ից
BACKWARD gRPC հարցումներ հարցումից հեռացնել պարտադիր դաշտ հեռացնել proto-ից
BACKWARD gRPC հարցումներ հարցմանը ավելացնել պարտադիր դաշտ խախտող
BACKWARD gRPC հարցումներ հարցման oneof-ին ավելացնել դաշտ ավելացնել proto-ում
BACKWARD gRPC հարցումներ հարցման մեջ դաշտը տեղափոխել նոր oneof-ի մեջ տեղափոխել proto-ում
BACKWARD gRPC հարցումներ հարցման oneof-ից հեռացնել դաշտ խախտող**
FORWARD gRPC պատասխաններ պատասխանին ավելացնել ընտրովի դաշտ ավելացնել proto-ում
FORWARD gRPC պատասխաններ պատասխանին ավելացնել պարտադիր դաշտ ավելացնել proto-ում
FORWARD gRPC պատասխաններ պատասխանից հեռացնել ընտրովի դաշտ հեռացնել proto-ից
FORWARD gRPC պատասխաններ պատասխանի պարտադիր դաշտը դարձնել ընտրովի խախտող
FORWARD gRPC պատասխաններ պատասխանից հեռացնել պարտադիր դաշտ խախտող*
FORWARD gRPC պատասխաններ պատասխանի oneof-ին ավելացնել դաշտ խախտող**
FORWARD gRPC պատասխաններ պատասխանում դաշտը տեղափոխել նոր oneof-ի մեջ միայն ընտրովի դաշտի համար, տեղափոխել proto-ում
FORWARD gRPC պատասխաններ պատասխանի oneof-ից հեռացնել դաշտ հեռացնել proto-ից

Հիշեք, որ Protobuf-ում դաշտերի հեռացումը թույլատրելի է, քանի դեռ ինդեքսի համարը երբեք նորից չի օգտագործվում։ reserved հիմնաբառը թույլ է տալիս բացահայտ նշել, որ ինդեքսը չպետք է նորից օգտագործվի։

  • հնարավոր է որոշակի սահմանափակումներով. տե՛ս ստորև Ընտրովիություն բաժինը։
    ** Հատուկ նկատառում oneof-ների վերաբերյալ. եթե հարցումներում oneof-ի տարբերակը հեռացվում է, server-ը այդ արժեքը դեկոդավորում է որպես UNKNOWN, որը տեսականորեն հնարավոր չէ տարբերել չսահմանված արժեքից։
    Այդ պատճառով ես այն դասակարգում եմ որպես backward անհամատեղելի։ Նույն կերպ՝ oneof-ին դաշտ ավելացնելը համարվում է forward անհամատեղելի փոփոխություն։ Եթե վստահ եք, որ ձեր բոլոր client-ները օգտագործում են ScalaPB և UNKNOWN արժեքները ճիշտ եք մշակում, կարող եք նման փոփոխություններ անել, բայց շատ զգույշ։

Messaging. իրադարձություններ (events)

Այստեղ հրատարակողը (publisher) տիրապետում է պայմանագրին, իսկ consumer-ները կարդում են իր հրապարակած իրադարձությունները։ Այս ոճը հաճախ իրականացվում է .jar արտեֆակտի միջոցով՝ .proto ֆայլով և գեներացված ScalaPB դասերով ու fs2grpc սերվիսներով, որոնք server-ը պահպանում և հրապարակում է։ Սովորաբար հրատարակողն է առաջինը հարմարեցնում իր կոդը նոր պայմանագրին, իսկ consumer-ները՝ հետո։ Այնուամենայնիվ, քննարկենք բոլոր ենթադեպքերը.

  1. Եթե producer-ը պետք է իրադարձությունները թարմացնի՝ առանց consumer-ներին խախտելու, որոնք կարող են շարունակել օգտագործել հին սխեման մինչև թարմացվելը, forward համատեղելիությունը բավական է։
  2. Կամ կարող եք նախընտրել առաջինը թարմացնել consumer-ներին։ Եթե ընտրեք այդ կարգը, պետք է պահպանեք backward համատեղելիություն։ Այս մոտեցումը նկարագրված է Avro-ի և Schema Registry-ի փաստաթղթերում. նայեք՝ ավելի խորանալու համար։
  3. Full համատեղելիությունը ամենախիստ տարբերակն է։ Այն նպատակահարմար է, երբ պետք է երաշխավորել, որ consumer-ները, նույնիսկ նորագույն սխեմային հարմարեցվելուց հետո, դեռ կարողանան վերլուծել հին իրադարձությունները և առանձնահատուկ մշակել այն դաշտերը, որոնց արժեքները առկա են կամ բացակայում են։ Ընտրեք այն, երբ սպասում եք պատմական իրադարձությունների կրկնարկմանը (replay), որպեսզի consumer-ները ճիշտ մշակեն յուրաքանչյուր հին տարբերակ. օրինակ՝ event sourcing-ում։
ռեժիմ հաղորդակցություն սցենար մեթոդ
FORWARD/FULL messaging. իրադարձություններ ավելացնել ընտրովի դաշտ ավելացնել proto-ում
FORWARD messaging. իրադարձություններ ավելացնել պարտադիր դաշտ ավելացնել proto-ում
FULL messaging. իրադարձություններ ավելացնել պարտադիր դաշտ խախտող
FORWARD/FULL messaging. իրադարձություններ հեռացնել ընտրովի դաշտ հեռացնել proto-ից
FORWARD ONLY messaging. իրադարձություններ ընտրովի դաշտը դարձնել պարտադիր ավելացնել no_box
FULL messaging. իրադարձություններ ընտրովի դաշտը դարձնել պարտադիր խախտող
FORWARD/FULL messaging. իրադարձություններ պարտադիր դաշտը դարձնել ընտրովի խախտող*
FORWARD/FULL messaging. իրադարձություններ հեռացնել պարտադիր դաշտ խախտող
FORWARD/FULL messaging. իրադարձություններ oneof-ին ավելացնել դաշտ խախտող
FORWARD/FULL messaging. իրադարձություններ դաշտը տեղափոխել նոր oneof-ի մեջ տեղափոխել proto-ում (միայն ընտրովի)
FORWARD ONLY messaging. իրադարձություններ oneof-ից հեռացնել դաշտ հեռացնել proto-ից
FULL messaging. իրադարձություններ oneof-ից հեռացնել դաշտ խախտող

Messaging. հրամաններ (commands)

Այս ռեժիմը սերտորեն նման է GRPC հարցումների մշակմանը։ Պայմանագրի սեփականատերը հրամանների մշակիչն է, ուստի այն պետք է մնա backward համատեղելի։

ռեժիմ հաղորդակցություն սցենար մեթոդ
BACKWARD messaging. հրամաններ ավելացնել ընտրովի դաշտ ավելացնել proto-ում
BACKWARD messaging. հրամաններ ավելացնել պարտադիր դաշտ խախտող
BACKWARD messaging. հրամաններ հեռացնել պարտադիր դաշտ հեռացնել proto-ից
BACKWARD messaging. հրամաններ հեռացնել ընտրովի դաշտ հեռացնել proto-ից
BACKWARD messaging. հրամաններ պարտադիր դաշտը դարձնել ընտրովի հեռացնել no_box
BACKWARD messaging. հրամաններ ընտրովի դաշտը դարձնել պարտադիր խախտող
BACKWARD messaging. հրամաններ oneof-ին ավելացնել դաշտ ավելացնել proto-ում
BACKWARD messaging. հրամաններ oneof-ից հեռացնել դաշտ խախտող
BACKWARD messaging. հրամաններ դաշտը տեղափոխել նոր oneof-ի մեջ տեղափոխել proto-ում

Ընտրովիություն և no_box

Տարբերակ 3-ից սկսած՝ Protobuf արձանագրությունն այլևս չի թույլատրում required դաշտեր, և optional-ը լռելյայն է։ Հիմնավորումն այն է, որ պարտադիր դաշտեր ավելացնելու/հեռացնելու հնարավորությունը հանգեցնում էր wire համատեղելիության անսպասելի խախտման հետ կապված չափազանց շատ խնդիրների (տե՛ս սկզբնական մեկնաբանությունը GitHub-ում)։

Այդուհանդերձ, ինչպես ցույց են տալիս վերը բերված աղյուսակները, որոշ սցենարներում պարտադիր դաշտերը խելամիտ են։ Օրինակ՝ BACKWARD համատեղելիության դեպքում լիովին ընդունելի է սկզբնական սխեմայում սկսել պարտադիր դաշտերով և հետագայում հեռացնել դրանք։ Սա վերաբերում է gRPC հարցումներին և ասինխրոն հրամաններին։ ScalaPB-ին խանգարելու համար, որ ոչ պրիմիտիվ տիպերը փաթաթի Option-ի մեջ, ավելացրեք no_box անոտացիա, օրինակ.

google.protobuf.Timestamp createdAt = 1 [(scalapb.field).no_box = true];

Պարտադիր դաշտերի հեռացումը խախտում է FORWARD համատեղելիությունը, բայց որոշակի իրավիճակներում այս գործողությունը կարելի է կատարել փուլերով.

  • Պարտադիր դաշտը դարձնել ընտրովի՝ հեռացնելով no_box wrapper-ը
  • Թարմացնել բոլոր consumer-ներին, որպեսզի մշակեն None դեպքը
  • Սկսել արտադրել None դեպքը

Զգույշ եղեք։ Սա վտանգավոր գործողություն է։ Այն լիովին չի համապատասխանում մեր համառոտ ուղեցույցի համատեղելիության կանոններին, ուստի ես այն դեռ համարում եմ «խախտող»։

Լռելյայն արժեքներ

ScalaPB-ն պրիմիտիվ protobuf տիպերը, ինչպիսիք են string-ը, double-ը և այլն, չի փաթաթում Option-ի մեջ։ Փոխարենը սահմանվում են լռելյայն արժեքներ, օրինակ՝ դատարկ տողը «»։ Սա կարող է բավական վտանգավոր լինել, քանի որ շատ դեպքերում այդպիսի լռելյայն արժեքները իրականում անվավեր են. ուստի եթե case class կառուցելիս դաշտը բաց թողնեք, դժվարության մեջ կընկնեք։ Տիպերի անվտանգությունը բարելավելու համար կարող եք ընտրել երկու մոտեցումներից մեկը.

  • Ձեր .proto ֆայլում դնել no_default_values_in_constructor, որը պարզապես անջատում է լռելյայն արժեքները։ Թերությունը. դաշտը դառնում է խիստ պարտադիր, և այն հետագայում ընտրովի դարձնելու պարզ միջոց չկա։

    option (scalapb.options) = {
    no_default_values_in_constructor: true
    };
  • Հենվել wrapper տիպերի վրա
    Դրանք կարող են աղմուկ ավելացնել կոդին, քանի որ իրական արժեքին հասնելու համար լրացուցիչ .value կանչեր են պետք, բայց no_box-ի հետ միասին այս մոտեցումը ձեզ ավելի լավ վերահսկողություն է տալիս ընտրովիության էվոլյուցիայի նկատմամբ։

Բոնուս. buf

Protobuf ֆայլերի պահպանումը, պայմանագրի տարածումը, համատեղելիության կանոնների կիրառումը և API նախագծման կանոնների համահունչ հավաքածուի պահպանումը պահանջում են զգալի ներդրում։ buf-ը հետաքրքիր գործիքակազմ է, որը նախատեսված է այս գործընթացներն ավտոմատացնելու համար։ Այն ներառում է նոր կառուցված բարձր արտադրողականության Protobuf կոմպիլյատոր, լինտեր, որը ապահովում է API նախագծման առողջ ընտրություններ և կառուցվածք, խախտող փոփոխությունների դետեկտոր, որը կիրառում է համատեղելիություն սկզբնական կոդի կամ wire մակարդակում, և գեներատոր, որը գործարկում է ձեր protoc պլագինները կարգավորելի կաղապարի համաձայն։ Այն ներառում է նաև The Buf Schema Registry (BSR)-ը՝ հոսթվող SaaS հարթակ, որը ծառայում է որպես ձեր կազմակերպության Protobuf API-ների ճշմարտության աղբյուր։ Մտածեք buf-ի մասերը ձեր նախագծի pipeline-ում ներառելու մասին՝ Protobuf-ի հետ աշխատանքից ավելի շատ օգուտ քաղելու համար։

Եզրակացություններ

Ձեր սխեմաներին ինչ համատեղելիության պահանջներ են պետք, կախված է բազմաթիվ գործոններից։ ScalaPB-ի ընդլայնումները, ինչպիսիք են պարտադիր դաշտերը կամ անջատված լռելյայն արժեքները, կարող են բարձրացնել տիպերի անվտանգությունը հավելվածի կողմում՝ առանց զոհաբերելու Protobuf wire համատեղելիությունը, պայմանով, որ էվոլյուցիայի կանոնները լավ համապատասխանեն կիրառման դեպքին։ Հուսով եմ՝ այս ուղեցույցը կօգնի ձեզ կարգավորել այդ կանոնները ձեր կոնկրետ հավելվածի համար, կամ նույնիսկ լիովին ավտոմատացնել դրանց կիրառումը։