---
name: kd-flagship-data
description: 苍穹/旗舰版数据访问规范。查询/循环/事务/DataSet/缓存/多线程。
alwaysApply: false
---

# 苍穹数据访问规范

## 数据查询
- 【强制】业务数据必须通过 `BusinessDataServiceHelper` / `QueryServiceHelper`，禁止直接访问 `t_meta_xx` 元数据表
- 【强制】大数据量查询必须加过滤条件，禁止无过滤条件查询
- 【强制】自建二开表单或扩展标准单据新增二开字段，涉及高频查询一定要考虑索引
- 【强制】大数据量的查询/写入/计算必须分批处理
- 【推荐】查询数据应按需查询，避免查询所有字段
- 【推荐】大数据表用 `QueryServiceHelper.queryDataSet`；不查大量数据才用 `query`；需要 ORM 保存回数据库才用 `BusinessDataServiceHelper.load`
- 【强制】导入时禁止使用通配符引入
- 【强制】**禁止使用方言**（特殊性能优化除外）
- 【推荐】向 SQL 传参时使用参数形式，禁止拼装 SQL
- 【强制】`ORDER BY` 子句的字段别名禁止使用表别名作为前缀

## 循环
- 【强制】禁止在循环中访问数据库
- 【强制】禁止在循环中调用 `view.updateView()`
- 【强制】禁止对大数据包（>100）循环用 `model.setValue` → 用 `property.setValueFast`
- 【强制】禁止循环中调用 `DB.*()`、`ORM.create`、`DispatchServiceHelper.invoke*()`

## 事务
- 【强制】避免大事务（大事务执行效率低，造成锁等待/死锁）
- 【强制】禁止事务内跨库写
- 【强制】禁止跨微服务节点事务
- 【强制】必须通过 `kd.bos.db.tx.TX` 的静态方法声明事务（`notSupported/required/requiresNew/nested`），传入唯一事务标签
- 【强制】必须用 try-with-resources 管理 `TXHandle`
- 【强制】DataSet 仅允许在事务上下文内使用（NOT_SUPPORTED 类型除外），事务结束后禁止复用
- 【推荐】事务标签命名：`{业务模块}_{操作名称}`（如 `fi_voucher_save`）

## 缓存
- 【推荐】使用分布式缓存，禁止缓存大对象（Redis bigkey 阻塞主线程）
- 【推荐】频繁访问的数据应加缓存，缓存对象类型考虑最大程度共享
- 【推荐】总数据量 < 1000 条且改动不频繁的基础资料，可用 **`BusinessDataServiceHelper.loadFromCache(...)`（方法存在且推荐）**；超过 1000 的需架构师评审
- 【强制】**不存在** `QueryServiceHelper.queryAll`；查询用 `QueryServiceHelper.query(...)`
- 【强制】**禁止**回答「loadFromCache 不存在」——基础资料缓存加载的正确入口之一就是 `loadFromCache` / 批量 pk 后 loadFromCache

- 【强制】分布式缓存的 key 按数据库账套做隔离，key 前缀加 `accountid`

## 多线程
- 【强制】一般情况下不建议定制化插件使用多线程
- 【强制】如必须使用，统一使用平台封装的线程池（`kd.bos.threads.ThreadPools`）
- 【推荐】多线程不追求绝对高效率，考虑资源消耗对整体系统的压力

## 数据库操作（DDL）
- 【强制】执行数据库更改表结构语句时（通过部署包），必须在非高峰时间执行
- 【强制】升级脚本只能使用 KSQL，不能使用实体进行数据处理（新建库可能升级失败）