Cursor rule

1---
2description: CodeSpirit 数据库与 EF Core 迁移规范 - 多数据库支持、DbContext 设计、迁移命令
3globs: 
4  - "*DbContext*.cs"
5  - "**/Data/**/*.cs"
6  - "**/Configurations/**/*.cs"
7  - "**/Migrations/**/*.cs"
8alwaysApply: false
9---
10 
11# 数据库与 EF Core 迁移规范
12 
13## 📋 目录
14 
151. [多数据库架构](#多数据库架构)
162. [DbContext 设计模式](#dbcontext-设计模式)
173. [迁移命令规范](#迁移命令规范)
184. [实体 ID 配置](#实体-id-配置)
195. [实体配置规范](#实体配置规范)
20 
21---
22 
23## 多数据库架构
24 
25CodeSpirit 支持多数据库（SQL Server / MySQL），每个 API 服务需要定义：
26 
27```
28Data/
29├── {Service}DbContext.cs              # 基础 DbContext（运行时使用）
30├── SqlServer{Service}DbContext.cs     # SQL Server 专用 DbContext
31├── SqlServer{Service}DbContextFactory.cs  # SQL Server 设计时工厂
32├── MySql{Service}DbContext.cs         # MySQL 专用 DbContext
33├── MySql{Service}DbContextFactory.cs  # MySQL 设计时工厂
34├── DatabaseSpecificConfigurations.cs  # 数据库特定配置
35├── Configurations/                    # 实体配置
36│   └── {Entity}Configuration.cs
37└── Migrations/
38    ├── SqlServer/                     # SQL Server 迁移
39    │   └── {timestamp}_{MigrationName}.cs
40    └── MySql/                         # MySQL 迁移
41        └── {timestamp}_{MigrationName}.cs
42```
43 
44---
45 
46## DbContext 设计模式
47 
48### 基础 DbContext
49 
50运行时使用的 DbContext，继承自 `MultiDatabaseDbContextBase`：
51 
52```csharp
53public class MallDbContext : MultiDatabaseDbContextBase
54{
55    public MallDbContext(
56        DbContextOptions options,
57        IServiceProvider serviceProvider,
58        ICurrentUser currentUser,
59        IHttpContextAccessor httpContextAccessor) 
60        : base(options, serviceProvider, currentUser, httpContextAccessor)
61    {
62    }
63 
64    // DbSet 属性
65    public DbSet<Product> Products => Set<Product>();
66    public DbSet<Order> Orders => Set<Order>();
67 
68    protected override void OnModelCreating(ModelBuilder modelBuilder)
69    {
70        base.OnModelCreating(modelBuilder);
71        modelBuilder.ApplyConfigurationsFromAssembly(typeof(MallDbContext).Assembly);
72    }
73}
74```
75 
76### 数据库特定 DbContext
77 
78**SQL Server 版本**：
79 
80```csharp
81/// <summary>
82/// SQL Server 特定的数据库上下文（用于迁移）
83/// </summary>
84public class SqlServerMallDbContext : MallDbContext
85{
86    public SqlServerMallDbContext(
87        DbContextOptions<SqlServerMallDbContext> options,
88        IServiceProvider serviceProvider,
89        ICurrentUser currentUser,
90        IHttpContextAccessor httpContextAccessor) 
91        : base((DbContextOptions)options, serviceProvider, currentUser, httpContextAccessor)
92    {
93    }
94 
95    protected override void ApplyDatabaseSpecificConfigurations(ModelBuilder modelBuilder)
96    {
97        DatabaseSpecificConfigurations.ApplySqlServerConfigurations(modelBuilder);
98    }
99}
100```
101 
102**MySQL 版本**：
103 
104```csharp
105/// <summary>
106/// MySQL 特定的数据库上下文（用于迁移）
107/// </summary>
108public class MySqlMallDbContext : MallDbContext
109{
110    public MySqlMallDbContext(
111        DbContextOptions<MySqlMallDbContext> options,
112        IServiceProvider serviceProvider,
113        ICurrentUser currentUser,
114        IHttpContextAccessor httpContextAccessor) 
115        : base((DbContextOptions)options, serviceProvider, currentUser, httpContextAccessor)
116    {
117    }
118 
119    protected override void ApplyDatabaseSpecificConfigurations(ModelBuilder modelBuilder)
120    {
121        DatabaseSpecificConfigurations.ApplyMySqlConfigurations(modelBuilder);
122    }
123}
124```
125 
126### 设计时工厂
127 
128用于 `dotnet ef` 命令的设计时 DbContext 创建：
129 
130**SQL Server**:
131 
132```csharp
133public class SqlServerMallDbContextFactory : IDesignTimeDbContextFactory<SqlServerMallDbContext>
134{
135    public SqlServerMallDbContext CreateDbContext(string[] args)
136    {
137        var optionsBuilder = new DbContextOptionsBuilder<SqlServerMallDbContext>();
138        
139        optionsBuilder.UseSqlServer(
140            "Server=localhost;Database=Mall;User Id=sa;Password=Password123!;TrustServerCertificate=True;",
141            options => options.MigrationsHistoryTable("__EFMigrationsHistory", "mall")
142        );
143 
144        var services = new ServiceCollection();
145        var serviceProvider = services.BuildServiceProvider();
146        var currentUser = new DesignTimeCurrentUser();
147        var httpContextAccessor = new HttpContextAccessor();
148 
149        return new SqlServerMallDbContext(optionsBuilder.Options, serviceProvider, currentUser, httpContextAccessor);
150    }
151}
152```
153 
154**MySQL**:
155 
156```csharp
157public class MySqlMallDbContextFactory : IDesignTimeDbContextFactory<MySqlMallDbContext>
158{
159    public MySqlMallDbContext CreateDbContext(string[] args)
160    {
161        var optionsBuilder = new DbContextOptionsBuilder<MySqlMallDbContext>();
162        
163        optionsBuilder.UseMySql(
164            "Server=localhost;Database=Mall;User=root;Password=password;",
165            new MySqlServerVersion(new Version(8, 0, 21)),
166            options => options.MigrationsHistoryTable("__EFMigrationsHistory")
167        );
168 
169        var services = new ServiceCollection();
170        var serviceProvider = services.BuildServiceProvider();
171        var currentUser = new DesignTimeCurrentUser();
172        var httpContextAccessor = new HttpContextAccessor();
173 
174        return new MySqlMallDbContext(optionsBuilder.Options, serviceProvider, currentUser, httpContextAccessor);
175    }
176}
177```
178 
179---
180 
181## 迁移命令规范
182 
183### ⚠️ 重要：必须使用数据库特定的 DbContext
184 
185**❌ 错误**：使用基础 DbContext
186```bash
187dotnet ef migrations add InitialCreate --context MallDbContext
188```
189 
190**✅ 正确**：使用数据库特定的 DbContext
191 
192#### SQL Server 迁移
193 
194```bash
195# 创建迁移
196dotnet ef migrations add InitialCreate --context SqlServerMallDbContext --output-dir Data/Migrations/SqlServer
197 
198# 更新数据库
199dotnet ef database update --context SqlServerMallDbContext
200 
201# 删除最后一次迁移
202dotnet ef migrations remove --context SqlServerMallDbContext
203```
204 
205#### MySQL 迁移
206 
207```bash
208# 创建迁移
209dotnet ef migrations add InitialCreate --context MySqlMallDbContext --output-dir Data/Migrations/MySql
210 
211# 更新数据库
212dotnet ef database update --context MySqlMallDbContext
213 
214# 删除最后一次迁移
215dotnet ef migrations remove --context MySqlMallDbContext
216```
217 
218### 迁移命名规范
219 
220| 场景 | 命名示例 |
221|------|---------|
222| 初始创建 | `InitialCreate` |
223| 添加实体 | `Add{EntityName}` |
224| 添加字段 | `Add{FieldName}To{EntityName}` |
225| 修改字段 | `Update{FieldName}In{EntityName}` |
226| 删除字段 | `Remove{FieldName}From{EntityName}` |
227| 添加索引 | `AddIndexTo{EntityName}` |
228 
229---
230 
231## 实体 ID 配置
232 
233### 雪花 ID 配置
234 
235当实体使用应用层生成的雪花 ID（通过 `IIdGenerator`）时，**必须**在实体配置中添加 `ValueGeneratedNever()`：
236 
237```csharp
238public class ProductConfiguration : IEntityTypeConfiguration<Product>
239{
240    public void Configure(EntityTypeBuilder<Product> builder)
241    {
242        builder.ToTable("Products");
243        builder.HasKey(x => x.Id);
244        
245        // ✅ 必须：禁用数据库自动生成 ID
246        builder.Property(x => x.Id).ValueGeneratedNever();
247        
248        // 其他配置...
249    }
250}
251```
252 
253### 常见错误
254 
255**❌ 缺少 `ValueGeneratedNever()` 导致的错误**：
256 
257```
258当 IDENTITY_INSERT 设置为 OFF 时，不能为表 'Products' 中的标识列插入显式值
259```
260 
261或 MySQL：
262 
263```
264Cannot insert explicit value for identity column in table 'Products' when IDENTITY_INSERT is set to OFF
265```
266 
267**✅ 解决方案**：
268 
2691. 在实体配置中添加 `ValueGeneratedNever()`
2702. 删除现有迁移
2713. 使用正确的 DbContext 重新生成迁移
272 
273### 需要配置 ValueGeneratedNever 的场景
274 
275| 场景 | 需要配置 | 说明 |
276|------|---------|------|
277| 使用 `IIdGenerator` 生成 ID | ✅ 是 | 应用层生成雪花 ID |
278| DemoDataService 中设置显式 ID | ✅ 是 | 测试数据生成 |
279| 数据导入时保留原始 ID | ✅ 是 | 数据迁移 |
280| 使用数据库自增 ID | ❌ 否 | 默认行为 |
281 
282### 检查清单
283 
284创建新实体时，确认以下事项：
285 
286- [ ] 实体是否继承 `AuditableEntityBase<long>` 或类似基类？
287- [ ] 是否在代码中使用 `_idGenerator.NewId()` 设置 ID？
288- [ ] 实体配置中是否添加了 `ValueGeneratedNever()`？
289 
290---
291 
292## 实体配置规范
293 
294### 配置文件位置
295 
296```
297Data/Configurations/{EntityName}Configuration.cs
298```
299 
300### 标准配置模板
301 
302```csharp
303using Microsoft.EntityFrameworkCore;
304using Microsoft.EntityFrameworkCore.Metadata.Builders;
305 
306namespace CodeSpirit.{Service}Api.Data.Configurations;
307 
308/// <summary>
309/// {EntityName} 实体配置
310/// </summary>
311public class {EntityName}Configuration : IEntityTypeConfiguration<{EntityName}>
312{
313    public void Configure(EntityTypeBuilder<{EntityName}> builder)
314    {
315        // 表名
316        builder.ToTable("{TableName}");
317        
318        // 主键
319        builder.HasKey(x => x.Id);
320        builder.Property(x => x.Id).ValueGeneratedNever(); // 雪花 ID
321        
322        // 租户 ID（多租户实体必须）
323        builder.Property(x => x.TenantId).IsRequired().HasMaxLength(50);
324        
325        // 必填字符串字段
326        builder.Property(x => x.Name).IsRequired().HasMaxLength(100);
327        
328        // 可选字符串字段
329        builder.Property(x => x.Description).HasMaxLength(500);
330        
331        // 金额字段
332        builder.Property(x => x.Amount).HasColumnType("decimal(18,2)");
333        
334        // 长文本字段
335        builder.Property(x => x.Content).HasColumnType("text");
336        
337        // 带默认值的字段
338        builder.Property(x => x.IsEnabled).HasDefaultValue(true);
339        builder.Property(x => x.SortOrder).HasDefaultValue(0);
340        
341        // 索引
342        builder.HasIndex(x => new { x.TenantId, x.Code })
343            .IsUnique()
344            .HasDatabaseName("IX_{TableName}_TenantId_Code");
345        
346        // 关系配置
347        builder.HasOne(x => x.Parent)
348            .WithMany(x => x.Children)
349            .HasForeignKey(x => x.ParentId)
350            .OnDelete(DeleteBehavior.Restrict);
351    }
352}
353```
354 
355---
356 
357## 注意事项
358 
3591. **始终使用数据库特定的 DbContext 进行迁移操作**
3602. **SQL Server 和 MySQL 的迁移必须分别生成**
3613. **使用雪花 ID 的实体必须配置 `ValueGeneratedNever()`**
3624. **迁移文件按数据库类型分目录存放**
3635. **设计时工厂中的连接字符串仅用于迁移生成，不用于运行时**
364