MyBatis 批次新增：前端資料封裝進 List<Entity>

場景

前端傳遞多筆資料 (如表單動態新增多列)，後端需批次寫入資料庫。MyBatis Mapper 定義：

<insert id="batchInsert" parameterType="java.util.List">
  INSERT INTO user_role (user_id, role_id) VALUES
  <foreach collection="list" item="item" separator=",">
    (#{item.userId}, #{item.roleId})
  </foreach>
</insert>

Controller 封裝 List<Entity> 範例

@PostMapping("/batchSave")
public Result batchSave(@RequestBody List dtos) {
    List entities = new ArrayList<>();
    for (UserRoleDTO dto : dtos) {
        UserRole entity = new UserRole();
        entity.setUserId(dto.getUserId());
        entity.setRoleId(dto.getRoleId());
        // 其他欄位映射...
        entities.add(entity);
    }
    userRoleService.batchInsert(entities);
    return Result.success();
}

Service/Mapper 層

// Service
public void batchInsert(List list) {
    if (list == null || list.isEmpty()) return;
    mapper.batchInsert(list); // MyBatis 自動處理 foreach
}

// Mapper Interface
void batchInsert(List list);

前端傳輸格式 (JSON)

[
  { "userId": 101, "roleId": 1 },
  { "userId": 101, "roleId": 3 },
  { "userId": 102, "roleId": 2 }
]

效能優化建議

• 批次大小限制：單次 SQL 過長可能超過 max_allowed_packet (MySQL) 或導致解析緩慢。建議 **500-1000 筆分批**。
• 使用 ExecutorType.BATCH (MyBatis)：

  SqlSession sqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH);
  try {
      UserRoleMapper mapper = sqlSession.getMapper(UserRoleMapper.class);
      for (UserRole entity : entities) {
          mapper.insert(entity); // 單條 insert，但批次提交
      }
      sqlSession.commit();
  } finally {
      sqlSession.close();
  }
  

• 資料庫層面：確保索引合理、關閉不必要的觸發器、考慮 LOAD DATA INFILE (MySQL) / COPY (PostgreSQL) 超大量匯入。

常見錯誤

• 前端傳 application/x-www-form-urlencoded 陣列格式，後端用 @RequestParam List 接收失敗 → 改用 @RequestBody 接收 JSON 陣列。
• Entity 欄位名稱與 DTO/JSON 不符，導致屬性為 null。
• 忘記在 Mapper XML <foreach> 指定 collection="list" (參數為 List 時預設即為 list，但明確指定較保險)。

正確封裝 List<Entity>> 並搭配 MyBatis <foreach>，即可高效完成批次新增。