csharp-dotnet.mdc

---
description: 使用 C# 和 .NET 的现代软件开发最佳实践和模式
globs: "**/*.cs", "src/**/*.cs"
---

# C# 和 .NET 最佳实践

## 项目结构
- 使用标准的 .NET 项目结构，按功能或层（Web, Application, Domain, Infrastructure）组织项目
- 使用解决方案（`.sln`）文件来组织多个项目
- 将接口和实现分离到不同的文件中
- 使用命名空间（namespaces）来组织代码

## 编码规范
- 遵循 Microsoft 的 C# 编码约定
- 使用 PascalCase 命名法命名类、方法、属性和事件
- 使用 camelCase 命名法命名局部变量和方法参数
- 私有字段前缀使用 `_` (e.g., `_myField`)
- 优先使用 `var` 进行局部变量声明，当类型明显时
- 使用属性（Properties）而不是公共字段

## .NET Core / .NET 5+
- 使用内置的依赖注入（Dependency Injection）容器
- 利用 `appsettings.json` 进行配置，并支持环境特定配置
- 使用中间件（Middleware）来构建 HTTP 请求处理管道
- 优先使用异步编程（`async`/`await`）处理 I/O 密集型操作

## LINQ
- 广泛使用 LINQ 进行数据查询和操作
- 优先使用方法语法（Method Syntax）而不是查询语法（Query Syntax）以保持一致性
- 注意延迟执行（Deferred Execution）的特性
- 使用 `.ToList()` 或 `.ToArray()` 来立即执行查询并缓存结果

## 实体框架 (Entity Framework Core)
- 使用 Code-First 方法进行数据库开发
- 使用迁移（Migrations）来管理数据库模式的变更
- 警惕 N+1 查询问题，使用 `Include()` 和 `ThenInclude()` 预加载相关数据
- 在单独的配置类中使用 Fluent API 来配置数据模型

## 异步编程
- 在整个调用堆栈中都使用 `async` 和 `await` ("async all the way")
- 避免使用 `.Result` 或 `.Wait()`，这可能导致死锁
- 返回 `Task` 或 `Task<T>`，而不是 `void`
- 使用 `CancellationToken` 来支持取消操作

## 错误处理
- 使用 `try-catch-finally` 块来处理异常
- 捕获具体的异常类型，而不是 `System.Exception`
- 创建自定义异常类来表示特定的应用错误
- 不要用异常来控制正常的程序流程

## 测试
- 使用 xUnit, NUnit, 或 MSTest 作为测试框架
- 使用 Moq 或 NSubstitute 进行模拟
- 遵循 Arrange-Act-Assert (AAA) 模式
- 编写单元测试和集成测试