diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d9b845..283e771 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
# Changelog
+## [1.1.0] - Unreleased
+
+### ⚠️ 破坏性变更
+
+- **`DefaultBeanRowMapper.of()` 不再抛出 `SQLException`**:工厂方法在反射异常时改为抛出非受检异常 `IllegalStateException`。调用方如果 `catch (SQLException e)` 包裹 `of()` 调用,该捕获将失效,需移除相关 `catch` 块或改为捕获 `IllegalStateException`。
+
+### 文档
+
+- 优化 `DefaultBeanRowMapper` 类注释,明确性能限制和使用建议
+
+---
+
## [1.0.0] - 2026-06-17
### 重构
diff --git a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
index 9f0e9c1..85a9fa8 100644
--- a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
+++ b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
@@ -41,16 +41,17 @@ import xyz.zhouxy.jdbc.util.NamingTools;
*
*
* 将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper} 的基础实现。
- * 仅在对性能不敏感的场景下使用。
+ *
+ * 性能和规则上的限制都比较大,仅在对性能不敏感的场景下便捷使用,
+ * 一般情况下你应该自定义 {@link RowMapper}。
*
*
* 说明:
*
* - 使用反射获取类型信息,也是使用反射调用无参构造器和 {@code setter} 方法。
- * - {@code propertyColMap} 未指定的列名和属性名的映射时,默认 JavaBean 的属性名为小驼峰,列名为小写蛇形命名。
+ * - 支持自定义列名和属性名的映射,当未指定 {@code propertyColMap} 时,默认 JavaBean 的属性名为小驼峰,列名为小写蛇形命名。
* - 使用 {@link ResultSet#getObject(String, Class)} 从 {@link ResultSet} 中获取属性值。
* - JavaBean 属性仅支持引用类型,不支持基本数据类型。
- * - 实际使用中更建议针对目标类型自定义 {@link RowMapper}。
*
*
* @author ZhouXY
@@ -86,9 +87,9 @@ public class DefaultBeanRowMapper implements RowMapper {
* @param Bean 类型
* @param beanType Bean 类型
* @return DefaultBeanRowMapper 对象
- * @throws SQLException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
+ * @throws IllegalStateException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
*/
- public static DefaultBeanRowMapper of(Class beanType) throws SQLException {
+ public static DefaultBeanRowMapper of(Class beanType) {
return of(beanType, null);
}
@@ -99,10 +100,10 @@ public class DefaultBeanRowMapper implements RowMapper {
* @param beanType Bean 类型
* @param propertyColMap Bean 字段与列名的映射关系。key 是字段,value 是列名。
* @return {@code DefaultBeanRowMapper} 对象
- * @throws SQLException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
+ * @throws IllegalStateException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
*/
- public static DefaultBeanRowMapper of(Class beanType, @Nullable Map propertyColMap)
- throws SQLException {
+ public static DefaultBeanRowMapper of(Class beanType,
+ @Nullable Map propertyColMap) {
try {
// 获取无参构造器
Constructor constructor = beanType.getDeclaredConstructor();
@@ -113,10 +114,10 @@ public class DefaultBeanRowMapper implements RowMapper {
return new DefaultBeanRowMapper<>(beanType, constructor, colPropertyMap, colSetterMap);
}
catch (IntrospectionException e) {
- throw new SQLException("There is an exception occurs during introspection.", e);
+ throw new IllegalStateException("There is an exception occurs during introspection.", e);
}
catch (NoSuchMethodException e) {
- throw new SQLException("Could not find a no-args constructor in " + beanType.getName(), e);
+ throw new IllegalStateException("Could not find a no-args constructor in " + beanType.getName(), e);
}
}
@@ -141,7 +142,7 @@ public class DefaultBeanRowMapper implements RowMapper {
return newInstance;
}
catch (IllegalAccessException | InstantiationException | InvocationTargetException e) {
- throw new SQLException("Could not map row to " + beanType.getName(), e);
+ throw new IllegalStateException("Could not map row to " + beanType.getName(), e);
}
}
diff --git a/src/main/java/xyz/zhouxy/jdbc/RowMapper.java b/src/main/java/xyz/zhouxy/jdbc/RowMapper.java
index d195bce..5db48a4 100644
--- a/src/main/java/xyz/zhouxy/jdbc/RowMapper.java
+++ b/src/main/java/xyz/zhouxy/jdbc/RowMapper.java
@@ -60,9 +60,9 @@ public interface RowMapper {
* @param Java Bean 的类型
*
* @return {@link DefaultBeanRowMapper}
- * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+ * @throws IllegalStateException 如果创建 {@link DefaultBeanRowMapper} 失败
*/
- static RowMapper beanRowMapper(Class beanType) throws SQLException {
+ static RowMapper beanRowMapper(Class beanType) {
return DefaultBeanRowMapper.of(beanType);
}
@@ -74,10 +74,9 @@ public interface RowMapper {
* @param Java Bean 的类型
*
* @return {@link DefaultBeanRowMapper}
- * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+ * @throws IllegalStateException 如果创建 {@link DefaultBeanRowMapper} 失败
*/
- static RowMapper beanRowMapper(Class beanType, Map propertyColMap)
- throws SQLException {
+ static RowMapper beanRowMapper(Class beanType, Map propertyColMap) {
return DefaultBeanRowMapper.of(beanType, propertyColMap);
}
}
diff --git a/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java b/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java
index f9bc5a0..aa71284 100644
--- a/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java
@@ -137,9 +137,9 @@ class RowMapperTest extends BaseH2Test {
}
@Test
- @DisplayName("DefaultBeanRowMapper:无无参构造器的 Bean 抛出 SQLException")
+ @DisplayName("DefaultBeanRowMapper:无无参构造器的 Bean 抛出 IllegalStateException")
void testDefaultBeanRowMapperNoNoArgConstructor() {
- assertThrows(SQLException.class, () ->
+ assertThrows(IllegalStateException.class, () ->
DefaultBeanRowMapper.of(BeanWithoutNoArgConstructor.class));
}