Bỏ qua

Ma trận tính năng

Bảng tổng hợp chi tiết mức độ hỗ trợ các tính năng trong LarkBatis: Đã hỗ trợ đầy đủ kèm test kiểm thử; Thu hẹp phạm vi theo quy tắc an toàn; Chủ động loại bỏ (báo lỗi compile kèm giải pháp thay thế).

Phiên bản hiện tại: 0.1.0.

Khai báo Statement

Tính năng Trạng thái Ghi chú kỹ thuật
@Select, @Insert, @Update, @Delete Chấp nhận mảng String[], tự động nối với nhau bằng dấu cách
<select>, <insert>, <update>, <delete> trong mapper XML Namespace là FQN của interface, id khớp với tên phương thức. Xem Mapper XML
Kết hợp cả annotation và XML trong cùng một mapper Xử lý độc lập theo từng phương thức (báo lỗi compile nếu trùng lặp hoặc thiếu định nghĩa)
Tham số liên kết #{} Xác định kiểu dữ liệu tĩnh từ tham số phương thức lúc biên dịch
Chèn chuỗi động ${} Chỉ chấp nhận SqlFragment, enum/primitive, hoặc @OrderBy. Xem Raw SQL & An toàn
@Param Đặt tên tham số tường minh cho câu lệnh SQL
@Options(useGeneratedKeys, keyProperty, keyColumn) Tự động gán khóa chính tự tăng sau khi insert. Xem Generated Keys
<selectKey> Thay thế bằng hai câu truy vấn độc lập để kiểm soát transaction rõ ràng
Provider annotations (@SelectProvider, v.v.) Chuỗi SQL dựng động qua reflection lúc runtime không thể phân tích trước lúc build
Tham số kiểu Map hoặc Object không định kiểu Cần định nghĩa parameter class rõ ràng hoặc gắn @Param cho từng tham số
RowBounds Phân trang trên bộ nhớ (in-memory) gây lãng phí RAM. Nên dùng LIMIT/OFFSET trực tiếp trong SQL

SQL Động (Dynamic SQL)

Tính năng Trạng thái Ghi chú kỹ thuật
<if> Biên dịch thành biến boolean cục bộ, đánh giá điều kiện một lần duy nhất
<choose>, <when>, <otherwise> Biên dịch thành khối lệnh if-else trong mã Java thuần
<where>, <set> Constant-fold lúc biên dịch, không quét chuỗi regex lúc runtime
<trim> Chỉ hỗ trợ chuỗi tiền tố/hậu tố cố định
<sql>, <include> refid phải cố định, được inline trực tiếp lúc biên dịch
<foreach> Ném exception nếu collection rỗng. Xem foreach & Batching
@PadPow2 Giới hạn số lượng biến thể prepared statement trong mệnh đề IN
<bind> Nên tính toán biến trong mã Java trước khi truyền vào mapper
Biểu thức OGNL phức tạp trong test Thay thế bằng ngữ pháp biểu thức an toàn
databaseId Nên tách riêng từng interface mapper cho mỗi loại database vendor

Ánh xạ kết quả (Result Mapping)

Tính năng Trạng thái Ghi chú kỹ thuật
Ánh xạ resultType theo quy ước Tự động chuyển đổi snake_case sang camelCase lúc biên dịch
Đọc dòng theo chỉ số vị trí cột Tối ưu khi câu SELECT liệt kê tên cột rõ ràng
Fallback đọc theo tên cột Sử dụng khi câu truy vấn là SELECT * (phân giải index một lần qua ResultSetMetaData)
Kết quả kiểu vô hướng (Scalar) Đọc trực tiếp kiểu nguyên thủy / wrapper từ cột đầu tiên
Trả về List<T> Đọc danh sách bản ghi tuần tự
Trả về Stream<T> Stream kết nối con trỏ database, caller chịu trách nhiệm đóng stream. Xem Streaming
<resultMap> Ánh xạ tường minh các cột được định nghĩa, không tự động auto-mapping
<association>, <collection> Hỗ trợ 1 cấp join, yêu cầu câu truy vấn ORDER BY theo khóa của bảng cha
Lồng select="..." trong result map Tránh phát sinh lỗi N+1 truy vấn; nên viết câu JOIN tường minh
<discriminator> Kiểu class kết quả phải cố định từ lúc biên dịch
<constructor> mapping POJO kết quả yêu cầu constructor không tham số và setter
extends, columnPrefix, autoMapping Khai báo tường minh tất cả ánh xạ cần thiết
Lazy loading Tránh tạo bytecode proxy bọc quanh đối tượng kết quả
Type alias Sử dụng tên class đầy đủ (FQN)

Kiểu dữ liệu & Type Handlers

Tính năng Trạng thái Ghi chú kỹ thuật
Kiểu nguyên thủy và wrapper Sử dụng JdbcCodec để xử lý null an toàn
String, BigDecimal, BigInteger, byte[] Đọc/ghi trực tiếp qua JDBC
java.sql.Date, Time, Timestamp Đọc/ghi trực tiếp qua JDBC
Instant, LocalDate, LocalTime, LocalDateTime Hỗ trợ toàn diện API java.time chuẩn
Enum (theo name()) Kiểu tập đóng an toàn, được phép dùng trong ${}
@Column Đặt tên cột thủ công trên field hoặc getter/setter. Xem Annotations
Custom TypeHandler với @Handler Gắn trên field, param hoặc trong XML. Xem Kiểu dữ liệu
<typeHandlers> cấp toàn cục Cấu hình qua compiler option -Alarkbatis.typeHandlers. Xem Cấu hình
Quét tự động TypeHandler (<package>) Không quét classpath lúc runtime; cần khai báo tường minh lúc biên dịch

Session & Quản lý Transaction

Tính năng Trạng thái Ghi chú kỹ thuật
Scope LarkBatisTx, cơ chế vote-to-commit Hỗ trợ lồng scope transaction độc lập. Xem Transactions
Spring @Transactional Tích hợp trực tiếp qua DataSourceUtils
Dịch mã lỗi Spring Tự động chuyển đổi sang cây exception DataAccessException
Spring Boot Starter Tương thích cả Spring Boot 3 và Spring Boot 4 trong cùng một jar
Sinh @Configuration tự động Thiết lập proxyBeanMethods = false để tránh CGLIB proxy
Batch insert Hỗ trợ phương thức nhận List<T> gọi addBatch() tự động
Insert nhiều bản ghi qua VALUES (...) Sử dụng <foreach> để sinh câu SQL gộp tối ưu
Escape hatch (query, queryOne, update) Thực thi qua SqlFragment, không nhận chuỗi String tùy tiện
ExecutorType.BATCH / REUSE Không dùng executor trung gian phức tạp
Plugins / Interceptors Xem Giải pháp thay thế Plugin
Level-2 Cache (<cache>, <cache-ref>) Nên cài đặt cache ở tầng Service thay vì tầng ORM
Level-1 Cache LarkBatisSession là stateless, không lưu trữ entity cache
Đăng ký addMapper() động lúc runtime Danh sách mapper được chốt cố định lúc biên dịch
Ghi log SQL (log-sql) Sử dụng logging proxy ở tầng DataSource (như datasource-proxy, p6spy)

Build & Đóng gói

Tính năng Trạng thái Ghi chú kỹ thuật
Annotation processor (javac) Chỉ hỗ trợ javac, không hỗ trợ ECJ
Gradle plugin Tự động cấu hình compile inputs và processor path
Maven plugin Yêu cầu cấu hình <extensions>true</extensions>
JPMS (Java Module System) Tất cả artifact đều có module-info.java chuẩn
Tương thích với Lombok Khai báo larkbatis-processor chạy sau Lombok
Incremental compilation Aggregating processor; cần bật cờ -parameters
GraalVM Native Image Sẵn sàng về mặt cấu trúc (không dùng reflection); kiểm thử quy trình build đầy đủ ở mốc M5
Quét mã nguồn cũ larkbatis-scan Công cụ CLI phân tích mức độ tương thích. Xem Migration

Tài liệu liên quan