跳到主要内容
版本：Next

扩展属性数据库检索指南

一、配置说明​

1. 数据库配置​

必须在DbContext中注册JSON_EXTRACT函数:

public class YourDbContext : AbpDbContext<YourDbContext>
{
    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        // 注册JSON查询函数
        builder.HasDbFunction(() =>
            CMSDbFunctionsExtensions.JSON_EXTRACT(default, default));

        // 配置对象扩展
        builder.TryConfigureObjectExtensions<YourDbContext>();
    }
}

2. 查询功能​

支持两种匹配模式:

var extraProps = new ExtraPropertyDictionary
{
    { "name", "张三" },     // 模糊匹配
    { "@status", "1" }      // 精确匹配(@前缀)
};

var query = _repository.GetQueryable().JsonMatch(extraProps);

3. 前端传参格式​

前端可通过URL参数传递扩展属性，格式如下：

url?Key=Value&ExtraProperties%5BKey%5D=Value

说明：

  • %5B和%5D是URL编码的方括号字符[和]
  • 使用ExtraProperties[Key]指定字典Key
  • 使用Key=Value对字典赋值

4. 数据格式要求​

数据库中ExtraProperties字段存储的内容必须是合法的JSON对象格式，具体要求如下：

{
    "key1": "value1",
    "key2": "value2"
}

注意事项：

  • 必须使用花括号包裹
  • 必须是有效的键值对格式
  • 不支持存储普通字符串或数组
  • 键名必须使用双引号
  • 值支持字符串、数字、布尔值等JSON基础类型

二、性能优化要点​

1. 查询优化​

public async Task<List<Order>> GetListAsync(OrderListInput input)
{
    // 1. 基础查询
    var query = _repository.GetQueryable()
        .Where(x => x.Status == OrderStatus.Active);

    // 2. 必要的Include
    query = query.Include(x => x.RequiredDetails);

    // 3. JSON查询放最后
    if (input.ExtraProperties?.Any() == true)
    {
        query = query.JsonMatch(input.ExtraProperties);
    }

    // 4. 分页
    return await query
        .Skip(input.SkipCount)
        .Take(input.MaxResultCount)
        .ToListAsync();
}

2. 数据库优化​

-- 创建JSON索引
CREATE INDEX idx_order_extra_status
ON Orders ((JSON_EXTRACT(ExtraProperties, '$.status')));

-- 限制JSON字段大小
ALTER TABLE Orders
ALTER COLUMN ExtraProperties NVARCHAR(1000);

三、使用限制​

1. 不建议场景​

  • 大表全表扫描
  • 频繁更新JSON字段
  • 复杂统计查询
  • 高频查询字段

2. 建议场景​

  • 动态扩展属性
  • 非核心查询字段
  • 数据量可控场景
  • 低频查询场景

四、监控建议​

  1. 性能监控：
  • 记录耗时>1s的JSON查询
  • 监控ExtraProperties字段大小
  • 跟踪索引使用情况
  1. 限制措施：
  • 设置查询超时
  • 限制JSON字段大小
  • 控制查询条件数量

五、最佳实践总结​

  1. 配置规范：
  • 必须注册JSON_EXTRACT函数
  • 建立必要的JSON索引
  • 限制JSON字段大小
  1. 查询规范：
  • 优先使用普通字段过滤
  • JsonMatch放在查询最后
  • 必须使用分页
  • 合理使用Include
  1. 开发建议：
  • 核心字段使用普通列
  • 动态扩展字段使用ExtraProperties
  • 保持JSON数据结构简单
  • 避免深层嵌套查询

通过合理使用ExtraProperties，可以在保持系统灵活性的同时，确保查询性能。