当前位置：首页 > news >正文

报表类系统后端API设计思路

news 2025/11/4 11:41:31

CRUD表单增强接口设计思路

高优先级接口设计

批量操作接口

设计背景

核心功能

接口设计

数据结构

技术实现要点

使用场景

数据验证接口

设计背景

核心功能

接口设计

验证规则配置

内置验证器

技术特点

数据导入接口

设计背景

核心功能

接口设计

数据结构

技术实现要点

使用流程

概述

设计目标

核心原则

接口优先级分析

高优先级 🔥

中优先级 ⭐

低优先级 📋

高优先级接口设计

批量操作接口

设计背景

当前系统只支持单条记录的增删改操作，在处理大量数据时效率低下。批量操作接口可以显著提升数据处理效率，减少网络请求次数。

核心功能

批量插入：一次性插入多条记录
批量更新：根据条件批量更新记录
批量删除：根据条件批量删除记录
批量状态变更：批量修改记录状态

接口设计

@RestController
@RequestMapping("/api/batch")
public class BatchOperationController {/*** 批量插入数据*/@PostMapping("/insert/{uri}")public ResponseResult<BatchOperationResult> batchInsert(@PathVariable String uri,@RequestBody BatchInsertRequest request) {BatchOperationResult result = batchOperationService.batchInsert(uri, request);return ResponseResult.success(result);}/*** 批量更新数据*/@PostMapping("/update/{uri}")public ResponseResult<BatchOperationResult> batchUpdate(@PathVariable String uri,@RequestBody BatchUpdateRequest request) {BatchOperationResult result = batchOperationService.batchUpdate(uri, request);return ResponseResult.success(result);}/*** 批量删除数据*/@PostMapping("/delete/{uri}")public ResponseResult<BatchOperationResult> batchDelete(@PathVariable String uri,@RequestBody BatchDeleteRequest request) {BatchOperationResult result = batchOperationService.batchDelete(uri, request);return ResponseResult.success(result);}
}

数据结构

/*** 批量插入请求*/
@Data
public class BatchInsertRequest {private List<Map<String, Object>> records;private boolean skipValidation = false;private boolean continueOnError = true;private int batchSize = 1000;
}/*** 批量更新请求*/
@Data
public class BatchUpdateRequest {private Map<String, Object> updateData;private Map<String, Object> whereCondition;private List<String> updateFields;private boolean skipValidation = false;
}/*** 批量操作结果*/
@Data
public class BatchOperationResult {private int totalCount;private int successCount;private int failureCount;private List<BatchOperationError> errors;private long executionTime;private String operationId;
}

技术实现要点

事务管理：支持全部成功或全部回滚的事务模式
分批处理：大数据量分批处理，避免内存溢出
错误处理：详细记录每条记录的处理结果
性能优化：使用批量SQL语句提升数据库性能
进度跟踪：长时间操作提供进度查询接口

使用场景

数据迁移时批量导入历史数据
定期批量更新数据状态
批量删除过期数据
Excel导入后的批量数据处理

数据验证接口

设计背景

数据质量是系统稳定运行的基础。当前系统缺乏统一的数据验证机制，容易产生脏数据。数据验证接口提供统一、可配置的验证服务。

核心功能

字段级验证：单个字段的格式、长度、类型验证
表单级验证：整个表单的完整性验证
业务规则验证：复杂的业务逻辑验证
实时验证：用户输入时的即时验证反馈

接口设计

@RestController
@RequestMapping("/api/validation")
public class DataValidationController {/*** 字段验证*/@PostMapping("/field")public ResponseResult<FieldValidationResult> validateField(@RequestBody FieldValidationRequest request) {FieldValidationResult result = validationService.validateField(request);return ResponseResult.success(result);}/*** 表单验证*/@PostMapping("/form/{uri}")public ResponseResult<FormValidationResult> validateForm(@PathVariable String uri,@RequestBody FormValidationRequest request) {FormValidationResult result = validationService.validateForm(uri, request);return ResponseResult.success(result);}/*** 获取验证规则*/@GetMapping("/rules/{uri}")public ResponseResult<List<ValidationRule>> getValidationRules(@PathVariable String uri) {List<ValidationRule> rules = validationService.getValidationRules(uri);return ResponseResult.success(rules);}
}

验证规则配置

/*** 验证规则*/
@Data
public class ValidationRule {private String fieldName;private String ruleType; // REQUIRED, LENGTH, PATTERN, CUSTOMprivate String expression;private String errorMessage;private boolean enabled = true;private int priority = 0;private Map<String, Object> parameters;
}/*** 验证器接口*/
public interface FieldValidator {ValidationResult validate(Object value, ValidationRule rule);String getValidatorType();
}

内置验证器

基础验证器
- 必填验证（RequiredValidator）
- 长度验证（LengthValidator）
- 格式验证（PatternValidator）
- 数值范围验证（RangeValidator）
业务验证器
- 唯一性验证（UniquenessValidator）
- 关联数据验证（ReferenceValidator）
- 自定义业务规则验证（CustomBusinessValidator）

技术特点

可配置化：验证规则通过数据库配置，支持动态修改
可扩展性：支持自定义验证器插件
高性能：验证规则缓存，减少数据库查询
用户友好：提供清晰的错误信息和修复建议

数据导入接口

设计背景

数据导入是系统常见需求，特别是在系统初始化、数据迁移、批量录入等场景。当前系统缺乏标准化的导入功能，用户只能手动逐条录入。

核心功能

Excel导入：支持.xlsx、.xls格式文件导入
CSV导入：支持CSV格式文件导入
JSON导入：支持JSON格式数据导入
模板下载：提供标准导入模板
导入预览：导入前数据预览和验证
错误处理：详细的错误报告和修复建议

接口设计

@RestController
@RequestMapping("/api/import")
public class DataImportController {/*** 文件上传导入*/@PostMapping("/upload/{uri}")public ResponseResult<ImportResult> uploadAndImport(@PathVariable String uri,@RequestParam("file") MultipartFile file,@RequestParam(value = "options", required = false) String options) {ImportOptions importOptions = parseImportOptions(options);ImportResult result = importService.importFromFile(uri, file, importOptions);return ResponseResult.success(result);}/*** 数据预览*/@PostMapping("/preview/{uri}")public ResponseResult<ImportPreviewResult> previewImport(@PathVariable String uri,@RequestParam("file") MultipartFile file) {ImportPreviewResult result = importService.previewImport(uri, file);return ResponseResult.success(result);}/*** 下载导入模板*/@GetMapping("/template/{uri}")public ResponseEntity<Resource> downloadTemplate(@PathVariable String uri) {Resource template = importService.generateTemplate(uri);return ResponseEntity.ok().header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=template.xlsx").body(template);}/*** 获取导入历史*/@GetMapping("/history/{uri}")public ResponseResult<PageResult<ImportHistory>> getImportHistory(@PathVariable String uri,@RequestParam(defaultValue = "1") int pageNum,@RequestParam(defaultValue = "10") int pageSize) {PageResult<ImportHistory> result = importService.getImportHistory(uri, pageNum, pageSize);return ResponseResult.success(result);}
}

数据结构

/*** 导入选项*/
@Data
public class ImportOptions {private boolean skipFirstRow = true;private boolean validateData = true;private boolean continueOnError = true;private int batchSize = 1000;private Map<String, String> fieldMapping;private List<String> ignoreFields;
}/*** 导入结果*/
@Data
public class ImportResult {private String importId;private int totalRows;private int successRows;private int errorRows;private List<ImportError> errors;private long executionTime;private ImportStatus status;
}/*** 导入错误*/
@Data
public class ImportError {private int rowNumber;private String fieldName;private String errorMessage;private String originalValue;private String suggestedValue;
}