Jeff.Utility 2.1.1

概述

本框架用于 Asp.Net Core WebApi 项目，核心是开箱即用的通用权限服务。框架可以在单个的 App 中使用，也可用作认证网关。 JeffUtility 本身只是一个类库，既适用于单体程序，也可用于多项目方案。

[[快速开始]]
[[内置 Api]]
[[权鉴网关]]
[[其他]]

快速开始

// 添加 JeffUtility 数据库
builder.Services.AddDbContext<JeffUtilityContext>(opt => opt.UseMySql(
    builder.Configuration.GetConnectionString("mysql"), ServerVersion.Parse("8.0.25"),
    option =>
    {
        option.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery);
        option.EnableRetryOnFailure();
    })
);

// 添加 JeffUtility 服务
builder.Services.AddJeffUtility(opt =>
{
    //首次使用时通过 EnsureCreated 创建数据库, 创建后可删除或置为 false
    opt.Database.DbContextEnsureCreated = true;

    //内置的权限管理API，比如用户管理，角色管理等
    opt.Auth.ShowAuthManageAPI();

    //启用本地权鉴默认服务
    opt.Auth.UseLocalAuth(jwt =>
    {
        jwt.Secret = "Your_Json_Web_Tokens_Private_Key";
        jwt.Expire = 1_000_000;
    });

    //定义返回对象格式，会覆盖默认的返回格式
    //opt.WebApi.UseResponseBody(b => new { code = b.Code == 200 ? 0 : 1 });

    //定义验证码发送委托，用于发送短信验证码
    //opt.Auth.SendSMSCode = Aliyun_SMSHandler.SendSMSCode;

    //多租户
    //opt.Auth.MultiTenant = true;

    //作为权鉴网关使用
    //opt.Auth.UseAuthGateway(jwt =>
    //{
    //    jwt.Secret = "Your_Json_Web_Tokens_Private_Key";
    //    jwt.Expire = 1_000_000;
    //});
});

//...

var app = builder.Build();

app.InitJeffUtility();   //初始化权限服务

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    //app.UsePathBase("/api");

    app.UseSwaggerUI(c =>
    {
        //设置 Swagger 的路径前缀
        c.SwaggerEndpoint("/swagger/JeffUtility/swagger.json", "Jeff Utility");
        c.SwaggerEndpoint("/swagger/MyApi/swagger.json", "My WebApi");
        c.DocExpansion(DocExpansion.None);
    });
}

Jeff.Repository

Jeff Utility 中引用了 Jeff.Repository，配置示例如下。具体使用可参考 Jeff.Repository 文档。

builder.Services.Configure<RepositoryConfig>(cfg =>
{
    cfg.PrimaryKeyAlgo = PKAlgo.SnowFlake;

    cfg.SoftDeleteProperty = "IsDeleted";
    cfg.UpdateTimeProperty = "UpdateTime";
    cfg.CreateTimeProperty = "CreateTime";
    cfg.VersionProperty = "Version";
});

Swagger XML 注释

Jeff Utility 内置了一些 WebAPI，通过以下方式添加 Swagger 注释。注意将其中的 1.x.x 换成实际的版本号。

<ItemGroup>
  <Content Include="$(NuGetPackageRoot)\jeff.utility\1.x.x\lib\net8.0\*.xml" Visible="false" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

数据库迁移

以上代码通过 EFCore 的 EnsureCreated 模式生成数据库。EnsureCreated 模式适合数据库初始创建的场景，若数据库中已有表，可使用 Migration 模式。

1. 修改上面的数据库配置

    //配置数据库连接
    opt.Db.SetDbContext(opt =>
    {
      opt.UseMySql(builder.Configuration.GetConnectionString("mysql"), ServerVersion.Parse("8.0.25"), c =>
      {
    	c.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery);
    	c.EnableRetryOnFailure();
    	c.MigrationsAssembly("Your_WebApi_Assembly"); //设置你的WebApi为迁移程序集
      });
    }); 
   
    //删除 EnsureCreated 或赋值为false，默认false
    //opt.Db.DbContextEnsureCreated = false;
   

2. 创建迁移

    dotnet ef migrations add JeffUtilityInit --context JeffUtilityContext
   

3. 迁移创建成功后，生成数据表

    dotnet ef database update --context JeffUtilityContext
   

   本框架暂只支持 EF Core。

内置 Api

管理 API

管理相关API在配置中，通过 opt.Auth.ShowAuthManageAPI();暴露接口。

认证 API

权鉴网关

• 权鉴网关为其他API提供权限认证
  • 负责 接口权鉴验证、拦截。验证失败，返回401/403，并拦截请求。验证成功，继续执行API。
  • 负责 提供用户信息。网关将当前用户信息写入请求头，API直接读取请求头获取当前用户。
• 权鉴网关基于 ngx_http_auth_request_module 实现。

1. 网关端

若配置为权鉴网关，需要配置 JWT。 配置后，系统会暴露网关接口: Get /auth-gateway/auth，供 nginx 调用。

builder.Services.AddJeffUtility(opt =>
{
  //配置为权鉴网关
  opt.Auth.AsAuthGateway(jwt =>
  {
	jwt.Secret = "Your_Json_Web_Tokens_Private_Key";
	jwt.Expire = 1_000_000;
  });
}

2. nginx 配置

nginx 需要支持 ngx_http_auth_request_module。在 nginx 为后端服务配置 auth_request，示例 :

server {
  listen       12345;
  server_name  "";
	
  # 权鉴服务
  location /auth/ {
	internal;
	proxy_pass http://localhost:7701/auth-gateway/auth/;     # 指定权鉴接口
	proxy_pass_request_body off;
	
	# 写入权鉴请求，用以权限验证
	proxy_set_header X-Request-Method $request_method;       # GET/POST
	proxy_set_header X-Request-URI $request_uri;             # /system-manage/user/123
	proxy_set_header X-Current-Location $current_location;   # /system-manage
  }

  # 后端服务
  location /system-manage/ {
	set $current_location "/system-manage";   # 当前 location 的路径
	
	auth_request /auth;    # 权鉴请求接口
	
	# 读取权鉴响应，写入变量
	auth_request_set $user_id $upstream_http_x_user_id;
	auth_request_set $user_phone $upstream_http_x_user_phone; 
	auth_request_set $tenant_id $upstream_http_x_tenant_id;          # 租户适用
	auth_request_set $tenant_code $upstream_http_x_tenant_code;      # 租户适用
	auth_request_set $refresh_token $upstream_http_x_refresh_token;  # 刷新token
	
	# 读取变量，写入请求头，传给后端
	proxy_set_header X-User-Id $user_id;
	proxy_set_header X-User-Phone $user_phone;
	proxy_set_header X-Tenant-Id $tenant_id;
	proxy_set_header X-Tenant-Code $tenant_code;
	
	# 读取变量，写入响应头，传给前端
	add_header X-Refresh-Token $refresh_token;
		
	proxy_pass http://localhost:7702/;
	proxy_set_header   Host  $host;
  }
	
  # error_page  404              /404.html;
	
  # redirect server error pages to the static page /50x.html
  error_page   500 502 503 504  /50x.html;
  location = /50x.html {
	root   /usr/share/nginx/html;
  }
	
  # error_page 401 =401 /auth/401;   # 替换状态码，=与401之间没有空格，200会覆盖原有的code
}

3. AppCode

• 多应用场景，以AppCode作为应用标识。单应用忽视该字段。
• 多应用场景，前端在调用API时，需要在 Header 中添加 X-App-Code，用以标识应用。比如 X-App-Code: SystemManage
• 数据表 uti_appservice 管理应用清单。其他表中的 AppCode 字段与之关联，包含 uti_anonymousapi, uti_authenticatedapi, uti_permission, uti_roleapi, uti_roleroute。  

其他

默认消息

支持默认消息配置。在 appsettings.json 中配置

// 状态码的默认消息
"StatusCodeMessage": {
  "200": "success",
  "400": "the argument is error.",
  "401": "身份验证失败",
  "403": "用户无相关权限",
  "404": "目标不存在",
  "500": "程序异常"
},

// 异常类型的默认状态和消息
"ExceptionMessage": {
  "System.ArgumentOutOfRangeException": "400 参数异常",
  "System.ArgumentNullException": "400 参数异常",
  "System.ArgumentException": "400 参数异常",
  "System.InvalidOperationException": "400 非法操作",
  "Microsoft.EntityFrameworkCore.DbUpdateConcurrencyException": "500 数据冲突",
  "Microsoft.EntityFrameworkCore.DbUpdateException": "500 数据保存失败",
  "System.Data.Common.DbException": "500 数据库操作异常",
  "System.IO.DirectoryNotFoundException": "404 目标不存在",
  "System.IO.FileNotFoundException": "404 文件不存在",
  "System.Exception": "500 发现异常"
}