spring-mysqlclient 開源發布：基於多年實踐的輕量級 MySQL 訪問庫，支援動態 SQL、分頁、讀寫分離

spring-mysqlclient 開源發布：基於多年實踐的輕量級 MySQL 訪問庫，支援動態 SQL、分頁、讀寫分離

經過多年生產環境打磨，spring-mysqlclient 正式開源發布。這是一個專注於 MySQL 場景的輕量級數據訪問庫，在 Spring 生態中提供比 MyBatis 更簡潔、比 JdbcTemplate 更強大的體驗，核心特性包括動態 SQL 模板、自動分頁、讀寫分離路由、類型安全構建器等。

一、項目地址與文檔

• GitHub 倉庫：https://github.com/risedragon/spring-mysqlclient
• 用戶指南 Wiki：spring-mysqlclient-user-guide
• Maven 坐標：io.github.risedragon:spring-mysqlclient:1.0.0 (假設)

二、核心設計理念

三、核心功能特性

1. 動態 SQL 模板引擎 (類 Velocity/Freemarker 語法)

@Repository
public interface UserRepository extends MysqlClientRepository<User, Long> {
    
    // 方法名解析 + 註解 SQL 模板
    @Select("""
        SELECT * FROM `user` 
        WHERE 1=1
        #if(:name) AND `name` LIKE CONCAT('%', :name, '%') #end
        #if(:status) AND `status` = :status #end
        ORDER BY `create_time` DESC
        """)
    Page<User> findByCondition(@Param("name") String name, 
                                @Param("status") Integer status, 
                                Pageable pageable);
}

• #if(...)、#else、#foreach、#include 完整控制流
• 參數自動綁定，防止 SQL 注入
• 支持嵌套模板複用

2. 類型安全查詢構建器 (Criteria API 風格)

List<User> users = mysqlClient.selectFrom(User.class)
    .where(User::getName, like("%張%"))
    .and(User::getStatus, eq(1))
    .or(User::getEmail, isNotNull())
    .orderByDesc(User::getCreateTime)
    .limit(10)
    .fetch();

• 方法引用 User::getName 映射列名，重構安全
• 豐富操作符：eq/ne/gt/lt/ge/le/like/in/between/isNull
• 支持子查詢、Join、Union

3. 自動分頁 (物理分頁 + Count 查詢優化)

// 只需傳入 Pageable，自動拼接 LIMIT/OFFSET 並執行 COUNT
Page<User> page = repository.findByCondition("張", 1, PageRequest.of(0, 20));

// 高性能優化：COUNT 查詢自動去除 ORDER BY、JOIN、SELECT 列
// 原查詢：SELECT * FROM user WHERE ... ORDER BY create_time DESC
// Count 查詢：SELECT COUNT(1) FROM user WHERE ...

4. 讀寫分離路由 (基於註解/方法名/事務特性)

@Configuration
public class DataSourceConfig {
    @Bean
    @Primary
    @ConfigurationProperties("spring.mysqlclient.master")
    DataSource masterDataSource() { return DataSourceBuilder.create().build(); }

    @Bean
    @ConfigurationProperties("spring.mysqlclient.slave")
    DataSource slaveDataSource() { return DataSourceBuilder.create().build(); }
}

// 使用
@Transactional(readOnly = true)  // 自動路由到 Slave
public List<User> findAll() { ... }

@ReadOnly  // 顯式註解路由 Slave
public User getById(Long id) { ... }

@WriteRouting  // 強制路由 Master
public void insertBatch(List<User> users) { ... }

5. 批量操作與 Upsert (ON DUPLICATE KEY UPDATE)

// 批量插入 (自動分批、參數佔位符優化)
mysqlClient.batchInsert(users, 1000);  // 每批 1000 條

// Upsert：主鍵/唯一鍵衝突時更新
mysqlClient.upsert(user)
    .onDuplicateKeyUpdate(User::getName, User::getEmail)
    .execute();

6. JSON 字段原生支援 (MySQL 5.7+)

@Table("order")
class Order {
    @Id Long id;
    @Column("ext_info")  // JSON 類型列
    JSONObject extInfo;  // 自動序列化/反序列化
}

// 查詢 JSON 字段
List<Order> orders = mysqlClient.selectFrom(Order.class)
    .whereJsonContains("ext_info", "$.tags", "促銷")
    .fetch();

四、快速開始

<!-- Spring Boot 2.7+ / 3.x -->
<dependency>
    <groupId>io.github.risedragon</groupId>
    <artifactId>spring-mysqlclient-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

spring:
  mysqlclient:
    master:
      url: jdbc:mysql://master:3306/mydb?useUnicode=true&characterEncoding=utf8
      username: root
      password: 123456
    slave:
      url: jdbc:mysql://slave1:3306/mydb,slave2:3306/mydb
      username: reader
      password: 123456
    # 分頁默認配置
    page:
      default-size: 20
      max-size: 100

五、與主流方案對比

六、適用場景與不適用場景

七、路線圖與社區

• v1.1：分布式事務支援 (Seata 整合)、查詢緩存註解
• v1.2：向量檢索支援 (MySQL 8.0+ 向量索引)、全文檢索整合
• v2.0：Reactive 非阻塞 API (R2DBC)、GraalVM Native 編譯優化
• 歡迎提交 Issue、PR、Star 支持：GitHub Repository

「不造輪子，只磨利刃。」spring-mysqlclient 致力於成為 MySQL 專屬場景下最銳利的數據訪問利器。