MyBatis插入数据时Numeric字段算术溢出

Question

在使用MyBatis向SQL Server（或其他支持`NUMERIC(p,s)`的数据库）插入数据时，若Java端传入的`BigDecimal`值精度或小数位数超出数据库列定义（如数据库列为`NUMERIC(10,2)`，却尝试插入`12345678.901`），常触发“Arithmetic overflow error converting numeric to data type numeric”异常。该问题并非MyBatis自身缺陷，而是JDBC驱动将Java数值严格映射为对应SQL类型时，因精度截断或舍入策略不匹配（如未配置`sendStringParametersAsUnicode=false`或未显式调用`setScale()`）导致服务端校验失败。尤其在批量插入、动态SQL或DTO未做前置精度校验场景下极易复现，且错误堆栈常掩盖真实字段上下文，排查成本高。

Answer 1

```html

一、现象层：异常表征与典型错误堆栈

当执行 INSERT INTO account (balance) VALUES (?)（列定义为 NUMERIC(10,2)），而传入 new BigDecimal("12345678.901") 时，SQL Server 抛出：
com.microsoft.sqlserver.jdbc.SQLServerException: Arithmetic overflow error converting numeric to data type numeric.
该异常不携带字段名、参数索引或原始值，仅在 JDBC 驱动层终止，导致日志中无法定位具体是哪个 DTO 字段越界。

二、驱动层：JDBC 类型映射的隐式行为

• SQL Server JDBC Driver（如 v12.6+）默认将 BigDecimal 直接绑定为 java.sql.Types.DECIMAL，并严格遵循其 precision 和 scale 元数据
• 若未显式调用 setScale(2, RoundingMode.HALF_UP)，则驱动直接传递原始精度（如 scale=3），触发服务端 NUMERIC(10,2) 的强制校验失败
• 配置项 sendStringParametersAsUnicode=false 对数值类型无影响，属常见误区；真正关键的是 sendTimeAsDatetime=false 等无关参数常被误配

三、框架层：MyBatis 的 TypeHandler 扩展机制

MyBatis 默认使用 BigDecimalTypeHandler，其 setNonNullParameter() 方法直接调用 PreparedStatement.setBigDecimal()，未做 scale 标准化。可自定义强约束处理器：

public class NumericScaleTypeHandler extends BaseTypeHandler<BigDecimal> {
  private final int targetScale;
  private final RoundingMode roundingMode;

  public NumericScaleTypeHandler(int scale) {
    this(scale, RoundingMode.HALF_UP);
  }

  @Override
  public void setNonNullParameter(PreparedStatement ps, int i, BigDecimal parameter, JdbcType jdbcType) 
      throws SQLException {
    BigDecimal scaled = parameter.setScale(targetScale, roundingMode);
    ps.setBigDecimal(i, scaled);
  }
  // ... 其余方法省略
}

四、应用层：DTO 与 Service 的防御性编程实践

场景	风险点	推荐方案
REST API 接收 JSON	前端传 "123.456" → Jackson 反序列化为 scale=3 的 BigDecimal	@JsonDeserialize(using = ScaledBigDecimalDeserializer.class)
批量插入（BatchExecutor）	单条失败导致整批回滚，无细粒度错误反馈	预校验 + 分片提交 + 失败记录标记
动态 SQL（<foreach>）	多个 NUMERIC 字段混用不同 scale，易遗漏	统一 BaseDTO 抽象 enforceScale() 模板方法

五、架构层：全链路精度治理策略

graph TD
  A[API Gateway] -->|JSON Schema 校验| B(Decimal 字段 maxDigits=10, maxFractionalDigits=2)
  B --> C[Spring Validator @DecimalMin/@DecimalMax]
  C --> D[MyBatis TypeHandler 强制缩放]
  D --> E[SQL Server Column Constraint]
  E --> F[监控告警：JDBC SQLException 包含 'overflow' 关键词]

六、诊断层：精准定位越界字段的工程化手段

在 MyBatis Interceptor 中增强日志：

• 捕获 Executor.update() 前的 BoundSql 与 ParameterObject
• 反射遍历 DTO 所有 BigDecimal 字段，比对数据库元数据 DatabaseMetaData.getColumns(..., "SCALE")
• 输出结构化诊断日志：[OVERFLOW-DETECT] Field 'order_amount' value=999999.999 scale=3 > column scale=2

七、生态层：跨数据库兼容性设计要点

除 SQL Server 外，Oracle 的 NUMBER(p,s)、PostgreSQL 的 NUMERIC(p,s)、MySQL 的 DECIMAL(p,s) 均存在同类问题。统一抽象应关注：

• 数据库方言差异：Oracle 不校验 scale 超出（静默截断），而 SQL Server/PostgreSQL 严格报错
• 连接池适配：HikariCP 的 leakDetectionThreshold 应设为 60000ms，避免因异常重试导致连接泄漏
• 单元测试覆盖：使用 testcontainers 启动真实 SQL Server 实例验证边界值

八、演进层：从防御到契约驱动的范式升级

引入 OpenAPI 3.0 的 x-numeric-constraint 扩展，在接口定义中声明精度契约：

components:
  schemas:
    PaymentDTO:
      properties:
        amount:
          type: string
          format: decimal
          x-numeric-constraint:
            precision: 10
            scale: 2
          example: "12345678.90"

结合 Codegen 工具自动生成带校验逻辑的 DTO 类，实现“契约即代码”。

```