RuoVea.ExDto 10.0.0.4

📦 RuoVea.ExDto

纯 BCL 共享契约库 — 提供 RESTful 响应模型、分页参数与结果、17 种业务枚举、实体基类接口、用户上下文抽象、Claim 常量及反射工具，内置 8 种语言的本地化资源，零 NuGet 依赖。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：RESTful 响应模型
  • 场景二：分页参数与结果
  • 场景三：实体基类接口
  • 场景四：用户上下文抽象
  • 场景五：枚举与常量管理
  • 场景六：Claim 常量
• ⚙️ 配置选项详解
• 🧵 线程安全
• 📊 类型速查表
• 🌍 国际化
• ⚠️ 关键警告
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExDto 为 .NET 企业级应用提供统一的 DTO 契约层，避免各层之间重复定义数据结构。纯 BCL 实现，零第三方依赖，可直接放入任何 .NET 8.0+ 项目中。

 ┌──────────────────────────────────────────────────────────┐
 │                    RuoVea.ExDto                           │
 ├──────────────────────────────────────────────────────────┤
 │  RESTful 响应          分页模型           实体接口        │
 │  ├─ RestfulResult      ├─ PageParam       ├─ IPrimaryKey  │
 │  ├─ RestfulResult<T>   ├─ PageParam<T>    ├─ IAuditable   │
 │  ├─ Restful (工厂)     ├─ PageResult<T>   ├─ IDeleted     │
 │  └─ Restful<T> (工厂)  ├─ PageData        ├─ IDataEntity  │
 │                        └─ Pagination      └─ ITenantEntity│
 │                                                           │
 │  枚举系统 (17种)       Claim 常量         用户上下文      │
 │  ├─ CodeStatus         ├─ CLAINM_USERID   ├─ ICurrentUser │
 │  ├─ ErrorEnum (81项)   ├─ CLAINM_ACCOUNT  └─ ICurrentUser<TT>
 │  ├─ DataOpType         ├─ CLAINM_NAME
 │  ├─ BusinessType       ├─ TENANT_ID
 │  ├─ QueryTypeEnum      └─ ... (共14项)
 │  └─ ... (共17种)
 │                                                           │
 │  反射工具              国际化 (8语言)                     │
 │  ├─ EnumManager        ├─ zh-CN / zh-TW / zh-HK          │
 │  └─ DisplayInfo        ├─ en-US / fr-FR / ja-JP / vi-VN │
 │                        └─ I18nConverter (NET5.0+)        │
 ├──────────────────────────────────────────────────────────┤
 │  命名空间: RuoVea.ExDto | RuoVea.ExEnum                    │
 │  零依赖   纯 BCL 共享契约库                                │
 └──────────────────────────────────────────────────────────┘

设计原则

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExDto --version 8.0.1.5

# .NET 10.0
dotnet add package RuoVea.ExDto --version 10.0.0.3

Package Manager

Install-Package RuoVea.ExDto -Version 8.0.1.5

PackageReference

<PackageReference Include="RuoVea.ExDto" Version="8.0.1.5" />

支持的 Target Framework

⚡ 30 秒快速开始

1. 导入命名空间

using RuoVea.ExDto;      // 模型、接口、工具类
using RuoVea.ExEnum;      // 所有枚举类型

2. 第一行代码

// <inheritdoc cref="Restful{T}.Success"/>
// 创建成功响应
var successResult = Restful<string>.Success("Hello, ExDto!");

// <inheritdoc cref="Restful.Bad(string)"/>
// 创建错误响应
var errorResult = Restful.Bad("参数校验失败");

// <inheritdoc cref="PageParam"/>
// 分页查询参数
var pageParam = new PageParam(pageNo: 1, pageSize: 20)
{
    Sidx = "CreateTime",
    Sord = "desc"
};

// <inheritdoc cref="PageResult{T}"/>
// 分页结果
var pageResult = new PageResult<string>(
    rows: new[] { "A", "B", "C" },
    pageNo: 1,
    pageSize: 20,
    totalRows: 100
);
Console.WriteLine($"共 {pageResult.TotalPage} 页，{pageResult.TotalRows} 条记录");

3. 使用枚举和反射工具

// <inheritdoc cref="EnumManager.GetEnumItems{T}"/>
var adminTypes = EnumManager.GetEnumItems<AdminType>();
// → [{ Key: "None", Value: "0" }, { Key: "Admin", Value: "1" }, { Key: "SuperAdmin", Value: "2" }]

// <inheritdoc cref="EnumManager.GetAllEnumTypesInfo"/>
var allEnums = EnumManager.GetAllEnumTypesInfo();
// → 返回当前程序集中所有 17 种枚举的结构化信息

// <inheritdoc cref="ClaimConst.GetAllConstantInfos"/>
var claimInfo = ClaimConst.GetAllConstantInfos();
// → 14 个 Claim 常量的结构化元数据

30 秒内你完成了: RESTful 成功/失败响应 → 分页参数构建 → 枚举反射查询 → Claim 常量读取。无需任何 DI 注册或配置。

🧩 核心场景

场景一：RESTful 响应模型

┌────────────┐   Restful<T>.Success(data)   ┌──────────────────────┐
│  业务数据   │ ──────────────────────────▶ │  RestfulResult<T>     │
│  (T data)   │                              │  ├─ Code: OK (200)    │
└────────────┘                              │  ├─ Data: <T>         │
                                            │  ├─ Message: string   │
┌────────────┐   Restful.Bad(message)       │  ├─ Extras: object    │
│  错误信息   │ ──────────────────────────▶ │  └─ Timestamp: long   │
└────────────┘                              └──────────────────────┘

泛型响应

// <inheritdoc cref="Restful{T}.Success(T)"/>
var result = Restful<UserDto>.Success(new UserDto { Id = 1, Name = "张三" });
// result.Code == CodeStatus.OK
// result.Data is UserDto

// <inheritdoc cref="Restful{T}.Bad(string)"/>
var error = Restful<UserDto>.Bad("用户名已存在");
// error.Code == CodeStatus.BadRequest (400)
// error.Message == "用户名已存在"
// error.Data == null

// <inheritdoc cref="Restful{T}.Bad(CodeStatus, string)"/>
// 自定义状态码
var forbidden = Restful<UserDto>.Bad(CodeStatus.Forbidden, "无权访问该资源");

非泛型响应

// <inheritdoc cref="Restful.Success(object)"/>
var result = Restful.Success(new { Total = 100, Items = new[] { 1, 2, 3 } });

// <inheritdoc cref="Restful.Bad(string)"/>
var error = Restful.Bad("操作失败");

附加数据 (Extras)

// <inheritdoc cref="RestfulResult.Extras"/>
var result = Restful<UserDto>.Success(user);
result.Extras = new { Token = "jwt-token-string", ExpiresIn = 7200 };
// 前端可一并获取 token 和业务数据

✅ 已修复: RestfulResult.Timestamp 已改为 DateTimeOffset.UtcNow.ToUnixTimeSeconds()，输出真正的 Unix 时间戳（UTC 秒），跨时区一致。

场景二：分页参数与结果

┌─────────────────┐                    ┌──────────────────────┐
│  PageParam       │  传入 Service 层   │  PageResult<T>        │
│  ├─ PageNo: 1    │ ────────────────▶ │  ├─ PageNo: 1         │
│  ├─ PageSize: 20 │                    │  ├─ PageSize: 20      │
│  ├─ Sidx: "Id"   │                    │  ├─ TotalRows: 100    │
│  ├─ Sord: "desc" │                    │  ├─ TotalPage: 5      │
│  └─ BeginTime    │                    │  └─ Rows: IEnumerable │
└─────────────────┘                    └──────────────────────┘

// <inheritdoc cref="PageParam"/>
// 基础分页参数
var param = new PageParam
{
    PageNo = 2,
    PageSize = 50,
    Sidx = "CreateTime",
    Sord = "desc",
    BeginTime = DateTime.Now.AddDays(-30),
    EndTime = DateTime.Now
};

// <inheritdoc cref="PageParam{T}"/>
// 带查询条件的分页参数
var paramWithFilter = new PageParam<OrderFilter>
{
    PageNo = 1,
    Filter = new OrderFilter { Status = "pending", MinAmount = 100 }
};

// <inheritdoc cref="PageResult{T}"/>
// 构建分页结果
var rows = await db.Orders
    .Where(o => o.Status == "pending")
    .OrderByDescending(o => o.CreateTime)
    .Skip((param.PageNo - 1) * param.PageSize)
    .Take(param.PageSize)
    .ToListAsync();

var total = await db.Orders.CountAsync(o => o.Status == "pending");

var pageResult = new PageResult<OrderDto>(rows, param.PageNo, param.PageSize, total);
// pageResult.TotalPage 自动计算 (向上取整)

分页模型对比

// <inheritdoc cref="PageData"/>
// 非泛型分页（用于兼容旧接口）
var pageData = new PageData(new { Items = dataList }, 1, 20, 100);

// <inheritdoc cref="Pagination"/>
// 精简分页（TotalPage 基于 Total 自动计算）
var pagination = new Pagination(page: 2, pageSize: 30) { Total = 100 };
Console.WriteLine(pagination.TotalPage); // 4 (100/30 = 3.33 → 向上取整)

❗ TotalPage 计算规则: PageResult<T>、PageData、Pagination 的 TotalPage 均采用 TotalRows % PageSize == 0 ? TotalRows / PageSize : TotalRows / PageSize + 1 的向上取整逻辑。当 TotalRows <= 0 时返回 0。

场景三：实体基类接口

┌──────────────────────────────────────────────────────┐
│                    IDataEntity                         │
│  ├─ IPrimaryKeyEntity: long Id                       │
│  ├─ IAuditableEntity: CreateTime, Creator,            │
│  │                    ModifyTime, Modifier             │
│  └─ IDeletedEntity: IsDelete? (逻辑删除)              │
├──────────────────────────────────────────────────────┤
│  ITenantEntity: long? TenantId (多租户)               │
└──────────────────────────────────────────────────────┘

using RuoVea.ExDto;
using RuoVea.ExEnum;

// <inheritdoc cref="IDataEntity"/>
// 完整的审计实体（主键 + 审计 + 逻辑删除）
public class UserEntity : IDataEntity, ITenantEntity
{
    public long Id { get; set; }
    public DateTime? CreateTime { get; set; }
    public long? Creator { get; set; }
    public DateTime? ModifyTime { get; set; }
    public long? Modifier { get; set; }
    public IsDelete? IsDelete { get; set; }
    public long? TenantId { get; set; }

    // 业务字段
    public string Name { get; set; }
    public string Email { get; set; }
}

// <inheritdoc cref="IAuditableEntity"/>
// 仅审计字段（无主键、无逻辑删除），适用于关联表
public class UserRoleEntity : IAuditableEntity
{
    public long UserId { get; set; }
    public long RoleId { get; set; }
    public DateTime? CreateTime { get; set; }
    public long? Creator { get; set; }
    public DateTime? ModifyTime { get; set; }
    public long? Modifier { get; set; }
}

// 通用仓储约束
public interface IRepository<T> where T : IDataEntity
{
    Task<T> GetByIdAsync(long id);
    Task<PageResult<T>> GetPagedAsync(PageParam param);
    Task SoftDeleteAsync(long id);  // 设置 IsDelete = IsDelete.Y
}

实体接口详解

场景四：用户上下文抽象

using RuoVea.ExDto;

// <inheritdoc cref="ICurrentUser"/>
// 标准 long 型用户上下文
public class AppUser : ICurrentUser
{
    public long UserId { get; set; }
    public long TenantId { get; set; }
    public string Account { get; set; }
    public string Name { get; set; }
    public bool IsSuperAdmin { get; set; }
    public bool IsTenantAdmin { get; set; }

    public T User<T>() where T : class
    {
        // 返回完整用户实体（可配合 EF Core 查询）
        return this as T;
    }
}

// <inheritdoc cref="ICurrentUser{TT}"/>
// 泛型用户上下文（支持 string / Guid 主键）
public class AppUser<TT> : ICurrentUser<TT>
{
    public TT UserId { get; set; }
    public TT TenantId { get; set; }
    public string Account { get; set; }
    public string Name { get; set; }
    public bool IsSuperAdmin { get; set; }
    public bool IsTenantAdmin { get; set; }

    public T User<T>() where T : class => null;
}

// Controller 中使用
[ApiController]
public class OrderController : ControllerBase
{
    private readonly ICurrentUser _currentUser;

    public OrderController(ICurrentUser currentUser)
    {
        _currentUser = currentUser;
    }

    [HttpGet]
    public IActionResult GetOrders()
    {
        // 利用用户上下文进行数据隔离
        if (!_currentUser.IsSuperAdmin)
        {
            // 非超级管理员仅查询本租户数据
            return Ok(await _orderService.GetByTenantAsync(_currentUser.TenantId));
        }
        return Ok(await _orderService.GetAllAsync());
    }
}

场景五：枚举与常量管理

┌──────────────┐    EnumManager.GetEnumItems<T>()    ┌─────────────────┐
│  枚举类型 T   │ ─────────────────────────────────▶ │  List<DisplayInfo>│
│  (17种枚举)   │     EnumManager.GetEnumDictionary<T>()│  (带缓存)        │
└──────────────┘                                    └─────────────────┘

获取单个枚举项

// <inheritdoc cref="EnumManager.GetEnumItems{T}"/>
var items = EnumManager.GetEnumItems<StatusEnum>();
// → [
//     { Key: "ENABLE", Value: "0", Name: "0", Description: "启用" },
//     { Key: "DISABLE", Value: "1", Name: "1", Description: "停用" }
//   ]

// <inheritdoc cref="EnumManager.GetEnumDictionary{T}"/>
var dict = EnumManager.GetEnumDictionary<Gender>();
// → { 1: "男", 2: "女", 3: "未知" }

批量获取与全局查询

// <inheritdoc cref="EnumManager.GetMultipleEnums"/>
var enums = EnumManager.GetMultipleEnums(typeof(StatusEnum), typeof(YesOrNot), typeof(Gender));

// <inheritdoc cref="EnumManager.GetAllEnumTypesInfo"/>
// 获取程序集中所有 17 种枚举的完整层级信息（含子项）
var allEnumInfo = EnumManager.GetAllEnumTypesInfo();
foreach (var enumInfo in allEnumInfo)
{
    Console.WriteLine($"{enumInfo.Name}: {enumInfo.Children.Count} 个值");
}

// <inheritdoc cref="EnumManager.GetSpecifiedEnumInfo"/>
var codeStatusInfo = EnumManager.GetSpecifiedEnumInfo("CodeStatus");
// → 包含 40 个 HTTP 状态码枚举值

// <inheritdoc cref="EnumManager.ClearEnumTypesCache"/>
// 若运行时动态加载了新枚举，可清除缓存强制重新反射
EnumManager.ClearEnumTypesCache();

❗ 性能提示: EnumManager 使用 ConcurrentDictionary 进行三层缓存。首次调用触发反射，后续直接返回缓存。新增 ClearAllCaches() 可一次性清除全部三层缓存；ClearEnumTypesCache() 仅清除类型信息缓存。

场景六：Claim 常量

// <inheritdoc cref="ClaimConst"/>
// 14 个标准 Claim Key 常量，避免硬编码字符串
var userIdClaim = ClaimConst.CLAINM_USERID;     // "UserId"
var accountClaim = ClaimConst.CLAINM_ACCOUNT;    // "Account"
var tenantIdClaim = ClaimConst.TENANT_ID;        // "TenantId"
var openIdClaim = ClaimConst.OpenId;             // "OpenId"

// JWT Token 生成时使用
var claims = new[]
{
    new Claim(ClaimConst.CLAINM_USERID, user.Id.ToString()),
    new Claim(ClaimConst.CLAINM_ACCOUNT, user.Account),
    new Claim(ClaimConst.CLAINM_NAME, user.Name),
    new Claim(ClaimConst.TENANT_ID, user.TenantId?.ToString() ?? ""),
    new Claim(ClaimConst.CLAINM_SUPERADMIN, user.IsSuperAdmin.ToString()),
    new Claim(ClaimConst.LoginMode, "PC")
};

// <inheritdoc cref="ClaimConst.GetAllConstantInfos"/>
var allClaimInfo = ClaimConst.GetAllConstantInfos();
// → 返回 DisplayInfo 树形结构，包含 14 个子项，每项含 Name/ShortName/Description/GroupName/Order
foreach (var child in allClaimInfo.Children)
{
    Console.WriteLine($"{child.Name} = \"{child.Value}\" ({child.Description})");
}

Claim 常量分组

⚙️ 配置选项详解

本包是纯数据契约库，无 DI 扩展方法，所有类型均可直接实例化，无需任何配置。

RestfulResult / RestfulResult<T>

Restful / Restful<T> 工厂方法

PageParam / PageParam<T>

IRESTfulResult 接口

❗ 命名警告: IRESTfulResult 接口定义在文件 IRestfulFilterLog.cs 中，接口名与文件名不匹配。查找该接口时请搜索 IRESTfulResult 而非 IRestfulFilterLog。

DisplayInfo 模型

I18nConverter（条件编译）

// 仅在 NET5.0_OR_GREATER 下可用
#if NET5_0_OR_GREATER
// <inheritdoc cref="I18nConverter.ConvertResxToJson"/>
// 将 resx 资源转换为 JSON 字符串
string json = I18nConverter.ConvertResxToJson();
// → { "continue": "Continue", "badrequest": "Bad Request", ... }
#endif

🧵 线程安全

✅ 全部线程安全。本包是纯数据契约库，所有类型均无共享可变状态。

📊 类型速查表

17 种枚举速查

模型类型速查

接口类型速查

🌍 国际化

i18n 资源类（RuoVea.ExDto.Language 命名空间）提供 8 种语言的本地化字符串，根据 CultureInfo.CurrentUICulture 自动切换：

注：i18n.resx 为默认回退资源（简体中文），其余按 CultureInfo 自动匹配。

using RuoVea.ExDto.Language;

// 当前线程 UI 文化为 en-US 时：
// i18n.@continue → "Continue"
// i18n.badrequest → "Bad Request"
// i18n.notfound → "Not Found"

// 当前线程 UI 文化为 ja-JP 时对应的日语本地化字符串

I18nConverter（NET5.0+ 专属）

#if NET5_0_OR_GREATER
// <inheritdoc cref="I18nConverter.ConvertResxToJson"/>
// 将当前语言的 resx 资源导出为 JSON 字符串
// 可用于前端 i18n 初始化或 API 输出
string json = I18nConverter.ConvertResxToJson();
#endif

⚠️ 关键警告

1. RestfulResult.Timestamp 时区硬编码

// RestfulResult.cs 原始实现:
public long Timestamp { get; set; } = 
    (DateTime.Now.Ticks - new DateTime(1970, 1, 1).Ticks) / 10000000 - 8 * 60 * 60;

✅ 已修复: Timestamp 现使用 DateTimeOffset.UtcNow.ToUnixTimeSeconds() 生成标准 Unix 时间戳，跨时区一致。

2. 无 DI 注册扩展

本包是纯数据库，不包含 IServiceCollection 扩展方法。DI 注册需由调用方自行处理：

// 需自行注册 ICurrentUser 的实现
services.AddScoped<ICurrentUser, AppUser>();

3. IRESTfulResult 接口文件名不匹配

接口 IRESTfulResult 定义在 IRestfulFilterLog.cs 文件中，两者名称不一致。通过 IDE 搜索时应使用接口名 IRESTfulResult 而非文件名。

4. PageData 非泛型限制

PageData.Rows 类型为 object，使用时需要手动类型转换。新项目建议优先使用 PageResult<T>。

5. EnumManager 程序集扫描范围

GetAllEnumTypesInfo() 仅扫描命名空间为 RuoVea.ExEnum 的枚举类型。若在外部程序集定义了同命名空间的枚举，不会被自动扫描到——需使用 GetAllEnums(assemblies) 重载。

🗺️ 版本迁移指南

从手工定义 DTO 迁移

v8.0.x → v10.0.x

• API 无变化。v10.0.x 仅在 net10.0 TFM 上编译，所有公开 API 签名与 v8.0.x 保持一致。
• 无依赖包变更。

📄 License

MIT License © RuoVea

🔗 相关资源: NuGet Gallery · 问题反馈