Muta.ApiExtensions.SqlSugar 1.0.0.7

Muta.ApiExtensions.SqlSugar

Muta.ApiExtensions.SqlSugar 是基于 SqlSugarCore 和 Muta.ApiExtensions.Core 的 WebAPI 数据访问扩展库，提供以下能力：

• SqlSugar 客户端快速注册与数据库初始化钩子。
• 通用仓储基类（增删改查、分页、排序、判重）。
• 通用控制器基类（开箱即用 CRUD + 分页查询接口）。
• Swagger 请求体按场景裁剪（Add/Update 仅展示指定字段）。
• 常用工具扩展（动态谓词、枚举描述转换）。

1. 安装与依赖

Install-Package Muta.ApiExtensions.SqlSugar

主要依赖：

• SqlSugarCore
• Muta.ApiExtensions.Core

2. 快速接入

2.1 appsettings.json

{
  "SqlSugar": [
    {
      "ConnectionString": "Server=localhost;Port=3306;Database=demo;Uid=root;Pwd=123456;",
      "DbType": "MySql",
      "ConfigId": "Default",
      "IsAutoCloseConnection": true
    },
    {
      "ConnectionString": "host=127.0.0.1;port=8812;username=admin;password=quest;database=qdb;ServerCompatibilityMode=NoTypeLoading;",
      "DbType": "QuestDB",
      "ConfigId": "QuestDB",
      "IsAutoCloseConnection": true
    }
  ]
}

2.2 Program.cs / Startup.cs

using SqlSugar;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// 1) 注册 SqlSugar 客户端（showNativeSql=true 时会输出原生 SQL）
builder.Services.AddMutaSqlSugarClient(builder.Configuration, showNativeSql: true);

// 2) 注册 SqlSugar 版 Swagger（含 dto 请求体裁剪）
builder.Services.AddMutaSwaggerDocumentation(
    title: "Demo API",
    version: "v1",
    xmlFileNames: new[] { "Demo.Api.xml" },
    useBearer: true).AddMutaSqlSugarSwaggerDoc();

// 3) 注册业务仓储
builder.Services.AddScoped(typeof(IRepositoryBase<,>), typeof(RepositoryBase<,>)); 

var app = builder.Build();

// 可选：应用启动后执行数据库初始化逻辑
app.UseMutaInitDb((db, config) =>
{
    // 示例：db.CodeFirst.InitTables(typeof(User));
});

app.MapControllers();
app.Run();

3. 每个扩展的用法说明

以下按项目中公开扩展逐一说明。

3.1 SqlSugarExtensions（服务注册与中间件扩展）

文件：Extensions/SqlSugarExtensions.cs

3.1.1 AddMutaSqlSugarClient

用途：读取 SqlSugar 配置并注册 ISqlSugarClient（SqlSugarScope 单例）。

services.AddMutaSqlSugarClient(Configuration, showNativeSql: true);

参数说明：

• configuration：配置源，需包含 SqlSugar 节点。
• showNativeSql：是否控制台输出原生 SQL（调试时推荐开启，生产建议关闭）。

3.1.2 UseMutaInitDb

用途：应用启动后执行一次数据库初始化委托。

app.UseMutaInitDb((db, config) =>
{
    // 初始化表结构/种子数据
});

3.1.3 AddMutaSqlSugarSwaggerDocumentation

用途：在 Muta.ApiExtensions.Core 的 Swagger 基础上增加 SqlSugar DTO 请求体过滤能力。

services.AddMutaSqlSugarSwaggerDocumentation(
    title: "API",
    version: "v1",
    xmlFileNames: new[] { "YourProject.xml" },
    useBearer: true);

3.2 RepositoryBaseController<TEntity, TFilter>（控制器基类扩展）

文件：RepositoryControllers/RepositoryBaseController.cs

用途：快速生成标准 CRUD + 分页查询接口。

默认路由：api/[controller]

内置接口：

• GET /{id}：按主键获取。
• POST /：新增（支持 duplicateFields 查重）。
• PUT /{id}：更新（支持 duplicateFields 查重）。
• DELETE /{id}：删除。
• POST /ToPage：按过滤对象分页查询。

使用示例：

[Route("api/[controller]")]
public class UsersController : RepositoryBaseController<User, UserFilter>
{
    public UsersController(IRepositoryBase<User, UserFilter> repository)
        : base(repository)
    {
    }
}

public class UserFilter
{
    public string? UserName { get; set; }
    public int? RoleId { get; set; }
}

说明：ToPage 内部会调用 this.SetPagination(...)（来自 Muta.ApiExtensions.Core）自动写入分页信息。

3.3 RepositoryBase<TEntity, TFilter>（仓储基类扩展）

文件：Repositories/Infrastructure/RepositoryBase.cs

用途：提供可继承的通用数据访问实现。

核心能力：

• AddAsync：可选判重表达式。
• UpdateAsync：支持按字段组合查重。
• DeleteAsync / GetByIdAsync / AnyAsync / GetFirstFilteredAsync。
• GetAllFilteredAsync：条件 + 排序 + 分页 + 冗余字段补全。
• CheckDuplicateAsync：统一字段判重逻辑。

推荐重写点：

• ExtendQuery(...)：追加 Join、过滤、租户隔离等。
• RedundantFillAsync(...)：补全冗余显示字段（如名称映射）。

使用示例：

protected override ISugarQueryable<UserEntity> ExtendQuery(
    ISugarQueryable<UserEntity> query,
    UserFilterParameters filterParameters)
{
    // 约定：
    // 1) 当前仓储主实体（UserEntity）的 Lambda 参数名必须是 entity，
    //    不能写成 it、x 等，否则会导致表达式解析异常。
    // 2) 连表实体（如 RoleEntity）的参数名可自定义（如 role）。
    return query
        .LeftJoin<RoleEntity>((entity, role) => entity.RoleId == role.Id)
        .Select((entity, role) => new UserEntity
        {
            RoleName = role.RoleName
        }, true);
}

3.4 MutaDtoRequestBodyFilter（Swagger 请求体扩展）

文件：OperationFilters/MutaDtoRequestBodyFilter.cs

用途：根据 Action 场景（新增/更新）只展示 DTO 中对应字段，避免 Swagger 请求体过大或误导。

配套标记：

• MutaDtoAttribute（标在属性上）
• MutaDtoRequestTypeAttribute（标在 Action 上）
• MutaDtoType（Add / Update）

示例：

public class User
{
    [MutaDto(MutaDtoType.Add)]
    public string UserName { get; set; }

    [MutaDto(MutaDtoType.Add, MutaDtoType.Update)]
    public string NickName { get; set; }

    [MutaDto(MutaDtoType.Update)]
    public int Id { get; set; }
}

当 Action 是新增：

[HttpPost]
[MutaDtoRequestType(MutaDtoType.Add)]
public async Task<IActionResult> Add([FromBody] User dto) => Ok();

Swagger 仅显示标记了 Add 的字段。

3.6 PredicateExtensions（表达式构建扩展）

文件：Tools/PredicateExtensions.cs

主要方法：

• BuildDuplicatePredicate<TEntity>(...)：按字段集合构建查重表达式。
• BuildDuplicatePredicateWithKey<TEntity>(...)：查重同时排除主键自身。
• GetOrderByExpression<TEntity>(...)：根据字段名动态构建排序表达式。
• BuildPredicate<TEntity, TFilter>(...)：按过滤对象生成 where 条件。
• And<T>(...)：组合表达式。

示例：

var predicate = PredicateExtensions.BuildPredicate<User, UserFilter>(filter);
var orderBy = PredicateExtensions.GetOrderByExpression<User>("CreateTime");

3.7 EnumHelper / EnumExtensions（枚举扩展）

文件：Tools/EnumHelper.cs

用途：输出枚举值 + 名称 + 描述，或直接读取单个枚举描述。

示例：

public enum DeviceStatus
{
    [Description("离线")]
    Offline = 0,
    [Description("在线")]
    Online = 1
}

var list = EnumHelper.GetEnumItemDtoList<DeviceStatus>();
var desc = DeviceStatus.Online.GetDescription();

5. 最小可运行组合示例

builder.Services.AddControllers().AddMutaFilters(useAuditLogFilter: false);
builder.Services.AddMutaSqlSugarClient(builder.Configuration, showNativeSql: true);
builder.Services.AddMutaSwaggerDocumentation("Demo API", "v1", null, useBearer: false).AddMutaSqlSugarSwaggerDoc();
builder.Services.AddScoped(typeof(IRepositoryBase<,>), typeof(RepositoryBase<,>));

var app = builder.Build();

app.UseMutaInitDb((db, config) =>
{
    // 启动初始化
});

app.MapControllers();
app.Run();

6. 注意事项

• RepositoryBaseController 的主键入参默认为 int id，实体主键建议与之保持一致。
• duplicateFields 支持多个字段，格式如 "UserName,Phone"。
• QueryPageAsync/QueryFirstAsync 等动态查询中，字段名、表名会进行合法性校验，避免注入。
• 若启用统一响应包装，请确认已在主项目中接入 Muta.ApiExtensions.Core 对应过滤器。