从零上手SmartSql：高效ORM框架的配置与实战指南

SmartSql是一款基于.NET Core的ORM框架，融合了MyBatis的SQL管理思想与现代.NET技术栈特性，提供缓存管理、读写分离、动态仓库等企业级功能。作为连接应用程序与数据库的桥梁，它通过XML配置文件集中管理SQL语句，既保留了SQL的灵活性，又简化了数据访问层的开发流程，帮助开发者构建高效、可维护的数据库操作逻辑。

3步完成环境部署

准备开发环境

SmartSql的运行依赖于.NET Core生态，确保系统已安装以下组件：

• .NET Core SDK 3.1或更高版本（推荐5.0+以获得更好性能）
• 任意代码编辑器（Visual Studio 2022、VS Code或Rider）
• 数据库环境（支持SQL Server、MySQL、PostgreSQL等主流数据库）

🛠️ 小贴士：通过dotnet --version命令可验证SDK安装情况，出现版本号即表示环境就绪。

获取项目代码

打开终端工具，执行以下命令克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/smar/SmartSql

进入项目目录后，可看到完整的解决方案结构，包含核心库、扩展组件和示例代码。其中src/SmartSql目录包含框架核心代码，sample目录提供了ASP.NET Core集成示例。

配置与构建项目

1. 使用代码编辑器打开SmartSql.sln解决方案文件
2. 右键点击解决方案，选择"还原NuGet包"以安装依赖
3. 执行"生成解决方案"命令（快捷键Ctrl+Shift+B）

📌 注意事项：若构建失败，检查是否安装了正确版本的.NET SDK，或尝试清理解决方案后重新构建。

5分钟实现数据库操作

基础配置文件

SmartSql通过XML文件管理数据库连接和SQL映射，典型的配置文件结构如下：

<SmartSqlMapConfig>
  <Database>
    <DbProvider Name="SqlServer"/>
    <WriteDataSource ConnectionString="Server=.;Database=TestDB;Trusted_Connection=True"/>
  </Database>
  <SqlMaps>
    <SqlMap Path="Maps" Type="Directory"/>
  </SqlMaps>
</SmartSqlMapConfig>

在sample/SmartSql.Sample.AspNetCore项目中可找到完整配置示例，根据实际数据库类型修改DbProvider和ConnectionString节点。

编写SQL映射文件

在Maps目录下创建实体对应的XML文件（如User.xml），定义CRUD操作：

<SqlMap Scope="User">
  <Statement Id="Insert">
    INSERT INTO User (Name, Age) VALUES (@Name, @Age);
    SELECT SCOPE_IDENTITY() AS Id;
  </Statement>
  <Statement Id="GetById">
    SELECT * FROM User WHERE Id = @Id
  </Statement>
</SqlMap>

执行数据库操作

通过SqlMapper对象执行定义好的SQL语句：

// 创建SmartSql实例
var smartSql = new SmartSqlBuilder()
    .UseXmlConfig()
    .Build();

// 插入数据
var userId = smartSql.ExecuteScalar<long>(new RequestContext
{
    Scope = "User",
    SqlId = "Insert",
    Request = new { Name = "Test", Age = 20 }
});

// 查询数据
var user = smartSql.QuerySingle<User>(new RequestContext
{
    Scope = "User",
    SqlId = "GetById",
    Request = new { Id = userId }
});

📚 官方文档：doc/SmartSqlMapConfig.xml包含完整配置说明，src/SmartSql/ISqlMapper.cs提供API详细定义。

高级功能应用

缓存策略配置

SmartSql支持内存缓存和Redis缓存，在SQL映射中添加缓存配置：

<Statement Id="GetById" Cache="True" CacheKey="User:Id:@Id" CacheExpire="3600">
  SELECT * FROM User WHERE Id = @Id
</Statement>

通过修改配置文件中的Cache节点，可切换不同的缓存提供器，满足不同场景的性能需求。

动态SQL编写

利用SmartSql的标签系统构建动态SQL：

<Statement Id="Query">
  SELECT * FROM User
  <Where>
    <IsNotEmpty Property="Name">AND Name LIKE CONCAT('%',@Name,'%')</IsNotEmpty>
    <IsGreaterThan Property="Age">AND Age > @Age</IsGreaterThan>
  </Where>
</Statement>

动态标签系统支持条件判断、循环等逻辑，减少拼接SQL字符串的工作。

读写分离实现

在配置文件中添加只读数据源，自动实现读写分离：

<ReadDataSources>
  <ReadDataSource ConnectionString="Server=slave1;Database=TestDB;Trusted_Connection=True"/>
  <ReadDataSource ConnectionString="Server=slave2;Database=TestDB;Trusted_Connection=True"/>
</ReadDataSources>

框架会自动将查询操作路由到只读数据源，写操作使用主数据源，提升系统整体吞吐量。

项目结构解析

SmartSql采用模块化设计，主要包含以下核心组件：

• SmartSql：框架核心，包含SQL解析、执行和结果映射
• SmartSql.DyRepository：动态仓库实现，通过接口自动生成数据访问代码
• SmartSql.Cache.Redis：Redis缓存实现
• SmartSql.Bulk：批量操作组件，支持多种数据库的批量插入
• SmartSql.TypeHandler：类型转换器，处理特殊数据类型映射

示例项目SmartSql.Sample.AspNetCore展示了如何在Web应用中集成SmartSql，包含控制器、服务层和仓储层的完整实现，可作为实际项目开发的参考模板。

🛠️ 常见问题：若遇到SQL映射文件不生效，检查文件属性是否设置为"始终复制"；数据库连接失败时，优先验证连接字符串格式和数据库服务状态。

通过本文介绍的步骤，你已经掌握了SmartSql的基本使用方法。这个轻量级ORM框架既能满足简单的CRUD需求，又能应对复杂的企业级应用场景，是.NET生态中值得尝试的数据访问解决方案。更多高级特性和最佳实践，请参考项目中的测试用例和示例代码。