CloudYxt.Api 3.3.4

云享通.Net Core针对WEBAPI常规操作库

跨域中间件使用

在Startup的Configure中定义

//支持所有域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>();

//支持一个域名跨域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>("https://www.domain1.com");

//支持多个域名跨域
app.UseMiddleware<AllowDomainCorsHeaderMiddleware>("https://www.domain1.com,https://www.domain2.com");

NSwag常见定义

services.AddOpenApiDocument(c =>
{
    c.Title = "WebApi";
    c.Version = "v1";
    c.Description = "WebApi说明";

    c.RequireParametersWithoutDefault = true;
    c.DocumentName = c.Title;
    c.SerializerSettings = new Newtonsoft.Json.JsonSerializerSettings() { ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver() };

    c.AddSecurity("Authorization", new NSwag.OpenApiSecurityScheme()
    {
        Description = "在下框中输入请求头中需要添加授权信息，格式：“{协议版本} {token}”（注意两者之间是一个空格）",
        Name = "Authorization",
        In = NSwag.OpenApiSecurityApiKeyLocation.Header,
        Type = NSwag.OpenApiSecuritySchemeType.ApiKey
    });

    //将控制器Summary显示为描述
    c.UseControllerSummaryAsTagDescription = true;

    //标记ApiMessageAuthorization为需授权接口
    c.OperationProcessors.Add(new ApiMessageAuthorizationNSwagProcessor("Authorization"));
});

NSwag上传文件

/// <summary>
/// 上传演示
/// </summary>
/// <param name="id">使用query参数的id</param>
/// <param name="type">使用form参数的type</param>
/// <param name="fileToUpload">文件的表单名fileToUpload，特别注意此处切勿加“[FromForm]”</param>
/// <returns></returns>
[HttpPost]
public messageData<long> PostUpload([Required][FromQuery] string id, [Required][FromForm] string type, [Required] IFormFile fileToUpload)
{
    return new messageData<long>() { data = fileToUpload.Length };
}

过滤器常见用法

在Startup中定义全局错误拦截

services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = ApiHelperExtend.ApiMessageInvalidModelState;
});

使用ApiMessageLog时，部分信息记录不到时，可在Startup的Configure中增加buffer回写

app.Use(async (ctx, next) =>
{
    ctx.Request.EnableBuffering();
    await next();
});

定义全局的Controller

[Route("Api/[controller]/[action]")]	//API路由
[ApiController]                         //声明为API控制器
[ApiMessageLog(ApiName = "Api名称")]	//API日志名称
[ApiMessagePackage]                     //使用code、message包装输出结果
public class extController : ControllerBase
{
}

演示的demo控制器，继承自extController

/// <summary>
/// 演示
/// </summary>
[OpenApiTag("demo", Description = "演示")]
public class demoController : extController
{
    /// <summary>
    /// 获取数据，并按code、message包装输出结果
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public async Task<messageData<response_class>> GetSomething()
    {
        var data = await......;

        if (something wrong) 
        {
            //抛出code、message错误信息
            throw new ApiMessageException(1, "错误提示");
        }

        return new messageData() { data = data };
    }

    /// <summary>
    /// 使用自定义包装、自定义状态码的输出
    /// </summary>
    /// <returns></returns>
    [HttpPost]
    [ApiMessageTException]      //自定义错误message
    [ApiMessagePackageIgnore]   //不使用code、message包装
    public async Task<response_result> PostSomething([Required][FromBody] request_something request)
    {
        var data = await......;

        if (something wrong) 
        {
            //抛出402状态码的错误信息
            throw new ApiMessageTException<response_result>(类实例变量, 402);    //402状态码
        }

        return new response_result();
    }

    /// <summary>
    /// 获取当前服务器时间相对1970-1-1的毫秒数
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [ApiMessageLogIgnore]       //忽略API日志
    [ApiMessagePackageIgnore]   //忽略使用结果包装
    public string GetMillTimer()
    {
        return $"{DateTime.Now.toMillTimer():F0}";
    }

}

ApiMessageAuthorization权限检测Filter

注意权限检测需加在方法上

权限认证成功后自动编写context.HttpContext.Items["userId"]

默认认证回调检查方法为用户自定义实现protected object mApiAuthorization(string Policy, string Roles, string AuthenticationSchemes, ActionExecutingContext context, string Scheme, string Parameter)

在WEBAPI中可通过User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme")?.BootstrapContext获取权限检查成功的用户信息

例：

//权限验证
protected object mApiAuthorization(string Policy, string Roles, string AuthenticationSchemes, ActionExecutingContext context, string Scheme, string Parameter)
{
    //AuthenticationSchemes
    if (!string.IsNullOrEmpty(AuthenticationSchemes) && !AuthenticationSchemes.Split(',').Contains(Scheme))
        throw new ApiMessageException(4020, "不允许的权限协议", $"{Scheme} not in ({AuthenticationSchemes})");

    if (Scheme == "PRC1")
    {
        //验证用户
        var userTag = ......;
        
        return userTag;
    }
    else if (Scheme == "PRC2")
    {
        //验证用户
        var userTag = ......;
        
        return userTag;
    }

    //验证未通过则返回空
    return null;
}

//在API中获取用户信息
private ClaimsIdentity _claims;

/// <summary>
/// 获取当前用户验证的Scheme
/// </summary>
/// <returns></returns>
protected string currentUserScheme()
{
    if (_claims == null)
        _claims = User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme");

    if (_claims == null)
        return string.Empty;

    return _claims.NameClaimType;
}

/// <summary>
/// 获取当前用户验证的用户信息
/// </summary>
/// <typeparam name="T"></typeparam>
/// <returns></returns>
protected T currentUserTag<T>()
{
    if (_claims == null)
        _claims = User.Identities.FirstOrDefault(m => m.AuthenticationType == "Scheme");

    if (_claims == null || _claims?.BootstrapContext == null)
        return default(T);

    return (T)_claims?.BootstrapContext;
}

//支持PRC1,PRC2的权限协议，并且Roles为0才可访问
[ApiMessageAuthorization(AuthenticationSchemes = "PRC1,PRC2", Roles = "0")]
public async Task<messageData<response_class>> GetSomething() 
{
    //获取当前用户
    var userTag = currentUserTag<用户类>();
    .....
}

基于HttpContext的扩展

var ip = HttpContext.remoteRealIp(); //来源IP
var from = HttpContext.remoteFrom(); //来源URL
var agent = HttpContext.remoteAgent(); //来源AGENT