MoneyTree.Core 核心抽象层

📋 概述

MoneyTree.Core 是 MoneyTree 框架的基石模块，提供纯粹的领域抽象，零持久化依赖。所有其他模块均基于此层构建。它定义了实体、值对象、领域事件、工作单元以及统一 API 响应等核心类型。

🏗️ 项目文件结构

MoneyTree.Core/
├── MoneyTree.Core.csproj
├── GlobalUsings.cs
├── Abstractions/                  # 抽象接口层
│   ├── IEntity.cs                 # 实体接口
│   ├── IAggregateRoot.cs          # 聚合根接口
│   ├── IValueObject.cs            # 值对象接口
│   ├── IUnitOfWork.cs             # 工作单元接口（泛型 + 非泛型）
│   ├── IModule.cs                 # 模块化注册接口
│   └── IDomainEvent.cs            # 领域事件接口
├── Primitives/                    # 基类实现
│   ├── EntityBase.cs              # 实体抽象基类（领域事件管理）
│   ├── SnowflakeEntity.cs         # 实体基类（雪花ID，默认推荐）
│   ├── UlidEntity.cs              # 实体基类（ULID string ID，可选）
│   ├── AggregateRoot.cs           # 聚合根基类
│   ├── ValueObject.cs             # 值对象基类（自动值相等）
│   ├── Enumeration.cs             # 枚举类基类
│   ├── DomainEvent.cs             # 领域事件基类
│   ├── DomainException.cs         # 领域异常
│   ├── PageQuery.cs               # 统一分页查询参数
│   ├── PageResult.cs              # 分页结果（无汇总）
│   ├── PageResultTSummary.cs      # 分页结果（带汇总）
│   ├── ApiResult.cs               # 统一 API 响应（无数据）
│   ├── ApiResultT.cs              # 统一 API 响应（带数据）
│   └── SecretEncryptionService.cs # AES-256-GCM 共享加密服务
├── Guard/
│   └── Ensure.cs                  # 守卫断言工具类
├── Attributes/
│   ├── IoCAttribute.cs              # [IoC] 类级 IoC 注册标记（替代 IInjectable）
│   ├── InjectAttribute.cs           # [Inject] 属性注入标记（含 KeyName）
│   └── TimeZoneAwareAttribute.cs    # [TimeZoneAware] 时区感知标记
├── CurrentUser/
│   ├── ICurrentUser.cs            # 当前用户接口
│   └── CurrentUser.cs             # 当前用户基类
└── Extensions/
    ├── UlidExtension.cs            # Ulid 扩展方法
    ├── BaseNConverter.cs           # 任意进制（2~64）转换工具
    ├── DateTimeExtension.cs        # DateTime 扩展（如解析 yyyy-MM 格式）
    ├── EnumHelper.cs               # 枚举描述、下拉框选项、字典转换
    ├── ListExtension.cs            # IList/IEnumerable 安全遍历扩展
    ├── SnowflakeIdGenerator.cs     # 雪花算法 ID 生成器（64 位有序唯一 ID）
    ├── StringExtension.cs          # 字符串扩展（snake_case 转换等）
    └── UserIdHelper.cs             # 用户/会员 ID 与邀请码生成

🧱 领域模型基类

MoneyTree.Core 提供了一套完整的 DDD 领域模型基类，帮助开发者快速构建符合领域驱动设计规范的业务模型。

EntityBase — 实体抽象基类

所有实体基类的根基，统一提供领域事件管理能力（AddDomainEvent/RemoveDomainEvent/ClearDomainEvents）。 Entity（ULID）和 SnowflakeEntity（雪花ID）均继承此类，消除领域事件管理的代码重复。 ID 的类型和生成策略由子类自行声明（因 init 属性默认值需在声明时设置）。

UlidEntity — 实体基类（string ID，Ulid）

继承 EntityBase，ID 为 string 类型（存储 Ulid 的 26 字符 Base32 字符串）。 适用于需要字符串主键的场景。框架预置能力，业务项目按需选用。 主键映射通过 EF Core Fluent API 配置，不使用 [Key] 数据注解。

public abstract class UlidEntity : EntityBase
{
    public string Id { get; init; } = Ulid.NewUlid().ToString();
}

SnowflakeEntity — 实体基类（long ID，雪花算法）

继承 EntityBase，默认推荐使用的实体基类。ID 为 long 类型（64 位有序唯一雪花 ID），对应数据库 bigint 列。 线程安全的雪花 ID 生成器在类初始化时自动分配主键。 主键映射通过 EF Core Fluent API 配置，不使用 [Key] 数据注解。

public abstract class SnowflakeEntity : EntityBase
{
    public long Id { get; init; } = _snowflake.Value.NextId();
}

public class Order : SnowflakeEntity  // 或继承 AggregateRoot（已基于 SnowflakeEntity）
{
    public long CustomerId { get; set; }  // 关联 User 的 ID（雪花 ID）
}

AggregateRoot — 聚合根

继承自 SnowflakeEntity，标记为聚合根。聚合根是领域模型中唯一允许外部访问的入口。 所有聚合根的 ID 均为 long（雪花 ID）。

ValueObject — 值对象

基于属性值的相等比较，而非 ID 引用。通过 GetEqualityComponents() 定义参与比较的属性。

public class Address : ValueObject
{
    public string Street { get; }
    public string City { get; }

    protected override IEnumerable<object> GetEqualityComponents()
    {
        yield return Street;
        yield return City;
    }
}

Enumeration — 枚举类

替代原始 enum 类型，支持更多的行为和属性：

public class OrderStatus : Enumeration
{
    public static readonly OrderStatus Pending = new(1, "待处理");
    public static readonly OrderStatus Shipped = new(2, "已发货");
    public static readonly OrderStatus Delivered = new(3, "已签收");
}

DomainEvent — 领域事件

领域事件基类，结合 MediatR.Contracts 实现事件驱动：

public class OrderCreatedDomainEvent : DomainEvent
{
    public string OrderId { get; }

    public OrderCreatedDomainEvent(string orderId)
    {
        OrderId = orderId;
    }
}

🔄 工作单元与依赖注入

👤 当前用户抽象

📦 ApiResult 设计

ApiResult 使用数字状态码 Code 替代 HTTP 状态码，提供丰富的静态工厂方法：

ApiResult 属性

ApiResult<T> 额外属性

实例方法

响应格式

{
    "code": 200,
    "message": null,
    "data": { "id": "01H2X5J4K3M7Q8R9S0T1V2W3X4", "name": "订单001" }
}

📄 PageQuery 分页设计

基于毫秒时间戳锚点的统一分页设计，避免传统偏移分页的数据漂移问题。

分页流程

客户端首次请求（PageIndex=1）
        │
        ▼
PageTime 返回当前 UTC 时间，并刷新 Timestamp
查询：WHERE CreatedAt <= PageTime OFFSET (PageIndex-1)*PageSize LIMIT PageSize
        │
        ▼
返回 { items, summary, totalCount, timestamp }
        │
        ▼
客户端翻页（PageIndex=2，回传 Timestamp）
        │
        ▼
PageTime 基于 Timestamp 还原分页时间，数据视图保持一致

PageResult<T>（无 Summary）

PageResult<T, TSummary>（带 Summary）

🛡️ Ensure 守卫工具

提供一组参数校验断言方法：

🧰 Extensions 工具类

SnowflakeIdGenerator — 雪花 ID 生成器

基于 Twitter Snowflake 算法的 64 位有序唯一 ID 生成器，线程安全。

// 使用全局单例
var generator = SnowflakeIdGenerator.Instance;
// 或手动指定 datacenterId 和 workerId 创建独立实例
var customGen = new SnowflakeIdGenerator(datacenterId: 1, workerId: 2);

// 生成 ID
long id = generator.NextId();          // 686542123456789012
string idStr = generator.NextIdString(); // "686542123456789012"

// 从 ID 反向提取生成时间
var timestamp = SnowflakeIdGenerator.ExtractTimestampFromId(id);

UserIdHelper — 用户 ID 与邀请码生成

提供多种适用于用户与会员场景的 ID 生成策略：

BaseNConverter — 任意进制转换

支持 2~64 进制字符串与整数（ulong/long/BigInteger）互转：

// 编码
string base62 = BaseNConverter.ToBase(12345UL, 62);     // "3D7"
string hex = BaseNConverter.ToBase(255UL, 16);           // "FF"

// 解码
ulong value = BaseNConverter.FromBaseToUInt64("3D7", 62); // 12345
BigInteger big = BaseNConverter.FromBaseToBigInteger("FF", 16); // 255

EnumHelper — 枚举帮助类

ListExtension — 集合安全遍历

StringExtension — 字符串扩展

DateTimeExtension — 日期扩展

⚠️ 领域异常

DomainException 用于在领域层抛出业务异常，包含错误码：

throw new DomainException("已发货的订单无法取消", 409, "ORDER_SHIPPED");

🎯 设计原则

• 零持久化依赖：Core 层不引用 EF Core 或任何数据库包
• ID 简单直接：默认使用 long（雪花 ID），对应数据库 bigint 列
• 无外键关联：通过 long 类型的 CustomerId 存储关联 ID
• 自动事务：IUnitOfWork.SaveChangesAsync() 内部自动处理事务
• 时区时间：配合 [TimeZoneAware] 特性或 UseTimeZoneAware() Fluent API 保障时区正确（按需配置，非全量应用）。MySQL 使用 CrossTimeZoneConverter，PG/SQL Server 使用 UtcDateTimeConverter。