Java 批量导入接口如何返回逐项错误：ProblemDetail 与行号映射实践

批量导入最让人头疼的不是接口直接请求失败，而是用户收到一个笼统的400错误，完全摸不清Excel里第17行和第42行到底哪里出了问题。用Spring Boot 3开发这类接口时，可以把成功结果、逐行校验错误和全局异常都统一成同一套ProblemDetail响应格式，同时配套行号映射规则，前端不需要额外猜错误来源。

先把调用方真正需要的结果说清楚

批量导入接口通常适配两种业务口径。财务月结这类场景要求全有或全无，任意一行失败就整体回滚；通讯录导入场景更适合部分成功模式，用户修正失败行的数据后就可以单独补传。两种模式都可以返回200或者422状态码，但响应结构里不能只放一句“数据有误”的提示。

这里我们采用部分成功模型，接口返回结构用稳定的业务对象承载所有结果：

public record ImportResult(
    int accepted,
    int rejected,
    List issues
) {}

public record RowIssue(
    int rowNumber,
    String field,
    String code,
    String message
) {}

rowNumber 直接使用用户看到的Excel实际行号，不要用代码里从零开始的集合下标。如果表头占第一行，解析器读到的第一个数据元素下标是0，映射行号时统一加2，这个逻辑要写到单元测试里校验，不要让前端去做额外的行号转换。

参数设计：让ProblemDetail和业务错误各司其职

Spring Boot 3 可以通过 ProblemDetail 表达状态码、错误标题和类型URI。批量导入的逐项错误属于自定义业务扩展字段，放到properties属性里处理会更合适：

@RestControllerAdvice
class ImportExceptionHandler {
    @ExceptionHandler(ImportFormatException.class)
    ResponseEntity handle(ImportFormatException ex) {
        var body = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
        body.setTitle("导入文件无法处理");
        body.setDetail("请修正文件格式后重新上传");
        body.setProperty("errorCode", "IMPORT_FORMAT");
        body.setProperty("issues", ex.issues());
        return ResponseEntity.unprocessableEntity().body(body);
    }
}

这样前端可以先按HTTP状态码处理通用逻辑，再读取 errorCode 和 issues 直接定位到对应错误单元格。不要把堆栈信息或者数据库异常原文直接放到 detail 里，traceId留在服务端日志里排查用，返回给前端的响应只放用户可以直接操作调整的提示内容。

校验流程：解析、校验、写入要分开

服务层可以先把每行数据转换为绑定了实际行号的中间对象，再执行字段校验。文件解析失败和业务字段校验失败要返回不同的错误码，不然用户分不清到底是Excel模板列没对齐，还是某行的手机号格式不对。

List rows = reader.read(file).stream()
    .map(row -> new IndexedRow(row.excelRowNumber(), row.values()))
    .toList();

List issues = new ArrayList();
for (IndexedRow row : rows) {
    validator.check(row).ifPresent(issues::add);
}
if (issues.size() == rows.size()) {
    throw new ImportFormatException(issues);
}

写入阶段只接收前面校验完全通过的对象。如果业务允许部分成功，可以给每一行配置独立的写入事务边界，遇到唯一索引冲突这类数据库层面的问题时，自动把异常转换成 DUPLICATE_KEY 结构，把冲突的行号放回错误明细集合里。不要直接把整个导入方法标成一个全局大事务，不然单条坏数据就会把所有正常的好数据都全部拖回滚。

兼容策略与测试检查点

如果旧客户端还依赖 {"message":"..."} 格式，可以先保留旧字段一段时间，同时新增 issues 和 errorCode。新客户端按 application/problem+json 解析新结构，旧客户端仍能正常读取原有message字段。等所有调用方都完成迁移后，再逐步移除旧字段。

测试环节至少覆盖四个场景：表头后面的第一条数据必须映射到第2行Excel行号；两条不同的失败数据要分别返回对应的错误字段和错误码；部分成功场景下，已处理成功的行数加失败行数等于总有效数据行数；全局异常不能向外泄露SQL语句或者Java堆栈信息。额外加一个重复提交测试，确认同一批次号的导入请求不会生成重复数据。

常见问题

批量导入失败应该返回400还是422？

文件本身损坏或者请求参数完全不符合规范时可以用400；文件格式没问题但里面的业务字段无法正常处理时，422更贴合语义，能明确表达“服务器已经理解了请求结构，但传入的内容不符合业务要求无法处理”。状态码和业务错误码要长期保持稳定，不要随意改动。

为什么不直接返回List存所有错误提示？

纯字符串适合打印日志，不适合前端做交互处理。把rowNumber、错误字段名、错误码拆分开之后，前端可以直接定位到导入预览表格的对应单元格，也能按错误码统计是模板问题还是用户输入问题。

部分成功是否一定要逐行事务？

不一定。数据量很大的时候可以分批提交，但是必须明确失败批次的重试规则、防重复写入逻辑，还要在返回结果里明确说明已处理成功和处理失败的边界。

结语

好用的批量导入接口不只是把文件里的数据存进数据库，而是把每一行的处理结果都清晰返回给调用方。先把响应语义固定下来，再去确定事务边界和兼容策略，ProblemDetail只是承载响应的工具层，真正能减少用户反复返工的核心，是稳定准确的行号、字段定位和明确的错误提示。