Cursor rule

1---
2description: CodeSpirit 性能优化规范 - 异步编程、缓存策略、查询优化、分布式场景
3globs: *.cs
4alwaysApply: false
5---
6 
7# 性能优化规范
8 
9## 异步编程
10- **所有 I/O 操作必须使用异步方法**（`async/await`）
11- **避免阻塞调用**：禁止使用 `Task.Result` 和 `Task.Wait()`
12- **高频调用优化**：使用 `ValueTask<T>` 减少堆分配
13- **避免异步循环**：使用批量处理代替循环中的异步操作
14 
15### 正确示例
16```csharp
17// ✅ 正确：使用异步方法
18public async Task<List<QuestionDto>> GetQuestionsAsync(QuestionQueryDto query)
19{
20    var entities = await _repository.GetListAsync(query);
21    return _mapper.Map<List<QuestionDto>>(entities);
22}
23 
24// ✅ 正确：批量处理
25public async Task<List<QuestionDto>> GetQuestionsByIdsAsync(List<long> ids)
26{
27    // 一次查询获取所有数据
28    var entities = await _dbContext.Questions
29        .Where(q => ids.Contains(q.Id))
30        .ToListAsync();
31    return _mapper.Map<List<QuestionDto>>(entities);
32}
33```
34 
35### 错误示例
36```csharp
37// ❌ 错误：阻塞调用
38public List<QuestionDto> GetQuestions(QuestionQueryDto query)
39{
40    var entities = _repository.GetListAsync(query).Result;  // 阻塞！
41    return _mapper.Map<List<QuestionDto>>(entities);
42}
43 
44// ❌ 错误：异步循环
45public async Task<List<QuestionDto>> GetQuestionsByIdsAsync(List<long> ids)
46{
47    var results = new List<QuestionDto>();
48    foreach (var id in ids)
49    {
50        var entity = await _repository.GetByIdAsync(id);  // N 次查询！
51        results.Add(_mapper.Map<QuestionDto>(entity));
52    }
53    return results;
54}
55```
56 
57## 缓存策略
58 
59### 缓存键命名
60```csharp
61// 格式：{service}:{entity}:{identifier}
62"exam:question:123"
63"exam:questions:list:categoryId_5"
64"exam:user:profile:456"
65 
66// 租户缓存：{tenantId}:{service}:{entity}:{identifier}
67"tenant_1:exam:question:123"
68```
69 
70### 缓存级别
71- **L1 (内存缓存)**：频繁访问的小数据（配置、枚举等）
72- **L2 (Redis)**：需要跨实例共享的数据
73- **L1AndL2**：热点数据（如用户信息、权限数据）
74 
75### 使用示例
76```csharp
77public class QuestionService
78{
79    private readonly ICacheService _cacheService;
80    
81    public async Task<QuestionDto> GetByIdAsync(long id)
82    {
83        return await _cacheService.GetOrSetAsync(
84            $"exam:question:{id}",
85            async () => await _repository.GetByIdAsync(id),
86            new CacheOptions 
87            { 
88                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30),
89                Level = CacheLevel.L1AndL2
90            });
91    }
92    
93    public async Task UpdateAsync(long id, UpdateQuestionDto dto)
94    {
95        await _repository.UpdateAsync(id, dto);
96        
97        // 更新后清除缓存
98        await _cacheService.RemoveAsync($"exam:question:{id}");
99    }
100}
101```
102 
103### 过期策略
104- **静态数据**：绝对过期时间（1小时以上）
105- **动态数据**：滑动过期时间（5-30分钟）
106- **实时数据**：不缓存或短期缓存（1-5分钟）
107 
108## EF Core 查询优化
109 
110### 1. AsNoTracking 只读查询
111```csharp
112// ✅ 只读查询使用 AsNoTracking
113public async Task<List<QuestionDto>> GetListAsync(QuestionQueryDto query)
114{
115    var entities = await _dbContext.Questions
116        .AsNoTracking()  // 不跟踪实体变化，提升性能
117        .Where(q => q.IsDeleted == false)
118        .ToListAsync();
119    return _mapper.Map<List<QuestionDto>>(entities);
120}
121```
122 
123### 2. Include 避免 N+1 查询
124```csharp
125// ✅ 正确：一次查询加载关联数据
126public async Task<List<QuestionDto>> GetListWithCategoryAsync()
127{
128    var entities = await _dbContext.Questions
129        .Include(q => q.Category)  // 预加载关联数据
130        .AsNoTracking()
131        .ToListAsync();
132    return _mapper.Map<List<QuestionDto>>(entities);
133}
134 
135// ❌ 错误：N+1 查询
136public async Task<List<QuestionDto>> GetListWithCategoryAsync()
137{
138    var entities = await _dbContext.Questions.ToListAsync();
139    foreach (var entity in entities)
140    {
141        entity.Category = await _dbContext.Categories.FindAsync(entity.CategoryId);  // N次查询！
142    }
143    return _mapper.Map<List<QuestionDto>>(entities);
144}
145```
146 
147### 3. AsSplitQuery 处理笛卡尔积
148```csharp
149// ✅ 多对多关联使用 AsSplitQuery
150public async Task<ExamDto> GetExamWithQuestionsAsync(long examId)
151{
152    var exam = await _dbContext.Exams
153        .Include(e => e.Questions)
154        .ThenInclude(q => q.Options)
155        .AsSplitQuery()  // 拆分为多个查询，避免笛卡尔积
156        .FirstOrDefaultAsync(e => e.Id == examId);
157    return _mapper.Map<ExamDto>(exam);
158}
159```
160 
161### 4. 批量操作
162```csharp
163// ✅ 批量更新（EF Core 7+）
164public async Task UpdateScoresAsync(Dictionary<long, decimal> scores)
165{
166    await _dbContext.Questions
167        .Where(q => scores.Keys.Contains(q.Id))
168        .ExecuteUpdateAsync(setters => setters
169            .SetProperty(q => q.Score, q => scores[q.Id]));
170}
171 
172// ✅ 批量删除（EF Core 7+）
173public async Task DeleteByCategoryAsync(long categoryId)
174{
175    await _dbContext.Questions
176        .Where(q => q.CategoryId == categoryId)
177        .ExecuteDeleteAsync();
178}
179```
180 
181### 5. 投影查询
182```csharp
183// ✅ 只查询需要的字段
184public async Task<List<QuestionListItemDto>> GetListAsync()
185{
186    return await _dbContext.Questions
187        .Select(q => new QuestionListItemDto
188        {
189            Id = q.Id,
190            Content = q.Content,
191            CategoryName = q.Category.Name
192        })
193        .ToListAsync();
194}
195```
196 
197## 分布式场景优化
198 
199### 1. 分布式锁
200```csharp
201public async Task<bool> TryStartExamAsync(long examId, long userId)
202{
203    var lockKey = $"exam:start:{examId}:{userId}";
204    
205    await using var lockHandle = await _distributedLock.TryAcquireAsync(
206        lockKey, 
207        TimeSpan.FromSeconds(10));
208    
209    if (lockHandle == null)
210    {
211        throw new BusinessException("Errors.ExamAlreadyStarted");
212    }
213    
214    // 执行业务逻辑
215    await _examService.StartExamAsync(examId, userId);
216    return true;
217}
218```
219 
220### 2. 分布式缓存
221```csharp
222public async Task<UserDto> GetUserAsync(long userId)
223{
224    return await _cacheService.GetOrSetAsync(
225        $"user:{userId}",
226        async () => await _userRepository.GetByIdAsync(userId),
227        new CacheOptions 
228        { 
229            Level = CacheLevel.L2  // Redis 分布式缓存
230        });
231}
232```
233 
234### 3. 事件驱动解耦
235```csharp
236// 发布事件
237public async Task CreateOrderAsync(CreateOrderDto dto)
238{
239    var order = await _orderRepository.CreateAsync(dto);
240    
241    // 发布事件，异步处理后续逻辑
242    await _eventBus.PublishAsync(new OrderCreatedEvent
243    {
244        OrderId = order.Id,
245        UserId = order.UserId
246    });
247}
248 
249// 订阅事件
250public class OrderCreatedEventHandler : IEventHandler<OrderCreatedEvent>
251{
252    public async Task HandleAsync(OrderCreatedEvent @event)
253    {
254        // 异步处理：发送通知、更新库存等
255        await _notificationService.NotifyOrderCreatedAsync(@event.OrderId);
256    }
257}
258```
259 
260### 4. 最终一致性
261```csharp
262// 避免分布式事务，采用最终一致性
263public async Task CreateOrderAsync(CreateOrderDto dto)
264{
265    // 1. 先创建订单（主业务）
266    var order = await _orderRepository.CreateAsync(dto);
267    
268    // 2. 发布事件，异步处理库存扣减
269    await _eventBus.PublishAsync(new OrderCreatedEvent
270    {
271        OrderId = order.Id,
272        Items = dto.Items
273    });
274    
275    // 库存扣减失败时，通过补偿机制处理
276}
277```
278 
279## 数据库连接池
280- 使用连接池管理数据库连接
281- 避免长时间占用连接
282- 及时释放连接（使用 `using` 或 DI 容器管理）
283 
284## 注意事项
285- 定期监控性能指标（响应时间、吞吐量、资源使用）
286- 使用 Application Insights 或类似工具进行性能分析
287- 避免过早优化，先测量后优化
288- 考虑分布式场景下的数据一致性
289- 缓存要考虑缓存穿透、雪崩、击穿等问题
290