介紹

Insql 是一個輕量級的.NET ORM類庫 . 對象映射基於Dapper , Sql配置靈感來自於Mybatis。簡單優雅是TA的追求。

github | gitee

閑聊

以下可跳過 : )

• 自己為什麽會開發Insql?

1. 最初的自己一樣是從寫最基本的Sql代碼來訪問數據庫
   進而我們發現查詢出的數據與保存的數據通常都是實體對象，而還需要跨不同類型數據庫的需要。
2. 這時ORM就成為了我們的工具。在使用ORM和Linq的出現讓我迫切希望找到一款好用的支持Linq的ORM框架。這個過程中使用了微軟的EntityFramework，還有各種同僚自己開發的ORM，有很多不錯的作品。自己也用了很多。當然在這裏面我的評判標準就是性能優先，無需中間緩存層。操作能以最直接的方式直達數據庫。在Linq的支持上當然也需要豐富些。
3. 我以為這就是我的歸宿，可是Linq只能解決不同類型數據庫的共性問題，有些ORM很難做到充分利用各個數據庫的特性，例如獨特的類型和獨特的方法。當然不要告訴我自己遇到那種問題時再寫原生SQL.我盡可能希望我使用工具時簡單統一，不要有負擔存在。
4. 直到我開發Java項目時，遇到了Mybatis。可以說真的很好用。它以XML配置SQL的方式，自己可以自由靈活的寫語句，當然數據庫的獨有方法特性都能使用。但是在dotnet core上我沒有找到類似好用的組件。於是就有了Insql。

• 如何設計Insql?
  整體功能架構就以下兩塊

1. 語句解析
   首先先加載xxx.insql.xml配置，加載方式支持擴展，目前實現以程序集嵌入式文件方式加載。
   
   解析各種配置節點元素，最終生成可直接執行的sql語句和sql參數。
2. 對象映射
   在保存和查詢時都需要實體對象的參與，這裏對象映射就提供類這個功能。目前也有很多對象映射類庫，我們這裏直接使用Dapper。輪子就不重復造了。

正題

安裝

如何使用

Add Insql

public void ConfigureServices(IServiceCollection services)
{
    services.AddInsql();

    services.AddInsqlDbContext<UserDbContext>(options =>
    {
        options.UseSqlite(this.Configuration.GetConnectionString("sqlite"));
    });
}

Create DbContext

public class UserDbContext : Insql.DbContext  
{
    public UserDbContext(Insql.DbContextOptions<UserDbContext> options) 
        : base(options)
    {
    }

    public IEnumerable<UserInfo> GetUserList(string userName)
    {
        //sqlId = "GetUserList"
        //sqlParam is PlainObject or IDictionary<string,object>
        return this.Query<UserInfo>(nameof(GetUserList), new { userName, userGender = Gender.W });
    }

    public void InsertUser(UserInfo info)
    {
        var userId = this.ExecuteScalar<int>(nameof(InsertUser),info);

        info.UserId = userId;
    }

    public void UpdateUserSelective(UserInfo info)
    {
        this.Execute(nameof(UpdateUserSelective), info);
    }
}

//user model
public class UserInfo
{
    public int UserId { get; set; }

    public string UserName { get; set; }

    public Gender? UserGender { get; set; }
}

public enum Gender
{
    M,
    W
}

Create DbContext.insql.xml

創建 UserDbContext.insql.xml 文件並且修改這個文件的屬性為嵌入式文件類型 . insql type 與 UserDbContext 類型對應.

<insql type="Example.Domain.Contexts.UserDbContext,Example.Domain" >

  <sql id="selectUserColumns">
    select user_id as UserId,user_name as UserName,user_gender as UserGender from user_info
  </sql>

  <select id="GetUserList">
    <include refid="selectUserColumns" />
    <where>
      <if test="userName != null">
        <bind name="likeUserName" value="'%' + userName + '%'" />
        user_name like @likeUserName
      </if>
      <if test="userGender != null and userGender != 'M' ">
        and user_gender = @userGender
      </if>
    </where>
    order by  user_id
  </select>

  <insert id="InsertUser">
    insert into user_info (user_name,user_gender) values (@UserName,@UserGender);
    select last_insert_rowid() from user_info;
  </insert>
  <update id="UpdateUser">
    update user_info set user_name=@UserName,user_gender=@UserGender where user_id = @userId
  </update>

  <update id="UpdateUserSelective">
    update user_info
    <set>
      <if test="UserName != null">
        user_name=@UserName,
      </if>
      <if test="UserGender != null">
        user_gender=@UserGender
      </if>
    </set>
    where user_id = @UserId
  </update>

</insql>

Use DbContext

public class ValuesController : ControllerBase
{
    private readonly UserDbContext userDbContext;

    public ValuesController(UserDbContext userDbContext)
    {
        this.userDbContext = userDbContext;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //可以這樣簡單的使用事務
        this.userDbContext.DoWithTransaction(() =>
        {
            this.userDbContext.InsertUser(new Domain.UserInfo
            {
                UserName = "loveW",
                UserGender = Domain.Gender.M
            });

            this.userDbContext.UpdateUserSelective(new Domain.UserInfo
            {
                UserId = 1,
                UserName = "loveWWW",
            });
        });

        var list = this.userDbContext.GetUserList("love");
    }
}

其他用法

Create Common DbContext

public class SqliteDbContext<T> : DbContext where T : class
{
    public SqliteDbContext(DbContextOptions<SqliteDbContext<T>> options) : base(options)
    {
    }

    protected override void OnConfiguring(DbContextOptions options)
    {
        var configuration = options.ServiceProvider.GetRequiredService<IConfiguration>();

        //T type mapping to insql.xml type
        options.UseSqlResolver<T>();

        options.UseSqlite(configuration.GetConnectionString("sqlite"));
    }
}

Create Domain Service

public interface IUserService
{
    IEnumerable<UserInfo> GetUserList(string userName,Gender? userGender);
}

public class UserService : IUserService
{
    private readonly DbContext dbContext;

    //T is UserService
    public UserService(SqliteDbContext<UserService> dbContext)
    {
        this.dbContext = dbContext;
    }

    public IEnumerable<UserInfo> GetUserList(string userName, Gender? userGender)
    {
        return this.dbContext.Query<UserInfo>(nameof(GetUserList), new { userName, userGender });
    }
}

Create Service.insql.xml

創建 UserService.insql.xml 文件並且修改這個文件的屬性為嵌入式文件類型 . insql type 與 UserService 類型對應.

<insql type="Example.Domain.Services.UserService,Example.Domain" >

  <sql id="selectUserColumns">
    select user_id as UserId,user_name as UserName,user_gender as UserGender from user_info
  </sql>

  <select id="GetUserList">
    <include refid="selectUserColumns" />
    <where>
      <if test="userName != null">
        <bind name="likeUserName" value="'%' + userName + '%'" />
        user_name like @likeUserName
      </if>
      <if test="userGender != null ">
        and user_gender = @userGender
      </if>
    </where>
    order by  user_id
  </select>

</insql>

Add Insql

public void ConfigureServices(IServiceCollection services)
{
    services.AddInsql();

    services.AddScoped(typeof(DbContextOptions<>));
    services.AddScoped(typeof(SqliteDbContext<>));

    services.AddScoped<IUserService, UserService>();
}

Use Domain Service

public class ValuesController : ControllerBase
{
    private readonly IUserService userService;

    public ValuesController(IUserService userService)
    {
        this.userService = userService;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        var list = this.userService.GetUserList("11", Domain.Gender.M);
    }
}

@謝謝大家支持！

[開源] .NET數據庫ORM類庫 Insql