PetroNet SystemDocumentation
Модуль

Модуль бичих

4 min readdocs/MODULES.mdEdit on GitHub

Бизнес апп нь энэ репод байдаггүй. Өөрийн репод амьдарч, pkg/nexus-ээр өөрийгөө бүртгүүлж, каталогоор ирдэг. Энэ баримт нь backend/pkg/nexus-ийн кодоос уншиж бичигдсэн.

This page has not been translated yet — it is shown in Mongolian, the language it is written in.


01Хамгийн бага модуль

main.go дотор гурван мөр:

go
func main() {    mymodule.New(db)   // өөрөө nexus.Register дуудна    host.Run()}

nexus.Register нь компиляцын үеийн бүртгэл. Платформ маршрут mount хийх, цэс барих, суулгасан апп ард нь код байгаа эсэхийг шалгахдаа энэ бүртгэлээс асууна. Багцын түвшний төлөв байдаг нь зориуд: «энэ програм ямар модуль агуулж байна» гэдэг нь програмын шинж чанар бөгөөд бүртгэлийг конструктор болгоноор дамжуулбал зөвхөн хоёр нь зөрөх боломж л нэмэгдэнэ.

Нэг id-г хоёр модуль нэхэх нь угсралтын алдаа, ажиллагааны нөхцөл биш — хоёулаа нэрээрээ компиляцлагдсан байдаг — тиймээс сүүлийнх нь ялна.

02Модуль юу зарлах вэ

go
type Module interface {    ID() string    Name() string    Version() string    Dependencies() []Dependency    Permissions() []PermissionDefinition    Menus() []MenuDefinition    RegisterRoutes(r chi.Router, workspaceAuth func(http.Handler) http.Handler)}

RegisterRoutes нь урьдчилан хүрээлэгдсэн бүлэг биш, үндсэн router-ыг авна. Хамт ирэх middleware нь платформын аль хэдийн гаргасан хоёр шийдвэрийг авч явна: энэ байгууллага аппыг суулгасан эсэх, ба — платформ эрхийн угтварыг нь мэддэг апп бол — дуудагч ийм төрлийн хүсэлт хийж болох эсэх.

03Эрхийг платформд даалгах

go
type AccessPolicy interface {    MenuPermission() string    RoutePermissionPrefix() string}

Хэрэгжүүлэх нь заавал биш. Хэрэгжүүлээгүй модуль зөвхөн «суулгасан эсэх»-ээр хамгаалагдана, эрхээ өөрөө шалгах үүрэгтэй.

Хоосон мөр нь бодит хариулт, орхигдсон зүйл биш: «платформ үүнийг бүү хаа» гэсэн үг. Үүнийг чангаар хэлэх нь чухал — өмнө нь чимээгүй байх нь «эрх шаардлагагүй» ба «энэ модуль өөрөө шалгадаг» хоёрыг хоёуланг нь илэрхийлдэг байсан бөгөөд кодод тэднийг ялгах арга байгаагүй.

RoutePermissionPrefix нь GET/HEAD-д prefix.read, өөрчилж чадах бүхэнд prefix.manage шаардана. Дүрэм нь үйл үгээр илэрхийлэгдэхээс нарийн бол — жишээ нь өргөдөл гаргагчийн харьяалагдах нэгжээс хамаарах зөвшөөрлийн алхам — хоосон үлдээгээд өөрөө шалгана.

Энэ нь өмнө нь платформ дотор апп бүрийг нэрээр нь жагсаасан хоёр switch байсны оронд бий болсон. Өөр репод амьдардаг модуль энэ репо доторх switch-д өөрийгөө нэмж чадахгүй, тэгээд юу болдог вэ гэвэл compile алдаа биш — чимээгүй сулрал: салгагдсан апп ажилласаар, хажуугийн самбарт харагдсаар, харин хаагдахаа болино. Refactor-ийн үеэр чимээгүй алга болдог эрхийн шалгалт бол энэ төрлийн алдааны хамгийн муу хэлбэр.

04Модулийн өөрийн schema

Модуль өөрийн migration-ыг embed хийж, конструктораасаа өгнө:

go
//go:embed migrations/*.sqlvar migrations embed.FS

Яагаад ийм болсныг мэдэх нь чухал: өмнө нь хүснэгт үүсгэх цорын ганц газар нь платформын migration хавтас байсан. Үр дүнд нь систем бүр энд хэзээ нэгэн цагт бичигдсэн бүх аппын schema-г авч явдаг байв — худалдаа, POS, төрийн үйлчилгээний урсгал зэрэг энэ репод байхаа больсон аппуудынх ч дотроо.

Модулийн migration нь суулгах үед л ажилладаг. Апп «суулгагдсан» атлаа хүснэгтгүй байх боломжтой — тэр нь суулгалт нь migration-аас өмнө бичигдсэн гэсэн үг.

05Платформоос юу авах вэ

go
type Platform interface {    DB() DB    Permissions() PermissionStore}

DB нь байгууллагад уясан холбоо: dbguard нь холболт бүрийг дуудагчийн байгууллагад уядаг тул модулийн query нь өөр байгууллагын мөр харах боломжгүй (Архитектур).

BeginTx нь pgx.ReadOnly-г дэмждэг: «энэ бичихгүй» гэдгээ компиляторт төдийгүй өгөгдлийн санд хэлж чаддаг байх ёстой.

06Илүү өргөн боломжууд

Платформын өгдөг бусад зүйлс — бүгд pkg/nexus-д:

nexus.AuditAudit мөр бичих. Модуль internal/workspace/audit-ыг import хийж чадахгүй тул энэ зам байдаг
nexus.RegisterReportТайлан зарлах; тайлангийн хөдөлгүүр түүнийг ажиллуулна
nexus.RequirePermissionЭрхийн middleware
nexus.RateLimit, nexus.QuotaGateХязгаарлалт
nexus.Documents, nexus.RecordSignedГарын үсгийн зам
nexus.EID, nexus.DANТанилтын зам
nexus.People, nexus.DirectoryХүн, лавлах
nexus.Provide / nexus.CapabilityЧадварыг өгөх, авах
nexus.SecretsНууц утга

TestTheSDKDoesNotDependOnInternal нь SDK нь internal/-ээс хамаарахгүйг, TestTheExportedAPIIsTheOneOnRecord нь экспортын гадаргуу санамсаргүй өөрчлөгдөхгүйг шалгана. Хоёулаа нэг зорилготой: өөр репод бичигдсэн модуль маргааш ч компиляцлагдах ёстой.

07Каталог

Апп нь catalog/apps.json-оор ирнэ. Энэ репод тэр файл [] — платформ нэг ч бизнес аппгүйгээр ачаална. Тэр нь дутуу ажил биш, экосистемийн стратегийн тавьсан шалгуур яг тэр байсан.

Каталогийн бичлэг нь платформын хувилбарыг нэрлэдэг ("platform": ">=1.1.0") ба систем өөрийн хувилбарыг config.PlatformVersion-оос хэлнэ. Тэр утга нь release build дээр ldflags-аар тавигддаг.

08Хувилбарын амлалт

pkg/nexus нь нэг major хувилбарын дотор эвдэрдэггүй.

Build шалгаж чадахгүй амлалт бол хэн нэгэн яарсан үдээс хойш хүртэл сахидаг амлалт. Энэ нь хэн нэгэн эвдэхээр шийдсэнээс болж эвдрэхгүй — refactor хийх явцад параметрийн нэр солигдож, эсвэл distribution-ы төрөл хэрэгжүүлдэг interface-д метод нэмэгдэж эвдэрнэ. Хоёулаа энэ репод нэг ч тестийг унагахгүй. Оронд нь distribution бүрийн build хэдэн өдрийн дараа унана.

Тиймээс экспортын гадаргуу нь golden файл:

sh
go test ./pkg/nexus -update    # санаатай API өөрчлөлтийн дараа

Үүнийг өөрчлөх нь зөвшөөрөгдсөн, ихэвчлэн зөв ч байдаг — энэ бол хөлдөөлт биш. Гэхдээ санамсаргүй болох боломжгүй, мөн review дэх diff нь экосистемийн гэрээ юу авсан, юу алдсаныг яг хэлнэ.

Эвдэх өөрчлөлт гэж юу вэ: экспортолсон interface-д метод нэмэх нь эвдэх өөрчлөлт. Тэр interface-ийг өөр репод хэн нэгэн хэрэгжүүлсэн байдаг.

v2-т орох гэж тэмдэглэгдсэн зүйлс кодод Deprecated: гэж бичигдэнэ. Жишээ нь эрхийн дагаврын дүрэм (.read бүгдэд, .manage менежерүүдэд): нэрлэх конвенц нь гэрээ байх ёсгүй — «үйлчилгээнд өргөдөл гаргах»-ыг илэрхийлж чадахгүй, шалгагдаж чадахгүй, түүнийг сонсоогүй модуль болгоны хувьд хэн юу хийж болохыг чимээгүй шийддэг.

Was this page helpful?Your answer helps improve the docs.
    DEV · Хөгжүүлэлтийн орчин