neo-dotnet-webapi

.NET Web API 专家技能

触发条件

• 用户请求创建、调试、重构或审查 ASP.NET Core Web API。
• 项目包含 Controllers 目录，且继承自 ControllerBase。
• 目标框架为 .NET 6.0（LTS）或更高版本。
• 需要对 API 代码进行现代化改造（例如，从使用中间件处理异常迁移到 .NET 8+ IExceptionHandler）。

工作流

1. 感知（架构认知）：
   • 检查 .csproj，确定 TargetFramework。
   • 分析项目结构，确认其采用 N-Tier 架构还是 Vertical Slice 架构。
   • 识别现有的横切关注点处理方式（筛选器、中间件）。
2. 推理（规划阶段）：
   • 评估是否引入“Problem Details”标准。
   • 确定是否使用 .NET 8+ 全局异常处理机制。
   • 根据项目规模选择合适的版本控制策略。
3. 执行（实施阶段）：
   • 编写符合 [ApiController] 约定的高质量控制器。
   • 实现强类型、不可变的 DTO（优先使用 record）。
   • 集成依赖注入，优先使用 Primary Constructors（C# 12+）。
4. 验证（标准验证）：
   • 验证操作返回类型是否符合 ActionResult<T> 规范。
   • 检查 NRT（可空引用类型）安全性。
   • 确保异步操作正确传递 CancellationToken。

功能路线图（.NET 6 - 10）

.NET 6 & 7（基础）

• 控制器架构：传统控制器模式和特性路由。
• Problem Details：统一的错误响应标准。
• 输出缓存：高性能服务端缓存。
• 可空引用类型：全面支持空值安全。

.NET 8 & 9（效率提升）

• IExceptionHandler：更简洁的集中式异常处理。
• 防伪：为 Web API 提供内置防伪支持。
• 键控服务：更灵活的依赖注入选项。
• HybridCache：多级缓存优化。

.NET 10+（特定版本功能）

• 控制器扩展成员：扩展基控制器功能。
• 增强序列化：针对大型负载的 JSON 优化。

编码标准

• 强类型：优先使用 ActionResult<T>，以改善 Swagger 支持。
• NRT 合规性：严格执行空值安全，减少运行时错误。
• 异步最佳实践：始终接受并传递 CancellationToken。
• 命名：控制器名称必须以 Controller 结尾，异步方法必须以 Async 结尾。

交付内容

• 针对版本优化的 Web API 代码：提供适用于目标版本的现代化控制器和配置。
• 架构见解：为 N-Tier 或 Clean Architecture 提供重构建议。
• 安全建议：针对 Problem Details 和异常处理提供安全建议。

验证

• 确保代码符合 C# 10+ 的现代语法标准。
• 验证端点是否正确返回符合 RFC 7807 的错误格式。
• 确认代码在测试环境中没有资源泄漏（正确使用 using 和异步操作）。

文档

官方参考资料

• ASP.NET Core Web API 概述
• 在 ASP.NET Core Web API 中处理错误（Problem Details）
• ASP.NET Core Web API 中的控制器操作返回类型

内部参考资料

• Web API 编码风格和命名约定
• Web API 反模式和最佳实践
• Web API 现代模式指南