用 .NET 8 构建最小 API…

在构建 .NET 8 应用（最小 API、整洁架构、CQRS、EF Core、JWT 认证、AOT 编译）时，按流程实现并遵守约束。

适用场景

解决思路

1. 分析需求：确定架构模式、数据模型与 API 设计
2. 设计解决方案：创建具有正确分层的整洁架构
3. 实现：使用现代 C# 特性编写高性能代码；运行 `dotnet build` 验证编译——若构建失败，检查错误、修复问题并在继续前重新构建
4. 安全：添加认证、授权与安全最佳实践
5. 测试：使用 xUnit 与集成测试编写全面测试；运行 `dotnet test` 确认所有测试通过——若测试失败，诊断失败原因、修复实现并在继续前重新运行；用 `curl` 或 REST 客户端验证端点
6. 按上下文加载详细参考：最小 API 参考 `references/minimal-apis.md`（创建端点、路由、中间件时）；整洁架构参考 `references/clean-architecture.md`（CQRS、MediatR、分层、DI 模式时）；Entity Framework 参考 `references/entity-framework.md`（DbContext、迁移、关系时）；认证参考 `references/authentication.md`（JWT、Identity、授权策略时）；云原生参考 `references/cloud-native.md`（Docker、健康检查、配置时）
7. 必须使用 .NET 8 与 C# 12 特性
8. 必须在 `.csproj` 中启用可空引用类型：`<Nullable>enable</Nullable>`
9. 所有 I/O 操作必须使用 async/await——例如 `await dbContext.Users.ToListAsync()`
10. 必须实现正确的依赖注入
11. DTO 必须使用 record 类型——例如 `public record UserDto(int Id, string Name);`
12. 必须遵循整洁架构原则
13. 必须使用 `WebApplicationFactory<Program>` 编写集成测试
14. 必须配置 OpenAPI/Swagger 文档
15. 禁止使用同步 I/O 操作
16. 禁止在 API 响应中直接暴露实体
17. 禁止跳过输入验证
18. 禁止使用遗留的 .NET Framework 模式
19. 禁止跨架构层混合关注点
20. 禁止使用已弃用的 EF Core 模式
21. 最小 API 端点示例：在 `Program.cs` 中创建 builder，注册 `AddEndpointsApiExplorer()`、`AddSwaggerGen()`、`AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly))`，构建 app 后 `UseSwagger()`、`UseSwaggerUI()`，用 `app.MapGet("/users/{id}", async (int id, ISender sender, CancellationToken ct) => ...)` 返回 `Results.NotFound()` 或 `Results.Ok(result)`，并链式调用 `.WithName("GetUser").Produces<UserDto>().ProducesProblem(404)`
22. MediatR 查询处理器示例：定义 `public record GetUserQuery(int Id) : IRequest<UserDto?>;`，实现 `IRequestHandler<GetUserQuery, UserDto?>`，注入 `AppDbContext`，在 `Handle` 中用 `_db.Users.AsNoTracking().Where(u => u.Id == request.Id).Select(u => new UserDto(u.Id, u.Name)).FirstOrDefaultAsync(ct)`
23. EF Core DbContext 与异步查询示例：`public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)`，暴露 `public DbSet<User> Users => Set<User>();`，在 `OnModelCreating` 中调用 `modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly)`；查询时用 `_db.Users.AsNoTracking().Select(u => new UserDto(u.Id, u.Name)).ToListAsync(ct)`
24. DTO 使用 record 类型：`public record UserDto(int Id, string Name);` 与 `public record CreateUserRequest(string Name, string Email);`
25. 实现 .NET 功能时输出：项目结构（solution/project 文件）、领域模型与 DTO、API 端点或服务实现、如适用的数据库上下文与迁移、架构决策的简要说明

适用边界 · 注意事项

• 不使用 .NET 8 / C# 12 的项目（如遗留 .NET Framework 项目）
• 不需要最小 API、整洁架构或云原生微服务的简单场景
• 无法使用 MediatR、EF Core 等依赖或不允许引入第三方库的环境