arch-domain-driven

目的

此技能运用领域驱动设计（DDD）原则，有效地组织代码。它可帮助生成和管理限界上下文、聚合、实体、值对象和领域事件，同时推广通用语言，促进团队达成一致。

何时使用

当复杂应用具有丰富的领域逻辑时，例如电子商务平台或金融系统，可使用此技能；清晰的边界有助于降低耦合。在架构设计阶段应用此技能可避免形成单体代码库，尤其适用于涉及多个子域或旧系统集成的情况。

主要功能

• 为特定领域生成隔离的模块，构建限界上下文。
• 将聚合定义为由多个实体组成的集群，并指定单一根实体以确保事务一致性。
• 创建具有身份标识的实体和用于表示不可变数据的值对象。
• 处理领域事件以触发响应，例如向事件总线发布消息。
• 将领域术语融入代码和配置中，贯彻通用语言。

使用模式

始终先映射领域，识别限界上下文。使用此技能搭建结构，然后在上下文中完善聚合。例如，可在构建脚本中运行生成命令，将其集成到 CI/CD 中。逐步测试：生成一个实体，将其加入聚合，并验证不变量。避免过度建模，将上下文限制在高内聚的领域，并使用事件进行跨上下文通信。

常用命令/API

通过 OpenClaw 的 CLI 或 REST API 进行交互。身份验证需要在环境中设置 $OPENCLAW_API_KEY。

CLI 命令：

• 生成限界上下文：openclaw ddd generate-context --name MyContext --description "User management" --language python 这会创建类似 ./my_context/ 的目录，其中包含用于聚合和实体的子文件夹。
• 定义聚合：openclaw ddd generate-aggregate --context MyContext --name AccountAggregate --root EntityName --invariants "balance > 0" 添加类似 account_aggregate.py 的文件，其中包含根实体和不变量检查。
• 创建实体：openclaw ddd generate-entity --context MyContext --name UserEntity --properties "id:UUID, name:String"
• 处理领域事件：openclaw ddd generate-event --context MyContext --name UserCreatedEvent --payload "user_id:UUID"

API 端点：

• POST /api/v1/ddd/contexts，JSON 请求体：{"name": "MyContext", "description": "User management", "language": "python"} 需要以下请求头：Authorization: Bearer $OPENCLAW_API_KEY
• POST /api/v1/ddd/aggregates，请求体：{"context": "MyContext", "name": "AccountAggregate", "root": "Account", "invariants": ["balance > 0"]}

配置格式： 使用 YAML 配置，例如在 .openclaw/config.yml 文件中：

ddd:
  default_language: python
  contexts:
    - name: MyContext
      description: User management

代码片段：

1. 在 Python 中生成并使用上下文：

import openclaw.ddd as oc
oc.generate_context(name="MyContext", description="User management")
context = oc.load_context("MyContext")

2. 在代码中定义聚合：

from openclaw.ddd import Aggregate
class AccountAggregate(Aggregate):
    def __init__(self, account_id):
        self.root = Entity(account_id)  # Assuming Entity is generated

集成说明

在调用 CLI/API 前，通过导出 $OPENCLAW_API_KEY=your_api_key 进行集成。将 OpenClaw 添加为项目依赖（例如，Python 使用 pip install openclaw）。对于 IDE，可使用 VS Code 扩展等插件，通过键盘快捷键触发命令，例如将 openclaw ddd generate-context 绑定到某个按键。与其他工具串联使用：将 CLI 输出通过管道传给 Git 以自动提交，或使用 Webhook 从 Jenkins 等服务调用 API 端点。通过指定语言标志（例如 --language java）以匹配技术栈，确保兼容性。

错误处理

始终检查 CLI 退出码；非零表示失败（例如，if [ $? -ne 0 ]; then echo "Error: Invalid input"; fi）。对于 API 调用，应检查响应状态并处理 HTTP 错误，例如表示验证失败的 400 或表示身份验证问题的 401。在代码中，使用 try-except 块包装操作：

try:
    oc.generate_aggregate(context="MyContext", name="InvalidAggregate", invariants=["invalid"])
except oc.DDDValidationError as e:  # Specific error for invariant checks
    print(f"Error: {e.message} - Fix invariants and retry")
except oc.AuthError as e:  # For $OPENCLAW_API_KEY issues
    print("Error: Authentication failed - Set $OPENCLAW_API_KEY")

提前验证输入，例如通过 --validate 等 CLI 标志确保上下文名称仅包含字母数字字符。

具体使用示例

1. 为电商订单系统构建有界上下文： 首先，确定领域：订单包含 Order 和 LineItems 等聚合。运行：openclaw ddd generate-context --name OrderContext --description "Manages orders" --modules orders,items 这会生成：./order_context/orders.py 和 ./order_context/items.py。接下来，添加聚合：openclaw ddd generate-aggregate --context OrderContext --name OrderAggregate --root Order --invariants "total > 0" 在代码中导入并使用：from order_context.aggregates import OrderAggregate; order = OrderAggregate(order_id=1)

2. 在用户注册流程中处理领域事件： 首先生成事件：openclaw ddd generate-event --context UserContext --name UserRegisteredEvent --payload "user_id:UUID, email:String" 这会创建 ./user_context/events/user_registered_event.py。然后，通过 API 触发事件：curl -H "Authorization: Bearer $OPENCLAW_API_KEY" -X POST /api/v1/ddd/events -d '{"context": "UserContext", "event": "UserRegisteredEvent", "payload": {"user_id": "123"}}' 在应用代码中，使用 oc.publish_event(context="UserContext", event="UserRegisteredEvent", payload={"user_id": "123"}) 通知其他服务。

图关系

• 与集群相关：se-architecture（例如，与其他架构技能共享依赖项）。
• 通过标签关联：ddd（关联到领域建模工具）、domain（关联到实体管理技能）、bounded-context（关联到微服务模式）、architecture（关联到 se-architecture 集群中的更多设计工具）。