SmartSql完全指南：从环境搭建到实战应用

SmartSql 是一款轻量级ORM框架，它将MyBatis的XML配置思想与.NET Core的现代特性完美结合，提供高效数据访问解决方案。作为对象关系映射技术（ORM：将对象模型与关系数据库表结构相互映射的技术）的创新实现，SmartSql以其独特的设计理念，在保持性能优势的同时大幅提升开发效率，成为.NET生态中备受关注的数据访问框架。

项目概览：重新定义数据访问体验

SmartSql的核心优势体现在三个维度，构建了一个既灵活又高效的数据访问层解决方案：

1. 配置驱动的SQL管理模式

不同于传统硬编码SQL的方式，SmartSql采用XML文件集中管理所有SQL语句，实现了业务逻辑与数据访问代码的彻底分离。这种设计不仅使SQL语句的修改无需重新编译程序，还提供了统一的SQL版本控制和优化入口，极大提升了大型项目的可维护性。

2. 多层次缓存架构

框架内置了二级缓存机制：一级内存缓存针对高频查询提供毫秒级响应，二级Redis缓存支持分布式场景下的数据共享。通过智能缓存策略，SmartSql能自动处理缓存失效问题，在保证数据一致性的前提下，将数据库访问压力降低60%以上。

3. 动态仓库技术

创新性地提出动态仓库概念，开发者只需定义接口即可自动生成数据访问实现，消除了80%的重复代码。配合基于AOP的事务管理和读写分离支持，SmartSql为企业级应用提供了完整的数据访问解决方案。

环境准备：跨平台开发环境搭建

SmartSql基于.NET Core构建，实现了全平台支持，无论你使用Windows、macOS还是Linux系统，都能获得一致的开发体验。

系统兼容性说明

操作系统	最低版本要求	推荐配置
Windows	Windows 10 1809+	Windows 11 + .NET 7.0
macOS	macOS 10.15+	macOS Monterey + .NET 7.0
Linux	Ubuntu 18.04+	Ubuntu 20.04 + .NET 7.0

核心依赖安装

💡 环境检查提示：安装前请先通过dotnet --version命令确认.NET SDK已正确安装，推荐使用.NET 6.0或更高版本以获得最佳性能。

1. .NET SDK安装

   • Windows：从微软官网下载安装程序，勾选"添加到PATH"选项
   • macOS：使用brew install dotnet-sdk命令安装
   • Linux：通过包管理器安装或手动下载二进制包

2. 开发工具准备

   • Visual Studio 2022（Windows）
   • Visual Studio Code + C#扩展（跨平台）
   • Rider（跨平台）

获取与配置：两种安装方式对比

SmartSql提供多种集成方式，可根据项目需求选择最适合的方案：

方式一：NuGet包管理器安装（推荐）

这种方式适合大多数开发场景，通过NuGet获取预编译的二进制包，实现快速集成。

# 核心包安装
dotnet add package SmartSql

# 按需安装扩展包
dotnet add package SmartSql.DyRepository  # 动态仓库支持
dotnet add package SmartSql.Cache.Redis   # Redis缓存支持
dotnet add package SmartSql.Bulk.SqlServer # SQL Server批量操作

方式二：源码编译安装

适合需要定制框架或贡献代码的场景，从源码构建最新版本。

# 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/smar/SmartSql

# 进入项目目录
cd SmartSql

# 构建解决方案
dotnet build SmartSql.sln -c Release

安装方式对比

安装方式	优点	缺点	适用场景
NuGet安装	简单快捷，版本管理清晰	无法定制框架源码	大多数企业应用开发
源码编译	可定制化，获取最新特性	构建过程复杂，需解决依赖	框架二次开发，贡献代码

💡 配置提示：无论采用哪种安装方式，都需要在项目根目录创建SmartSqlMapConfig.xml配置文件，指定数据库连接字符串和SQL映射文件路径。

核心功能示例：用户数据CRUD操作实现

下面通过一个完整的"用户管理"场景，展示SmartSql的核心功能如何协同工作：

1. 定义实体模型

using SmartSql.Annotations;

[Table("T_User")] // 映射到数据库表T_User
public class User
{
    [Column(IsPrimaryKey = true)]
    public long Id { get; set; }
    
    [Column("UserName")] // 映射到表中UserName字段
    public string Name { get; set; }
    
    public int Age { get; set; }
    
    public DateTime CreateTime { get; set; }
    
    [NotMapped] // 该属性不映射到数据库
    public string ExtraInfo { get; set; }
}

2. 创建SQL映射文件

在项目中创建Maps/User.xml文件，定义CRUD操作的SQL语句：

<?xml version="1.0" encoding="utf-8" ?>
<SmartSqlMap Scope="User">
  <!-- 查询单个用户 -->
  <Statement Id="GetById">
    SELECT * FROM T_User WHERE Id = @Id
  </Statement>
  
  <!-- 分页查询用户列表 -->
  <Statement Id="QueryByPage">
    SELECT * FROM T_User
    <Where>
      <IsNotEmpty Prepend="AND" Property="Name">
        Name LIKE CONCAT('%',@Name,'%')
      </IsNotEmpty>
      <IsGreaterThan Prepend="AND" Property="Age" Value="0">
        Age > @Age
      </IsGreaterThan>
    </Where>
    ORDER BY CreateTime DESC
    LIMIT @Offset,@Size
  </Statement>
  
  <!-- 插入用户 -->
  <Statement Id="Insert">
    INSERT INTO T_User (UserName,Age,CreateTime)
    VALUES (@Name,@Age,@CreateTime);
    SELECT LAST_INSERT_ID();
  </Statement>
  
  <!-- 更新用户 -->
  <Statement Id="Update">
    UPDATE T_User
    <Set>
      <IsNotEmpty Property="Name">UserName=@Name,</IsNotEmpty>
      <IsGreaterThan Property="Age" Value="0">Age=@Age,</IsGreaterThan>
    </Set>
    WHERE Id=@Id
  </Statement>
  
  <!-- 删除用户 -->
  <Statement Id="DeleteById">
    DELETE FROM T_User WHERE Id=@Id
  </Statement>
</SmartSqlMap>

3. 定义动态仓库接口

using SmartSql.DyRepository;
using System.Collections.Generic;
using System.Threading.Tasks;

public interface IUserRepository : IRepository<User, long>
{
    // 继承IRepository获得基础CRUD方法
    
    // 自定义分页查询方法
    [Statement(Scope = "User", SqlId = "QueryByPage")]
    IEnumerable<User> QueryByPage(dynamic param);
    
    // 异步查询方法
    [Statement(Scope = "User", SqlId = "GetById")]
    Task<User> GetByIdAsync(long id);
}

4. 服务集成与使用

using Microsoft.Extensions.DependencyInjection;
using SmartSql;
using SmartSql.DIExtension;

// 1. 配置依赖注入
var services = new ServiceCollection();
services.AddSmartSql(options =>
{
    options.UseXmlConfig(); // 使用XML配置文件
});
services.AddRepositoryFactory(); // 注册动态仓库工厂
services.AddRepository<IUserRepository>(); // 注册用户仓库

// 2. 获取服务实例
using var serviceProvider = services.BuildServiceProvider();
var userRepository = serviceProvider.GetService<IUserRepository>();

// 3. 执行数据操作
var newUser = new User 
{ 
    Name = "SmartSql", 
    Age = 3, 
    CreateTime = DateTime.Now 
};

// 插入用户
var userId = userRepository.Insert(newUser);

// 查询用户
var user = userRepository.GetById(userId);

// 更新用户
user.Age = 4;
userRepository.Update(user);

// 分页查询
var users = userRepository.QueryByPage(new { Name = "Sql", Age = 1, Offset = 0, Size = 10 });

// 删除用户
userRepository.DeleteById(userId);

常见问题：错误排查与最佳实践

常见错误排查

1. 配置文件找不到异常

   • 检查SmartSqlMapConfig.xml是否设置为"始终复制"
   • 确认配置文件中SqlMapPath路径是否正确

2. SQL语句执行错误

   • 启用诊断日志：在配置文件中设置<Settings EnableDiagnostic="true" />
   • 检查参数名称与SQL中的占位符是否一致

3. 动态仓库接口无法解析

   • 确保接口使用[Statement]特性正确标记
   • 检查接口方法参数是否与SQL语句参数匹配

性能优化建议

1. 缓存策略：对查询频繁且更新较少的数据启用缓存

   <Statement Id="GetById" Cache="True" CacheTimeout="3600">
     SELECT * FROM T_User WHERE Id = @Id
   </Statement>
   

2. 批量操作：使用Bulk扩展处理大量数据插入

   var users = new List<User>();
   // 添加用户数据...
   sqlMapper.BulkInsert(users);
   

3. 读写分离：在配置文件中设置主从数据源

   <Database>
     <Write Name="WriteDB" ConnectionString="..." />
     <Reads>
       <Read Name="ReadDB1" ConnectionString="..." Weight="100" />
       <Read Name="ReadDB2" ConnectionString="..." Weight="200" />
     </Reads>
   </Database>
   

官方资源与社区支持

• 官方文档：docs/quickstart.md
• 示例项目：sample/SmartSql.Sample.AspNetCore/
• 单元测试：src/SmartSql.Test.Unit/

下一步学习路径

掌握基础使用后，可深入学习以下高级特性：

1. 动态SQL高级技巧：掌握<For>、<Switch>等标签实现复杂条件查询
2. 自定义类型处理器：实现特殊数据类型与数据库字段的映射
3. 分布式事务：结合消息队列实现最终一致性事务
4. 性能监控：集成Application Insights进行性能分析

SmartSql通过灵活的配置和强大的扩展能力，为.NET开发者提供了一个既简单又强大的数据访问解决方案。无论是小型项目还是大型企业应用，都能从中获益。现在就开始你的SmartSql之旅，体验高效数据访问的乐趣！