PetaPojo：Java 版輕量級 ORM 框架——從 PetaPoco 移植的實戰之作

項目背景與動機

作者從 C# 轉型 Java，習慣了 PetaPoco 的極簡體驗，調研主流方案後決定自研：

• MyBatis：XML 寫 SQL 不適應，無 DBA 團隊維護成本高。
• Hibernate：學習曲線陡峭，互聯網遊戲項目不適配。
• sql2o：輕量但體驗不如 PetaPoco。

目標：學習 Java 高級特性、掌握底層數據組件、構建團隊遷移利器。

核心功能特性

• 🪶 極致輕量，零依賴核心包
• 🎯 POJO 映射，支持註解驅動（@TableName、@PrimaryKey、@Column、@Ignore）
• 🔧 泛型 CRUD：insert/update/delete/query 一行搞定
• 📄 自動分頁：PageInfo 封裝總頁數、總記錄數、當前頁數據
• 🔐 簡易事務 支持
• 🐬 專注 MySQL，參數綁定更智能
• 🧱 SQL Builder：鏈式構建動態查詢，告別字符串拼接
• 📦 開源免費

快速上手

1. 實體映射

@TableName("user_info")
@PrimaryKey(value = "id", autoIncrement = true)
public class UserInfo {
    private int id;
    private String userName;
    @Column("password") private String password;
    @Ignore private String none; // 不映射
    // getter/setter 省略
}

2. 基礎查詢

DruidDataSource ds = new DruidDataSource(); // 配置數據源
Database db = new Database(ds);

// 查詢所有
List list = db.query(UserInfo.class, "SELECT * FROM user_info");

// 單值查詢
Integer count = db.executeScalar(Integer.class, "SELECT COUNT(1) FROM user_info");

// 首條記錄
UserInfo user = db.firstOrDefault(UserInfo.class, "SELECT * FROM user_info WHERE id = ?", 123);

3. 分頁查詢

PageInfo page = db.pagedList(UserInfo.class, 1, 10,
    "SELECT * FROM user_info WHERE age > ? ORDER BY createDate DESC", 20);

PageInfo 包含：currentPage, totalPages, totalItems, itemsPerPage, items。

4. 實體增刪改

// 新增
UserInfo u = new UserInfo();
u.setUserName("PetaPojo");
u.setPassword("123123");
db.insert(u);

// 修改
u = db.firstOrDefault(UserInfo.class, "SELECT * FROM user_info WHERE id = ?", 1);
u.setPassword("123456");
db.update(u);

// 刪除（多種方式）
db.delete(u);                    // 實體刪除
db.delete(UserInfo.class, 1);    // 主鍵刪除
db.delete(UserInfo.class, "WHERE id = ?", 1); // 條件刪除

進階特性

自動補全 SELECT 列與表名

// 原始
db.firstOrDefault(UserInfo.class, "SELECT * FROM user_info WHERE id = ?", 1);
// 簡化：自動根據實體註解推斷表名、主鍵、列名
db.firstOrDefault(UserInfo.class, "WHERE id = ?", 1);

SQL Builder 動態構建

// 基礎鏈式
Sql sql = Sql.create()
    .append("SELECT * FROM user_info")
    .append("WHERE id = ?", id)
    .append("AND createDate >= ?", DateTime.now());

// 條件化組裝
Sql sql = Sql.create().append("SELECT * FROM user_info");
if (age != null) sql.append("AND age > ?", age);
if (startDate != null) sql.append("AND createDate >= ?", startDate);

// 高級鏈式 API（配合自動補全更簡潔）
Sql sql = Sql.create()
    .where("id = ?", 1)
    .where("age >= ? AND age <= ?", 10, 20)
    .orderBy("createDate DESC");
PageInfo page = db.pagedList(UserInfo.class, 1, 10, sql);

枚舉與 Joda-Time 支持

// 枚舉實現 IEnumMessage 接口
public enum UserType implements IEnumMessage {
    Student(1, "學生"), Teacher(2, "老師"), Coder(4, "碼農");
    // 存儲為 int，讀取自動映射回枚舉
}

// 實體中直接使用
private UserType userType;
private DateTime createDate; // 需 toString() 傳參

// 查詢參數
sql.where("createDate >= ?", DateTime.now().toString());