BugFree.XCode.Extensions 1.1.2026.121-beta1110

BugFree.Framework.Component.Extensions

本目录用于存放 BugFree 的“扩展组件”类库：在不改变上游组件（例如 NewLife/XCode、Microsoft DI 等）使用方式的前提下，提供更贴近 BugFree 项目生态的封装与约定。

组件列表

• BugFree.XCode.Extensions：XCode（ORM）相关扩展（数据库连接配置、防篡改校验、查询条件转换等）。

BugFree.XCode.Extensions

目标框架

• net8.0
• net10.0

依赖项

• BugFree.Configuration：配置加载/保存能力（支持加密、绑定到配置文件等）。
• NewLife.XCode：ORM/数据访问基础能力。
• Microsoft.Extensions.DependencyInjection.Abstractions：依赖注入抽象。

功能概览

1. 数据库连接配置（DbSetting）

提供统一的数据库连接配置模型，支持：

• 多数据源配置（DbConns）
• 连接串等敏感信息加密保存（[Config(IsEncrypted = true)]）
• 防篡改校验策略配置（TamperProofOptions）

配置类型：BugFree.XCode.Extensions.DbSetting

2. Linq 条件转换（LinqExpressionBuilder<TEntity>）

将 Linq 的布尔表达式（Expression<Func<TEntity, Boolean>>）转换为 XCode 的 Expression/WhereExpression，用于在不拼接 SQL 的情况下构建动态查询条件。

支持范围（见 Expressions\LinqExpressionBuilder.cs 头部注释）：

• 逻辑运算：AND/OR（&& / ||）
• 比较运算：==、!=、>、>=、<、<=
• 字符串：Contains / StartsWith / EndsWith
• 布尔字段：e => e.IsEnable、e => !e.IsEnable
• 集合包含：new[] { 1,2,3 }.Contains(e.Id) / list.Contains(e.Id)（转换为 IN）

使用示例（示意）：

using BugFree.XCode.Extensions.Expressions;

var builder = new LinqExpressionBuilder<MyEntity>();
var where = builder.Build(e => e.Name.Contains("张") && e.Age >= 18);

// MyEntity.FindAll(where, ...)

3. QueryCondition 条件转换（QueryConditionExpressionBuilder<TEntity>）

将前端通用条件模型（字段名/操作符/值/逻辑符）转换为 XCode 的 Expression。

适用场景：

• 前端以统一结构表达筛选条件（例如列表筛选、组合检索）；
• 后端把条件安全映射到实体字段元数据（IEntityFactory.Fields），避免直接拼 SQL。

支持操作符（见 Expressions\QueryConditionExpressionBuilder.cs）：

• Equal / NotEqual
• GreaterThan / GreaterThanOrEqual
• LessThan / LessThanOrEqual
• Contains / StartsWith / EndsWith
• In / NotIn（值为集合时转换为 FieldItem.In/NotIn）

类型对齐：

• 条件值按字段类型进行 ChangeType（兼容 JSON 数字默认 Int64/Double、日期字符串等）。

使用示例（示意）：

using BugFree.XCode.Extensions.Expressions;
using BugFree.XCode.Extensions.Model;

var builder = new QueryConditionExpressionBuilder<MyEntity>();
var where = builder.Build([
    new QueryCondition { Field = "Name", Operator = QueryOperator.Contains, Value = "张" },
    new QueryCondition { Field = "Age", Operator = QueryOperator.GreaterThanOrEqual, Value = 18, Logical = QueryLogical.And },
]);

// MyEntity.FindAll(where, ...)

安装

在使用方项目中引用：

• NuGet：BugFree.XCode.Extensions

或在本仓库中通过项目引用：

• BugFree.Framework\Component\Extensions\BugFree.XCode.Extensions\BugFree.XCode.Extensions.csproj

配置示例

DbSetting 继承自 Config<T>，可通过 Load() / Save() 与配置文件交互（配置文件格式由 BugFree.Configuration 决定）。

字段结构说明：

• DbConns：数据库连接列表

  • Name：连接名（如 default、report）
  • Provider：数据库提供程序（如 MySql、SqlServer、SQLite）
  • ConnectionString：连接串

• TamperProofOptions：防篡改配置

  • IsEnable：是否启用
  • SignField：签名字段（默认 Sign）
  • ExcludeFields：参与签名字段黑名单
  • IncludePrimaryKeys：是否把主键纳入签名
  • HashAlgorithm：签名算法（默认 HMACSHA256）

使用示例

1. 读取并选择默认连接

using BugFree.XCode.Extensions;

var set = DbSetting.Load();
var conn = set.DbConns?.FirstOrDefault(e => e.Name == "default");
if (null == conn) throw new InvalidOperationException("未配置 default 数据库连接");

// conn.Provider / conn.ConnectionString

2. 防篡改（行级签名）基础用法

TamperProofOptions 提供三步核心能力：

• BuildCanonical(IEntity, IEnumerable<FieldItem>)：构造稳定原文
• BuildSign(String)：计算签名
• VerifySign(String, String)：校验签名

using BugFree.XCode.Extensions;

var opt = DbSetting.Load().TamperProofOptions;
if (opt?.IsEnable == true)
{
    // canonical = opt.BuildCanonical(entity, fields);
    // sign = opt.BuildSign(canonical);
    // ok = opt.VerifySign(canonical, entity[opt.SignField] + "");
}

测试

仓库内可参考测试工程：

• TestProject\Db\TamperProofTest.cs

运行测试（示例）：

dotnet test .\TestProject\TestProject.csproj -c Release -f net8.0 --filter FullyQualifiedName~TamperProofTest

注意事项

• 防篡改校验属于“应用层保护”，最终安全性仍依赖密钥保护与数据库权限策略。
• ExcludeFields 建议排除审计字段（Create*/Update*）等高频变化字段，减少无意义的签名变化。