Cursor rule

1---
2description: CodeSpirit 包管理规范 - 集中式包管理、版本统一、冗余引用处理
3globs: ["*.csproj", "Directory.Packages.props"]
4alwaysApply: false
5---
6 
7# CodeSpirit 包管理规范
8 
9## 集中式包管理（Central Package Management）
10 
11项目已启用集中式包管理，所有包版本在 `Directory.Packages.props` 文件中统一管理。
12 
13### 工作原理
14 
151. **版本定义**: 在 `Directory.Packages.props` 中使用 `<PackageVersion>` 定义所有包版本
162. **项目引用**: 在项目文件中使用 `<PackageReference Include="PackageName" />`，**不指定 Version**
173. **自动应用**: MSBuild 自动从 `Directory.Packages.props` 获取版本
18 
19### 添加新包
20 
21**步骤 1**: 在 `Directory.Packages.props` 中添加包版本
22 
23```xml
24<ItemGroup>
25  <!-- 按功能分类添加 -->
26  <PackageVersion Include="NewPackage" Version="1.0.0" />
27</ItemGroup>
28```
29 
30**步骤 2**: 在项目文件中添加包引用（不指定版本）
31 
32```xml
33<ItemGroup>
34  <PackageReference Include="NewPackage" />
35</ItemGroup>
36```
37 
38### 版本覆盖（特殊情况）
39 
40仅在必要时使用 `VersionOverride`，并添加注释说明原因：
41 
42```xml
43<!-- 注意：Aspire.Microsoft.EntityFrameworkCore.SqlServer 13.0.2 需要 EF Core 10.0.0 -->
44<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" VersionOverride="10.0.0" />
45```
46 
47**使用 VersionOverride 的场景**：
48- Aspire EF Core 集成包需要特定版本的 EF Core
49- 特定项目需要不同版本的包（应尽量避免）
50 
51## 包版本策略
52 
53### 版本更新原则
54 
551. **补丁版本更新**（推荐）
56   - 如：`9.0.9` → `9.0.10`
57   - 通常只包含 bug 修复，风险较低
58 
592. **小版本更新**（谨慎）
60   - 如：`9.0.x` → `9.1.x`
61   - 可能包含新功能和 API 变化，需要测试
62 
633. **大版本更新**（充分测试）
64   - 如：`9.x` → `10.x`
65   - 通常包含破坏性更改，需要全面测试
66 
67### 当前统一版本
68 
69主要包的统一版本（详见 `Directory.Packages.props`）：
70 
71- **Aspire 包**: `13.0.2`（部分使用 `13.1.0`）
72- **Entity Framework Core**: `9.0.9`（使用 Aspire EF Core 集成的项目使用 `10.0.0`）
73- **Microsoft Extensions**: `10.0.0`
74- **OpenTelemetry**: `1.11.1`
75- **StackExchange.Redis**: `2.9.32`
76- **Newtonsoft.Json**: `13.0.3`
77- **AutoMapper**: `13.0.1`
78- **FluentValidation**: `11.11.0`
79 
80## 传递依赖处理
81 
82### 识别传递依赖
83 
84使用以下命令查看传递依赖：
85 
86```bash
87dotnet list package --include-transitive
88```
89 
90### 常见传递依赖
91 
92以下包通过项目引用传递可用，通常不需要显式引用：
93 
94#### 通过 `CodeSpirit.Shared` 传递
95 
96- `Newtonsoft.Json`
97- `Microsoft.EntityFrameworkCore.SqlServer`
98- `Microsoft.EntityFrameworkCore`
99- `Pomelo.EntityFrameworkCore.MySql`
100- `LinqKit.Core`
101- `RabbitMQ.Client`
102- `Aspire.RabbitMQ.Client`
103- `StackExchange.Redis`
104- `ClosedXML`
105- `Polly`
106- `Scrutor`
107- `System.Linq.Dynamic.Core`
108 
109#### 通过 `CodeSpirit.ServiceDefaults` 传递
110 
111- `Aspire.Seq`
112- `Aspire.StackExchange.Redis.DistributedCaching`
113- `Microsoft.Extensions.Diagnostics.HealthChecks`
114- `Microsoft.Extensions.Http.Resilience`
115- `Microsoft.Extensions.ServiceDiscovery`
116- `OpenTelemetry.*` 相关包
117 
118#### 通过 `FrameworkReference` 提供（.NET 10）
119 
120- `Microsoft.AspNetCore.Http.Abstractions`
121- `Microsoft.AspNetCore.Mvc.Core`
122- 大部分 `Microsoft.AspNetCore.*` 包
123 
124### 何时需要显式引用
125 
126以下情况需要显式引用传递依赖：
127 
1281. **需要特定版本**
129   - 使用 `VersionOverride` 覆盖传递的版本
130 
1312. **需要特定 API**
132   - 如果项目直接使用包的公共 API，建议显式引用
133 
1343. **避免版本冲突**
135   - 当传递依赖版本与项目需求不匹配时
136 
1374. **工具包**
138   - 如 `Microsoft.EntityFrameworkCore.Design`、`Microsoft.EntityFrameworkCore.Tools`
139   - 这些包需要显式引用并设置 `PrivateAssets`
140 
141## 包分类组织
142 
143`Directory.Packages.props` 中的包按以下分类组织：
144 
1451. **Aspire 包** - Aspire 框架相关
1462. **Entity Framework Core** - EF Core 相关
1473. **Microsoft Extensions** - Microsoft.Extensions.* 包
1484. **Microsoft ASP.NET Core** - Microsoft.AspNetCore.* 包
1495. **OpenTelemetry** - 监控和追踪
1506. **缓存和消息队列** - Redis、RabbitMQ
1517. **工具和库** - 第三方工具包
1528. **FluentValidation** - 验证框架
1539. **其他工具包** - 各种工具库
15410. **云服务 SDK** - 云服务集成
15511. **开发工具** - 开发时使用的工具
15612. **测试框架包** - 测试相关包
157 
158## 最佳实践
159 
160### 添加新包
161 
1621. ✅ 先检查 `Directory.Packages.props` 是否已存在该包
1632. ✅ 如果存在，直接使用现有版本
1643. ✅ 如果不存在，添加到 `Directory.Packages.props` 的相应分类
1654. ✅ 在项目文件中只引用包名，不指定版本
1665. ✅ 添加注释说明包的用途（如需要）
167 
168### 更新包版本
169 
1701. ✅ 在 `Directory.Packages.props` 中更新版本
1712. ✅ 运行 `dotnet restore` 验证兼容性
1723. ✅ 运行 `dotnet build` 确保构建成功
1734. ✅ 运行 `aspire run` 验证运行时功能
174 
175### 移除包引用
176 
1771. ✅ 检查是否通过传递依赖可用
1782. ✅ 使用 `dotnet list package --include-transitive` 确认
1793. ✅ 移除后立即构建验证
1804. ✅ 如果编译失败，说明需要显式引用
181 
182### 版本冲突处理
183 
1841. ✅ 优先统一版本到最新补丁版本
1852. ✅ 必要时使用 `VersionOverride`（添加注释）
1863. ✅ 考虑升级相关包到兼容版本
1874. ✅ 记录版本冲突原因和解决方案
188 
189## 工具和命令
190 
191### 检查过时的包
192 
193```bash
194dotnet list package --outdated
195```
196 
197### 查看传递依赖
198 
199```bash
200dotnet list package --include-transitive
201```
202 
203### 查看特定项目的包
204 
205```bash
206dotnet list package --project Src/ApiServices/CodeSpirit.ExamApi/CodeSpirit.ExamApi.csproj
207```
208 
209### 还原包
210 
211```bash
212dotnet restore
213```
214 
215### 构建验证
216 
217```bash
218dotnet build
219```
220 
221## 常见问题
222 
223### Q: 如何知道一个包是否通过传递依赖可用？
224 
225A: 使用 `dotnet list package --include-transitive` 查看。如果包出现在传递依赖列表中，通常不需要显式引用。
226 
227### Q: 为什么有些包显示"可能不需要"的警告？
228 
229A: NuGet 的静态分析可能误判。如果项目确实使用了包的 API，应保留引用。建议通过代码搜索验证实际使用情况。
230 
231### Q: 如何更新所有包到最新版本？
232 
233A: 
2341. 使用 `dotnet outdated-tool` 分析
2352. 在 `Directory.Packages.props` 中逐个更新版本
2363. 每次更新后构建验证
2374. 优先更新补丁版本，谨慎更新小版本和大版本
238 
239### Q: 版本冲突如何解决？
240 
241A:
2421. 优先统一到最新补丁版本
2432. 必要时使用 `VersionOverride`（添加注释说明）
2443. 考虑升级相关包到兼容版本
2454. 记录冲突原因和解决方案
246 
247## 参考文档
248 
249- [NuGet Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management)
250- [Directory.Packages.props 文件](../../Directory.Packages.props)
251- [包管理优化报告](../../Docs/PackageOptimizationReport.md)