Language Reference

Ամբողջական շարահյուսական հղում Datro DSL (.dtro ֆայլերի համար): Բլոկի յուրաքանչյուր տեսակ, յուրաքանչյուր դաշտ, յուրաքանչյուր ախտորոշիչ կոդը՝ բոլորը մեկ տեղում:

Յուրաքանչյուր .dtro ֆայլ պետք է սկսվի 1-ին տողում գտնվող կախարդական վերնագրով: Վերլուծիչը վերադարձնում է E100, եթե այն բացակայում է կամ սխալ ձևավորված է:

#!DATRO 1.0

Ընտրովի փաստաթղթի մակարդակի մետատվյալներ: Արտադրում է I003 տեղեկատվական հուշում, եթե բաց թողնվի: Բոլոր դաշտերը կամընտիր տողեր/զանգվածներ են, բացառությամբ kind-ի:

#!DATRO 1.0

meta {
  title:       "Payment Service"
  version:     "2.1.0"
  description: "Handles card and crypto charges"
  author:      "jane@example.com"
  owner:       "payments-team"
  tags:        ["payments", "critical"]
  sla:         "99.95%"
  criticality: "P0"
  kind:        architecture
}

Դիագրամում հայտարարում է սուբյեկտ: Յուրաքանչյուր հանգույց ունի եզակի id, իմաստային type, որը վերահսկում է իր ստացված ձևը և լռելյայն գույնը, և կամընտիր attrs բլոկ մետատվյալների համար։

# Minimal
node api_gw { type: gateway label: "API Gateway" }

# With attrs block
node payment_svc {
  type:  service
  label: "Payment Service"
  attrs {
    tech:       "nestjs"
    owner:      "payments-team"
    deprecated: false
    sla:        "99.95%"
  }
}

# Inline attrs (alternative syntax)
node db { type: database label: "Payments DB"  attrs { tech: "postgres" } }

Հայտարարում է հարաբերություն երկու հանգույցների միջև: Եզրային ուղղությունը ուղղակիորեն գրված է հռչակագրում.

# Minimal
edge api_gw -> payment_svc { kind: http }

# Full metadata
edge payment_svc -> stripe {
  kind:   http
  label:  "charge API"
  weight: 2.0
  async:  false
  attrs { sla: "200ms" }
}

# Bidirectional edge
edge cache <-> service { kind: read }

# Undirected edge
edge svc_a -- svc_b { kind: depends }

Կլաստերավորում է կապված հանգույցները պիտակավորված ենթագրաֆիկի վանդակում: Հանգույցը կարող է պատկանել առավելագույնը մեկ խմբի՝ E403 կրակում է կոնֆլիկտների վրա: Խմբերը կարող են տեղադրվել. անդամի ID-ն կարող է հղում կատարել մեկ այլ խմբի ID-ին:

group data_tier {
  label:   "Data Layer"
  members: [payments_db, fraud_cache, audit_log]
  attrs { compliance: "PCI-DSS" }
}

# Alternative: assign group on the node
node payments_db {
  type:  database
  label: "Payments DB"
  group: data_tier
}

Հայտարարում է ճարտարապետական կանոն, որը վավերացնողը գնահատում է IR-ի համեմատ: Խախտումները առաջացնում են E501 (կամ W501, երբ severity: warn): rule դաշտը օգտագործում է հակիրճ երեք նշանների քերականություն:

# Prohibition: databases may not call external services
constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect directly to external APIs"
  severity: error
}

# Requirement: every gateway must connect to a service
constraint {
  rule:     "gateway -> service"
  message:  "Each gateway must route to at least one service"
  severity: warn
}

# Membership: all databases must be in the data_tier group
constraint {
  rule:     "database in data_tier"
  message:  "All database nodes must belong to the data_tier group"
  severity: error
}

Սահմանափակող բայեր

• `!->` — ոչ մի SUBJECT հանգույց չի կարող ուղղորդված եզր ունենալ դեպի որևէ OBJECT հանգույց:
• `->` — յուրաքանչյուր SUBJECT հանգույց պետք է ունենա առնվազն մեկ ուղղորդված եզր դեպի OBJECT հանգույց:
• `!<->` — SUBJECT և OBJECT հանգույցների միջև երկկողմանի եզրեր չեն կարող գոյություն ունենալ:
• `<->` — յուրաքանչյուր SUBJECT հանգույց պետք է ունենա երկկողմանի եզր դեպի որոշ OBJECT հանգույց:
• `in` — յուրաքանչյուր SUBJECT հանգույց պետք է լինի OBJECT խմբի անդամ:
• `!in` — ոչ մի SUBJECT հանգույց չի կարող OBJECT խմբի անդամ լինել։

Մեծ դիագրամները բաժանում է բազմաթիվ .dtro ֆայլերի վրա: Լուծիչը միաձուլում է ներմուծված IR-ը ծնողի մեջ նախքան վավերացումը: Օգտագործեք as-ը անունների տարածության համար և expose-ը՝ որոշակի ID-ների սպիտակ ցուցակում տեղադրելու համար:

# Import everything from another .dtro file
import "auth.dtro"

# Import with a namespace alias — IDs become auth.user_service, etc.
import "auth.dtro" as auth

# Import only specific IDs (whitelist)
import "infra.dtro" as infra expose [load_balancer, cdn]

Հուշումներ մատուցողին, թե ինչպես դասավորել գրաֆիկը: Բոլոր դաշտերը կամընտիր են. ցուցադրիչը օգտագործում է խելամիտ լռելյայններ, երբ բլոկը բաց է թողնվում:

layout {
  direction:       LR          # LR | RL | TB | BT
  algo:            dagre        # dagre | dot | elk | force | none
  node_sep:        60           # px between nodes in the same rank
  rank_sep:        120          # px between ranks
  margin:          20           # graph margin in px
  cluster_padding: 16           # padding inside group boxes
}

Վերահսկում է ներկայացված գծապատկերի տեսողական տեսքը: palette-ը քարտեզագրում է հանգույցների տեսակները վեցանկյուն գույներով: accessibility ենթաբլոկը հնարավորություն է տալիս ավտոմատ կերպով ստուգել WCAG 2.1 հակադրությունը:

theme {
  name: "Corporate"

  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    gateway:    "#FFD0D0"
    queue:      "#E8D0FF"
    cache:      "#C0FFE8"
    external:   "#F0F0F0"
    background: "#FFFFFF"
  }

  typography {
    font_family:      "Inter, sans-serif"
    node_font_size:   11
    edge_font_size:   9
    label_font_weight: "600"
  }

  accessibility {
    min_contrast:    AA          # AA | AAA | none
    max_label_length: 60
  }
}

Թեմայից հետո կիրառվել են յուրաքանչյուր տարրի մանրահատիկ վերափոխումներ: Կանոնների կասկադ. by_id վերացնում է by_type: Յուրաքանչյուր ենթաբլոկ քարտեզագրում է սեփականության քարտեզի բանալին:

style {
  # Override by node type
  by_type {
    database { fill: "#FFF3CD"  stroke: "#E6A817"  shape: cylinder }
    external { fill: "#F8F9FA"  stroke: "#6C757D"  dash: true }
  }

  # Override individual node by id
  by_id {
    stripe { fill: "#635BFF"  stroke: "#4B44CC" }
  }

  # Style edge kinds
  by_edge_kind {
    query   { color: "#E6A817"  width: 2 }
    publish { color: "#198754"  dash: true }
  }

  # Style edges that carry a boolean attr set to true
  by_edge_attr {
    async { dash: true  color: "#ADB5BD" }
  }
}

Բոլոր ախտորոշիչները ներառում են code, severity, message և կամընտիր line:col տեղադրություն: Ստորև բերված աղյուսակում թվարկված են բոլոր ծածկագրերը, որոնք կարող է թողարկել գործիքաշարը:

Սխալներ (E×××)

• `E100` — Կախարդական վերնագիր #!DATRO 1.0 բացակայում է կամ սխալ ձևավորված է
• `E201` — Կրկնվող հանգույցի id
• `E202` — Հանգույցը հղում է անում անհայտ խմբի id-ին
• `E301` — Եզր from հանգույցը չի գտնվել
• `E302` — Եզր to հանգույցը չի գտնվել
• `E303` — Եզր weight բացասական է
• `E401` — Կրկնվող խմբի id
• `E402` — Խումբը members հղում է անհայտ ID-ին
• `E403` — Հանգույցը նշանակված է մեկից ավելի խմբի
• `E404` — Հայտնաբերվել է շրջանաձև խմբակային բույն
• `E500` — Սահմանափակման կանոնն ունի շարահյուսական սխալ
• `E501` — Սահմանափակման կանոնը խախտված է (խստությունը արտացոլում է սահմանափակման սեփական severity)

Զգուշացումներ (Վ×××)

• `W301` - Կրկնվող եզր (նույնը / to/ kind / label)
• `W501` — Սահմանափակման կանոնն օգտագործում է անհայտ բայ
• `W601` — Հանգույցի պիտակը գերազանցում է max_label_length-ը (կանխադրված 80 նիշ)
• `W602` - Թեմայի ներկապնակի գույնը ընկնում է WCAG AA կոնտրաստից ցածր (4.5:1)
• `W603` - Թեմայի ներկապնակի գույնը ընկնում է WCAG AAA կոնտրաստից ցածր (7.0:1)

Տեղեկատվական հուշումներ (I×××)

• `I001` — Մեկուսացված հանգույց — դրա հետ եզրեր չկան
• `I002` — Դատարկ խումբ — անդամներ չկան
• `I003` — Ոչ meta բլոկ — խորհուրդ է տրվում փաստաթղթերի համար
• `I601` — Թեմայի գունապնակ սահմանված չէ. հակադրության ստուգումները բաց են թողնվել

• Օգտագործեք CLI Reference՝ հրամանի տողից վավերացնելու, ձևաչափելու և արտահանելու համար:
• Տեղադրեք դիագրամները Markdown-ում Markdown plugin-ով:
• Վերադարձեք Quick Start՝ քայլ առ քայլ ուսումնասիրության համար: