RuoVea.OmiApi.UserRoleMenu 10.0.0.5

RuoVea.OmiApi.UserRoleMenu

用户角色菜单管理 API 组件 —— 基于 .NET 构建的轻量级、跨平台 RBAC 权限管理系统后端。

RuoVea.OmiApi.UserRoleMenu 是一个开箱即用的用户-角色-菜单权限管理 NuGet 包，提供用户 CRUD、角色 CRUD、菜单树管理、角色菜单授权、用户角色授权、按钮权限控制、JWT 认证集成、缓存管理的完整能力。基于 SqlSugar ORM 和 DynamicWebApi，注册即自动生成 RESTful API 端点，支持 MySql / SqlServer / PostgreSQL / SQLite / Oracle 等多种数据库。

目录

• 概览
• 安装
• 30 秒快速开始
• 核心场景
• 配置选项详解
• API 接口速览
• 错误处理与日志
• 版本迁移指南
• 常见问题

概览

功能特性

架构一览

┌─────────────────────────────────────────────────────────────┐
│                      NuGet Package                           │
│  RuoVea.OmiApi.UserRoleMenu                                 │
├─────────────────────────────────────────────────────────────┤
│  Service Layer (7 Services)                                 │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐     │
│  │ SysUser       │ │ SysRole       │ │ SysMenu       │     │
│  │ Service       │ │ Service       │ │ Service       │     │
│  │ 14 endpoints  │ │ 8 endpoints   │ │ 8 endpoints   │     │
│  ├───────────────┤ ├───────────────┤ ├───────────────┤     │
│  │ SysUserRole   │ │ SysRoleMenu   │ │ SysCache      │     │
│  │ Service       │ │ Service       │ │ Service       │     │
│  │ (internal)    │ │ (internal)    │ │ 9 endpoints   │     │
│  └───────────────┘ └───────────────┘ └───────────────┘     │
│                                                             │
│  DI Extensions                                              │
│  ├─ AddOmiSystemSetup()       (3 overloads)                 │
│  └─ AddSystemInitSetup()      (种子数据 + 建表)             │
├─────────────────────────────────────────────────────────────┤
│  Domain Layer (5 Entities)                                  │
│  SysUser ──< SysUserRole >── SysRole                       │
│  SysRole ──< SysRoleMenu >── SysMenu                       │
│  SysMenu ─── SysMenu (Self-ref tree, Pid)                  │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure                                             │
│  SqlSugar ORM · DynamicWebApi · ExSugar Repo               │
│  ExJwtBearer · ExFilter · ExPws · OmiApi.Config            │
└─────────────────────────────────────────────────────────────┘

支持的 .NET 版本

安装

NuGet 包管理器

# .NET 8 项目
Install-Package RuoVea.OmiApi.UserRoleMenu -Version 8.0.2.19

# .NET 10 项目
Install-Package RuoVea.OmiApi.UserRoleMenu -Version 10.0.0.4

.NET CLI

dotnet add package RuoVea.OmiApi.UserRoleMenu --version 8.0.2.19

依赖项

本包依赖以下组件（安装时会自动引入）：

30 秒快速开始

1. 配置数据库连接 (appsettings.json)

{
  "ConnectionConfigs": [
    {
      "DbType": "Sqlite",
      "ConnectionString": "DataSource=./ruovea.db"
    }
  ],
  /* Jwt 配置 */
  "Jwt": {
    "ValidateIssuerSigningKey": true,
    "IssuerSigningKey": "3c1cbc3f546eda35168c3aa3cb91780fbe703f0996c6d123ea96dc85c70bbc0a",
    "ValidateIssuer": true,
    "ValidIssuer": "SecurityDemo.Authentication.JWT",
    "ValidateAudience": true,
    "ValidAudience": "jwtAudience",
    "ValidateLifetime": true,
    "ExpiredTime": 1440,
    "ClockSkew": 5
  },
  "Swagger": {
    "ApiVersions": [
      {
        "Title": "系统应用",
        "Version": "system"
      }
    ]
  }
}

支持的 DbType 值： MySql、SqlServer、Sqlite、Oracle、PostgreSQL、Dm、Kdbndp、OpenGauss、ClickHouse 等。

2. 注册服务 (Program.cs)

// <summary>
// 在 Program.cs 中注册 OmiApi.UserRoleMenu 组件服务
// </summary>
var builder = WebApplication.CreateBuilder(args);

// 注册动态 Web API（自动将 Service 映射为 REST 控制器）
builder.Services.AddDynamicWebApi(options =>
{
    options.RemoveControllerPostfixes = new List<string> { "AppService", "Service" };
    options.RemovePrefix = new List<string> { "get", "post" };
});

// 注册用户角色菜单模块服务（默认 Scoped 生命周期）
builder.Services.AddOmiSystemSetup();

// 注册 SqlSugar ORM
builder.Services.AddSqlSugarSetup();

// 注册 HttpContext 用户上下文
builder.Services.AddHttpContextSetup<AspNetUser>();

// 注册 JWT 认证
builder.Services.AddAuthenticationSetup(IdentifyEnum.Jwt, true);

// 初始化数据库表结构和种子数据（isWeb: true=Web菜单, false=API菜单）
builder.Services.AddSystemInitSetup(isWeb: true);

// 注册请求拦截、验证、异常处理
builder.Services
    .RequestActionSetup()
    .ResultSetup()
    .ExceptionSetup();

// 注册 Swagger
builder.Services.AddSwaggerSetup();

// 跨域配置
builder.Services.AddCors(option =>
{
    option.AddDefaultPolicy(builder =>
    {
        builder.AllowAnyOrigin().AllowAnyHeader().AllowAnyMethod();
    });
});

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Run();

3. 启动并访问 Swagger

启动项目后，访问 https://localhost:xxxx/swagger，即可看到 "系统应用" 分组下的全部 RESTful API 端点。

核心场景

场景一：创建用户并授权角色

// <summary>
// 创建用户并授权角色 —— 异步写法。先创建用户，再为其分配角色集合。
// </summary>
public async Task<bool> CreateUserWithRolesAsync(
    SysUserService userService, AddUserInput input, List<long> roleIds)
{
    // 1. 创建用户（账号去重检查自动执行）
    var user = await userService.AddUser(input);

    // 2. 授权用户角色
    await userService.GrantRole(new UserRolesInput
    {
        UserId  = user.Id,
        RoleIds = roleIds
    });

    return true;
}

// <summary>
// 创建用户并授权角色 —— 同步写法（通过 .GetAwaiter().GetResult() 调用）
// ⚠️ 注意：在 ASP.NET 上下文中可能导致死锁，仅推荐在 Console/测试环境使用。
// </summary>
public bool CreateUserWithRoles(SysUserService userService, AddUserInput input, List<long> roleIds)
{
    var user = userService.AddUser(input).GetAwaiter().GetResult();
    userService.GrantRole(new UserRolesInput
    {
        UserId  = user.Id,
        RoleIds = roleIds
    }).GetAwaiter().GetResult();
    return true;
}

创建用户并授权流程:

  开始
    │
    ├─ 1. 校验账号是否已存在 → 存在则抛出 i18n.account_exists
    │
    ├─ 2. 密码加密（IPasswordServer）
    │
    ├─ 3. INSERT SysUser（用户主表）
    │
    └─ 4. DELETE + INSERT SysUserRole[]（先清空旧角色，再批量写入新角色）
    │
  完成

场景二：角色菜单授权（完整权限配置）

// <summary>
// 为角色授予菜单权限 —— 异步写法。传入角色ID和菜单ID集合，先清空旧权限再批量写入。
// </summary>
public async Task GrantMenuToRoleAsync(SysRoleService roleService, long roleId, List<long> menuIds)
{
    await roleService.GrantMenu(new RoleMenuInput
    {
        RoleId = roleId,
        MenuIds = menuIds
    });
}

// <summary>
// 查询角色已有的菜单权限 —— 用于授权页面的回显
// </summary>
public async Task<List<long>> GetRoleMenuIdsAsync(SysRoleService roleService, long roleId)
{
    return await roleService.GetOwnMenuList(new RoleInput { Id = roleId });
}

角色菜单授权流程:

  开始事务
    │
    ├─ 1. DELETE FROM SysRoleMenu WHERE RoleId = @roleId（清空旧权限）
    │
    ├─ 2. INSERT SysRoleMenu[]（批量写入新权限）
    │
    └─ 3. 清除按钮权限缓存（按前缀批量删除）
    │
  提交事务

场景三：获取登录用户菜单树（动态导航）

// <summary>
// 获取当前登录用户的菜单树 —— 根据用户角色动态构建，自动过滤禁用菜单和按钮类型节点。
// 异步写法：适用于 Controller 或 Service 中直接调用。
// </summary>
public async Task<List<MenuTreeOutput>> GetUserMenuTreeAsync(SysMenuService menuService)
{
    return await menuService.GetLoginMenuTree();
}

// <summary>
// 获取系统菜单树（用于角色授权时选择） —— 包含所有节点供管理员勾选。
// </summary>
public async Task<List<MenuTreeOutput>> GetGrantMenuTreeAsync(
    SysMenuService menuService, long roleId)
{
    return await menuService.TreeForGrant(
        new TreeForGrantInput { RoleId = roleId },
        includeButton: true,
        roleId: roleId
    );
}

// <summary>
// 获取登录用户菜单树 —— 同步写法
// ⚠️ 注意：在 ASP.NET 上下文中可能导致死锁，仅推荐在 Console/测试环境使用。
// </summary>
public List<MenuTreeOutput> GetUserMenuTree(SysMenuService menuService)
{
    return menuService.GetLoginMenuTree().GetAwaiter().GetResult();
}

登录菜单树构建流程:

  1. 获取当前用户信息（ICurrentUser）
    │
  2. 查询用户角色集合（SysUserRole）
    │
  3. 查询角色菜单集合（SysRoleMenu）
    │
  4. 查询所有菜单（SysMenu）
    │
  5. 过滤：
     ├─ 仅保留用户角色拥有的菜单
     ├─ 排除 IsDisable = Y（已禁用）
     └─ 排除 Type = 按钮类型（目录/菜单保留）
    │
  6. 递归构建树形结构（Pid 自引用）
    │
  返回树形菜单

场景四：按钮权限校验（细粒度权限控制）

// <summary>
// 获取当前用户的按钮权限标识集合 —— 支持缓存，用于前端按钮显隐控制。
// 异步写法：返回 List<string>，如 ["user:add", "user:delete", "role:grant"]。
// </summary>
public async Task<List<string>> GetUserButtonPermissionsAsync(SysMenuService menuService)
{
    return await menuService.GetOwnBtnPermList();
}

// <summary>
// 检查用户是否拥有特定按钮权限 —— 用于后端 API 鉴权。
// </summary>
public async Task<bool> HasPermissionAsync(SysMenuService menuService, string permission)
{
    var perms = await menuService.GetOwnBtnPermList();
    return perms.Contains(permission);
}

// <summary>
// 检查用户是否拥有特定按钮权限 —— 同步写法
// </summary>
public bool HasPermission(SysMenuService menuService, string permission)
{
    var perms = menuService.GetOwnBtnPermList().GetAwaiter().GetResult();
    return perms.Contains(permission);
}

按钮权限缓存流程:

  首次请求 GetOwnBtnPermList()
    │
    ├─ 缓存命中 → 直接返回
    │
    └─ 缓存未命中:
        │
        ├─ 1. 获取用户角色（SysUserRole）
        ├─ 2. 获取角色菜单（SysRoleMenu）
        ├─ 3. 查询按钮类型菜单（Type = 按钮）
        ├─ 4. 提取 Permission 字段
        ├─ 5. 过滤空值和非法格式
        ├─ 6. 写入缓存，设置过期时间
        │
        返回权限标识集合

  角色权限变更时:
    → GrantMenu() 自动调用 RemoveByPrefixKey() 清除按钮权限缓存

场景五：密码修改与重置（安全闭环）

// <summary>
// 用户自行修改密码 —— 需验证旧密码，且新密码不能与旧密码相同。
// 异步写法。
// </summary>
public async Task<bool> ChangePasswordAsync(
    SysUserService userService, ChangePwdInput input)
{
    // input 包含: OldPassword, NewPassword
    await userService.ChangePwd(input);
    return true;
}

// <summary>
// 管理员重置用户密码 —— 无需旧密码，直接设置为新密码。
// 异步写法。
// </summary>
public async Task<bool> ResetUserPasswordAsync(
    SysUserService userService, ResetPwdUserInput input)
{
    // input 包含: Id (用户ID), Password (新密码)
    await userService.ResetPwd(input);
    return true;
}

// <summary>
// 解除用户登录锁定 —— 清除密码错误次数缓存。
// 异步写法。
// </summary>
public async Task UnlockUserAsync(SysUserService userService, long userId)
{
    await userService.UnlockLogin(new UnlockLoginInput { Id = userId });
}

// <summary>
// 修改密码 —— 同步写法
// </summary>
public bool ChangePassword(SysUserService userService, ChangePwdInput input)
{
    userService.ChangePwd(input).GetAwaiter().GetResult();
    return true;
}

密码修改流程:

  1. 获取当前用户信息（ICurrentUser）
    │
  2. 验证旧密码（IPasswordServer.Verify）
    ├─ 不匹配 → 抛出 i18n.password_error
    │
  3. 校验新旧密码不能相同
    ├─ 相同 → 抛出 i18n.new_password_same_as_old
    │
  4. 加密新密码（IPasswordServer.Hash）
    │
  5. UPDATE SysUser SET Password = @newPwd WHERE Id = @userId
    │
  完成

配置选项详解

数据库连接配置 (ConnectionConfigs)

{
  "ConnectionConfigs": [
    {
      "DbType": "Sqlite",
      "ConnectionString": "DataSource=./ruovea.db",

      "EnableUnderLine": false,
      "EnableDiffLog": false,
      "IsEncrypt": false,
      "DbSecurity": "",
      "IsDeleteFilter": true,
      "IsUserIdFilter": false,
      "IsTenantIdFilter": false,
      "CommandTimeOut": 30
    }
  ]
}

JWT 认证配置 (Jwt)

{
  "Jwt": {
    "ValidateIssuerSigningKey": true,
    "IssuerSigningKey": "3c1cbc3f546eda35168c3aa3cb91780fbe703f0996c6d123ea96dc85c70bbc0a",
    "ValidateIssuer": true,
    "ValidIssuer": "SecurityDemo.Authentication.JWT",
    "ValidateAudience": true,
    "ValidAudience": "jwtAudience",
    "ValidateLifetime": true,
    "ExpiredTime": 1440,
    "ClockSkew": 5
  }
}

Swagger API 版本配置

{
  "Swagger": {
    "ApiVersions": [
      {
        "Title": "系统应用",
        "Version": "system"
      }
    ]
  }
}

DI 注册配置

// <summary>
// AddOmiSystemSetup —— 三种重载，适应不同配置来源。
// </summary>

// 重载 1：自动从全局 AppSettings 读取配置
builder.Services.AddOmiSystemSetup();

// 重载 2：传入自定义 IConfiguration
builder.Services.AddOmiSystemSetup(configuration.GetSection("MySystem"));

// 重载 3：通过 Action 委托配置 DbInitConfig
builder.Services.AddOmiSystemSetup(options =>
{
    options.InitTable = true;
});

// 自定义服务生命周期
builder.Services.AddOmiSystemSetup(ServiceLifetime.Singleton);

// <summary>
// AddSystemInitSetup —— 初始化数据库表和种子数据。
// </summary>

// isWeb = true：初始化 Web 菜单种子数据
builder.Services.AddSystemInitSetup(isWeb: true);

// isWeb = false：初始化 API 菜单种子数据
builder.Services.AddSystemInitSetup(isWeb: false);

⚠️ 线程安全： 切换为 Singleton 生命周期时，确保注入的 SugarRepository<T> 和 ISqlSugarClient 本身支持并发访问。SqlSugar 的 SqlSugarClient 是线程安全的，但仓储的某些操作依赖请求上下文（如 ICurrentUser 自动填充），单例模式下可能导致用户信息串扰。

❗ 性能提醒： AddSystemInitSetup 使用后台任务执行表结构检查和种子数据写入。生产环境首次启动后，已完成初始化的数据库无需重复执行，可通过 AddOmiSystemSetup(options => { options.InitTable = false; }) 关闭。

API 接口速览

所有接口自动归入 Swagger "system" 分组，默认路由前缀由 DynamicWebApi 配置决定。

SysUserService —— 用户管理

SysRoleService —— 角色管理

SysMenuService —— 菜单管理

SysCacheService —— 缓存管理

内部服务（不公开 API）

错误处理与日志

错误码速查

组件内部使用 i18n 国际化资源管理错误信息，支持多语言切换：

异常处理示例

// <summary>
// 安全创建用户 —— 捕获参数、业务和数据库异常。
// 异步写法。
// </summary>
public async Task<(bool Success, string Message)> SafeCreateUserAsync(
    SysUserService userService, AddUserInput dto)
{
    try
    {
        await userService.AddUser(dto);
        return (true, "用户创建成功");
    }
    catch (Exception ex) when (ex.Message.Contains("account_exists"))
    {
        // 账号已存在
        return (false, $"账号 '{dto.Account}' 已存在，请更换账号名");
    }
    catch (ArgumentException ex)
    {
        // 参数校验失败（必填字段缺失、格式错误）
        return (false, $"参数校验失败: {ex.Message}");
    }
    catch (Exception ex) when (ex.Message.Contains("transaction", StringComparison.OrdinalIgnoreCase))
    {
        // 事务执行失败（数据库层面错误）
        return (false, $"数据操作失败，已自动回滚: {ex.Message}");
    }
}

// <summary>
// 安全删除角色 —— 含关联数据防护检查。
// 异步写法。
// </summary>
public async Task<(bool Success, string Message)> SafeDeleteRoleAsync(
    SysRoleService roleService, long roleId)
{
    try
    {
        await roleService.DeleteRole(new DeleteRoleInput { Id = roleId });
        return (true, "角色删除成功");
    }
    catch (Exception ex) when (ex.Message.Contains("prohibit_delete_admin"))
    {
        return (false, "系统管理员角色禁止删除");
    }
    catch (Exception ex) when (ex.Message.Contains("role_has_accounts"))
    {
        return (false, "该角色下仍有用户关联，请先解除用户角色关系");
    }
    catch (Exception ex) when (ex.Message.Contains("record_not_exists"))
    {
        return (false, "角色不存在或已被删除");
    }
}

// <summary>
// 安全删除角色 —— 同步写法（仅在非 ASP.NET 上下文使用）
// </summary>
public (bool Success, string Message) SafeDeleteRole(SysRoleService roleService, long roleId)
{
    try
    {
        roleService.DeleteRole(new DeleteRoleInput { Id = roleId }).GetAwaiter().GetResult();
        return (true, "角色删除成功");
    }
    catch (Exception ex)
    {
        return (false, ex.Message);
    }
}

日志集成

组件不直接输出日志，依赖调用方集成的日志框架。推荐在 Program.cs 中配置 Serilog 或 NLog 来捕获：

// SqlSugar 的 SQL 日志可通过 AOP 事件捕获
builder.Services.AddSqlSugarSetup(); // 内部配置了 SQL 执行日志

版本迁移指南

从 8.0.x 升级到 10.0.x

API 变更历史

常见问题

Q: 如何切换数据库？

修改 appsettings.json 中的 DbType 和 ConnectionString，然后重新运行。AddSystemInitSetup 会自动为新数据库创建表结构并写入种子数据。

// MySql 示例
{ "DbType": "MySql", "ConnectionString": "Server=localhost;Database=ruovea;Uid=root;Pwd=123456;" }

// SqlServer 示例
{ "DbType": "SqlServer", "ConnectionString": "Server=.;Database=ruovea;Trusted_Connection=True;" }

// PostgreSQL 示例
{ "DbType": "PostgreSQL", "ConnectionString": "Host=localhost;Database=ruovea;Username=postgres;Password=123456;" }

Q: 如何自定义 API 路由前缀？

在 AddDynamicWebApi 中配置 DefaultApiPrefix：

builder.Services.AddDynamicWebApi(options =>
{
    options.DefaultApiPrefix = "/openapi/api";
});

Q: Web 菜单和 API 菜单有什么区别？

AddSystemInitSetup(isWeb: true) 初始化的是前端 Web 应用的菜单种子数据（含路由路径、组件、图标等），isWeb: false 初始化的是纯 API 接口的菜单种子数据。根据您的项目类型选择合适的模式。

Q: ⚠️ 超级管理员账号是什么？有哪些防护？

种子数据中预置的超级管理员账号在组件内部有严格防护：

• 禁止删除超级管理员（i18n.prohibit_delete_super_admin）
• 禁止修改超级管理员状态（i18n.prohibit_modify_super_admin_status）
• 禁止修改本人账号状态（i18n.prohibit_modify_self_status）
• 禁止删除系统管理员角色（i18n.prohibit_delete_admin）

这些防护确保系统始终至少有一个可用管理员。

Q: ❗ 按钮权限缓存何时失效？

按钮权限缓存在以下场景自动失效：

1. 角色菜单授权变更（GrantMenu）时，自动调用 RemoveByPrefixKey 清除相关缓存
2. 缓存过期时间到达后自动失效
3. 手动调用 SysCacheService.RemoveByPrefixKey(prefixKey) 强制清除

如果需要立即刷新缓存，可通过 SysCacheService 的 RemoveByPrefixKey 方法清除按钮权限缓存前缀。

Q: 为什么删除角色时提示"此角色下面存在账号"？

该角色仍有用户关联时，为防止权限失控，组件会抛出 i18n.role_has_accounts 错误。解决方案：通过 SysUserService.GrantRole() 先解除所有用户与该角色的关联，再执行删除。

Q: 菜单的三种类型（目录/菜单/按钮）各自用途是什么？

创建菜单时，父节点不能为按钮类型（i18n.parent_node_cannot_be_button），且路由名称不允许重复（i18n.route_name_duplicate）。

Q: ⚠️ 修改密码后需要重新登录吗？

修改密码操作不会使当前 JWT Token 失效。如果业务需要修改密码后强制重新登录，请在调用方额外实现 Token 失效逻辑（如将 Token 加入黑名单缓存）。

Q: ❗ 多租户场景下数据如何隔离？

所有实体（SysUser、SysRole、SysMenu）均实现 ITenantEntity 接口。启用租户过滤后，查询和操作会自动按 TenantId 过滤。配置方式：

{
  "ConnectionConfigs": [
    {
      "IsTenantIdFilter": true
    }
  ]
}

许可证

本项目基于 Apache 2.0 License 开源发布。