software-csharp-backend

C# 后端工程

快速参考

决策	默认选择	备注
运行时	当前 .NET LTS 及其 C# 版本	指定版本前，请在 dotnet 支持策略页面查询当前 LTS 及其支持结束日期。将任何距离支持结束不到一年的目标版本视为需要跟踪迁移，而非稳定状态。默认选择当前 LTS；仅当团队每年升级时，才选择更新的 STS
API 风格	新端点使用 Minimal API	对于包含大量筛选器/操作结果的大型 CQRS 接口，使用控制器
持久化（SQL，写入密集型）	EF Core	查询结构复杂且手动调优 SQL 效果更好时，使用 Dapper
持久化（SQL，查询密集型）	Dapper	如果存在聚合，可在写入路径中搭配 EF Core 使用
持久化（文档）	MongoDB 驱动程序	仅在确实存在架构可变性，而非出于习惯时使用
后台工作程序	IHostedService / BackgroundService	从一开始就添加租约、优雅关闭和毒消息处理
弹性	Microsoft.Extensions.Resilience（Polly v8）	AddStandardResilienceHandler() 会按从外到内的顺序运行五种策略：速率限制器 → 总超时 → 重试 → 熔断器 → 单次尝试超时。默认会重试所有 HTTP 方法。对于不安全方法和严格的截止时间，应覆盖默认设置。仅在一层进行重试：添加到已由 ConfigureHttpClientDefaults（例如服务默认设置）包装的客户端的处理程序，或在重试客户端或 EF 执行策略外添加应用级重试，都会使尝试次数成倍增加。请参阅 references/resilience-policy-defaults.md
OpenAPI	内置 ASP.NET Core OpenAPI（Microsoft.AspNetCore.OpenApi）	除非代码库已在使用 Swashbuckle，否则不要添加

其他任务请转至：

• NUnit 测试夹具设计、WireMock/Testcontainers 配置或减少不稳定测试 → $qa-testing-nunit
• nuke/Build.cs、CI 目标排序或制品发布 → $ops-nuke-cicd
• 旧版 ILogger 或 Serilog 重写自动化 → $dev-structured-logs

何时使用此技能

• 构建或评审 C# / .NET 后端服务（此技能负责该库中的 C#/.NET；software-backend 会将 .NET 工作路由至此处）
• 在 ASP.NET Core API 风格（控制器、Minimal API、后台工作程序）之间进行选择
• 使用 EF Core、Dapper 或 MongoDB 实现数据访问
• 为 .NET 服务添加弹性、可观测性或安全基线
• 重构 .NET 后端代码或检测常见反模式

何时不使用此技能

• 通用后端模式（Node.js、Python、Go、Rust） → software-backend
• NUnit 测试夹具设计和测试基础设施 → qa-testing-nunit
• NUKE 流水线目标和 CI/CD → ops-nuke-cicd
• ILogger/Serilog 迁移自动化 → dev-structured-logs
• 单个服务之外的系统架构 → software-architecture-design
• 安全审计和威胁建模 → software-security-appsec

工作流

1. 对请求的变更进行分类（新功能、重构、Bug 修复、审查）。
2. 在实现细节之前选择运行时形态。对于目标框架限制、多目标框架或旧版迁移，加载 references/version-compatibility-notes.md。 加载 references/scenario-guides.md；对于 HTTP 服务，还要加载 references/aspnet-core-api-patterns.md。
3. 遵循语言和编码标准。 加载 references/csharp-language-practices.md 和 references/dotnet-coding-standards.md。
4. 在编辑内部实现之前确认架构和边界。 加载 references/backend-architecture-principles.md 和 references/modular-architecture-principles.md。
5. 根据查询和写入模式选择持久化与一致性策略。 加载 references/data-access-patterns.md；如果选择 EF Core，还要加载 references/efcore-persistence-patterns.md。
6. 为出站 I/O 和长时间运行的工作添加弹性行为。 加载 references/reliability-and-resilience.md 和 references/resilience-policy-defaults.md。
7. 根据风险和边界定义测试。 加载 references/testing-practices.md；对于新的 NUnit 组件测试 Fixture，从 assets/test-fixture-template-nunit.cs 开始。
8. 添加日志、追踪、指标、健康探针和可运维性默认配置。 加载 references/observability-standards.md；对于 API/运行时部署默认配置，加载 references/runtime-ops-checklist.md。如果服务在设计上是分布式或云原生的，还要加载 references/scenario-guides.md 中面向 Aspire 的配置文件。
9. 验证身份验证、验证逻辑和机密信息处理。 加载 references/security-baseline.md。
10. 对变更后的行为运行反馈循环验证。 运行代码库自身的构建、单元测试和 API 测试目标（对于基于 NUKE 的代码库，运行其定义的构建目标）；编辑流水线目标时使用 $ops-nuke-cicd。
11. 根据反模式检查清单进行最终审查。 加载 references/code-review-checklist.md。

应做 / 避免

取消与截止时间约定。

在每个可取消的请求和工作线程边界接受 CancellationToken，并将其传递给数据库、HTTP、队列和延迟调用。如果存在父级截止时间，则根据剩余时间派生子级超时；对于队列和计划任务，定义操作截止时间，并将其与主机关闭取消信号合并。记录无法响应取消的依赖项。不要将客户端断开连接或截止时间到期转换为通用 500 错误。在测试中，验证外部调用期间取消操作后工作会停止，且不会提交部分更改或泄漏后台任务。

规则：当 Claude 编辑匹配的文件时，rules/dotnet/csharp.md 会加载此不变约定。

应做	避免
让应用服务保持精简，并明确声明依赖项	将领域逻辑直接耦合到 HTTP、数据库驱动类型或特定框架类
对预期失败返回确定的领域/应用结果	吞掉异常，或用含糊的错误消息替代根本原因
在每个异步层和外部调用中传递 CancellationToken	只在控制器中停止取消，而下游调用仍继续运行
使用 IOptions<T> 验证选项；启动配置无效时快速失败	未经选项验证就将配置直接绑定到服务
有意选择 API 风格；明确中间件顺序	在没有明确错误格式策略的情况下混用最小 API、控制器和自定义端点框架
优先使用内置 ASP.NET Core OpenAPI 和 ProblemDetails，再考虑添加第三方封装	内置管道已足够时仍添加 Swashbuckle 或 MediatR
根据用例形态而非团队习惯选择持久化方案	在没有超时和幂等性保障的情况下使用重试
将遥测和安全检查纳入完成标准	发布缺少结构化日志、跟踪、指标和健康信号的端点
分别在单元测试和集成测试边界编写测试	在同一个测试夹具中混合单元测试和集成测试关注点
—	在事件处理程序之外使用 async void
—	在并发操作/线程之间共享同一个 DbContext 实例
—	依赖关系捕获（单例依赖作用域服务）

已知陷阱

• 混用 Minimal API、控制器和自定义端点框架，却没有明确的契约策略或错误格式规范。
• 取消操作止步于控制器边界，下游 HTTP、EF Core、队列或缓存调用却仍在继续运行。
• 认为 EF Core 的默认设置在高负载下是安全的：延迟加载、隐式跟踪和缺少查询整形经常带来隐性开销。在一个查询中使用两个或更多集合 Include 会导致行数倍增（笛卡尔积膨胀）；请参阅 references/efcore-persistence-patterns.md。
• 在非幂等处理程序、事务范围或第三方调用外使用重试，却没有协调去重或超时。
• 发布后台工作程序时，没有优雅关闭、租约或锁的所有权管理，或毒消息处理机制。
• 直接将配置绑定到服务，却没有选项验证、启动失败检查或明确的密钥处理方式。
• 尚未检查目标 EF Core 版本的 NativeAOT 支持和限制、序列化器元数据和动态加载要求，就选择 Native AOT。普通 Dapper 不支持 AOT，因为它使用运行时反射和 IL emit；在 AOT 下请使用原始 ADO.NET 或 Dapper.AOT。通过实际发布来验证每个依赖项对裁剪/AOT 的支持，并在出现 IL2xxx/IL3xxx 裁剪/AOT 警告时让发布失败；否则保留标准运行时。
• 每个请求都创建并释放一个拥有所有权的 HttpClient/处理程序，可能导致端口耗尽。默认使用生命周期较短的工厂客户端；配置了适应预期 DNS 变化的 SocketsHttpHandler.PooledConnectionLifetime 的长生命周期客户端也有效。对于依赖 Cookie 的会话，使用工厂之前，请检查处理程序池化和 Cookie 隔离（Microsoft 生命周期指南）。
• 不检查部署形态对应的 GC 模式。在 net8 上，Server GC（ASP.NET Core 的默认设置）会根据可见处理器数量调整堆大小，在小型或共享容器中可能过度分配。在这类环境中，可以考虑启用 DATAS（Dynamic Adaptation to Application Sizes）、设置 DOTNET_GCHeapHardLimit 或使用 Workstation GC。在 net9+ 上，DATAS 已默认启用。对于专用且受吞吐量限制的 Pod，请先进行测量；只有在数据支持时才禁用 DATAS；请查看 DATAS 文档页面，了解目标框架当前的行为。

常见反模式

• 构建几乎只是透传包装层、没有边界或策略价值的 clean architecture 分层。
• 对预期的领域结果返回异常，而不是明确的结果或错误契约。
• 到处共享仓储抽象，即使实际需求只是一个专用查询处理程序或聚合持久化边界。
• 将横切行为隐藏在临时辅助工具中，而不是有意使用中间件、筛选器、选项或弹性处理程序。
• 只依赖集成测试作为安全网，却不测试单元测试接缝、虚拟时间和确定性的失败场景。

导航

参考资料

• C# 语言实践
• Dotnet 编码标准
• 后端架构原则
• 模块化架构原则
• ASP.NET Core API 模式
• 数据访问模式
• EF Core 持久化模式
• 场景指南
• 可靠性与弹性
• 弹性策略默认值
• 测试实践
• 可观测性标准
• 运行时运维清单
• 版本兼容性说明
• 安全基线
• 代码审查清单
• 技能来源：精选的一手来源及模块化架构辅助参考资料。

模板

• API 主机模板
• 服务类模板
• Options 配置模板
• 弹性 HTTP 客户端模板
• Dapper 查询处理器模板
• Mongo 仓储模板
• 测试数据构建器模板
• NUnit 测试夹具模板
• 拉取请求清单模板

相关技能

• software-backend → 通用后端模式和多语言指南
• software-architecture-design → 系统级设计与分解
• software-security-appsec → 安全审计与威胁建模
• software-code-review → 审查工作流与判断模式
• qa-testing-nunit → NUnit 测试夹具设计与测试基础设施
• ops-nuke-cicd → NUKE 构建流水线与 CI/CD 目标
• dev-structured-logs → 结构化日志迁移

已知 Bug、回归问题、框架／编译器／运行时陷阱，以及特定版本的崩溃或变通方案指南，必须先通过当前的一手网络来源核实，才能作为当前事实对待。请从 data/sources.json 开始查找版本和支持周期时，优先参考 Microsoft 官方文档，而非博客。

经验反馈循环

如果以往的决策或陷阱与当前任务相关，且存在 learnings.consolidated.md，请先查阅；仅在需要了解历史记录或该文件不可用时，才使用 learnings.md。否则跳过这两个文件。

应用相关内容后，如果你遇到值得记住的模式、值得防止的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。不要修改 SKILL.md 本身。