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:

Identify domains — the high-level business capabilities
Declare teams and classifications — who owns what, how strategically important
Define bounded contexts — concrete boundaries with terminology
Map relationships — how contexts integrate, with DDD patterns
Organize — use namespaces and imports for large models

创建DomainLang模型时，请遵循以下步骤：

识别领域——确定高层业务能力
声明团队与分类——明确职责归属和战略重要性
定义限界上下文——确定带有专属术语的具体边界
映射关系——通过DDD模式定义上下文间的集成方式
组织架构——对大型模型使用命名空间和导入机制

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:

Pattern	Abbreviation	Meaning
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
```
—— 以编程方式解析和查询模型