BugFree.XCode.Extensions 1.2.2026.806-beta1125

BugFree.XCode.Extensions

NewLife.XCode 企业级扩展库，提供实体基类增强、多数据源初始化、通用查询条件和代码生成等能力。

项目结构

BugFree.XCode.Extensions/          # 核心类库
├── BugFreeEntity.cs               # 实体基类（字段过滤、敏感字段自动排除）
├── BugFreeEntity.Linq.cs          # Linq 表达式查询扩展
├── BugFreeEntity.QueryCondition.cs # 前端通用查询条件扩展
├── DbOptions.cs                   # 数据库连接及字段过滤配置
├── ExpressionExtensions.cs        # XCode 表达式辅助扩展
├── ServiceCollectionExtensions.cs # XCode DI 初始化扩展
├── Expressions/
│   └── QueryConditionExpressionProvider.cs # QueryCondition→WhereExpression
├── ShardPolicy/
│   ├── FieldValueShardPolicy.cs           # 单字段按值分库/分表策略
│   └── DualFieldValueShardPolicy.cs       # 双字段按值/时间组合分库分表策略
└── Model/
    └── QueryCondition.cs          # 通用查询条件模型

DbEntityTool/                      # 代码生成工具
└── Builder/
    ├── BugFreeEntityBuilder.cs    # 自定义实体生成器
    ├── BugFreeInterfaceBuilder.cs # 自定义接口生成器
    └── BugFreeModelBuilder.cs    # 自定义模型生成器

BugFree.XCode.Extensions.TestProject/ # 单元测试项目
├── DbOptionsTests.cs                 # 敏感字段/删除字段配置测试
├── EntityInitTests.cs                # 实体初始化测试
├── XCodeLinqQueryTests.cs             # XCode LINQ Provider 集成测试
├── QueryConditionWhereExpressionTests.cs # QueryCondition→WhereExpression 测试
└── Fixtures/
    ├── TestUser.cs                   # 表达式测试实体
    └── LinqTestUser.cs               # SQLite LINQ 集成测试实体

核心功能

1. 实体基类增强 (BugFreeEntity<TEntity>)

继承自 XCode Entity<T>，提供：

• 列表查询字段：自动过滤敏感字段（密码、令牌、密钥等）和超长文本字段，优化列表查询性能
• 实体查询字段：自动过滤敏感字段，适用于详情页展示
• 字段缓存热更新：配置变更后调用 InvalidateFieldCache() 使缓存失效

2. 多数据源初始化 (ServiceCollectionExtensions)

通过 ASP.NET Core DI 一键初始化：

builder.Services.InitConnection();

支持多数据源配置（default、report、archive 等），自动注册连接字符串、检查数据库和表结构、初始化实体工厂。

3. 数据库配置 (DbOptions)

支持从配置文件加载：

• 多数据源连接字符串（加密存储）
• 敏感字段正则匹配规则
• 逻辑删除字段识别规则
• 字段显示长度阈值
• 拷贝时排除字段列表

4. 通用查询条件

QueryCondition 方式（前端通用模型）

var conditions = new List<QueryCondition>
{
    new() { Field = "Name", Operator = QueryOperator.Contains, Value = "admin" },
    new() { Field = "Enable", Operator = QueryOperator.Equal, Value = true, Logical = QueryLogical.And }
};
var user = BugFreeEntity<User>.Find(conditions);

QueryCondition 直接转换为 XCode WhereExpression，不经过 LINQ 表达式树，继续支持 Equal、NotEqual、GreaterThan、GreaterThanOrEqual、LessThan、LessThanOrEqual、Contains、StartsWith、EndsWith、In、NotIn、Between、IsNull、IsNotNull。 无效字段、敏感字段、空集合及类型转换失败会直接抛出异常，不会静默丢弃条件。

Linq 表达式方式

var users = BugFreeEntity<User>.FindAll(x => x.Name.Contains("张") && x.Age >= 18);
var total = BugFreeEntity<User>.FindCount(x => x.Age >= 18);

LINQ 查询统一复用 XCode Entity<TEntity>.Query 和 EntityQueryProvider，支持字段位于比较运算符左侧的 &&/||、==/!=、>/>=/</<=，以及字符串 Contains/StartsWith/EndsWith。

FindData、FindMin、FindMax 和 Delete 继续使用 XCode 原生数据库端操作，过滤条件由同一 Provider 解析。 具体表达式支持范围跟随所引用的 XCode 版本；当 BuildWhere 无法生成任何条件时会抛出 NotSupportedException。

5. 分库分表策略 (ShardPolicy)

提供 XCode 分片策略扩展：

• FieldValueShardPolicy：单字段按值分库、分表或分库分表。
• DualFieldValueShardPolicy：分库字段和分表字段独立配置，每个维度可按字段值或时间字段路由。

6. 代码生成工具 (DbEntityTool)

基于 NewLife.XCode 代码生成框架，提供自定义的实体类、接口和模型类的生成器，支持：

• 自定义类名模板
• 接口继承
• 中/英文文件名
• 批量生成

单元测试

项目使用 NUnit 框架进行单元测试，覆盖核心逻辑：

• DbOptions 测试：验证敏感字段匹配、逻辑删除字段识别、边界条件（空值/大小写/部分匹配）
• 实体初始化测试：验证实体字段注册
• XCode LINQ 测试：验证官方 Provider、比较/逻辑/字符串表达式、闭包变量、Query 组合查询，以及 Find/FindAll/FindCount/FindMin/FindMax/FindData/Delete 的 SQLite 端到端行为
• QueryCondition 测试：验证 WhereExpression、逻辑组合、IN/Between/Null 和 JSON 数组转换
• ExpressionExtensions 测试：验证字段匹配、大小写规则和嵌套 WhereExpression 查找
• ShardPolicy 测试：验证单字段值分片、双字段值/时间组合分片、缺失条件和异常边界

运行测试

dotnet test BugFree.XCode.Extensions.TestProject

环境要求

• .NET 8.0 / .NET 10.0
• NewLife.XCode (>= 12.1.2026.801)
• BugFree.Configuration

安装

通过 NuGet 安装：

dotnet add package BugFree.XCode.Extensions

快速开始

1. 配置 Db 配置节（支持多数据源）：

{
  "Db": {
    "DbConns": [
      {
        "Name": "default",
        "Type": "MySql",
        "ConnectionString": "Server=localhost;Database=mydb;..."
      }
    ]
  }
}

2. 在 Program.cs 中初始化：

var builder = WebApplication.CreateBuilder(args);
builder.Services.InitConnection();

3. 实体类继承 BugFreeEntity<TEntity> 即可使用扩展功能。