Cursor rule

1---
2description: CodeSpirit 统一启动框架规范 - API项目配置标准化
3globs: "**/Configuration/*ApiConfiguration.cs,**/Program.cs"
4alwaysApply: false
5---
6 
7# 统一启动框架规范
8 
9## 快速开始
10 
11### Program.cs（标准模板）
12```csharp
13using CodeSpirit.ExamApi.Configuration;
14using CodeSpirit.Shared.Startup;
15using System.Text;
16 
17Console.OutputEncoding = Encoding.UTF8;
18 
19var builder = WebApplication.CreateBuilder(args);
20 
21// 1. 注册服务
22builder.AddCodeSpiritApi<ExamApiConfiguration>();
23 
24var app = builder.Build();
25 
26try
27{
28    // 2. 配置中间件和初始化数据库
29    await app.UseCodeSpiritApiAsync<ExamApiConfiguration>();
30    app.Run();
31}
32catch (Exception ex)
33{
34    var logger = app.Services.GetRequiredService<ILogger<Program>>();
35    logger.LogError(ex, "服务启动过程中发生错误");
36}
37```
38 
39> ⚠️ **规范**：不要在 `Program.cs` 中添加额外配置，所有配置放在 API 配置类中。
40 
41---
42 
43## API 配置类
44 
45### 位置和命名
46- **位置**：`{ProjectName}/Configuration/` 文件夹
47- **命名**：`{ApiName}Configuration`（如 `ExamApiConfiguration`）
48- **继承**：`BaseApiConfiguration`
49 
50### 最小配置类
51```csharp
52namespace CodeSpirit.ExamApi.Configuration;
53 
54public class ExamApiConfiguration : BaseApiConfiguration
55{
56    /// <summary>服务名称，用于 Aspire 服务发现</summary>
57    public override string ServiceName => "exam";
58    
59    /// <summary>数据库连接字符串键名</summary>
60    public override string ConnectionStringKey => "exam-api";
61}
62```
63 
64---
65 
66## 核心方法
67 
68### ConfigureServices - 服务注册
69 
70#### 简化配置方式（推荐）
71 
72使用扩展方法简化配置，减少重复代码：
73 
74```csharp
75public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
76{
77    // ⚠️ 必须调用基类方法（初始化路径前缀配置）
78    base.ConfigureServices(services, configuration);
79    
80    // 配置标准数据库服务（多数据库支持、仓储模式）
81    this.ConfigureStandardDatabaseServices<ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
82        services, configuration);
83    
84    // 配置标准基础设施服务（事件总线、HTTP客户端）+ 可选组件（多租户、设置管理）
85    this.ConfigureStandardInfrastructureServices(services, configuration, (s, c) =>
86    {
87        s.AddCodeSpiritMultiTenant(c);
88        s.AddSettingsManagerWithDatabase(c);
89    });
90    
91    // 只配置特定业务服务
92    services.AddLLMServices();
93    AddExamSpecificServices(services);
94}
95```
96 
97#### 传统配置方式
98 
99如果需要更多控制，可以使用传统方式：
100 
101```csharp
102public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
103{
104    // ⚠️ 必须调用基类方法（初始化路径前缀配置）
105    base.ConfigureServices(services, configuration);
106    
107    // 配置多数据库支持（推荐方式）
108    DatabaseMigrationHelper.ConfigureMultiDatabaseDbContext<
109        ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
110        services, configuration, ConnectionStringKey);
111    
112    // 注册仓储模式
113    services.AddScoped(typeof(IRepository<>), typeof(Repository<>));
114    
115    // 添加多租户支持
116    services.AddCodeSpiritMultiTenant(configuration);
117    
118    // 其他服务注册...
119}
120```
121 
122#### 常用服务注册方法
123| 方法 | 说明 |
124|------|------|
125| `services.AddCodeSpiritMultiTenant(configuration)` | 多租户支持 |
126| `services.AddEventBus()` | 事件总线 |
127| `services.AddCodeSpiritCaching(configuration)` | 统一缓存服务 |
128| `services.AddLLMServices()` | LLM 服务 |
129| `services.AddAiFormFillEndpoints()` | AI 表单填充端点 |
130| `services.AddSettingsManagerWithDatabase(configuration)` | 设置管理 |
131| `services.AddScheduledTasks()` | 定时任务 |
132| `services.AddChartServices()` | 图表服务 |
133 
134#### 线程池配置（可选）
135```csharp
136// 高并发服务
137ThreadPoolConfiguration.ConfigureThreadPool(
138    ThreadPoolConfiguration.ServiceTier.High, 
139    expectedInstances: 3, 
140    logger);
141 
142// 服务等级：Low, Medium, High
143```
144 
145---
146 
147### 中间件配置
148 
149#### 1. ConfigurePreAuthenticationMiddlewareAsync - 认证前
150在认证之前执行，用于租户解析等：
151```csharp
152public override Task ConfigurePreAuthenticationMiddlewareAsync(WebApplication app)
153{
154    app.UseCodeSpiritMultiTenant();
155    return Task.CompletedTask;
156}
157```
158 
159#### 2. ConfigurePreControllerMiddlewareAsync - 控制器前
160在控制器映射之前执行：
161```csharp
162public override Task ConfigurePreControllerMiddlewareAsync(WebApplication app)
163{
164    // 通常审计由网关处理，API 服务不需要
165    return Task.CompletedTask;
166}
167```
168 
169#### 3. ConfigureMiddlewareAsync - 自定义中间件
170在通用中间件之后执行：
171 
172**简化配置方式（推荐）：**
173 
174```csharp
175public override async Task ConfigureMiddlewareAsync(WebApplication app)
176{
177    // 配置标准中间件（聚合器）+ 可选组件（多租户、AI表单填充）
178    await this.ConfigureStandardMiddlewareAsync(app, a =>
179    {
180        a.UseCodeSpiritMultiTenant();
181        a.UseAiFormFillEndpoints();
182    });
183    
184    // 只配置特定中间件
185    app.MapHub<ExamHub>("/exam-hub");
186}
187```
188 
189**传统配置方式：**
190 
191```csharp
192public override async Task ConfigureMiddlewareAsync(WebApplication app)
193{
194    // 多租户中间件
195    app.UseCodeSpiritMultiTenant();
196    
197    // 聚合器中间件
198    app.UseCodeSpiritAggregator();
199    
200    // AI 表单填充端点
201    app.UseAiFormFillEndpoints();
202    
203    // SignalR Hub 映射
204    app.MapHub<ExamHub>("/exam-hub");
205    
206    await Task.CompletedTask;
207}
208```
209 
210---
211 
212### InitializeDatabaseAsync - 数据库初始化
213 
214**简化配置方式（推荐）：**
215 
216```csharp
217public override async Task InitializeDatabaseAsync(WebApplication app)
218{
219    // 使用标准数据库初始化方法
220    // 自动应用迁移和初始化种子数据（如果 DbContext 实现了 IInitializableDbContext）
221    await this.InitializeStandardDatabaseAsync<ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
222        app, "ExamApi");
223}
224```
225 
226**传统配置方式：**
227 
228```csharp
229public override async Task InitializeDatabaseAsync(WebApplication app)
230{
231    using var scope = app.Services.CreateScope();
232    var services = scope.ServiceProvider;
233    var logger = services.GetRequiredService<ILogger<ExamApiConfiguration>>();
234    var configuration = services.GetRequiredService<IConfiguration>();
235    
236    try
237    {
238        // 1. 自动应用数据库迁移
239        await DatabaseMigrationHelper.ApplyDatabaseMigrationsAsync<
240            MySqlExamDbContext, 
241            SqlServerExamDbContext>(
242            services, configuration, logger, "ExamApi");
243        
244        // 2. 初始化种子数据
245        var context = services.GetRequiredService<ExamDbContext>();
246        await context.InitializeDatabaseAsync();
247        
248        logger.LogInformation("数据库初始化完成");
249    }
250    catch (Exception ex)
251    {
252        logger.LogError(ex, "初始化数据库时发生错误：{Message}", ex.Message);
253        throw;
254    }
255}
256```
257 
258**注意：** 如果 DbContext 实现了 `IInitializableDbContext` 接口，标准初始化方法会自动调用 `InitializeDatabaseAsync()` 方法。
259 
260---
261 
262## 中间件执行顺序
263 
264```
265请求 ──▶ CORS
266         ↓
267     ApplicationId 中间件
268         ↓
269  ┌──────────────────────────────────────┐
270  │ ConfigurePreAuthenticationMiddlewareAsync │ ← 插入点1（认证前）
271  │ 示例：多租户解析                          │
272  └──────────────────────────────────────┘
273         ↓
274     Authentication & Authorization
275         ↓
276  ┌──────────────────────────────────────┐
277  │ ConfigurePreControllerMiddlewareAsync    │ ← 插入点2（控制器前）
278  │ 示例：审计日志                           │
279  └──────────────────────────────────────┘
280         ↓
281     Controller Mapping
282         ↓
283     AMIS UI / Authorization / Navigation
284         ↓
285  ┌──────────────────────────────────────┐
286  │ ConfigureMiddlewareAsync                 │ ← 插入点3（自定义）
287  │ 示例：聚合器、SignalR Hub                │
288  └──────────────────────────────────────┘
289         ↓
290     响应
291```
292 
293---
294 
295## 统一框架自动配置
296 
297无需手动配置，框架自动完成：
298- ✅ Aspire 服务默认配置（OpenTelemetry、健康检查等）
299- ✅ Scrutor 自动依赖注入（`IScopedDependency` 等）
300- ✅ JWT 认证配置
301- ✅ Redis 分布式缓存
302- ✅ AutoMapper 自动扫描
303- ✅ CORS 配置
304- ✅ 控制器配置（路径前缀路由约定）
305- ✅ 仓储模式注册
306- ✅ 异常处理中间件
307- ✅ 数据库迁移应用
308 
309---
310 
311## 路径前缀配置
312 
313### PathPrefixOptions 属性
314```csharp
315// 基类已定义，从配置文件自动读取
316public virtual PathPrefixOptions PathPrefixOptions { get; protected set; }
317```
318 
319配置文件 `appsettings.json`：
320```json
321{
322  "PathPrefix": {
323    "Enabled": true,
324    "Prefix": "/exam"
325  }
326}
327```
328 
329---
330 
331## 完整配置类示例
332 
333### 简化配置示例（推荐）
334 
335```csharp
336using CodeSpirit.ExamApi.Data;
337using CodeSpirit.Shared.Performance;
338using CodeSpirit.Shared.Startup;
339 
340namespace CodeSpirit.ExamApi.Configuration;
341 
342public class ExamApiConfiguration : BaseApiConfiguration
343{
344    public override string ServiceName => "exam";
345    public override string ConnectionStringKey => "exam-api";
346    
347    public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
348    {
349        // 线程池配置（可选）
350        var logger = services.BuildServiceProvider()
351            .GetService<ILoggerFactory>()?.CreateLogger<ExamApiConfiguration>();
352        ThreadPoolConfiguration.ConfigureThreadPool(
353            ThreadPoolConfiguration.ServiceTier.High, 
354            expectedInstances: 3, 
355            logger);
356        
357        // 调用基类（初始化路径前缀）
358        base.ConfigureServices(services, configuration);
359        
360        // 配置标准数据库服务（多数据库支持、仓储模式）
361        this.ConfigureStandardDatabaseServices<ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
362            services, configuration);
363        
364        // 配置标准基础设施服务（事件总线、HTTP客户端）+ 可选组件（多租户、设置管理）
365        this.ConfigureStandardInfrastructureServices(services, configuration, (s, c) =>
366        {
367            s.AddCodeSpiritMultiTenant(c);
368            s.AddSettingsManagerWithDatabase(c);
369        });
370        
371        // 只配置特定业务服务
372        services.AddLLMServices();
373    }
374    
375    public override async Task ConfigureMiddlewareAsync(WebApplication app)
376    {
377        // 配置标准中间件（聚合器）+ 可选组件（多租户、AI表单填充）
378        await this.ConfigureStandardMiddlewareAsync(app, a =>
379        {
380            a.UseCodeSpiritMultiTenant();
381            a.UseAiFormFillEndpoints();
382        });
383    }
384    
385    public override async Task InitializeDatabaseAsync(WebApplication app)
386    {
387        // 使用标准数据库初始化方法
388        await this.InitializeStandardDatabaseAsync<ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
389            app, "ExamApi");
390    }
391}
392```
393 
394### 传统配置示例
395 
396```csharp
397using CodeSpirit.Aggregator;
398using CodeSpirit.AiFormFill;
399using CodeSpirit.ExamApi.Data;
400using CodeSpirit.MultiTenant.Extensions;
401using CodeSpirit.Shared.Data;
402using CodeSpirit.Shared.Performance;
403using CodeSpirit.Shared.Repositories;
404using CodeSpirit.Shared.Startup;
405 
406namespace CodeSpirit.ExamApi.Configuration;
407 
408public class ExamApiConfiguration : BaseApiConfiguration
409{
410    public override string ServiceName => "exam";
411    public override string ConnectionStringKey => "exam-api";
412    
413    public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
414    {
415        // 线程池配置
416        var logger = services.BuildServiceProvider()
417            .GetService<ILoggerFactory>()?.CreateLogger<ExamApiConfiguration>();
418        ThreadPoolConfiguration.ConfigureThreadPool(
419            ThreadPoolConfiguration.ServiceTier.High, 
420            expectedInstances: 3, 
421            logger);
422        
423        // 调用基类（初始化路径前缀）
424        base.ConfigureServices(services, configuration);
425        
426        // 数据库配置
427        DatabaseMigrationHelper.ConfigureMultiDatabaseDbContext<
428            ExamDbContext, MySqlExamDbContext, SqlServerExamDbContext>(
429            services, configuration, ConnectionStringKey);
430        
431        // 仓储模式
432        services.AddScoped(typeof(IRepository<>), typeof(Repository<>));
433        
434        // 多租户
435        services.AddCodeSpiritMultiTenant(configuration);
436        
437        // 事件总线
438        services.AddEventBus();
439    }
440    
441    public override async Task ConfigureMiddlewareAsync(WebApplication app)
442    {
443        app.UseCodeSpiritMultiTenant();
444        app.UseCodeSpiritAggregator();
445        app.UseAiFormFillEndpoints();
446        await Task.CompletedTask;
447    }
448    
449    public override async Task InitializeDatabaseAsync(WebApplication app)
450    {
451        using var scope = app.Services.CreateScope();
452        var services = scope.ServiceProvider;
453        var logger = services.GetRequiredService<ILogger<ExamApiConfiguration>>();
454        var configuration = services.GetRequiredService<IConfiguration>();
455        
456        try
457        {
458            await DatabaseMigrationHelper.ApplyDatabaseMigrationsAsync<
459                MySqlExamDbContext, SqlServerExamDbContext>(
460                services, configuration, logger, "ExamApi");
461            
462            var context = services.GetRequiredService<ExamDbContext>();
463            await context.InitializeDatabaseAsync();
464        }
465        catch (Exception ex)
466        {
467            logger.LogError(ex, "初始化数据库失败：{Message}", ex.Message);
468            throw;
469        }
470    }
471}
472```
473 
474---
475 
476## 注意事项
477 
478| 规则 | 说明 |
479|------|------|
480| ✅ 调用 `base.ConfigureServices()` | 必须调用以初始化路径前缀配置 |
481| ✅ 使用扩展方法简化配置 | 推荐使用 `ConfigureStandardDatabaseServices`、`ConfigureStandardInfrastructureServices` 等扩展方法 |
482| ✅ 使用回调委托配置可选组件 | 通过委托参数显式配置可选组件，避免反射调用 |
483| ✅ 使用 `DatabaseMigrationHelper` | 简化多数据库配置 |
484| ✅ 实现 `IInitializableDbContext` | 如果 DbContext 需要初始化种子数据，实现此接口 |
485| ✅ 异步方法返回 `Task` | 所有中间件配置方法都是异步的 |
486| ❌ 在 Program.cs 添加配置 | 所有配置放在 API 配置类中 |
487| ❌ 重复注册框架已有服务 | 检查自动配置列表避免重复 |
488| ❌ 使用反射调用扩展方法 | 反射调用失去编译时类型安全，且性能较差 |
489 
490---
491 
492## 可选组件配置最佳实践
493 
494### ❌ 错误方式：使用反射调用
495 
496```csharp
497// ❌ 不推荐：使用反射动态调用扩展方法
498private static void TryInvokeExtensionMethod(IServiceCollection services, 
499    string namespaceName, string className, string methodName, IConfiguration configuration)
500{
501    var assembly = AppDomain.CurrentDomain.GetAssemblies()
502        .FirstOrDefault(a => a.GetTypes().Any(t => t.Namespace == namespaceName));
503    var type = assembly.GetType($"{namespaceName}.{className}");
504    var method = type.GetMethod(methodName, BindingFlags.Public | BindingFlags.Static);
505    method?.Invoke(null, new object[] { services, configuration });
506}
507```
508 
509**问题**：
510- ❌ 编译时无法检测方法签名变更
511- ❌ 运行时性能损耗
512- ❌ IDE 无法追踪引用关系
513- ❌ 错误被默默吞掉，不易察觉
514- ❌ 重构时容易遗漏
515 
516### ✅ 正确方式：使用回调委托
517 
518```csharp
519// ✅ 推荐：通过回调委托配置可选组件
520public static void ConfigureStandardInfrastructureServices(
521    this BaseApiConfiguration config,
522    IServiceCollection services,
523    IConfiguration configuration,
524    Action<IServiceCollection, IConfiguration>? additionalConfiguration = null)
525{
526    // 核心服务（必需）
527    services.AddEventBus();
528    services.AddHttpClient();
529    
530    // 可选组件通过委托配置
531    additionalConfiguration?.Invoke(services, configuration);
532}
533```
534 
535**调用示例**：
536 
537```csharp
538// 显式配置需要的可选组件
539this.ConfigureStandardInfrastructureServices(services, configuration, (s, c) =>
540{
541    s.AddCodeSpiritMultiTenant(c);        // 多租户支持
542    s.AddSettingsManagerWithDatabase(c);  // 设置管理
543});
544```