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

CRUD表单增强接口设计思路

目录

CRUD表单增强接口设计思路

高优先级接口设计

批量操作接口

设计背景

核心功能

接口设计

数据结构

技术实现要点

使用场景

数据验证接口

设计背景

核心功能

接口设计

验证规则配置

内置验证器

技术特点

数据导入接口

设计背景

核心功能

接口设计

数据结构

技术实现要点

使用流程

概述

设计目标

核心原则

接口优先级分析

[高优先级 🔥](#高优先级 🔥)

[中优先级 ⭐](#中优先级 ⭐)

[低优先级 📋](#低优先级 📋)

---

高优先级接口设计

批量操作接口

设计背景

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

核心功能

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

接口设计

@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;
}

技术实现要点

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

使用场景

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

---

数据验证接口

设计背景

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

核心功能

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

接口设计

@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, CUSTOM
    private 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();
}

内置验证器

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

技术特点

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

---

数据导入接口

设计背景

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

核心功能

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

接口设计

@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;
}

技术实现要点

1. 文件解析：支持多种文件格式的解析
2. 字段映射：灵活的字段映射配置
3. 数据验证：集成数据验证接口
4. 异步处理：大文件异步处理，提供进度查询
5. 错误恢复：支持错误数据的修复和重新导入

使用流程

1. 下载模板：用户下载标准导入模板
2. 填写数据：按模板格式填写数据
3. 上传预览：上传文件进行数据预览
4. 确认导入：确认无误后执行导入
5. 查看结果：查看导入结果和错误报告

---

概述

基于现有的CRUD表单系统，本文档提出了一系列增强接口的设计思路，旨在提升系统的便利性、数据质量、处理效率和用户体验。这些接口按照业务价值和实施复杂度分为三个优先级，为系统的渐进式升级提供指导。

设计目标

• 提升效率：通过批量操作和自动化功能减少重复工作
• 保证质量：通过验证和审计机制确保数据完整性
• 增强体验：通过智能关联和便捷导入提升用户体验
• 确保安全：通过权限控制和备份机制保障数据安全
• 支持扩展：通过标准化接口支持系统集成和扩展

核心原则

1. 向后兼容：新接口不影响现有功能
2. 渐进实施：按优先级分阶段实现
3. 统一标准：遵循RESTful API设计规范
4. 性能优先：考虑大数据量处理的性能需求
5. 安全第一：所有接口都需要权限验证和安全控制

---

接口优先级分析

高优先级 🔥

特点：直接影响用户日常操作效率，投入产出比高

1. 批量操作接口 - 显著提高数据处理效率
2. 数据验证接口 - 保证数据质量，减少错误数据
3. 数据导入接口 - 便于数据迁移和批量录入

中优先级 ⭐

特点：增强系统功能性，提升管理能力

1. 数据统计接口 - 提供数据分析能力
2. 审计日志接口 - 满足合规要求
3. 数据关联接口 - 增强用户体验

低优先级 📋

特点：提供高级功能，支持复杂业务场景

1. 数据备份与恢复 - 数据安全保障
2. 数据权限接口 - 细粒度权限控制
3. 数据快照接口 - 版本管理
4. 数据同步接口 - 系统集成

---