mm_dao 1.8.2 → 1.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,6 +17,83 @@ npm install mm_sql
17
17
 
18
18
  ## 使用方法
19
19
 
20
+ ### 0. 数据域(推荐入口)
21
+
22
+ DAO 层按数据域组织,用 `daoAdmin(域)` 取用:
23
+
24
+ ```javascript
25
+ const { daoAdmin } = require('mm_dao');
26
+
27
+ // 系统 / 用户 / 机构 / 项目 / 客户端 / 应用
28
+ daoAdmin('os').load('./sys.sql');
29
+ daoAdmin('user').run('account', query, body);
30
+
31
+ // 某个域需要独立数据库时,随作用域一起给 sql 配置
32
+ daoAdmin('org', {
33
+ sql: { way: 'mysql', mysql: { host: '127.0.0.1', database: 'org' } }
34
+ });
35
+ ```
36
+
37
+ - 同一域复用同一管理器实例;`os` 为默认域。
38
+ - 域未单独配置 `sql` 时复用主库,便于同库分域、后续平滑拆库。
39
+ - 简单 CURD 允许直接 `sqlAdmin('os')` 访问,少一层封装、性能更好。
40
+
41
+ ### 0.1 查询参数的字段过滤
42
+
43
+ 生成 SQL 条件之前,查询参数会先按 `filter` 抽取一遍,确保进入 where 的只有真实表字段。
44
+ `filter` 是一张「参数名 → 数据管理器属性名」的映射表,默认包含:
45
+
46
+ | 参数 | 赋值给 | 说明 |
47
+ |---|---|---|
48
+ | `table` | `db.table` | 表名,`table` 配置含 `{0}` 时生效 |
49
+ | `page` | `db.page` | 页码 |
50
+ | `size` | `db.size` | 每页条数 |
51
+ | `method` | `db.method` | 操作方式 |
52
+ | `orderby` | `db.orderby` | 排序 |
53
+ | `field` | `db.field` | 返回字段 |
54
+ | `count_ret` | `db.count_ret` | 是否返回总数 |
55
+ | `groupby` | `db.groupby` | 分组(sum/avg/count 用) |
56
+ | `db` | — | 数据域,仅用于选择数据源(值为空表示只抽取不赋值) |
57
+
58
+ 业务可在 dao.json 中追加自己的非表字段,例如机构ID只用于选择机构库,不参与查询条件:
59
+
60
+ ```json
61
+ {
62
+ "table": "ai_agent",
63
+ "filter": { "org_id": "" }
64
+ }
65
+ ```
66
+
67
+ - 声明与默认清单**合并**,追加业务字段不会丢掉通用控制参数。
68
+ - 抽取与取值真假无关:`page=0`、`size=''` 这类假值同样被抽走,不会被拼成 `` `page` = 0 ``。
69
+ - 只有真值才赋给数据管理器;`""`(空字符串)表示只抽取、不赋值。
70
+ - 未声明的字段仍按等值条件处理(`` `field` = value ``),保持与既有 dao 兼容。
71
+
72
+ ### 0.2 默认条件(query_default)与增删改查的一致性
73
+
74
+ `query_default` 里形如 `{"user_id": "\`user_id\` = {user_id}"}` 的条件,在参数不含该字段时自动追加。
75
+ 它通常是**数据隔离条件**(用户、机构),所以所有读写路径必须一致:
76
+
77
+ - `get`、`set`、`del`、`addOrSet`、`del_repeat` 都走同一个 `_buildQueryString`,都会追加默认条件;
78
+ - 条件用 `AND` 拼接而非 `&&`,MySQL 与 SQLite 通用;
79
+ - `del` 在最终条件为空时直接返回「删除条件不能为空」,不会退化成删全表;
80
+ - 前端显式传了同名字段(如 `user_id`)时按「参数优先」处理,不再追加默认条件 —— 这类字段应视为不可由前端覆盖的隔离字段,接口层需自行拦截。
81
+
82
+ **写入侧要配 `body_default`**:`query_default` 会在新增前校验隔离字段,`body_default` 负责把同样的字段值补进新记录。
83
+ 两者取值模板相同(如都为 ``"`user_id` = {user_id}"``),否则新增出来的记录缺少隔离字段,按同一用户再也查不到,表现为**反复新增重复数据**。
84
+
85
+ ```json
86
+ {
87
+ "query_default": { "user_id": "`user_id` = {user_id}" },
88
+ "body_default": { "user_id": "`user_id` = {user_id}" }
89
+ }
90
+ ```
91
+
92
+ `addOrSet` 的「新增 / 更新」由 Dao 自己判定存在性后分派(`countSql` → `add` / `setSql`):
93
+ 部分适配器的 `addOrSet` 在新增时只写入 `body`,不会带上条件字段,会让新记录不满足条件、下次调用又插一条。
94
+ `del_repeat` 的分组查询与逐条取行同样叠加默认条件,只在本用户范围内去重。
95
+
96
+
20
97
  ### 1. 基本使用
21
98
 
22
99
  ```javascript
package/index.js CHANGED
@@ -1,24 +1,64 @@
1
1
  const Dao = require('./lib/dao');
2
2
  const Manager = require('./lib/manager');
3
+ const { Sql } = require('mm_sql');
3
4
  const Admin = require('mm_corejs').Admin;
4
5
 
5
6
  const admin = new Admin();
6
7
  admin.setClass(Manager);
7
8
 
9
+ /**
10
+ * 数据域配置模板:config.sql 中含 {org_id} 占位符时只登记、不实例化,
11
+ * 供 daoAdmin(域, { org_id }) 按机构派生独立库
12
+ * @type {Object}
13
+ */
14
+ const templates = {};
15
+
16
+ /**
17
+ * 按机构生成数据源配置(替换 {org_id} 占位符,深拷贝避免污染模板)
18
+ * @param {object} sql_config 数据源配置模板
19
+ * @param {number} org_id 机构ID
20
+ * @returns {object} 该机构的数据源配置
21
+ */
22
+ function bindOrg(sql_config, org_id) {
23
+ const cfg = JSON.parse(JSON.stringify(sql_config));
24
+ return JSON.parse(JSON.stringify(cfg).replace(/\{org_id\}/g, String(org_id)));
25
+ }
26
+
8
27
  module.exports = {
28
+ Sql,
9
29
  Dao,
10
30
  Manager,
11
31
  admin,
12
32
  /**
13
- * 获取指定作用域的 SQL 管理器
14
- * @param {string} [scope='sys'] 作用域名称
15
- * @param {object} [config] 配置参数
16
- * @returns {object} SQL 管理器实例
33
+ * 获取指定作用域的 DAO 管理器
34
+ * 作用域即数据域:os(系统)、user(用户)、org(机构)、project(项目)、client(客户端)、app(应用)。
35
+ * 每个作用域可独立绑定数据源(config.sql),未配置时复用主库;同一作用域复用同一实例。
36
+ *
37
+ * 按机构分库:数据源配置里用 {org_id} 占位时,该域只登记模板;
38
+ * 用 daoAdmin('org', { org_id: 3 }) 取用时,派生实例 org_3,库名按模板替换为 org_3.db。
39
+ * @param {string} [scope='os'] 作用域名称
40
+ * @param {object} [config] 配置参数,config.sql 指定数据源,config.org_id 指定机构
41
+ * @returns {object|null} DAO 管理器实例;登记模板时返回 null
17
42
  */
18
43
  daoAdmin(scope, config) {
19
44
  if (!scope) {
20
45
  scope = 'os';
21
46
  }
47
+ // 1) 登记模板:含 {org_id} 的数据源不建固定实例,等按机构取用时再派生
48
+ if (config && config.sql && /\{org_id\}/.test(JSON.stringify(config.sql))) {
49
+ templates[scope] = config.sql;
50
+ return null;
51
+ }
52
+ // 2) 按机构派生:daoAdmin('org', { org_id: 3 }) → 实例名 org_3,库按模板替换
53
+ if (config && config.org_id) {
54
+ const org_id = parseInt(config.org_id) || 0;
55
+ const name = scope + '_' + org_id;
56
+ const tpl = config.sql || templates[scope];
57
+ const next = Object.assign({}, config);
58
+ delete next.org_id;
59
+ next.sql = tpl ? bindOrg(tpl, org_id) : undefined;
60
+ return admin.get(name, next);
61
+ }
22
62
  return admin.get(scope, config);
23
63
  }
24
- };
64
+ };