Imizuki.UniversalApi

面向 .NET 10 与 ASP.NET Core 的通用 API 组件。

• 包名：Imizuki.UniversalApi
• 版本：1.1.1
• 作者：Imizuki
• Copyright © 2026 Imizuki

更新日志

1.1.1

• 在生成的路由调用链末尾添加成功响应 Produces 声明，按最终 NonUnify 配置选择业务类型或 ApiResult<T>。
• 新增方法级 ApiResponse<T>，用于覆盖业务响应文档类型，不改变运行时返回值和序列化行为。
• 按接口返回类型识别 Task、Task<T>、ValueTask、ValueTask<T>，显式生成 async/await 调用。
• 无返回值端点默认声明 ApiResult<object>；禁用包装时仅声明 HTTP 200，不声明响应体。
• 重复或无效的响应类型覆盖通过 IUA002 定位到对应源码特性。

1.1.0

• 将端点分组改为 EndpointGroup<TService>，通过接口注入调用实例方法。
• 新增 AddGeneratedEndpointServices()，按特性配置注册瞬态、作用域或单例服务，默认瞬态。
• HTTP 方法特性支持独立分组及方法优先的 NonUnify 响应开关。
• 移除非泛型分组和两套独立的 NonUnify 特性，属于破坏性 API 变更。
• 新增接口契约、方法签名及重复服务绑定的编译期诊断（IUA001–IUA003）。
• 保留实现方法的参数顺序、绑定特性和默认值，支持重载、显式接口实现及异步返回值。
• 旧静态端点需迁移为接口实例方法，并调用 AddGeneratedEndpointServices()；迁移步骤见下文。

1.0.2

• 修复代码源生成时二次生成造成引用不明的BUG。

功能与命名空间

生成器独立编译为 netstandard2.0 程序集，通过 NuGet 包的 analyzers/dotnet/cs 目录加载。运行时库不执行生成器，生成的扩展方法使用 Imizuki.UniversalApi.Generated 命名空间。

接口注入与自动注册

using Imizuki.UniversalApi.Attributes;
using Imizuki.UniversalApi.Generated;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGeneratedEndpointServices();

var app = builder.Build();
app.MapGeneratedEndpoints();
app.Run();

public interface ITestService
{
    string Get(int id);
}

[EndpointGroup<ITestService>("/test", ServiceLifetime.Scoped, NonUnify = true)]
public class TestService : ITestService
{
    [Get("/{id}", Group = "/other", NonUnify = false)]
    public string Get(int id) => id.ToString();
}

上述声明生成 services.AddScoped<ITestService, TestService>()，并将端点映射为：

var group0 = endpoints.MapGroup("/other");
group0.MapGet(
    "/{id}",
    ([Microsoft.AspNetCore.Mvc.FromServices] ITestService service, int id) => service.Get(id))
    .WithMetadata(new Imizuki.UniversalApi.Unify.EndpointResponseMetadata(false))
    .AddEndpointFilter<Imizuki.UniversalApi.Unify.UnifyEndpointFilter>()
    .Produces<Imizuki.UniversalApi.Unify.ApiResult<string>>();

• EndpointGroup<TService> 的泛型参数必须是标记类实现的接口；类须可访问、非抽象、非开放泛型并有公共构造函数。
• 生命周期使用 ServiceLifetime：默认 Transient，也支持 Scoped 和 Singleton。每个标记类注册一次，同一接口不能绑定多个端点实现类。
• 标记的端点必须属于指定接口或其父接口契约。支持重载、显式接口实现及普通和异步返回值；不支持静态方法、泛型方法、async void 和按引用参数或返回值。
• Lambda 第一参数始终注入服务接口，其余参数按被标记实现方法的顺序保留名称、类型、可空性、默认值和参数绑定特性。绑定信息不从接口参数继承。
• Get、Post、Put、Delete 都支持 Group：不设置或为 null 时继承类前缀，设置时完全替换前缀，空字符串表示根分组。
• 类级 NonUnify 默认 false。方法未设置时继承类值，显式 false 可覆盖类上的 true。独立分组只改变路由，不改变响应继承关系。
• NonUnify 仅跳过成功响应包装，异常处理保持启用。MVC 结果过滤器同样按方法配置优先、类配置次之读取这些特性。

响应类型声明与异步调用

生成器从所映射的接口方法推导响应类型，使用方法显式配置优先、类配置次之的最终 NonUnify 值：

所有声明使用默认成功状态码 200。IResult、Results<...> 等类型不会被进一步拆解为实际响应体；需要精确描述时，在实现方法上使用 ApiResponse<T>。声明类型需要与实际响应相符，生成器不会替换、转换或验证实际业务数据。

public interface IOrderService
{
    object Get(int id);
    Task<object> GetAsync(int id);
}

public record OrderDto(int Id);

[EndpointGroup<IOrderService>("/orders")]
public class OrderService : IOrderService
{
    [Get("/{id}")]
    [ApiResponse<OrderDto>]
    public object Get(int id) => new OrderDto(id);

    [Get("/{id}/raw", NonUnify = true)]
    [ApiResponse<OrderDto>]
    public Task<object> GetAsync(int id) => Task.FromResult<object>(new OrderDto(id));
}

同步方法生成 service.Get(id) 和 .Produces<ApiResult<OrderDto>>()；异步方法即使实现没有 async 关键字，也会生成以下调用：

group0.MapGet(
        "/{id}/raw",
        async ([Microsoft.AspNetCore.Mvc.FromServices] IOrderService service, int id)
            => await service.GetAsync(id))
    .WithMetadata(new Imizuki.UniversalApi.Unify.EndpointResponseMetadata(true))
    .AddEndpointFilter<Imizuki.UniversalApi.Unify.UnifyEndpointFilter>()
    .Produces<OrderDto>();

非泛型 Task / ValueTask 生成 async (...) => { await service.ExecuteAsync(...); }，void 生成 (...) => { service.Execute(...); }。其他同步返回值直接转发。本次仅识别四种标准任务类型，不为自定义 awaitable 自动生成 await。

以下示例省略路由调用链，但保留实际 Lambda 的显式参数类型和服务注入特性（Task<T> 与 ValueTask<T> 使用同一种生成形式）：

// 同步返回 T
([Microsoft.AspNetCore.Mvc.FromServices] ITestService service, int id) => service.Get(id)

// Task<T> / ValueTask<T>
async ([Microsoft.AspNetCore.Mvc.FromServices] ITestService service, int id) => await service.GetAsync(id)

// Task / ValueTask
async ([Microsoft.AspNetCore.Mvc.FromServices] ITestService service, int id) => { await service.ExecuteAsync(id); }

// void
([Microsoft.AspNetCore.Mvc.FromServices] ITestService service, int id) => { service.Execute(id); }

ApiResponse<T> 只读取被标记的实现方法，不读取接口方法，也不影响同步或异步调用的判断。覆盖类型也要经过包装规则：[ApiResponse<OrderDto>] 在启用包装时声明 ApiResult<OrderDto>，禁用时声明 OrderDto；无返回值方法同样允许覆盖。重复声明（包括泛型实参不同的声明）、类型不可访问或不能用作普通泛型参数时，生成器在对应实现方法特性处报告 IUA002；推导类型无效时定位到实现方法。

迁移旧代码

将 [EndpointGroup("/test")] 改为 [EndpointGroup<ITestService>("/test")]，让服务类实现接口，将静态端点改为接口实例方法，并在构建应用前调用 AddGeneratedEndpointServices()。

删除独立的 [NonUnify] / [NonUnifyAttribute]，改为分组或 HTTP 方法特性上的 NonUnify = true。类上禁用后，方法可设置 NonUnify = false 恢复包装。

生成器会报告源码位置明确的错误：IUA001 表示分组或生命周期无效，IUA002 表示方法、参数或响应配置无法映射，IUA003 表示服务接口绑定冲突。

MVC 配置示例

using Imizuki.UniversalApi.Core;
using Imizuki.UniversalApi.Unify;
using Imizuki.UniversalApi.Utils;

var builder = WebApplication.CreateBuilder(args);
builder.AddApplicationCore();
builder.Services.AddControllers()
    .AddNewtonsoftJson(options => options.UseMvcJsonOptions())
    .AddInjectWithUnifyResult();

var app = builder.Build();
app.UseApplicationCore();
app.MapControllers();
app.Run();

构建与打包

dotnet build Imizuki.UniversalApi.slnx -c Release
dotnet pack Imizuki.UniversalApi/Imizuki.UniversalApi.csproj -c Release -o artifacts

代码规范与验证

项目通过 .editorconfig 统一代码格式，类、方法和关键处理步骤使用中文注释。

dotnet format whitespace Imizuki.UniversalApi.slnx --verify-no-changes
dotnet format style Imizuki.UniversalApi.slnx --verify-no-changes

本次改造不新增测试用例或临时测试程序，使用 Release 构建、格式检查和生成逻辑静态核查验证。构建检查不会替代消费者端点的运行时验证。

尚未指定开源许可证、项目主页或源码仓库地址；发布前应按实际情况补充相应 NuGet 元数据。