PlumX.Core.Platform 1.0.0-preview.7

PlumX.Core.Platform

NuGet 包 ID：PlumX.Core.Platform PlumX.Core.Platform 是 .NET 8 Web 应用入口，提供认证、Swagger、异常处理、健康检查、CORS、本地限流和业务程序集 DI 注册。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddPlumCore(builder.Configuration, options =>
{
    options.Authentication = EnumAuthSystem.AuthCenter;
});
var app = builder.Build();
app.UsePlumCore();
app.MapControllers();
app.Run();

API Versioning 与 Swagger

将 ApiVersion:Enabled 显式设为 true 后，AddPlumCore 才注册 URL 段 API Versioning 和 API Explorer。控制器可使用 Asp.Versioning 的 ApiVersion 特性和 v{version:apiVersion} 路由，Platform 会生成对应的 Swagger 文档与 UI 入口，例如 /swagger/v1/swagger.json 和 /swagger/v2/swagger.json。未启用版本化时，应用使用 /swagger/v1/swagger.json 回退文档。

{
  "ApiVersion": {
    "Enabled": true
  }
}

[ApiController]
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/orders")]
public sealed class OrdersController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

Swagger:Title 和 XML 注释配置仍对所有版本文档生效；Swagger:Name 用作无版本回退文档的 OpenAPI info.description，不会改变版本路由。

枚举成员可使用标准 [Description("备注")]。Platform 会将 数值: 备注 写入 Swagger schema 和枚举查询参数描述（包括复杂 DTO 展平后的枚举属性）；未标注成员回退显示成员名称。当配置了 Swagger:XmlFiles 时，枚举备注会追加在 XML 描述之后。此行为只影响 OpenAPI 文档，不改变枚举的 JSON 序列化格式。

When Runtime:Authentication is not AllowAnonymous, Platform adds an OpenAPI apiKey scheme named Bearer in the Authorization header and Swagger UI displays Authorize. Anonymous hosts do not emit the scheme or the control. This affects OpenAPI documentation only; endpoint authorization remains controlled by ASP.NET Core authorization and controller attributes.

Swagger:Enabled controls whether OpenAPI documents and Swagger UI are registered. IsDebug and Swagger:RequireAuthentication do not control whether document content is generated. Applications without explicitly versioned controllers use the fallback document at /swagger/v1/swagger.json.

Swagger:RequireAuthentication is the explicit Swagger Basic Auth switch. When it is not configured, the legacy Swagger:IsUseAuth value is used instead and defaults to true. Basic Auth protects both the Swagger UI and OpenAPI JSON beneath /swagger; when ApiRoutePrefix is configured, the protected prefix is /{ApiRoutePrefix}/swagger. Configure Swagger:AuthUserName and Swagger:AuthUserPassword outside version control.

BusinessModule

AddPlumCore 会在 BusinessModule:DllPrefixs、DllSuffix 和 ClassSuffix 都配置时，扫描运行目录中同时匹配 DLL 前缀与后缀的程序集。普通实现按 ClassSuffix 匹配并默认注册为 Scoped；接口名以实现类名结尾时注册接口到实现，BaseAppSrv 子类按自身注册。

所有 EF Core DbContext 子类都会按自身自动注册为 Scoped，不依赖 ClassSuffix，适用于在 OnConfiguring 中配置 Provider 和连接的上下文。若使用标准 AddDbContext 配置方式，请直接调用 EF Core 的注册 API，不要重复调用批量扫描。

{
  "BusinessModule": {
    "DllPrefixs": ["Orders."],
    "DllSuffix": [".AppSrv.dll", ".UseCase.dll"],
    "ClassSuffix": ["Service", "Repository"]
  }
}

业务 DLL 及其依赖必须随 WebAPI 发布到运行目录。未配置其中任一数组或没有匹配 DLL 时不会扫描；命中 DLL 但无法加载时启动失败，以便暴露发布缺少依赖的问题。BusinessModule:DllPrefixs 同时可被 PlumX.Core.MessageBus 用于消费者发现，DllSuffix 不影响该模块。

需要精确控制程序集范围时，仍可在 AddPlumCore 后调用显式重载：

builder.Services.AddPlumBusinessModules(
    builder.Configuration,
    typeof(OrderApplicationService).Assembly,
    typeof(OrdersDbContext).Assembly);

显式重载与自动发现同时使用会产生重复注册，因此二者应二选一。

启动注册期间，AddPlumCore 和 AddPlumBusinessModules 会通过 [PlumX.Core.Platform] Console 日志输出 Platform 模块状态、业务程序集匹配、服务映射、生命周期和数量汇总。业务服务注册会先输出扫描程序集数量，再输出本次新增的服务描述符数量；选择器不完整时会记录跳过原因。日志不输出 OAuth、连接串或其他配置值。

配置

Platform 读取 Runtime、Swagger、OAuth、ApiVersion、RateLimiting 和 BusinessModule:ClassSuffix。ApiVersion:Enabled 和 RateLimiting:Enabled 默认为 false，只有显式设置为 true 时才分别注册 API Versioning 或启用本地固定窗口限流。

当 Runtime:Authentication 为 ZBB 时，Platform 会直接注册认证 handler，不需要引用或调用额外的 Introspection 项目。OAuth:Authority、OAuth:ApiName 与 OAuth:ApiSecret 为必填项；该模式同时支持 JWT 和 Reference Token，Reference Token 会提交到 introspection endpoint，JWT 使用认证中心的签名元数据校验。若旧 IdentityServer4 组件未将 discovery 的签名密钥载入，JWT 分支会按 jwks_uri 直接读取并缓存公钥。ZBB JWT 子方案关闭入站 Claim 名称映射，因此 sub、name 等原始 Claim 类型会直接保留，兼容既有业务读取方式。RequireHttpsMetadata、ValidateIssuer 和 ValidateAudience 默认均为 true，该模式使用前两项，不使用 ValidateAudience 或 AllowInvalidServerCertificate。AuthCenter 与 YYY 继续使用 JWT Bearer 认证。

当 Runtime:ExposeDeveloperErrors 为 true 且宿主环境为 Development 时，UsePlumCore 使用 ASP.NET Core 开发异常页，便于本地调试；在其他环境（包括配置未启用该选项时）使用标准异常处理器并返回空响应的 HTTP 500，避免向客户端暴露异常详情。生产环境不应启用 ExposeDeveloperErrors。

AddPlumCore 会将传入的 IConfiguration 赋给 AppConfig.Configuration，供尚未完成依赖注入改造的可选模块读取。配置中心应在调用该方法前通过 PlumX.Core.Config 和相应 Provider 载入。

AddPlumCore 同时注册控制器 JSON 默认值：属性名保持 CLR 原始大小写，long 输出为字符串，DateTime 使用 yyyy-MM-dd HH:mm:ss。非匿名认证模式会添加全局授权过滤器；模型验证失败返回错误码 6000，调试模式下消息包含字段名。

这些启动诊断默认写入 Console.Out，当前不提供 PlumX.Core 配置开关；它们不注册日志 Provider，也不替代 PlumX.Core.Observability 或应用自己的 ILogger 配置。

完整字段见 配置中心完整配置参考，可运行示例见 PlumX.Demo.Platform。