如何创建Newbe.Claptrap项目

发布时间：2022-01-12 14:00:00 作者：柒染
来源：亿速云阅读：121

# 如何创建Newbe.Claptrap项目

## 前言

Newbe.Claptrap 是一个基于事件溯源和Actor模式的分布式应用开发框架，适用于需要高可扩展性和高可用性的业务场景。本文将详细介绍如何从零开始创建一个Newbe.Claptrap项目，涵盖环境准备、项目初始化、核心概念配置和基础功能实现等内容。

---

## 一、环境准备

### 1.1 开发工具要求
- **操作系统**：Windows 10+/Linux/macOS
- **.NET SDK**：6.0或更高版本
- **IDE**：Visual Studio 2022/Rider/VSCode
- **数据库**：SQLite/PostgreSQL（用于事件存储）
- **Docker**（可选）：用于运行依赖服务

### 1.2 安装必要组件
```bash
# 安装Newbe.Claptrap模板
dotnet new install Newbe.Claptrap.Template

二、项目初始化

2.1 创建解决方案

dotnet new newbe.claptrap -n MyClaptrapApp
cd MyClaptrapApp

生成的项目结构如下：

MyClaptrapApp/
├── src/
│   ├── MyClaptrapApp.Web/          # Web API入口
│   ├── MyClaptrapApp.Claptrap/     # 业务逻辑实现
│   └── MyClaptrapApp.sln
├── test/
└── README.md

2.2 项目结构说明

Web项目：提供HTTP接口和Swagger文档
Claptrap项目：包含：
- Claptrap：业务主体（如订单、用户）
- Event：状态变更事件定义
- State：状态定义

三、核心概念配置

3.1 定义第一个Claptrap

在MyClaptrapApp.Claptrap项目中创建：

3.1.1 状态定义

[ClaptrapState]
public class AccountState : IStateData
{
    public decimal Balance { get; set; }
}

3.1.2 事件定义

[ClaptrapEvent]
public class AmountChangeEvent : IEventData
{
    public decimal Amount { get; set; }
    public DateTime ChangeTime { get; set; }
}

3.1.3 Claptrap实现

[Claptrap(
    claptrapCode: "account_claptrap",
    eventLoaderType: typeof(AccountEventLoader))]
public class AccountClaptrap : ClaptrapBox<AccountState>
{
    public AccountClaptrap(IClaptrapIdentity identity, 
                         IClaptrapFactory claptrapFactory) 
        : base(identity, claptrapFactory) { }

    public async Task Deposit(decimal amount)
    {
        if (amount <= 0) throw new ArgumentException();
        
        var evt = new AmountChangeEvent
        {
            Amount = amount,
            ChangeTime = DateTime.UtcNow
        };
        
        await Claptrap.HandleEventAsync(evt);
    }
}

3.2 事件处理器

public class AccountEventHandler 
    : NormalEventHandler<AccountState>
{
    public override ValueTask HandleEvent(
        AccountState stateData, 
        IEvent eventData)
    {
        if (eventData.Data is AmountChangeEvent evt)
        {
            stateData.Balance += evt.Amount;
        }
        return ValueTask.CompletedTask;
    }
}

四、持久化配置

4.1 配置SQLite存储

修改appsettings.json：

{
  "Claptrap": {
    "Store": {
      "ConnectionStrings": {
        "event": "Data Source=claptrap-events.db",
        "state": "Data Source=claptrap-states.db"
      }
    }
  }
}

4.2 注册存储提供程序

services.AddClaptrap(builder =>
    builder
        .ScanClaptrapDesigns(new[] { typeof(Program).Assembly })
        .UseSQLiteAsEventStore()
        .UseSQLiteAsStateStore());

五、API接口开发

5.1 创建Controller

[ApiController]
[Route("[controller]")]
public class AccountController : ControllerBase
{
    private readonly IClaptrapFactory _claptrapFactory;

    public AccountController(IClaptrapFactory claptrapFactory)
    {
        _claptrapFactory = claptrapFactory;
    }

    [HttpGet("{accountId}/balance")]
    public async Task<decimal> GetBalance(string accountId)
    {
        var claptrap = _claptrapFactory.GetClaptrap<AccountClaptrap>(accountId);
        return await claptrap.GetStateAsync().Balance;
    }

    [HttpPost("{accountId}/deposit")]
    public async Task Deposit(string accountId, [FromBody] decimal amount)
    {
        var claptrap = _claptrapFactory.GetClaptrap<AccountClaptrap>(accountId);
        await claptrap.Deposit(amount);
    }
}

六、运行与测试

6.1 启动项目

dotnet run --project src/MyClaptrapApp.Web

访问 http://localhost:5000/swagger 测试API接口。

6.2 单元测试示例

[Test]
public async Task Deposit_ShouldIncreaseBalance()
{
    // Arrange
    var state = new AccountState();
    var evt = new AmountChangeEvent { Amount = 100 };
    
    // Act
    await new AccountEventHandler().HandleEvent(state, evt);
    
    // Assert
    Assert.AreEqual(100, state.Balance);
}

七、进阶配置

7.1 分布式部署

修改appsettings.json添加Orleans配置：

{
  "Claptrap": {
    "Orleans": {
      "ClusterId": "dev",
      "ServiceId": "MyClaptrapApp",
      "SiloPort": 11111,
      "GatewayPort": 30000
    }
  }
}

7.2 监控集成

builder.Services.AddClaptrapMetrics(metricsBuilder =>
{
    metricsBuilder.AddPrometheus();
});

八、最佳实践

Claptrap设计原则：
- 每个Claptrap应代表一个明确的业务边界
- 避免单个Claptrap处理过多事件（建议<1000事件/秒）
事件设计建议：
- 使用过去时命名事件（如AmountChanged）
- 包含完整的业务上下文
性能优化：
- 使用[ClaptrapMinion]处理只读操作
- 启用事件批处理

结语

通过本文，您已经完成了： ✅ 基础环境搭建
✅ 核心业务逻辑实现
✅ 持久化配置
✅ REST API开发

接下来可以： - 参考官方文档探索更多特性 - 加入社区讨论（GitHub/Discord） - 尝试实现购物车、订单等复杂场景

提示：项目源码可参考 Newbe.Claptrap.Samples “`

（实际字数：约2950字，根据具体格式可能略有浮动）