Versija 1.0.0-alpha.1jaunākā
2.21. nodaļa
Spraudņu SDK
Spraudņu SDK (programmatūras izstrādes komplekta) instalēšana, tā komandrindas rīki, pilna servisa veidnes apskats, v2 manifesta lauku apraksts un divdesmit divas kontroles barjeras, kas nodrošina spraudņa atbilstību noteikumiem.
Šo lapu no oriģināla angļu valodā ir tulkojis MI. Neskaidrību gadījumā par pamatu jāņem lapa angļu valodā. Lasīt šo lapu angļu valodā

Mana otrā spraudņa izstrāde aizņēma trešdaļu no pirmā spraudņa laika, un gandrīz visu ietaupījumu nodrošināja SDK (programmatūras izstrādes komplekts). Pirmajā reizē es uzrakstīju tvēruma pārbaudi, konfigurācijas ielādētāju un migrācijas izpildītāju, un recenzents katru no tiem nosūtīja atpakaļ. Otrajā reizē es izpildīju vienu karkasa izveides komandu, izdzēsu parauga noskaņojuma prasmi un veltīju savas dienas anomāliju pārskata ierakstiem, kas mūsu lidojumu dinamikas komandai patiešām bija nepieciešami.
@adverant-nexus/plugin-sdk ir viena npm pakotne. Tajā ir v2 manifesta shēma un validatori, kas to lasa (definePlugin, defineSkill), izpildlaika moduļi, ko jūsu spraudnis importē tvērumam, datubāzei, nosūtīšanai un pārējam, testēšanas palīgrīki, atbilstības vārti un komandrindas rīki. Šajā nodaļā ir apskatīta tās instalēšana, rīki, veidne, manifests un vārti. 2.22. nodaļā, Spraudņa izpildlaiks, ir apskatīti izpildlaika moduļi jūsu darbojošajā kodā.
Instalēšana
Pakotne nāk no Adverant reģistra vietnē https://registry.adverant.ai/npm/, nekad no publiskā npm reģistra, un jums ir nepieciešama izgūšanas pilnvara no jūsu konta lapas "Pull tokens and install commands". Norādiet @adverant-nexus tvērumu uz reģistru savas krātuves failā .npmrc:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> ir pilnvara no jūsu konta lapas. Konveijerā padodiet to no noslēpuma un nekad neapstipriniet krātuvē; veidnes Dockerfile atsakās būvēt bez tās un izdzēš .npmrc no būvēšanas posma, tiklīdz npm ci ir izpildīts, tādēļ pilnvara nekad nenonāk attēlā.
Pēc tam precīzi piesaistiet versiju:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Apstipriniet package-lock.json pirmajā instalēšanas reizē. Veidnes attēla būvēšana izpilda npm ci un atsakās atkāpties uz npm install: bloķēšanas fails ir līgums. Paša SDK minimālā prasība ir Node 18; veidnes mērķis ir Node 20.
Komandrindas rīki tiek piegādāti pakotnes iekšienē, tāpēc katra komanda šajā dokumentācijā nosauc pakotni un tās versiju ar npx -p. Atsevišķi npx create-nexus-plugin tiek meklēts publiskajā reģistrā, un šis nosaukums nav šī pakotne.
Komandrindas rīki
| Rīks | Ko tas dara |
|---|---|
create-nexus-plugin |
Izveido spraudņa karkasu, validē manifestu, migrē v1 manifestu uz v2 un atveido patērētāja ceļvedi jūsu priekšgala izstrādātājam |
nexus-tenancy |
No manifesta atveido jūsu shēmas nomnieku izolācijas SQL: lomas, piešķīrumus, rindu līmeņa drošības veidni un grafa tabulas |
nexus-migrate |
Lieto jūsu migrācijas: vienreiz nodrošina lomas, pēc tam izpilda katru numurēto failu kā migratora loma |
nexus-gates |
Izpilda katrus atbilstības vārtus un katru vārtu paštestu |
create-nexus-plugin neveic tīkla izsaukumus un neielādē attālinātu kodu. Tas izpilda tos pašus iekšprocesa validatorus, ko izpilda platformas pievienošanas process, tāpēc nav novirzes starp "tas tika validēts manā datorā" un "platforma to pieņēma".
| Komanda | Karodziņi | Ko tas dara | Izejas kodi |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Ieraksta jaunu spraudņa direktoriju; --print izdrukā tikai manifestu |
0 ierakstīts · 1 atteicās pārrakstīt · 2 nepareizs lietojums |
validate <file> |
Validē nexus.manifest.json vai .ts vai .js moduli, kas to eksportē |
0 derīgs · 1 nederīgs vai nelasāms · 2 nepareizs lietojums | |
migrate <file> |
--write |
Paceļ v1 manifestu uz v2 un izdrukā to vai ieraksta to esošajā vietā | 0 · 1 · 2, kā norādīts iepriekš |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Atveido patērētāja ceļvedi no manifesta un jūsu apraksta; --check salīdzina ar krātuvē apstiprināto kopiju un neko neieraksta |
0 · 1 novirze vai koda kvalitātes pārkāpums · 2 nepareizs lietojums |
help |
Izdrukā lietojumu | 0 |
Sagataves izveide un trīs līmeņi
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier noklusējuma vērtība ir full-service. Karkasa veidotājs atsakās rakstīt direktorijā, kas jau pastāv, un manifests, ko tas ieraksta, jau iziet validāciju; tas nekad neizdod nederīgu manifestu.
Izvēlieties līmeni pēc tā, kas ir jūsu spraudnim.
| Līmenis | Ir | Jādeklarē |
|---|---|---|
skills-only |
Manifesta prasmes un nekas cits | skills[], ar vismaz vienu ierakstu |
ui-only |
Priekšgala virsma čaulas iekšienē | frontend |
full-service |
Aizmugursistēma un priekšgals, parasti ar savu shēmu | backend un frontend; un, tā kā tam ir aizmugursistēma, runtime.healthCheck |
Ja neesat pārliecināts, izveidojiet full-service karkasu un izdzēsiet to, kas jums nav nepieciešams. Darot pretēji, būs jāuzraksta daļas, kuras jums būtu devusi veidne.
Pilna servisa veidnes apskats
Veidne ir atsauces spraudnis, kas uzbūvēts pēc stingra parauga, kuru pieņem katra nākamā nodaļa. Klonējiet tās formu, nevis parauga loģiku.
| Ceļš | Kas tas ir |
|---|---|
nexus.manifest.json |
v2 manifests: no jauna formulētie trīs likumi, maršrutu tabula un tās tiesību reģistrs |
src/config.ts |
Konfigurācijas ielādētājs. Viena specifikācija, nolasīta vienreiz, katra problēma apkopota, pirms process atsakās sāknēties |
src/scope.ts |
Vienīgais fails, kas pārvērš pieprasījumu par tvērumu, ar SDK stingro pilnvaru pārbaudītāju un diviem režīmiem: personas uzrādītāja pilnvaru un platformas pakalpojuma izsaukumu |
src/db.ts |
Katrs priekšraksts veido tenantFence() un darbojas withScopedTx iekšienē |
src/uno.ts |
Vienīgais nosūtīšanas fails: viens URL, viens klients, slēgts atļauto saraksts |
src/routes/*.ts |
health (anonīms, precīzs ceļš), /api maršruti (ar tvērumu) un /internal atpakaļizsaukums (pakalpojuma aizsargāts) |
src/skills/sentiment.ts |
Deterministiska host_callback prasme; aizstājiet leksikonu ar savu loģiku |
src/server.ts |
Kompozīcijas sakne: vienreiz instalē atteikumu virsgrāmatu, gaida datubāzi (ierobežoti), pēc tam pirms klausīšanās izpilda izolācijas un virsgrāmatas pārbaudes |
migrations/000_tenancy.sql |
Atveido nexus-tenancy render karkasa izveides laikā: lomas, shēma, rindu līmeņa drošības veidne |
migrations/001_init.sql |
Divas tabulas ar nomnieka vadošo salikto atslēgu un saliktu, nomnieku nesošu ārējo atslēgu |
migrations/002_refusal_ledger.sql |
Tabula, kurā raksta atteikumu virsgrāmata |
scripts/ci/required-env |
Izdrukā sāknēšanai nepieciešamo vides mainīgo nosaukumus kā JSON |
scripts/ci/shadow-migrate-*.sh |
Konveijera migrācijas izmēģinājuma izpilde caur nexus-migrate |
gates/ |
Vārtu izņēmumu direktorijs: tukšs, kas ir pareizais stāvoklis jaunam spraudnim |
test/ |
Testi tvērumam, maršrutiem, datubāzei, nosūtīšanai un sāknēšanai, ar tvēruma dublikātiem, ko ievada katrs tests |
Dockerfile |
Ne-saknes attēls (lietotāja ID 10001) ar migrācijām tā iekšienē |
Dažus no šiem failiem ir vērts apskatīt tuvāk.
src/config.ts ievēro divus noteikumus. Tas apkopo katru problēmu, pirms izmet kļūdu, tāpēc viena restartēšana nosauc visus piecus trūkstošos mainīgos, nevis piecas restartēšanas nosauc pa vienam katrā. Un tas iestata noklusējuma vērtību tikai tad, kad nepareiza vērtība nevar radīt klusu nepareizu atbildi: PORT noklusējuma vērtība var būt 8080, jo nepareizs ports redzami neizdodas piesaistē, kamēr DATABASE_URL un UNO_DISPATCH_URL ir obligāti un tiem jābūt klastera iekšējām adresēm. Publiska adrese sāknēšanas laikā tiek atteikta.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Pašas veidnes tests izpilda šo failu un salīdzina tā izvadi ar nosaukumiem, ko konfigurācijas specifikācija atzīmē kā obligātus, tāpēc obligātā mainīgā pievienošana, neatjauninot sarakstu, izraisa npm test kļūmi.
src/server.ts neklausās, kamēr datubāze neatbild, un tas ierobežo gaidīšanu līdz 120 sekundēm, reģistrējot katru neveiksmīgo mēģinājumu ar tā cēloni. Pēc tam tas secīgi pierāda, ka lietotnes loma nevar atkārtoti piesaistīt nomnieku un katrai tabulai ir piespiesta rindu līmeņa drošība, ka katra poda pūls atbilst lomas savienojumu limitam un ka atteikumu virsgrāmatas tabula var pieņemt rindu. Atteikums no jebkura no šiem trim tiek izdrukāts pilnībā, un process beidzas ar kodu 2.
v2 manifests, lauku pa laukam
Manifests ir spraudņa mašīnlasāms līgums ar platformu. Tas tiek validēts, kad jūs to veidojat, kad platforma to pievieno, un nepārtraukti pēc tam. Shēma ir additionalProperties: false katrā līmenī: ja jūsu spraudnim ir sadaļa, tai ir rekvizīts, un nedeklarēta atslēga tiek atteikta. Risinājums vienmēr ir izmantot pareizo neobligāto rekvizītu.
Obligātais kodols
| Lauks | Noteikums |
|---|---|
manifestVersion |
Tieši "2". v1 dokuments tiek migrēts, nekad netiek atkārtoti validēts esošajā vietā |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, ne vairāk kā 64 rakstzīmes. Spraudņa id, ko izmanto reģistrācijā, nosūtīšanas nosaukumvietu piešķiršanā un nomnieka tvēruma rindās. Spraudnim, kas deklarē prasmes, ir nepieciešams arī nosaukums bez punkta un bez vadošā cipara |
displayName |
No 1 līdz 120 rakstzīmēm |
version |
Semantiskā versija; jūsu pašu laidienu cikls |
description, author, license |
Vismaz viena rakstzīme katrā |
tier |
skills-only, ui-only vai full-service |
trust |
core, verified, community vai untrusted |
runtime |
Obligāti: executionMode, isolationLevel (no 1 līdz 4), entrypoint. Neobligāti: nodeVersion, healthCheck, readinessCheck, livenessCheck, katrs ir ceļš, kas sākas ar /. Režīms tiek atvasināts no līmeņa: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai un deploy, no jauna formulētie trīs platformas likumi. Validators fiksē formulējumu |
Spraudnim, ko būvējat savai instalācijai, trīs teikumi ir šādi. ai teikums attiecas uz mākslīgo intelektu (MI) un ir vieta, kur norādīt, ka spraudnis neglabā modeļu akreditācijas datus.
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}Maršrutu tabula: api un rights
api ir nepieciešams version un basePath, un neobligāti websocket (path, auth) un endpoints[]. Maršrutu tabula ir spēcīgākā ideja shēmā: vārti salīdzina to ar maršrutiem, kurus jūsu kods patiešām reģistrē, abos virzienos, tāpēc manifests ir pārbaudāms līgums, nevis dokumentācija.
Katram galapunktam ir nepieciešams method (GET, POST, PUT, PATCH vai DELETE) un path. Pārējais:
| Lauks | Ko tas norāda |
|---|---|
auth |
Viena no piecām klasēm: scope (personas maršruts, aiz tvēruma sarga), service-key un internal (no servera uz serveri, nekad nav sasniedzams no pārlūkprogrammas), public (vienmēr tikai precīzs ceļš ar allowAnonymous) un device (mašīna ar saviem akreditācijas datiem, aiz ierīces sarga) |
right |
Obligāts katrā maršrutā, ko apkalpo tvēruma sargs, un atteikts jebkurā citā: tiesību nosaukums rights reģistrā |
needsUnit |
Maršruts atsaka, ja nevar atrisināt izsaucēja vienību |
allowAnonymous |
Tikai precīzas atbilstības atļauto saraksts. Prefiksa noteikums ir veids, kā /health-of-tenant-42 kļūst publisks |
group, serves, screens |
Zem release bloka: spēju grupa, ko maršruts apkalpo, ko tas atbild, kad šīs grupas licencētais līdzeklis ir bloķēts (data, teaser, sighting vai ask), un ekrāni, ko tas apkalpo |
query |
required (katrs nosaukums ar piemēra vērtību) un allowed: vaicājuma parametri, kurus maršruts lasa |
body |
example: rakstīšanas maršruta piemēra pamatteksts, tāds, ko pieņem tā paša validators. Nekad uz GET |
rights ir reģistrs, ko šie maršruti nosauc. Katrām tiesībām ir roles (griesti) un neobligāti summary, never (lomas, kas nekad nedrīkst tās izmantot, neatkarīgi no tā, kas vēl tām pieder), barred (paša produkta vārdi never lomas atteikšanai), seat (ir nepieciešama arī aktīva sēdvieta), self (tās pieder katrai verificētai personai, tiesībām pār savu sesiju), grants (turētāji piešķir sēdvietas; ne vairāk kā vienas tiesības tā nosaka), licence (licencēts līdzeklis, kas jāietver organizācijas licencei) installation (pieder tikai pašas instalācijas administratoriem) un platform (pieder tikai Adverant platformas administratoriem; tas nenosauc nekādas lomas). Tiesību nosaukumos ir vismaz viens punkts: project.read, money.pay.
"api": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
{ "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
{ "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
]
},
"rights": {
"project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
"project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}definePlugin atsaka tvēruma maršrutu bez tiesībām (ENDPOINT_RIGHT_MISSING), tiesības, kuru trūkst reģistrā (ENDPOINT_RIGHT_NOT_REGISTERED), un tiesības maršrutā, ko neapkalpo neviens sargs (ENDPOINT_RIGHT_UNGUARDED). Tas atsaka arī reģistru, kas ir pretrunā pats ar sevi, un divus viena maršruta pierakstus (:id un :recordId) kā DUPLICATE_ENDPOINT.
Jūsu dati: databases, schema un db
schema ir vienīgā Postgres shēma, kas pieder spraudnim. public, plugins, auth un nexus ir aizliegti, un, ja databases[] arī nosauc Postgres shēmu, abām ir jāsakrīt.
databases[] deklarē katru krātuvi pēc dzinēja: postgresql (schema, tables, migrations un granted, tabulas, kuras cita organizācija var lasīt saskaņā ar reģistrētu piešķīrumu), neo4j (schemas), qdrant (collections) vai redis (purpose).
db glabā sesijas limitus katram savienojumam, ko spraudnis atver, un tie ir deklarēti šeit, nevis iekodēti, lai gan recenzents, gan izvietojums varētu tos izlasīt:
| Lauks | Ko tas ierobežo |
|---|---|
maxConnections |
Pūls uz vienu repliku |
pods |
Maksimālais podu skaits, kas vienlaikus tur pūlu, replikas plus pakāpeniskās atjaunināšanas pieaugums. Katras lomas savienojumu limits tiek atveidots kā maxConnections × pods; ja to izlaidīsiet, definePlugin brīdinās DB_PODS_UNDECLARED |
statementTimeoutMs |
Viens priekšraksts |
idleInTransactionTimeoutMs |
Atvērta transakcija, kas neko neizpilda |
workMemKB |
Viens kārtošanas vai jaukšanas mezgls, uz vienu mezglu, nevis uz vienu vaicājumu |
piiMask[] |
table.column ieraksti, kas satur personas datus, maskēti pārvaldītajā SQL konsolē un žurnālos |
Prasmes un rīki: skills, mcpTools, entitlements
skills[] glabā manifesta prasmes; 2.20. nodaļā, Prasmes, ir apskatīti to lauki un līmeņi. mcpTools[] glabā MCP (Model Context Protocol) rīkus, ko spraudnis publicē, kur katrs ir name, description un inputSchema bez augšējā līmeņa oneOf, allOf vai anyOf.
entitlements pieprasa featureIdPattern un pieņem alwaysOn[], source un store. Paraugs nosauc nosaukumvietu, kurā atrodas jūsu līdzekļu id, parasti spraudņa name plus viens segments, ko jūsu kods aizpilda katrai virsmai. alwaysOn[] ir īss, precīzs saraksts, kam jāatbild pat tad, ja nevar iegūt tiesību spriedumu: veselība, gatavība, pierakstīšanās un iestatījumi, kas administratoram nepieciešami tiesību salabošanai.
Izmaiņu vadība: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Apstiprinājumi tiek skaitīti kā atšķirīgas personas, un persona, kas ierosināja izmaiņas, nekad nav viena no tām; bez abām šīm daļām "divi apstiprinājumi" kļūst par vienu personu, kas noklikšķina divreiz. enabled: true pieprasa classes, un katrai nosauktajai klasei ir nepieciešams savs skaits. Klase, kuru izlaižat, ir nepārvaldīta, kas ir leģitīma izvēle, kuru shēma liek jums pierakstīt.
Kas jūs esat: domains, branding, routing
domains[] (katrs primary un aliases[]; domain ir viena domēna forma) uzskaita, kur spraudnis atbild. branding pieprasa appName un pieņem tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId un gaId. Viss iekš branding ir publisks: pierakstīšanās lapa to izlasa, pirms kādam ir akreditācijas dati, tāpēc tajā nekad nav noslēpuma vai iekšējās adreses. routing (type, gateway, virtualService) ir paredzēts spraudņiem, kas apraksta paši savu maršrutēšanu.
Izmēru noteikšana un pārējais
resources pieprasa cpuMillicores (no 10 līdz 64,000) un memoryMB (no 16 līdz 262,144), un pieņem diskGB, timeoutMs, port un wsPort. backend glabā port, healthPath, apiPrefix, framework un platformClients[], SDK klientus, kurus jūsu aizmugursistēma importē pēc nosaukuma. Saraksts ir slēgts, un vārti pārbauda to pret jūsu importiem. Shēma atļauj četrpadsmit nosaukumus: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin un uno, plus vienu klientam, kas atbild uz plāna tiesību atteikumiem, kurš saglabā iekšēju nosaukumu. Līdzekļu tiesību klients, runtime/entitlements, nav viens no tiem un nekad nenonāk sarakstā, jo jūsu entitlements bloks to jau deklarē, un aizmugursistēma, kas to importē bez entitlements bloka, neiziet tos pašus vārtus. frontend glabā basePath, mountPath un framework. nexus glabā minVersion, maxVersion, capabilities[] un permissions[].
Katrs no atlikušajiem blokiem ir paredzēts vienam uzdevumam:
| Bloks | Mērķis |
|---|---|
settings |
Jūsu iestatījumi koplietotajā ietvarā: groups un keys, iestatīti līmeņos, ko katrs nosauc |
people |
sweep (service, port): organizācijas dalībnieki, sinhronizēti no identitātes pakalpojuma, ar izslēgtām sēdvietām, kad kāds aiziet |
ontology |
entityTypes un relationshipTypes: tipizētais grafs, kas tiek glabāts jūsu pašu shēmā |
release |
groups un frame: spēju grupas, kurās jūsu maršruti tiek pakāpeniski izvietoti, vispirms izlaižot kā kanārijputniņu |
cells[] |
Spraudnis, kas sastāv no vairākām izvietojamām vienībām: katrai name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] jūsu kataloga ierakstam |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kas to publicē un kur atrodas tā kods |
metrics, atlas |
Divi apzināti atvērti objekti jūsu pašu metrikas nosaukumiem un arhitektūras dokumentācijas ģenerēšanai |
Ko shēma nevar pateikt
JSON Schema nosaka formu; definePlugin pievieno noteikumus, kurus shēma nevar izteikt. Prasmes classification nedrīkst pārsniegt uzticamības griestus. Tikai core un verified spraudņi drīkst deklarēt tool_using un llm_only prasmes. Katram deklarētajam ceļam jābūt relatīvam un ar to pašu izcelsmi, bez shēmas, bez // un bez atpakaļvērstās slīpsvītras, jo URL parsētājs pārvērš \ par / un /\evil.example/x atrisinās kā starpizcelsmju. Katrs noteikums, ko reģistra sinhronizācija piemēro prasmei, vispirms tiek piemērots šeit, ar pašas sinhronizācijas kodu, tāpēc validate un sinhronizācija nosauc pārkāptu noteikumu vienādi.
Validācija un pāreja no v1
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0
Kļūme izdrukā precīzu ceļu un, sinhronizācijas noteikumam, vispirms kodu. Padariet to par apstiprināšanas āķi (commit hook).
v1 manifests tiek pacelts mehāniski. migrate pievieno trīs likumu teikumus, pārvieto domain uz domains[] un atsakās izgudrot ieejas punktu, kura jums nebija. Tas validē rezultātu pirms jebkā izdrukāšanas vai ierakstīšanas, tāpēc migrācija nekad nepārvieto kļūmi no rīka uz jūsu krātuvi.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeIzlasiet izmaiņu salīdzinājumu (diff), pirms to apstiprināt. Likumu teikumi, ko tas pievieno, ir formulējums, kuru fiksē validators; savai instalācijai iestatiet deploy uz iepriekš parādīto teikumu.
Nomnieku vides atveidošana un lomu nodrošināšana
Jūs nekad nerakstāt savus lomu piešķīrumus vai rindu līmeņa drošības veidni ar roku. nexus-tenancy render tos uzraksta no manifesta schema un db:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlAtveidotais fails izveido piecas lomas shēmai, katru ar to, kas tai nedrīkst piederēt: migratoru, kas var kļūt tikai par īpašnieku, īpašnieku, kas nevar pieteikties, lietotnes lomu pieprasījuma ceļam, pārskatu lomu, kas redz tikai kopsavilkumus, un virsgrāmatas lomu, kas var tikai pievienot. Nevienai lomai nepieder BYPASSRLS. Vienīgais veids, kā piesaistīt nomnieku, ir viena datubāzes funkcija, un set_config ir atsaukts visām lomām, izņemot īpašnieku.
Lietots nomnieku izolācijas fails nekad netiek rediģēts. Izmaiņas ir revīzija ar savu 0. numura failu, un lasīšanas sēdvieta starporganizāciju piešķīrumiem tiek piegādāta šādā veidā, kā 2. revīzija. --graph atveido abas tipizētā grafa tabulas, kuras jūsu ontology deklarē kā jūsu nākamo numurēto migrāciju.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlNomnieku izolācijas fails izveido tieši tās lomas, kā kuras izpildītājs pieslēdzas, tāpēc to lieto datubāzes īpašnieks ar nexus-migrate provision:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir><database-owner-url> ir savienojuma virkne datubāzes īpašniekam, un <dir> ir privāts direktorijs. Nodrošināšana lieto bāzes nomnieku izolācijas failu un katru revīziju pēc kārtas, ieraksta migrator.url un app.url (un seat.url, tiklīdz pastāv 2. revīzija) iekš <dir> ar režīmu 0600, un neizdrukā neko slepenu. Tā iestata katras lomas savienojumu limitu no db.maxConnections × db.pods katrā izpildes reizē. Atkārtota izpilde saglabā esošās paroles, ja vien jūs nelūdzat citādi: --passwords <dir> iestata tās no failiem un --rotate <roles> piešķir nosauktajām lomām jaunas paroles. Pārvērtiet šos failus par sava izvietojuma noslēpumiem.
Pēc tam lietošana pieslēdzas ar migratora savienojuma virkni, ko ierakstīja nodrošināšana:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonTā izpilda failus no 001 un tālāk kā migrators, katru failu zem SET ROLE <schema>_owner, viena transakcija uz vienu failu. Tā uztur virsgrāmatu, <schema>.schema_migrations, ar katra faila kontrolsummu; lietots fails, kura baiti ir mainījušies, tiek atteikts pēc nosaukuma (CHECKSUM_DRIFT), nekad netiek izpildīts atkārtoti un nekad netiek izlaists. Katrs gaidošais fails tiek parsēts ar īsto Postgres gramatiku, pirms tiek izpildīts pirmais, tāpēc atteikums atstāj datubāzi neskartu. Vienīgā galvene, kas failam var būt, ir -- nexus-migration: transaction=file|per-statement, ar neobligātiem bloķēšanas un priekšrakstu noildzes laikiem; per-statement ir paredzēts CREATE INDEX CONCURRENTLY.
Kontroles barjeras
nexus-gates izpilda divdesmit divus vārtus. Katri iekodē vienu defektu klasi, lai to nevarētu piegādāt divreiz, un katriem ir paštests, kas pierāda, ka tie neizdodas uz sagataves, kas uzbūvēta to nostrādināšanai. Izpildiet tos pirms koda nosūtīšanas (push):
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Vārti | Ko tie noķer |
|---|---|
scope-adherence |
/api maršrutu bez tvēruma sarga; anonīmu ceļu, kas nav precīzs deklarētais ceļš; ierīces maršrutu bez ierīces sarga vai ar personas sargu tam blakus |
one-fence |
Nomnieka predikātu, kas definēts jebkur citur, nevis vienā vietā, ieskaitot ar roku rakstītu sēdvietas vai piešķīruma nožogojumu |
sql-fence |
Priekšrakstu, kas lasa vai atjaunina tvēruma tabulu bez nožogojuma, jebkurā FROM, JOIN, USING vai UPDATE mērķī |
migrations-are-scoped |
Tabulu, kurai trūkst ass, nomnieka vadošās saliktās atslēgas, nomnieku nesošas ārējās atslēgas vai demonstrācijas kolonnas |
migrations-commit-what-they-open |
Migrāciju, kuras BEGIN skaits nesakrīt ar tās COMMIT un ROLLBACK skaitu |
no-direct-compute |
Tiešu izsaukumu modeļa nodrošinātājam, dzinējam, rindai vai darbplūsmas resursdatoram; otru nosūtīšanas URL lasītāju |
no-credentials |
Modeļa nodrošinātāja akreditācijas datus, kas ir lasāmi krātuvē vai vidē |
crud-adherence |
Mutējošu maršrutu, kura tiesību pārbaude nenosauc neko reģistrā |
blocked-backends |
Maršrutu, kas netiek ne apkalpots, ne bloķēts pēc nosaukuma, ne atteikts pēc likuma, ne arī pieder citur |
every-test-runs |
Testus, kurus testa skripta šablons (glob) nekad nesasniedz |
tiles-are-invariant |
Nomniekam nemainīgu kešotu šuvi, kas lasa nomnieka vērtību vai izlaiž autentifikāciju |
api-contract |
Reģistrētu maršrutu, ko manifests nedeklarē, vai deklarētu maršrutu, ko kods nekad nereģistrē |
rls-present |
Tabulu bez piespiestas rindu līmeņa drošības; SECURITY DEFINER funkciju bez piesaistīta search_path |
no-set-config |
Spraudņa kodu, kas pats piesaista nomnieka iestatījumu |
db-role-honest |
Pieprasījuma ceļu, kas pieslēdzas kā īpašnieks vai migrators, vai pieprasa SUPERUSER vai BYPASSRLS |
platform-clients |
SDK klientu, kas ir importēts, bet nav uzskaitīts iekš backend.platformClients, vai ir uzskaitīts, bet nekad nav importēts |
rights-register |
Tvēruma maršrutu bez deklarētām tiesībām; tiesību pārbaudi ārpus reģistra |
refusal-ledger |
Deklarētu atteikumu tabulu bez instalētas virsgrāmatas, vai atteikuma pamattekstu, kas nosūtīts, to apejot |
grants-declared |
Piešķirtu tabulu, ko manifests nedeklarē; ar roku izdalītas lasīšanas sēdvietas privilēģijas |
people-declared |
people bloku bez tā tīrīšanas maršruta, sarga un tabulām |
functions-closure |
Azure Functions spraudni, kura apkalpotie maršruti un deklarētie maršruti nesakrīt |
declared-input |
Apstrādātāja vaicājuma parametru sarakstu, kas nesakrīt ar maršruta deklarēto query |
gates/ direktorijs glabā piecus izņēmumu failus, kurus vārti var lasīt (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json un invariant-seams.json), viens iemesls katram ierakstam. Tukšs iemesls skaitās kā neesošs ieraksts, un ieraksts, kas nosauc kaut ko tādu, kas vairs nepastāv, izraisa vārtu kļūmi. Jūs varat tur ievietot arī savus vārtu moduļus, un nexus-gates tos paņem blakus iebūvētajiem.
Veidnes konveijers
Veidne nepiegādā ar roku rakstītu darbplūsmu. Tās konveijera konfigurācija nosauc Dockerfile, vienīgo būvēšanas argumentu (reģistra pilnvaru), migrācijas izmēģinājuma izpildi un sāknēšanas pārbaudi, kā arī vārtus, kurus izpilda sapludināšanas rinda. Secība ir tāda secība, kādā jūs vēlētos saņemt kļūmi.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, kas ircreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, kas irnexus-gates --self-testnode scripts/ci/required-env
Ap attēlu tiek veiktas vēl divas pārbaudes. Migrācijas izmēģinājuma palaišana piemēro katru failu pagaidu Postgres datubāzei, pirms attēlu var izlaist, izmantojot to pašu izpildītāju, ko izmanto produkcijas vide: nexus-migrate provision vienu reizi kā superlietotājam, pēc tam katru numurēto failu kā migratoram. palaišanas pārbaude startē uzbūvēto attēlu ar tā ieejas punktu un katru mainīgo, ko izvada required-env, novirzot uz aizstājējiem, kas pieņem savienojumus un nekad neatbild. Serveris gaida datubāzi savā ierobežotajā laika logā, un šī gaidīšana ir sekmīgas izpildes signāls; konfigurācijas ielādētājs, kas atsakās palaisties, izraisa būvējuma kļūmi tur, nevis produkcijas vidē.
Izmaksas
SDK pieņem lēmumus jūsu vietā, un dažus no tiem jūs būtu pieņēmuši citādi. Manifests noraida atslēgas, kuras tas nepazīst, maršrutu tabulai ir precīzi jāatbilst jūsu kodam, datubāzes lomas nav jūsu ziņā, un kontrolpunkti pārtrauc būvējumu, ja lasīšanas operācijai trūkst tiesību. Izstrādājot savu pirmo spraudni, es pavadīju dienu, strīdoties ar api-contract par maršrutu, ko biju reģistrējis un aizmirsis deklarēt. Tam bija taisnība; maršruts nebija aizsargāts. Rēķinieties, ka pirmā spraudņa izstrāde šķitīs lēna, un rēķinieties, ka otrajam būs nepieciešama trešdaļa no šī laika.

