SmartSql：.NET开发的轻量级ORM框架全攻略

SmartSql是一款灵感源自MyBatis的.NET轻量级ORM框架，它通过XML配置管理SQL语句，集成了内存/Redis缓存、读写分离、动态仓库等实用功能，为开发者提供了高效、灵活的数据访问解决方案。本文将从核心优势、环境准备、多方式安装到快速上手，全方位带你掌握这个强大工具。

🌟 SmartSql核心优势解析

高效开发体验

• XML配置SQL：将SQL与业务代码分离，便于维护和优化
• 动态仓库：无需编写实现类，接口定义即可完成数据访问
• 智能缓存：内置多级缓存机制，大幅提升查询性能

企业级特性

• 读写分离：轻松实现数据库负载均衡
• 事务支持：完善的事务管理机制保证数据一致性
• 诊断功能：详细的执行日志和性能指标监控

灵活扩展能力

• 多数据库支持：适配SQL Server、MySQL、PostgreSQL等主流数据库
• 自定义类型处理器：轻松处理复杂数据类型转换
• 中间件架构：可按需扩展功能模块

🛠️ 零基础环境准备指南

系统要求

组件	最低版本	推荐版本
.NET Core SDK	3.1	6.0+
Visual Studio	2019	2022
数据库	任意主流关系型数据库	MySQL 8.0+/SQL Server 2019+

环境检查脚本

# 检查.NET SDK版本
dotnet --version

# 检查Visual Studio版本(Windows)
reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\SxS\VS7" /v 17.0

# 检查数据库连接(以MySQL为例)
mysql --version

💡 小贴士：执行环境检查脚本后，请确保所有组件版本均满足最低要求，特别是.NET SDK版本，过低可能导致项目无法构建。

📦 多方式安装对比

方式一：源码编译安装

# 克隆项目
git clone https://gitcode.com/gh_mirrors/smar/SmartSql

# 进入项目目录
cd SmartSql

# 还原依赖并构建
dotnet restore
dotnet build -c Release

方式二：NuGet包安装

# 安装核心包
dotnet add package SmartSql

# 安装缓存扩展(可选)
dotnet add package SmartSql.Cache.Redis

# 安装动态仓库(可选)
dotnet add package SmartSql.DyRepository

安装方式对比

安装方式	优点	缺点	适用场景
源码编译	可修改源码，最新特性	编译耗时，步骤多	贡献者，高级用户
NuGet包	简单快捷，版本可控	无法修改源码	普通开发者，生产环境

📌 注意事项：如果选择源码编译方式，请确保你的开发环境已安装.NET SDK和相关构建工具。

🚀 快速上手实战

1. 基础配置

创建SmartSqlMapConfig.xml配置文件：

<?xml version="1.0" encoding="utf-8" ?>
<SmartSqlMapConfig xmlns="http://SmartSql.net/schemas/SmartSqlMapConfig.xsd">
  <Settings IgnoreParameterCase="true"/>
  <Database>
    <DbProvider Name="MySql"/>
    <WriteDataSource ConnectionString="server=localhost;database=test;uid=root;pwd=123456;"/>
  </Database>
  <SqlMaps>
    <SqlMap Path="Maps" Type="Directory"/>
  </SqlMaps>
</SmartSqlMapConfig>

2. 定义数据模型

public class User
{
    public long Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public DateTime CreateTime { get; set; }
}

3. 创建SQL映射文件

在项目中创建Maps/User.xml文件：

<?xml version="1.0" encoding="utf-8" ?>
<SmartSqlMap Scope="User" xmlns="http://SmartSql.net/schemas/SmartSqlMap.xsd">
  <Statements>
    <Statement Id="Insert">
      INSERT INTO User 
      (Name, Age, CreateTime) 
      VALUES 
      (@Name, @Age, @CreateTime);
      SELECT LAST_INSERT_ID();
    </Statement>
    
    <Statement Id="GetById">
      SELECT * FROM User WHERE Id = @Id
    </Statement>
    
    <Statement Id="Update">
      UPDATE User 
      SET Name = @Name, Age = @Age 
      WHERE Id = @Id
    </Statement>
    
    <Statement Id="Delete">
      DELETE FROM User WHERE Id = @Id
    </Statement>
  </Statements>
</SmartSqlMap>

4. 数据访问实现

using SmartSql;
using SmartSql.DyRepository;

// 定义仓储接口
public interface IUserRepository : IRepository<User, long>
{
    // 继承IRepository获得基础CRUD方法
}

// 使用SmartSql
class Program
{
    static void Main(string[] args)
    {
        // 初始化SmartSql
        var sqlMapper = new SmartSqlBuilder()
            .UseXmlConfig()
            .Build().SqlMapper;
            
        // 获取仓储实例
        var userRepository = sqlMapper.GetRepository<IUserRepository>();
        
        // 新增用户
        var newUser = new User 
        { 
            Name = "张三", 
            Age = 25, 
            CreateTime = DateTime.Now 
        };
        var userId = userRepository.Insert(newUser);
        
        // 查询用户
        var user = userRepository.GetById(userId);
        Console.WriteLine($"用户: {user.Name}, 年龄: {user.Age}");
        
        // 更新用户
        user.Age = 26;
        userRepository.Update(user);
        
        // 删除用户
        userRepository.Delete(userId);
    }
}

⚡ 性能优化技巧

缓存策略

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

批量操作

// 批量插入
var users = new List<User>
{
    new User { Name = "用户1", Age = 20 },
    new User { Name = "用户2", Age = 22 }
};
sqlMapper.Execute(new RequestContext
{
    Scope = "User",
    SqlId = "BatchInsert",
    Request = new { Users = users }
});

读写分离配置

<Database>
  <DbProvider Name="MySql"/>
  <WriteDataSource ConnectionString="server=master;database=test;uid=root;pwd=123456;"/>
  <ReadDataSources>
    <ReadDataSource ConnectionString="server=slave1;database=test;uid=root;pwd=123456; Weight="10"/>
    <ReadDataSource ConnectionString="server=slave2;database=test;uid=root;pwd=123456; Weight="20"/>
  </ReadDataSources>
</Database>

🔍 常见问题排查

配置文件找不到

graph TD
    A[错误：配置文件找不到] --> B{检查配置文件路径}
    B -->|路径正确| C[检查文件属性]
    B -->|路径错误| D[修正路径]
    C -->|复制到输出目录| E[设置"始终复制"]
    C -->|已设置| F[检查文件名拼写]

数据库连接失败

graph TD
    A[错误：数据库连接失败] --> B{检查连接字符串}
    B -->|正确| C[检查数据库服务状态]
    B -->|错误| D[修正连接字符串]
    C -->|运行中| E[检查网络权限]
    C -->|未运行| F[启动数据库服务]

📚 官方资源速查表

• 核心文档：doc/SmartSqlConfig.nuspec
• 配置示例：sample/SmartSql.Sample.AspNetCore/SmartSqlMapConfig.xml
• 测试用例：src/SmartSql.Test/
• API参考：src/SmartSql/ISqlMapper.cs

💡 小贴士：遇到问题时，建议先查看测试用例中的相关实现，大部分常见场景都有对应的示例代码。

通过本文的介绍，相信你已经对SmartSql有了全面的了解。这个轻量级ORM框架不仅提供了高效的数据访问能力，还通过灵活的配置和丰富的特性，让.NET开发变得更加简单高效。无论是小型项目还是大型企业应用，SmartSql都能成为你得力的开发助手。现在就开始尝试，体验它带来的开发乐趣吧！