Web API 与 Minimal API

// 反例：把动词放进 URL
GET  /api/getOrders
POST /api/createOrder
GET  /api/deleteOrder/5

// 正例：资源 + 方法
GET    /api/orders        // 列表
POST   /api/orders        // 新建
GET    /api/orders/{id}   // 单个
PUT    /api/orders/{id}   // 全量更新
PATCH  /api/orders/{id}   // 局部更新
DELETE /api/orders/{id}   // 删除

// Program.cs —— Minimal API 最小示例
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World");

app.MapGet("/orders/{id}", async (IOrderService svc, int id) =>
{
    var order = await svc.GetByIdAsync(id);
    return order is null ? Results.NotFound() : Results.Ok(order);
});

app.MapPost("/orders", async (IOrderService svc, CreateOrderRequest req) =>
{
    var id = await svc.CreateAsync(req);
    return Results.Created($"/orders/{id}", id);
});

app.Run();

// 传统 Controller 等价实现
[ApiController]
[Route("api/orders")]
public class OrdersController(IOrderService svc) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id)
    {
        var order = await svc.GetByIdAsync(id);
        return order is null ? NotFound() : Ok(order);
    }

    [HttpPost]
    public async Task<IActionResult> Create(CreateOrderRequest req)
    {
        var id = await svc.CreateAsync(req);
        return Created($"/api/orders/{id}", id);
    }
}

// 路由约束：int 只匹配整数，不符合返回 404
app.MapGet("/orders/{id:int}", (int id) => ...);
app.MapGet("/orders/{code:length(4,16)}", (string code) => ...);

// 查询与 Header 显式来源
app.MapGet("/orders", (
    [FromQuery] int page = 1,
    [FromQuery] int size = 20,
    [FromHeader(Name = "X-Request-Id")] string? requestId) =>
{
    return Results.Ok(new { page, size, requestId });
});

// 请求体复杂类型
app.MapPost("/orders", (CreateOrderRequest req) => ...);

// 文件上传
app.MapPost("/upload", async (IFormFile file) =>
{
    await using var fs = File.Create(Path.Combine("uploads", file.FileName));
    await file.CopyToAsync(fs);
    return Results.Ok(new { name = file.FileName, size = file.Length });
});

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();                    // 生成 /openapi/v1.json

var app = builder.Build();

app.MapOpenApi();                                  // 暴露 JSON 端点
app.MapSwagger();                                  // 可选：Swagger UI 页面

// 为端点补充 OpenAPI 元数据
app.MapGet("/orders/{id:int}", async (IOrderService svc, int id) =>
    await svc.GetByIdAsync(id) is { } o ? Results.Ok(o) : Results.NotFound())
   .WithName("GetOrder")
   .WithSummary("按 ID 获取订单")
   .WithDescription("返回订单详情，不存在时返回 404")
   .Produces<Order>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

app.Run();

// 生成的 openapi/v1.json 片段
{
  "openapi": "3.0.1",
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "GetOrder",
        "summary": "按 ID 获取订单",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Success" },
          "404": { "description": "Not Found" }
        }
      }
    }
  }
}

// 请求模型：声明式校验规则
public class CreateOrderRequest
{
    [Required]
    [StringLength(64, MinimumLength = 2)]
    public string CustomerName { get; set; } = string.Empty;

    [Range(0.01, 1_000_000)]
    public decimal Total { get; set; }

    [Required]
    public List<OrderLineDto> Lines { get; set; } = [];
}

public class OrderLineDto
{
    [Required]
    public int ProductId { get; set; }

    [Range(1, 100)]
    public int Quantity { get; set; }
}

// Minimal API：手动校验（Controller 自动）
app.MapPost("/orders", async (IOrderService svc, CreateOrderRequest req) =>
{
    // 需要引入 Microsoft.AspNetCore.Http.HttpResults 扩展的 Validate 方法
    // 或自行校验后返回 ValidationProblem
    if (!Validator.TryValidateObject(req, new ValidationContext(req), out var errors))
    {
        return Results.ValidationProblem(
            errors.GroupBy(e => e.MemberNames.FirstOrDefault() ?? "")
                  .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage ?? "").ToArray()));
    }

    var id = await svc.CreateAsync(req);
    return Results.Created($"/orders/{id}", id);
});

// 引入 Asp.Versioning.Http 包
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;      // 响应头返回 api-supported-versions
}).AddApiExplorer();                        // 让 OpenAPI 显示各版本

var app = builder.Build();

var v1 = app.MapGroup("/api/v1/orders");
v1.MapGet("/", async (IOrderService svc) => Results.Ok(await svc.ListV1Async()));
v1.MapGet("/{id:int}", async (IOrderService svc, int id) => ...);

var v2 = app.MapGroup("/api/v2/orders");
v2.MapGet("/", async (IOrderService svc) => Results.Ok(await svc.ListV2Async()));

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();          // 注册 ProblemDetails 服务
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

var app = builder.Build();
app.UseExceptionHandler();                      // 启用全局异常中间件

app.MapGet("/orders/{id:int}", async (IOrderService svc, int id) =>
{
    var order = await svc.GetByIdAsync(id);
    return order is null
        ? Results.Problem(
            statusCode: 404,
            title: "订单不存在",
            detail: $"找不到 ID 为 {id} 的订单")
        : Results.Ok(order);
});

// 全局异常处理：收敛未捕获异常
public class GlobalExceptionHandler : IExceptionHandler
{
    public ValueTask<bool> TryHandleAsync(
        HttpContext ctx, Exception ex, CancellationToken ct)
    {
        ctx.Response.StatusCode = StatusCodes.Status500InternalServerError;
        ctx.Response.ContentType = "application/problem+json";
        return ctx.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = 500,
            Title = "服务内部错误",
            Detail = ctx.RequestServices.GetService<IHostEnvironment>()?
                             .IsDevelopment() == true ? ex.ToString() : null
        }, ct).ContinueWith(_ => new ValueTask<bool>(true)).GetAwaiter().GetResult() is var r
            ? r : new ValueTask<bool>(true);
    }
}