构建 REST API：Minimal API 与 Controller

这一课你将能做到

1. 用 Minimal API 和 Controller 两种形态实现同一组「提交代码」接口，并说出选型依据
2. 完成模型绑定、参数校验、DTO 转换、分页返回的完整链路
3. 用 IExceptionHandler 实现全局异常到 ProblemDetails 的统一映射（对应 @ControllerAdvice）

为什么要学

API 层是后端的第一道门面：绑定参数、校验输入、调用业务、映射状态码、描述文档。Spring 生态里这套由 @RestController + @Valid + @ControllerAdvice + Springdoc 组成；ASP.NET Core 8 把同样的能力拆成两套门面——Minimal API（轻、代码即路由）和 Controller（重约定、适合大团队），共享绑定/校验/文档底座。学完能按团队规模选形态，而不是背「哪个新用哪个」。

先建立图像

一次 POST 提交代码请求的完整旅程：

POST /api/submissions  {"problemId":1,"language":"cpp","code":"int main(){}"}
   │
   ├─ 路由匹配        MapPost / [HttpPost] 决定谁接单
   ├─ 模型绑定        JSON → SubmitDto（对应 @RequestBody）
   ├─ 模型校验        [Required] / @NotNull 不通过 → 自动 400
   ├─ 业务执行        注入的 JudgeService 干活（@Autowired）
   └─ 结果映射        201/400/404 + JSON 体（ResponseEntity 语义）

跟着做

步骤 1：Minimal API 版提交接口

public record SubmitDto(long ProblemId, string Language, string Code);
public record SubmissionView(long Id, string Status, DateTime CreatedAt);

var api = app.MapGroup("/api/submissions").WithTags("提交");

api.MapPost("/", async (SubmitDto dto, OjDbContext db, IJudgeQueue queue) =>
{
    var problem = await db.Problems.FindAsync(dto.ProblemId);
    if (problem is null) return Results.NotFound();

    var submission = new Submission
    {
        ProblemId = dto.ProblemId, Language = dto.Language,
        Status = "PENDING", CreatedAt = DateTime.UtcNow,
    };
    db.Submissions.Add(submission);
    await db.SaveChangesAsync();
    await queue.EnqueueAsync(submission.Id);   // 入判题队列（第 9 课）

    return Results.Created($"/api/submissions/{submission.Id}",
        new SubmissionView(submission.Id, "PENDING", submission.CreatedAt));
});

Results.Created(locationUrl, body) 返回 201 + Location 头，等价 ResponseEntity.created(uri).body(dto)。返回 IResult 而非裸对象：状态码显式可控。

步骤 2：等价 Controller 版

[ApiController]
[Route("api/submissions")]
public class SubmissionsController(OjDbContext db, IJudgeQueue queue) : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<SubmissionView>> Submit(SubmitDto dto)
    {
        var problem = await db.Problems.FindAsync(dto.ProblemId);
        if (problem is null) return NotFound();

        var submission = new Submission { ProblemId = dto.ProblemId, Language = dto.Language, Status = "PENDING" };
        db.Submissions.Add(submission);
        await db.SaveChangesAsync();
        await queue.EnqueueAsync(submission.Id);

        return Created($"/api/submissions/{submission.Id}",
            new SubmissionView(submission.Id, "PENDING", submission.CreatedAt));
    }
}
// Program.cs：AddControllers() + MapControllers()