Back to Details

domainlang

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DomainLang modeling

DomainLang 建模

Write DDD architecture models in 
.dlang
files. DomainLang is a domain-specific language for expressing Domain-Driven Design concepts as code — domains, bounded contexts, context maps, teams, ownership, ubiquitous language, and integration patterns.
Reference: https://domainlang.net
在
.dlang
文件中编写DDD架构模型。DomainLang是一种领域特定语言，用于将领域驱动设计（DDD）概念以代码形式表达——包括领域、限界上下文、上下文映射、团队、所有权、通用语言和集成模式。
参考链接： https://domainlang.net

Workflow

工作流程

Follow these steps when creating a DomainLang model:
  1. Identify domains — the high-level business capabilities
  2. Declare teams and classifications — who owns what, how strategically important
  3. Define bounded contexts — concrete boundaries with terminology
  4. Map relationships — how contexts integrate, with DDD patterns
  5. Organize — use namespaces and imports for large models
创建DomainLang模型时，请遵循以下步骤：
  1. 识别领域——确定高层业务能力
  2. 声明团队与分类——明确职责归属和战略重要性
  3. 定义限界上下文——确定带有专属术语的具体边界
  4. 映射关系——通过DDD模式定义上下文间的集成方式
  5. 组织架构——对大型模型使用命名空间和导入机制

Core syntax

核心语法

Domains

领域

dlang
Domain Sales {
    description: "Revenue generation"
    vision: "Make buying easy"
}

// Subdomains use 'in'
Domain OnlineSales in Sales {
    description: "Digital sales channel"
}
Use nouns reflecting business capabilities, not technical terms.
dlang
Domain Sales {
    description: "Revenue generation"
    vision: "Make buying easy"
}

// Subdomains use 'in'
Domain OnlineSales in Sales {
    description: "Digital sales channel"
}
使用反映业务能力的名词，而非技术术语。

Teams and classifications

团队与分类

dlang
Classification CoreDomain
Classification SupportingDomain
Classification GenericSubdomain

Team SalesTeam
Team PlatformTeam
Declare these before referencing them in bounded contexts.
dlang
Classification CoreDomain
Classification SupportingDomain
Classification GenericSubdomain

Team SalesTeam
Team PlatformTeam
在限界上下文中引用之前，需先声明这些内容。

Bounded contexts

限界上下文

dlang
bc Orders for Sales as CoreDomain by SalesTeam {
    description: "Order lifecycle and orchestration"

    terminology {
        term Order: "A customer's request to purchase"
            aka PurchaseOrder
            examples "Order #12345"
        term OrderLine: "A single item in an order"
    }

    decisions {
        decision EventSourcing: "Capture every state change"
        policy Refunds: "Allow refunds within 30 days"
        rule MinOrder: "Minimum order is $10"
    }

    metadata {
        Language: "TypeScript"
    }
}
Header keywords: 
for
(parent domain), 
as
(classification), 
by
(team).
Body-only form is also valid — use 
classification:
and 
team:
inside body.
Optional body — 
bc Orders for Sales
is valid for quick declarations.
Block aliases: 
terminology
/
glossary
, 
metadata
/
meta
, 
decisions
/
rules
, 
relationships
/
integrations
.
dlang
bc Orders for Sales as CoreDomain by SalesTeam {
    description: "Order lifecycle and orchestration"

    terminology {
        term Order: "A customer's request to purchase"
            aka PurchaseOrder
            examples "Order #12345"
        term OrderLine: "A single item in an order"
    }

    decisions {
        decision EventSourcing: "Capture every state change"
        policy Refunds: "Allow refunds within 30 days"
        rule MinOrder: "Minimum order is $10"
    }

    metadata {
        Language: "TypeScript"
    }
}
头部关键字：
for
（父领域）、
as
（分类）、
by
（所属团队）。
仅包含主体的形式同样有效——在主体内使用
classification:
和
team:
来声明。
主体为可选内容——
bc Orders for Sales
可用于快速声明。
块别名：
terminology
/
glossary
、
metadata
/
meta
、
decisions
/
rules
、
relationships
/
integrations
。

Metadata

元数据

Declare keys before use:
dlang
Metadata Language
Metadata Repository

bc Orders for Sales {
    metadata {
        Language: "TypeScript"
        Repository: "github.com/acme/orders"
    }
}
使用前需先声明键：
dlang
Metadata Language
Metadata Repository

bc Orders for Sales {
    metadata {
        Language: "TypeScript"
        Repository: "github.com/acme/orders"
    }
}

Context maps

上下文映射

dlang
ContextMap SalesSystem {
    contains Orders, Billing, Shipping

    [OHS] Orders -> [CF] Billing
    [ACL] Shipping <- Orders
    [P] Orders <-> [P] Inventory
    Orders >< LegacySystem
}
Arrows: 
->
upstream-to-downstream, 
<-
downstream-to-upstream, 
<->
bidirectional, 
><
separate ways.
Integration patterns:
PatternAbbreviationMeaning
Open Host Service
[OHS]
Well-defined protocol for consumers
Conformist
[CF]
Adopts upstream model without translation
Anti-Corruption Layer
[ACL]
Translates between models to protect downstream
Published Language
[PL]
Shared documented language for integration
Shared Kernel
[SK]
Shared subset of the domain model
Partnership
[P]
Two contexts coordinate development together
dlang
ContextMap SalesSystem {
    contains Orders, Billing, Shipping

    [OHS] Orders -> [CF] Billing
    [ACL] Shipping <- Orders
    [P] Orders <-> [P] Inventory
    Orders >< LegacySystem
}
箭头： 
->
上游到下游，
<-
下游到上游，
<->
双向，
><
独立方式。
集成模式：
模式缩写含义
Open Host Service
[OHS]
为消费者定义的标准化协议
Conformist
[CF]
采用上游模型，无需转换
Anti-Corruption Layer
[ACL]
在模型间进行转换，保护下游系统
Published Language
[PL]
用于集成的共享文档化语言
Shared Kernel
[SK]
领域模型的共享子集
Partnership
[P]
两个上下文协作开发

Inline relationships

内联关系

Inside bounded contexts, use 
this
as self-reference:
dlang
bc Orders for Sales {
    relationships {
        [OHS] this -> [CF] Billing
        [ACL] this <- Payments
    }
}
在限界上下文中，使用
this
指代自身：
dlang
bc Orders for Sales {
    relationships {
        [OHS] this -> [CF] Billing
        [ACL] this <- Payments
    }
}

Domain maps

领域映射

dlang
DomainMap Portfolio {
    contains Sales, Support, Platform
}
dlang
DomainMap Portfolio {
    contains Sales, Support, Platform
}

Namespaces

命名空间

dlang
Namespace Acme.Sales {
    bc Orders for Sales {}
}

// Reference with FQN
ContextMap System {
    contains Acme.Sales.Orders
}
dlang
Namespace Acme.Sales {
    bc Orders for Sales {}
}

// Reference with FQN
ContextMap System {
    contains Acme.Sales.Orders
}

Imports

导入

dlang
import "./shared/teams.dlang"
import "../common/classifications.dlang"
import "acme/ddd-core" as Core

bc Orders for Core.SalesDomain {}
External imports require a 
model.yaml
manifest.
dlang
import "./shared/teams.dlang"
import "../common/classifications.dlang"
import "acme/ddd-core" as Core

bc Orders for Core.SalesDomain {}
外部导入需要
model.yaml
清单文件。

Comments and assignment

注释与赋值

dlang
// Line comment
/* Block comment */

// All equivalent:
description: "Using colon"
vision = "Using equals"
team is SalesTeam
dlang
// Line comment
/* Block comment */

// All equivalent:
description: "Using colon"
vision = "Using equals"
team is SalesTeam

DDD modeling guidelines

DDD建模指南

Strategic design checklist

战略设计检查清单

  • Every bounded context needs a parent domain (
    for
    )
  • Core domains deserve the best teams and custom solutions
  • Supporting domains are necessary but not differentiating
  • Generic domains are commodity — buy or use standard solutions
  • Name contexts after capabilities, not teams
  • 每个限界上下文都需要父领域（
    for
    关键字）
  • 核心领域应配备最优团队和定制解决方案
  • 支撑领域是必要的，但不具备差异化优势
  • 通用领域属于通用组件——可直接购买或使用标准解决方案
  • 上下文名称应基于业务能力，而非团队名称

Bounded context sizing

限界上下文规模

  • A context should have a clear, autonomous boundary
  • If two contexts share too much, consider merging
  • If one context does too much, consider splitting
  • One team should own one or a few closely related contexts
  • 每个上下文应具备清晰、自主的边界
  • 如果两个上下文共享过多内容，考虑合并
  • 如果一个上下文职责过多，考虑拆分
  • 一个团队应负责一个或几个紧密相关的上下文

Context map best practices

上下文映射最佳实践

  • Keep maps focused on one concern (technical, team, data flow)
  • Limit each map to 7-10 contexts maximum
  • Use multiple maps for different views of the same system
  • Always annotate integration patterns — they capture DDD intent
  • 保持映射聚焦于单一关注点（技术、团队、数据流）
  • 每个映射最多包含7-10个上下文
  • 对同一系统的不同视图使用多个映射
  • 始终标注集成模式——它们承载了DDD的设计意图

Terminology captures ubiquitous language

术语记录通用语言

  • Define every important term within its bounded context
  • Use 
    aka
    for synonyms the team encounters
  • Use 
    examples
    for concrete illustrations
  • Different contexts may define the same word differently — that's expected
  • 在限界上下文中定义所有重要术语
  • 使用
    aka
    记录团队常用的同义词
  • 使用
    examples
    提供具体示例
  • 不同上下文对同一词汇的定义可能不同——这是正常现象

File organization

文件组织

Single file (small models)

单文件（小型模型）

Put everything in one 
.dlang
file.
将所有内容放在一个
.dlang
文件中。

Multi-file projects

多文件项目

text
my-project/
├── model.yaml
├── index.dlang
├── shared/
│   ├── teams.dlang
│   └── classifications.dlang
└── domains/
    ├── sales/
    │   └── index.dlang
    └── shipping/
        └── index.dlang
Use 
index.dlang
as entry points. Configure path aliases in 
model.yaml
:
yaml
model:
  name: my-company/domain-model
  version: 1.0.0
  entry: index.dlang

paths:
  "@": "./"
  "@shared": "./shared"

dependencies:
  acme/ddd-core: "v1.0.0"
text
my-project/
├── model.yaml
├── index.dlang
├── shared/
│   ├── teams.dlang
│   └── classifications.dlang
└── domains/
    ├── sales/
    │   └── index.dlang
    └── shipping/
        └── index.dlang
使用
index.dlang
作为入口文件。在
model.yaml
中配置路径别名：
yaml
model:
  name: my-company/domain-model
  version: 1.0.0
  entry: index.dlang

paths:
  "@": "./"
  "@shared": "./shared"

dependencies:
  acme/ddd-core: "v1.0.0"

Complete example

完整示例

dlang
Classification CoreDomain
Classification SupportingDomain

Team OrderTeam
Team ShippingTeam

Domain ECommerce {
    description: "Online retail platform"
    vision: "Seamless shopping experience"
}

Metadata Language

bc Orders for ECommerce as CoreDomain by OrderTeam {
    description: "Order lifecycle from cart to delivery"

    terminology {
        term Order: "A customer's request to purchase items"
        term Cart: "Temporary collection of items before purchase"
    }

    metadata {
        Language: "TypeScript"
    }
}

bc Shipping for ECommerce as SupportingDomain by ShippingTeam {
    description: "Package routing and delivery tracking"

    terminology {
        term Shipment: "A collection of packages traveling together"
        term Carrier: "The company performing delivery"
    }
}

ContextMap ECommerceIntegration {
    contains Orders, Shipping

    [OHS] Orders -> [CF] Shipping
}
dlang
Classification CoreDomain
Classification SupportingDomain

Team OrderTeam
Team ShippingTeam

Domain ECommerce {
    description: "Online retail platform"
    vision: "Seamless shopping experience"
}

Metadata Language

bc Orders for ECommerce as CoreDomain by OrderTeam {
    description: "Order lifecycle from cart to delivery"

    terminology {
        term Order: "A customer's request to purchase items"
        term Cart: "Temporary collection of items before purchase"
    }

    metadata {
        Language: "TypeScript"
    }
}

bc Shipping for ECommerce as SupportingDomain by ShippingTeam {
    description: "Package routing and delivery tracking"

    terminology {
        term Shipment: "A collection of packages traveling together"
        term Carrier: "The company performing delivery"
    }
}

ContextMap ECommerceIntegration {
    contains Orders, Shipping

    [OHS] Orders -> [CF] Shipping
}

Keyword quick reference

关键字速查

See references/SYNTAX.md for the complete keyword and alias table.
Top-level: 
Domain
(
dom
), 
BoundedContext
(
bc
), 
ContextMap
(
cmap
), 
DomainMap
(
dmap
), 
Namespace
(
ns
), 
Team
, 
Classification
, 
Metadata
, 
Import
(
import
)
BC header: 
for
, 
as
, 
by
BC blocks: 
terminology
/
glossary
, 
decisions
/
rules
, 
metadata
/
meta
, 
relationships
/
integrations
Items: 
term
, 
decision
, 
policy
, 
rule
Term modifiers: 
aka
/
synonyms
, 
examples
查看references/SYNTAX.md获取完整的关键字和别名表。
顶级关键字： 
Domain
（
dom
）、
BoundedContext
（
bc
）、
ContextMap
（
cmap
）、
DomainMap
（
dmap
）、
Namespace
（
ns
）、
Team
、
Classification
、
Metadata
、
Import
（
import
）
限界上下文头部： 
for
、
as
、
by
限界上下文块： 
terminology
/
glossary
、
decisions
/
rules
、
metadata
/
meta
、
relationships
/
integrations
条目： 
term
、
decision
、
policy
、
rule
术语修饰符： 
aka
/
synonyms
、
examples

Tooling

工具支持

  • VS Code extension: 
    DomainLang.vscode-domainlang
    — syntax highlighting, validation, completion, hover, go-to-definition
  • VS Code AI tools: When working in VS Code with GitHub Copilot or Claude, use these Language Model Tools: 
    • domainlang_validate
      — Validate the model and get diagnostics
    • domainlang_list
      — List entities (domains, bcs, teams, classifications, relationships, context-maps, domain-maps) with filters
    • domainlang_get
      — Get a specific element by FQN or model summary
    • domainlang_explain
      — Get rich markdown explanations of any element
    • Example: "Show me all Core bounded contexts" or "Explain the OrderContext"
  • CLI: 
    npm install -g @domainlang/cli
    — 
    dlang install
    , 
    dlang model tree
    , 
    dlang model status
  • SDK: 
    npm install @domainlang/language
    — parse and query models programmatically
  • VS Code扩展： 
    DomainLang.vscode-domainlang
    —— 语法高亮、验证、自动补全、悬停提示、跳转到定义
  • VS Code AI工具： 在VS Code中使用GitHub Copilot或Claude时，可使用以下语言模型工具： 
    • domainlang_validate
      —— 验证模型并获取诊断信息
    • domainlang_list
      —— 列出实体（领域、限界上下文、团队、分类、关系、上下文映射、领域映射）并支持过滤
    • domainlang_get
      —— 通过完全限定名称（FQN）获取特定元素或模型摘要
    • domainlang_explain
      —— 获取任意元素的详细Markdown解释
    • 示例："显示所有核心限界上下文"或"解释OrderContext"
  • CLI： 
    npm install -g @domainlang/cli
    —— 支持
    dlang install
    、
    dlang model tree
    、
    dlang model status
    等命令
  • SDK： 
    npm install @domainlang/language
    —— 以编程方式解析和查询模型