在 .NET 开发中，如何兼顾开发环境的轻量便捷与生产环境的高性能？本文基于 HagiCode 项目实战，分享一套 PostgreSQL 与 SQLite 双数据库适配方案，帮助你在不同环境下无缝切换，提升开发体验与系统稳定性。
双数据库需求的诞生背景
在构建 HagiCode 平台时，我们面临一个典型的两难困境。这个基于 ASP.NET Core 10 和 React 的 AI 辅助开发系统，内部集成了 Orleans 进行分布式状态管理，技术栈复杂且前沿。开发团队希望本地环境能够“开箱即用”，无需安装配置繁重的 PostgreSQL；而生产环境则需应对高并发写入和复杂 JSON 查询，轻量级的 SQLite 难以胜任。
如何在保持代码库统一的前提下，让应用既能像客户端软件一样利用 SQLite 的便携性，又能像企业级服务一样发挥 PostgreSQL 的强悍性能？这成为亟待解决的核心问题。我们探索出的方案，不仅适用于 HagiCode，也为任何需要在轻量级开发与重量级生产之间寻找平衡的 .NET 项目提供了参考。
架构设计：抽象优先，配置驱动
实现双数据库支持的关键，在于“依赖抽象而非具体实现”。我们需要将数据库的选择权从业务代码中剥离，完全交由配置层决定。这一设计思路与前端开发中的“面向接口编程”理念不谋而合，如同 React 或 Angular 通过抽象组件来隔离底层差异。
具体而言，我们遵循以下设计原则：
- 统一接口：所有业务逻辑依赖于
DbContext基类或自定义接口，而非具体的PostgreSqlDbContext。 - 配置驱动：通过
appsettings.json中的配置项，在应用启动时动态决定加载哪个数据库提供程序。 - 特性隔离：针对 PostgreSQL 特有功能（如 JSONB）进行适配，确保在 SQLite 中也能降级运行。
在 ASP.NET Core 的 Program.cs 中，我们不应硬编码 UseNpgsql 或 UseSqlite。相反，应该读取配置来动态决定。首先，定义配置类：
public class DatabaseSettings
{
public const string SectionName = "Database";
// 数据库类型：PostgreSQL 或 SQLite
public string DbType { get; set; } = "PostgreSQL";
// 连接字符串
public string ConnectionString { get; set; } = string.Empty;
}然后，在 Program.cs 中根据配置注册服务：
// 读取配置
var databaseSettings = builder.Configuration.GetSection(DatabaseSettings.SectionName).Get<DatabaseSettings>();
// 注册 DbContext
builder.Services.AddDbContext<ApplicationDbContext>(options =>
{
if (databaseSettings?.DbType?.ToLower() == "sqlite")
{
// SQLite 配置
options.UseSqlite(databaseSettings.ConnectionString);
// SQLite 的并发写入限制处理
// 注意：在生产环境中建议开启 WAL 模式以提高并发性能
}
else
{
// PostgreSQL 配置（默认）
options.UseNpgsql(databaseSettings.ConnectionString, npgsqlOptions =>
{
// 开启 JSONB 支持，这在处理 AI 对话记录时非常有用
npgsqlOptions.UseJsonNet();
});
// 配置连接池重连策略
options.EnableRetryOnFailure(3);
}
});差异处理：JSON 类型的兼容策略
PostgreSQL 和 SQLite 虽都支持 SQL 标准，但在具体特性和行为上差异显著。若不处理好这些差异，很可能出现“本地跑得通，上线就报错”的尴尬情况。在 HagiCode 中，我们需要存储大量提示词和 AI 元数据，这通常涉及 JSON 列。
PostgreSQL 拥有原生的 JSONB 类型，查询性能极佳；而 SQLite 没有原生 JSON 类型（新版本有 JSON1 扩展，但对象映射上仍有差异），通常存储为 TEXT。我们的解决方案是：在 EF Core 的实体映射中，将其配置为可转换的类型。
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
base.OnModelCreating(modelBuilder);
// 配置实体
modelBuilder.Entity<PromptTemplate>(entity =>
{
entity.Property(e => e.Metadata)
.HasColumnType("jsonb") // PG 使用 jsonb
.HasConversion(
v => JsonSerializer.Serialize(v, (JsonSerializerOptions)null),
v => JsonSerializer.Deserialize<Dictionary<string, object>>(v, (JsonSerializerOptions)null)
);
});
}当使用 SQLite 时，虽然 HasColumnType("jsonb") 会被忽略或产生警告，但由于配置了 HasConversion 转换器，数据会被正确地序列化和反序列化为字符串存入 TEXT 字段，从而保证了兼容性。
️ 迁移策略：双轨并行，互不干扰
绝对不要试图让同一套 Migration 脚本同时适配 PG 和 SQLite。由于主键生成策略、索引语法等不同，这必然会导致失败。推荐实践是维护两个迁移分支或项目。在 HagiCode 的开发流中，我们这样处理：
- 开发阶段：主要在 SQLite 下工作，使用
Add-Migration Init_Sqlite -OutputDir Migrations/Sqlite快速迭代。 - 适配阶段：开发完一段功能后，切换连接字符串指向 PostgreSQL，执行
Add-Migration Init_Postgres -OutputDir Migrations/Postgres验证兼容性。 - 自动化脚本：编写简单的 PowerShell 或 Bash 脚本，根据当前环境变量自动应用对应迁移。
# 简单的部署逻辑伪代码
if [ "$DATABASE_PROVIDER" = "PostgreSQL" ]; then
dotnet ef database update --project Migrations.Postgres
else
dotnet ef database update --project Migrations.Sqlite
fi⚡ 实战经验：性能与稳定性的平衡
在将 HagiCode 从单一数据库重构为双数据库支持的过程中，我们踩过不少坑，也总结了一些关键经验。
并发与事务的区别：PostgreSQL 是服务端-客户端架构，支持高并发写入，事务隔离级别强大；而 SQLite 是文件锁机制，写入操作会锁定整个数据库文件（除非开启 WAL 模式）。在编写涉及频繁写入的业务逻辑时，一定要考虑 SQLite 的锁机制。在设计 HagiCode 的 OpenSpec 协作模块时，我们引入了“写前合并”机制，减少数据库的直接写入频率，从而在两种数据库下都保持高性能。
连接字符串的生命周期管理：PostgreSQL 连接建立成本较高，依赖连接池；而 SQLite 连接非常轻量，但若不及时释放，文件锁可能导致后续操作超时。在 Program.cs 中，我们可以针对不同数据库做精细化调整：
if (databaseSettings?.DbType?.ToLower() == "sqlite")
{
// SQLite：保持连接开启能提升性能，但要注意文件锁
options.UseSqlite(connectionString, sqliteOptions =>
{
// 设置命令超时时间
sqliteOptions.CommandTimeout(30);
});
}
else
{
// PG：利用连接池
options.UseNpgsql(connectionString, npgsqlOptions =>
{
npgsqlOptions.MaxBatchSize(100);
npgsqlOptions.CommandTimeout(30);
});
}测试覆盖的重要性：很多开发者容易犯一个错误——只在开发环境（通常是 SQLite）跑单元测试。我们在 HagiCode 的 CI/CD 流水线中强制加入了 GitHub Action 步骤，确保每次 Pull Request 都要跑过 PostgreSQL 的集成测试。
# .github/workflows/test.yml 示例片段
- name: Run Integration Tests (PostgreSQL)
run: |
docker-compose up -d db_postgres
dotnet test --filter "Category=Integration"这帮助我们拦截了无数次关于 SQL 语法差异、大小写敏感性的 Bug。这种对测试的重视，与前端开发中强调的跨浏览器测试异曲同工。
✅ 总结：双数据库架构的核心要点
通过引入抽象层和配置驱动的依赖注入，我们在 HagiCode 项目中成功实现了 PostgreSQL 和 SQLite 的“双轨制”运行。这不仅极大降低了新开发者的上手门槛（无需安装 PG），也为生产环境提供了坚实的性能保障。回顾一下关键点：
- 抽象至上：业务代码不依赖具体数据库实现。
- 配置分离：开发和生产使用不同的
appsettings.json。 - 迁移分离：不要尝试一套 Migration 走天下。
- 特性降级：在 SQLite 中以兼容性优先，在 PostgreSQL 中以性能优先。
这种架构模式不仅适用于 HagiCode，也适用于任何需要在轻量级开发和重量级生产之间寻找平衡的 .NET 项目。
作为技术决策者，你可能会问：这样的双数据库方案是否适合所有项目？答案取决于你的具体需求。如果你的团队足够小，产品处于早期验证阶段，优先选择 SQLite 快速迭代；当用户量增长、数据复杂度提升时，再切换到 PostgreSQL 并保持代码兼容性。这种渐进式的演进策略，让技术选型不再成为业务发展的阻碍。
如果你正在寻找更高效的开发工具链，不妨关注 HagiCode 项目本身——它正是这套架构的最佳实践案例。欢迎访问我们的 GitHub 仓库 了解项目全貌，或通过 Docker Compose 一键安装 体验完整的开发流程。
[AFFILIATE_SLOT_1]在构建这类跨环境应用时，前端工具的选择同样重要。一个好的 UI 开发框架配合合理的架构设计，能显著提升全栈开发效率。
[AFFILIATE_SLOT_2]在构建现代化应用时，我们经常面临这样的抉择：开发环境渴望轻量便捷，而生产环境则需要高并发与高可用。本文将分享如何在 .NET Core 项目中优雅地同时支持 PostgreSQL 和 SQLite，实现“开发用 SQLite，生产用 PG”的最佳实践。
浙公网安备 33010602011771号