在微服务与模块化单体架构中，API Host 的职责常常被严重误解：

很多团队把业务逻辑直接写在 Controller 中，导致 Controller 臃肿不堪；
中间件顺序随意拼接，导致认证发生在租户解析之后，产生严重的安全越权漏洞。

BitzOrcas.Modern 确立了严格的“API Host 是组合根（Composition Root），而非业务层”的架构铁律：所有 HTTP 端点由 [GenerateEndpoint] 在编译期静态绑定为 Minimal API，业务用例完全保留在 Application 垂直切片中。

API Host 中间件装配与请求流转拓扑

第一步：声明式 Minimal API 端点

通过标注 [GenerateEndpoint]，Roslyn 增量生成器在编译期直接产出高性能静态映射代码：

using BitzOrcas.Application.Abstractions.Authorization;
using BitzOrcas.Domain.Results;
using BitzOrcas.Endpoint.Attributes;
using Mediator;

namespace BitzOrcas.Sandbox.Application.Commands;

// 声明式端点：支持 HTTP 方法、路径、Swagger 分组与速率限制策略
[GenerateEndpoint(
    HttpRoute.Post,
    "/api/notes",
    Tag = "Notes",
    RateLimitPolicy = "userPolicy",
    RequestTimeoutPolicy = "StandardCommand")]
public sealed record CreateNoteCommand(string Title)
    : ICommand<Result<string>>, IAuthorizedRequest
{
    // 资源与动作授权凭据
    public ResourceDescriptor Resource { get; } = new("sandbox", "note");
    public AuthorizationAction Action { get; } = AuthorizationAction.Create;
}

第二步：标准 RFC 9457 Problem Details 错误响应

当 Handler 返回 Result.Failure 或发生未捕获异常时，框架统一转换为标准的 Problem Details JSON 格式：

{
  "type": "https://docs.bitzsoft.com/problems/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "客户名称长度不能超过 100 个字符。",
  "instance": "/api/customers",
  "errorCode": "Customer.NameTooLong",
  "errorType": "Validation",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

总结

BitzOrcas 的 Web API 基础设施实现了极致的高内聚：

编译期静态化：零运行时反射扫描，启动毫秒级；
中间件顺序即契约：严格保障认证、租户与授权的执行顺序；
RFC 工业标准：统一的 Problem Details 响应结构让前端异常处理极其标准。