Skip to content

文件存储与 Excel ​

业务后端按需引用 Maven Central 上的 com.kaiwuzaidao 组件,三个组件在本版都使用 0.2.0。kaiwu-system-starter 提供平台接入和可选的存储客户端,kaiwu-data-scope 用于数据范围过滤,kaiwu-excel 用于读写工作簿。Starter · 数据范围 · Excel

给项目绑定存储 ​

平台管理员先在「对象存储」配置存储账号。下面在入口仓目录操作,以已有账号 assets 和项目 order-center 为例,执行前替换为实际名称。先完成 CLI 登录,再调用 System 脚本。

bash
cli=./workspace/kaiwu-system-service/scripts/kaiwu.sh
"$cli" storage accounts
"$cli" storage test assets
"$cli" storage bind order-center --account assets --max-mb 10 --types image/png,image/jpeg
"$cli" storage bindings order-center

v0.2.0 的 Gateway 缺少部分存储管理路由。如果用管理员账号查询存储账号或绑定仍返回 404,请查看路由修复进展。

连通性测试会写入并删除一个探测对象。在项目后端按 SDK 文档启用对象存储,选用 kaiwu 提供方获取项目范围的临时凭据,这套架构有三个工程优势:

  • 长期密钥不出平台:阿里云 OSS / MinIO 等长期 AK/SK 加密保存在 System 内,业务服务通过服务凭据仅换取限定到 {bucket}/{projectCode}/* 前缀的 STS 临时凭据(后台自动预取与续签,不阻塞业务请求)。
  • 文件字节不经平台中转:上传与预签名下载直连对象存储,System 不成为流量瓶颈与数据汇集点。
  • 只存引用不固化 URL:业务库仅保存 storage_ref 与 object_key,切换存储绑定后,只要原绑定和对象仍可用,历史附件就能沿原引用读取,无需在切换时迁移。

需要全项目统一的文件登记台账时,参考 Starter 仓的 docs/storage-file.sql,在业务仓中追加建表迁移并开启 StoredFileService,自动支持上传确认、软删除缓冲与过期孤儿清理任务(kaiwu.file.purge)。由业务接口校验文件归属和用户权限,用项目成员上传小图并读取,再用无访问权的账号验证读取被拒,绑定改为 READ_ONLY 时另测写入被拒。配置示例 · 文件登记契约

给订单列表加 Excel 导入导出 ​

在业务 domain 模块引入 com.kaiwuzaidao:kaiwu-excel:0.2.0。组件针对企业常见表格风险内置了防护:仅接受未加密单 Sheet XLSX、严格校验顺序表头、拒绝公式注入、限制 ZIP 条目数(最多 256)与展开大小(16 MiB),并在查询超限时直接报错而不静默截断。以下是业务代码片段,headers 的顺序就是模板契约,ExcelTable 来自 com.kaiwu.excel.ExcelTable。

java
var headers = List.of("订单号", "金额");
byte[] template = ExcelTable.template(headers);
var rows = ExcelTable.read(file.getInputStream(), headers, 5 * 1024 * 1024, 5000);
var result = ExcelTable.process(rows, row -> validateAndSave(row));

validateAndSave 由业务实现,返回安全的错误说明或 null。用正确模板和一行错误金额做验收,确认返回错误行号。导出前执行与列表相同的筛选、权限和数据范围检查,查询最多取上限加一行,超限直接提示;校验完成后再调用 ExcelTable.write。订单号按文本处理可保留前导零。支持的 XLSX 格式与限制

Apache License 2.0