Netor.MicroService.Abstractions

项目功能

Netor.MicroService.Abstractions 提供构建微服务控制器的基础能力，包括统一返回格式、便捷的 HttpContext 访问、全局拦截与响应格式化配置等，帮助以 Minimal API 风格快速实现业务端点。

核心功能

Netor.MicroService.Generator
Install-Package Netor.MicroService.Generator
dotnet add package Netor.MicroService.Generator

Netor.MicroService.Generator
Install-Package Netor.MicroService.Abstractions
dotnet add package Netor.MicroService.Abstractions

• 统一结果输出：提供 Success/Failed/Json 便捷方法，约定统一响应格式。
• 便捷上下文访问：通过 HttpContext/Request/Response 快速访问请求上下文（由宿主或上层框架注入）。
• 参数绑定默认策略：通过 MicroServiceOptions.ValueFrom 指定默认参数值来源。
• 控制器标记：提供 [Controller] 特性用于参与控制器发现（由宿主或上层组件完成路由与激活）。
• AOT 友好：避免使用反射，适配 AOT 场景。
• 依赖注入支持：支持通过 [FromServices] 属性注入服务实例。
• 异常处理：通过 MicroServiceOptions.UseExceptionHandler 进行全局异常捕获与处理。
• 请求拦截：通过 MicroServiceOptions.UseRequestHandler 进行全局请求拦截。
• IP 地址验证：通过 MicroServiceOptions.UseIPAddressVerifyHandler 进行请求 IP 白名单验证。
• 授权验证：通过 MicroServiceOptions.UseAuthorizeHandler 进行请求授权验证。
• 响应格式化：通过 MicroServiceOptions.Formater 定制统一响应格式。
• 支持 .NET 8 Minimal API 风格。
• 支持 ASP.NET Core MVC 特性（如 [FromQuery]、[FromForm]、[FromBody]、[FromHeader]、[FromRoute]、[FromServices] 等）。
• 支持异步控制器方法（返回 Task）。
• 支持控制器与方法级别的 [AllowAnonymous] 特性，允许匿名访问。
• 依耐源代码生成器以简化控制器与路由的注册（见 Netor.MicroService.Generator）。

技术架构

• 语言：C#
• 目标框架：.NET 8
• 依赖技术：
  • ASP.NET Core Abstractions（IResult、HttpContext、MVC 特性）
  • Microsoft.Extensions.Options（配置绑定）

项目结构（与当前代码一致）

• Controllers
  • BaseController：统一返回与上下文访问的基类。
• Attributes
  • ControllerAttribute：标记控制器类型，用于控制器发现。
• Extensions
  • MicroServiceOptions：全局选项（ValueFrom、Formater、OnRequest）。
  • TypeExtensions：简单类型判定（AOT 友好）。
• Enums
  • ValueFrom：参数默认绑定来源枚举。

使用方法

1. 在应用中配置 MicroServiceOptions（可选）

var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddLogging()
    // 添加微服务支持（必须）
    .AddMicroService(options =>
    {
        options.ValueFrom = ValueFrom.FromForm;
        //配置全局请求拦截器
        options.UseRequestHandler(OnRequestHandler);
        //配置IP地址验证拦截器
        options.UseIPAddressVerifyHandler(OnIPAddressVerifyHandler);
        //一旦设置该拦截器，所有请求均需通过授权验证，除非请求路径被标记为允许匿名访问。
        options.UseAuthorizeHandler(OnAuthorizeHandler);
        //配置全局异常处理器
        options.UseExceptionHandler(OnExceptionHandler);
    });


var app = builder.Build();
// 启用微服务中间件（必须）
app.UseMicroService();
await app.RunAsync();

//全局请求拦截器
Task<(bool status,string message)> OnRequestHandler(HttpContext context)
{
    context.RequestServices.GetRequiredService<ILogger<Program>>().LogWarning("OnRequestHandler");
    return Task.FromResult((true, "ok"));
}
//IP地址验证
Task<(bool status, string message)> OnIPAddressVerifyHandler(string ipAddress,HttpContext context)
{
    context.RequestServices.GetRequiredService<ILogger<Program>>().LogWarning("OnIPAddressVerifyHandler:{ip}",ipAddress);
    return Task.FromResult((true, "ok"));
}
//授权验证
Task<(bool status, string message)> OnAuthorizeHandler(HttpContext context)
{
    context.RequestServices.GetRequiredService<ILogger<Program>>().LogWarning("OnAuthroan");
    return Task.FromResult((true, "ok"));
}
//全局异常处理器
Task<(bool status, int code, string message)> OnExceptionHandler(Exception ex, IServiceProvider service)
{
    service.GetRequiredService<ILogger<Program>>().LogError(ex,"OnExceptionHandler");
    return Task.FromResult((true,500, "ok"));
}

2. 定义控制器（Minimal API 风格，返回 IResult）

using Microsoft.AspNetCore.Mvc;
using Netor.MicroService;
// 必须 1. [Controller]
// 必须 2. partial
[Controller]       // 标志该类为控制器
//[AllowAnonymous] 控制器下所有方法允许匿名访问 默认不需要授权除非设置了options.UseAuthorizeHandler(OnAuthorizeHandler);
public partial class UserController 
{
    // [属性注入] 通过依赖注入获取日志实例 
    [FromServices]
    public ILogger<OrderController> Logger { get; set; }=default!;

    //[AllowAnonymous] 单个方法允许匿名访问
    [HttpGet("/users")]
    public IResult Index()
        => Success(new { items = Array.Empty<object>(), total = 0 });

    [HttpPost("/users")]
    public IResult Create([FromForm] string name)
        => string.IsNullOrWhiteSpace(name)
            ? Failed("name is required", 400)
            : Success(new { id = Guid.NewGuid(), name });
}

3. 健康检查

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks

var builder = WebApplication.CreateBuilder(args);
// 注册健康检查服务
builder.Services.AddHealthChecks();
//需要什么自己添加扩展包
//builder.Services.AddHealthChecks()
//    .AddSqlServer(connectionString, name: "SQL Server");

var app = builder.Build();
// 映射健康检查端点
app.MapHealthChecks("/health");

说明：

• BaseController 提供 Success/Failed/Json 便捷方法与 HttpContext 访问属性。
• HttpContext 需由宿主或上层框架（或配套生成器/激活器）在执行前注入。
• 统一响应格式可通过 MicroServiceOptions.Formater 全局定制。

贡献

欢迎通过 Issue 或 Pull Request 参与贡献。