mm_admin 0.0.0-stage → 1.0.0
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 +138 -2
- package/example/demo.js +78 -0
- package/index.js +7 -0
- package/lib/admin.js +191 -0
- package/package.json +34 -4
package/README.md
CHANGED
|
@@ -1,3 +1,139 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mm_admin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
管理器实例池模块。按名称缓存管理器实例(如同作用域的缓存、会话、通道管理器),提供同步/异步获取、实例创建钩子与删除清空,供各 `xxxAdmin()` 统一对外出口复用。
|
|
4
|
+
|
|
5
|
+
## 项目信息
|
|
6
|
+
|
|
7
|
+
- **当前版本**: 1.0.0
|
|
8
|
+
- **依赖**: 无
|
|
9
|
+
- **运行环境**: Node.js(使用私有字段 `#map`,需 Node.js 12+)
|
|
10
|
+
- **Gitee地址**: https://gitee.com/qiuwenwu91/mm_admin
|
|
11
|
+
|
|
12
|
+
## 特点
|
|
13
|
+
|
|
14
|
+
- 实例池内部用私有 `Map` 存储,不对外暴露 Map,避免绕过缓存规则写入
|
|
15
|
+
- `get` 按名称缓存实例,同名实例只创建一次,配置仅在首次创建时生效
|
|
16
|
+
- `config.name` 始终以传入名称为准,避免被外部配置覆盖
|
|
17
|
+
- `getAsync` 支持实例创建钩子 `onCreate`,新实例创建后执行异步初始化,已存在实例不再执行
|
|
18
|
+
- `setClass` / `setServer` / `onCreate` 只允许设置一次,重复设置抛错,防止运行期被篡改
|
|
19
|
+
- 提供 `has` / `del` / `clear` / `keys` / `values` / `size` 完整管理方法,`clear` 支持链式调用
|
|
20
|
+
|
|
21
|
+
## 安装
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install mm_admin
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 基本使用
|
|
28
|
+
|
|
29
|
+
```javascript
|
|
30
|
+
const { Admin } = require('mm_admin');
|
|
31
|
+
|
|
32
|
+
// 1. 定义被管理的类,构造参数为 (config, server)
|
|
33
|
+
class CacheManager {
|
|
34
|
+
constructor(config, server) {
|
|
35
|
+
this.config = config;
|
|
36
|
+
this.server = server;
|
|
37
|
+
this.data = new Map();
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// 2. 创建管理器并绑定被管理的类与服务器
|
|
42
|
+
const admin = new Admin({ debug: true }, { tag: 'server' });
|
|
43
|
+
admin.setClass(CacheManager);
|
|
44
|
+
|
|
45
|
+
// 3. 按名称获取实例,同名实例只创建一次
|
|
46
|
+
const cache = admin.get('cache:a', { ttl: 60 });
|
|
47
|
+
console.log(cache.config); // { ttl: 60, name: 'cache:a' }
|
|
48
|
+
console.log(cache.server); // { tag: 'server' }
|
|
49
|
+
console.log(admin.get('cache:a') === cache); // true
|
|
50
|
+
|
|
51
|
+
// 4. 异步获取:新实例创建后执行 onCreate 钩子
|
|
52
|
+
admin.onCreate(async (mod) => {
|
|
53
|
+
await mod.init(); // 可执行异步初始化
|
|
54
|
+
});
|
|
55
|
+
const session = await admin.getAsync('session:1');
|
|
56
|
+
|
|
57
|
+
// 5. 遍历、删除与清空
|
|
58
|
+
console.log(Array.from(admin.keys())); // [ 'cache:a', 'session:1' ]
|
|
59
|
+
console.log(admin.size); // 2
|
|
60
|
+
admin.del('cache:a'); // true
|
|
61
|
+
admin.clear(); // 返回管理器自身
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## API 说明
|
|
65
|
+
|
|
66
|
+
### 入口(index.js)
|
|
67
|
+
|
|
68
|
+
| 导出 | 签名 | 返回值 | 说明 |
|
|
69
|
+
| --- | --- | --- | --- |
|
|
70
|
+
| Admin | `Admin` | `Class` | 管理器类,见下文 |
|
|
71
|
+
|
|
72
|
+
> 各业务模块建议参照 `mm_container` 的用法:模块入口创建一个 `Admin` 实例并 `setClass` 绑定自身管理类,再导出 `xxxAdmin(name, config?)` 函数统一对外提供实例。
|
|
73
|
+
|
|
74
|
+
### 构造函数
|
|
75
|
+
|
|
76
|
+
```javascript
|
|
77
|
+
const admin = new Admin(config?, server?);
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
| 参数 | 类型 | 默认值 | 说明 |
|
|
81
|
+
| --- | --- | --- | --- |
|
|
82
|
+
| config | `Object` | `{}` | 管理器配置,浅合并保存在 `admin.config` |
|
|
83
|
+
| server | `Object` | `undefined` | 服务器实例,等价于调用 `setServer(server)` |
|
|
84
|
+
|
|
85
|
+
### 属性
|
|
86
|
+
|
|
87
|
+
| 属性 | 类型 | 说明 |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| config | `Object` | 管理器配置 |
|
|
90
|
+
| size | `number` | 只读,当前实例数量 |
|
|
91
|
+
|
|
92
|
+
### 方法
|
|
93
|
+
|
|
94
|
+
| 方法 | 签名 | 返回值 | 说明 |
|
|
95
|
+
| --- | --- | --- | --- |
|
|
96
|
+
| setClass | `setClass(cs)` | `void` | 设置被管理的类;为空或已设置时抛错 |
|
|
97
|
+
| getClass | `getClass()` | `Class \| undefined` | 获取被管理的类 |
|
|
98
|
+
| setServer | `setServer(server)` | `void` | 设置服务器实例;为空或已设置时抛错 |
|
|
99
|
+
| getServer | `getServer()` | `Object \| undefined` | 获取服务器实例 |
|
|
100
|
+
| onCreate | `onCreate(fn)` | `void` | 注册实例创建钩子;非函数或已设置时抛错 |
|
|
101
|
+
| setConfig | `setConfig(config)` | `void` | 与已有配置浅合并,同名键覆盖 |
|
|
102
|
+
| get | `get(name, config?, server?)` | `Object` | 获取实例,不存在时创建并缓存;未设置类时抛错 |
|
|
103
|
+
| getAsync | `getAsync(name, config?, server?)` | `Promise<Object>` | 异步获取,新实例创建后执行 `onCreate` 钩子 |
|
|
104
|
+
| has | `has(name)` | `boolean` | 判断实例是否存在 |
|
|
105
|
+
| del | `del(name)` | `boolean` | 删除实例,成功返回 `true`,不存在返回 `false` |
|
|
106
|
+
| clear | `clear()` | `Admin` | 清空实例池,返回自身便于链式调用 |
|
|
107
|
+
| keys | `keys()` | `Iterator<string>` | 按插入顺序返回全部名称迭代器 |
|
|
108
|
+
| values | `values()` | `Iterator<Object>` | 按插入顺序返回全部实例迭代器 |
|
|
109
|
+
|
|
110
|
+
- 实例的 `config` 为创建时传入配置的浅拷贝并自动补充 `name`,**配置仅在首次创建时生效**
|
|
111
|
+
- `get` / `getAsync` 的 `server` 缺省时使用管理器自身的服务器实例
|
|
112
|
+
- `del` 后再次 `get` 同名会创建新实例
|
|
113
|
+
|
|
114
|
+
## 示例
|
|
115
|
+
|
|
116
|
+
仓库内提供可运行示例:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
npm run demo
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
示例代码见 `example/demo.js`,会依次演示实例池缓存、配置生效规则、异步创建钩子、遍历删除与清空。
|
|
123
|
+
|
|
124
|
+
## 测试
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
npm test
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
使用 jest 运行,覆盖构造、类/服务器/钩子的一次性设置、同步与异步获取、缓存与配置规则、删除清空遍历等场景。覆盖率阈值为 100%(语句、分支、函数、行)。
|
|
131
|
+
|
|
132
|
+
## 更新日志
|
|
133
|
+
|
|
134
|
+
### 1.0.0
|
|
135
|
+
|
|
136
|
+
- 提供 `Admin` 管理器类:`setClass` / `getClass` / `setServer` / `getServer` / `onCreate` / `setConfig`
|
|
137
|
+
- 实例池按名称缓存,提供 `get` / `getAsync` / `has` / `del` / `clear` / `keys` / `values` 及 `size`
|
|
138
|
+
- 实例创建钩子仅在异步获取新实例时执行
|
|
139
|
+
- 新增测试与示例,测试覆盖率 100%
|
package/example/demo.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Admin } = require('../index');
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* 示例管理器类
|
|
7
|
+
* 内部用 Map 存储缓存数据,演示 Admin 的实例池管理。
|
|
8
|
+
*/
|
|
9
|
+
class CacheManager {
|
|
10
|
+
/**
|
|
11
|
+
* 构造函数
|
|
12
|
+
* @param {Object} config 管理器配置
|
|
13
|
+
* @param {Object} server 服务器实例
|
|
14
|
+
*/
|
|
15
|
+
constructor(config, server) {
|
|
16
|
+
this.config = config;
|
|
17
|
+
this.server = server;
|
|
18
|
+
this.data = new Map();
|
|
19
|
+
this.ready = false;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* 写入缓存
|
|
24
|
+
* @param {string} key 键名
|
|
25
|
+
* @param {*} value 键值
|
|
26
|
+
*/
|
|
27
|
+
set(key, value) {
|
|
28
|
+
this.data.set(key, value);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* 读取缓存
|
|
33
|
+
* @param {string} key 键名
|
|
34
|
+
* @returns {*} 键值,不存在时返回 undefined
|
|
35
|
+
*/
|
|
36
|
+
get(key) {
|
|
37
|
+
return this.data.get(key);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* 使用示例:演示 Admin 的实例池缓存、创建钩子与删除清空
|
|
43
|
+
*/
|
|
44
|
+
async function runDemo() {
|
|
45
|
+
const admin = new Admin({ debug: true }, { tag: 'server' });
|
|
46
|
+
admin.setClass(CacheManager);
|
|
47
|
+
admin.onCreate(async (manager) => {
|
|
48
|
+
await Promise.resolve();
|
|
49
|
+
manager.ready = true;
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
console.log('=== 基础实例池 ===');
|
|
53
|
+
const cache_a = admin.get('cache:a', { ttl: 60 });
|
|
54
|
+
console.log(' 配置: ' + JSON.stringify(cache_a.config));
|
|
55
|
+
console.log(' 服务器: ' + JSON.stringify(cache_a.server));
|
|
56
|
+
console.log(' 同一名称返回同一实例: ' + (admin.get('cache:a') === cache_a));
|
|
57
|
+
console.log(' 配置仅在首次创建时生效: ' + JSON.stringify(admin.get('cache:a', { ttl: 99 }).config));
|
|
58
|
+
|
|
59
|
+
console.log('=== 异步获取与创建钩子 ===');
|
|
60
|
+
const cache_b = admin.get('cache:b');
|
|
61
|
+
console.log(' 同步创建 ready: ' + cache_b.ready);
|
|
62
|
+
const cache_c = await admin.getAsync('cache:c');
|
|
63
|
+
console.log(' 异步创建 ready: ' + cache_c.ready);
|
|
64
|
+
const cache_c2 = await admin.getAsync('cache:c');
|
|
65
|
+
console.log(' 已存在实例钩子不再执行: ' + (cache_c2 === cache_c));
|
|
66
|
+
|
|
67
|
+
console.log('=== 遍历与删除 ===');
|
|
68
|
+
cache_a.set('user:1', { name: '张三' });
|
|
69
|
+
console.log(' size: ' + admin.size);
|
|
70
|
+
console.log(' keys: ' + JSON.stringify(Array.from(admin.keys())));
|
|
71
|
+
console.log(' has cache:a: ' + admin.has('cache:a'));
|
|
72
|
+
console.log(' del cache:a: ' + admin.del('cache:a'));
|
|
73
|
+
console.log(' del 不存在的名称: ' + admin.del('cache:x'));
|
|
74
|
+
admin.clear();
|
|
75
|
+
console.log(' clear 后 size: ' + admin.size);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
runDemo();
|
package/index.js
ADDED
package/lib/admin.js
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 管理器类
|
|
3
|
+
* 维护按名称缓存的管理器实例池,支持同步/异步获取、创建钩子与清空。
|
|
4
|
+
* 实例池内部使用私有 Map 存储,不对外暴露 Map,避免绕过缓存规则写入。
|
|
5
|
+
*/
|
|
6
|
+
class Admin {
|
|
7
|
+
#class;
|
|
8
|
+
#server;
|
|
9
|
+
#onCreate;
|
|
10
|
+
#map;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* 构造函数
|
|
14
|
+
* @param {Object} config 管理器配置
|
|
15
|
+
* @param {Object} server 服务器实例
|
|
16
|
+
*/
|
|
17
|
+
constructor(config = {}, server) {
|
|
18
|
+
this.#map = new Map();
|
|
19
|
+
this.config = {};
|
|
20
|
+
this.setConfig(config);
|
|
21
|
+
if (server) {
|
|
22
|
+
this.setServer(server);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* 获取实例数量
|
|
28
|
+
* @returns {number} 实例数量
|
|
29
|
+
*/
|
|
30
|
+
get size() {
|
|
31
|
+
return this.#map.size;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* 设置被管理的类
|
|
36
|
+
* 只允许设置一次,重复设置抛错。
|
|
37
|
+
* @param {Function} cs 被管理的类
|
|
38
|
+
* @throws {Error} 类为空或已设置时抛错
|
|
39
|
+
*/
|
|
40
|
+
setClass(cs) {
|
|
41
|
+
if (!cs) {
|
|
42
|
+
throw new Error('类实例不能为空');
|
|
43
|
+
}
|
|
44
|
+
if (this.#class) {
|
|
45
|
+
throw new Error('类实例已设置');
|
|
46
|
+
}
|
|
47
|
+
this.#class = cs;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* 获取被管理的类
|
|
52
|
+
* @returns {Function|undefined} 被管理的类
|
|
53
|
+
*/
|
|
54
|
+
getClass() {
|
|
55
|
+
return this.#class;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* 设置服务器实例
|
|
60
|
+
* 只允许设置一次,重复设置抛错。
|
|
61
|
+
* @param {Object} server 服务器实例
|
|
62
|
+
* @throws {Error} 服务器为空或已设置时抛错
|
|
63
|
+
*/
|
|
64
|
+
setServer(server) {
|
|
65
|
+
if (!server) {
|
|
66
|
+
throw new Error('服务器实例不能为空');
|
|
67
|
+
}
|
|
68
|
+
if (this.#server) {
|
|
69
|
+
throw new Error('服务器实例已设置');
|
|
70
|
+
}
|
|
71
|
+
this.#server = server;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 获取服务器实例
|
|
76
|
+
* @returns {Object|undefined} 服务器实例
|
|
77
|
+
*/
|
|
78
|
+
getServer() {
|
|
79
|
+
return this.#server;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* 注册实例创建钩子
|
|
84
|
+
* 新实例创建后由 getAsync 调用,可执行异步初始化。只允许设置一次,重复设置抛错。
|
|
85
|
+
* @param {Function} fn 创建钩子,接收实例参数,可返回 Promise
|
|
86
|
+
* @throws {Error} 钩子不是函数或已设置时抛错
|
|
87
|
+
*/
|
|
88
|
+
onCreate(fn) {
|
|
89
|
+
if (typeof fn !== 'function') {
|
|
90
|
+
throw new Error('创建钩子必须是函数');
|
|
91
|
+
}
|
|
92
|
+
if (this.#onCreate) {
|
|
93
|
+
throw new Error('创建钩子已设置');
|
|
94
|
+
}
|
|
95
|
+
this.#onCreate = fn;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* 设置管理器配置
|
|
100
|
+
* 与已有配置浅合并,后传入的同名键覆盖旧值。
|
|
101
|
+
* @param {Object} config 管理器配置
|
|
102
|
+
*/
|
|
103
|
+
setConfig(config) {
|
|
104
|
+
this.config = { ...this.config, ...config };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* 获取管理器实例
|
|
109
|
+
* 实例不存在时创建并缓存;配置中的 name 始终以传入名称为准,避免被外部覆盖。
|
|
110
|
+
* @param {string} name 管理器名称
|
|
111
|
+
* @param {Object} config 管理器配置,仅在首次创建时生效
|
|
112
|
+
* @param {Object} server 服务器实例,缺省时使用管理器自身的服务器
|
|
113
|
+
* @returns {Object} 管理器实例
|
|
114
|
+
* @throws {Error} 未设置被管理的类时抛错
|
|
115
|
+
*/
|
|
116
|
+
get(name, config, server) {
|
|
117
|
+
let mod = this.#map.get(name);
|
|
118
|
+
if (!mod) {
|
|
119
|
+
if (!this.#class) {
|
|
120
|
+
throw new Error('请先设置类实例');
|
|
121
|
+
}
|
|
122
|
+
const cg = config ? { ...config } : {};
|
|
123
|
+
cg.name = name;
|
|
124
|
+
mod = new this.#class(cg, server || this.#server);
|
|
125
|
+
this.#map.set(name, mod);
|
|
126
|
+
}
|
|
127
|
+
return mod;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* 异步获取管理器实例
|
|
132
|
+
* 实例不存在时创建并执行 onCreate 钩子后返回;已存在时直接返回。
|
|
133
|
+
* @param {string} name 管理器名称
|
|
134
|
+
* @param {Object} config 管理器配置,仅在首次创建时生效
|
|
135
|
+
* @param {Object} server 服务器实例,缺省时使用管理器自身的服务器
|
|
136
|
+
* @returns {Promise<Object>} 管理器实例
|
|
137
|
+
*/
|
|
138
|
+
async getAsync(name, config, server) {
|
|
139
|
+
const existed = this.has(name);
|
|
140
|
+
const manager = this.get(name, config, server);
|
|
141
|
+
if (!existed && this.#onCreate) {
|
|
142
|
+
await this.#onCreate(manager);
|
|
143
|
+
}
|
|
144
|
+
return manager;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* 判断管理器实例是否存在
|
|
149
|
+
* @param {string} name 管理器名称
|
|
150
|
+
* @returns {boolean} 是否存在
|
|
151
|
+
*/
|
|
152
|
+
has(name) {
|
|
153
|
+
return this.#map.has(name);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* 删除管理器实例
|
|
158
|
+
* @param {string} name 管理器名称
|
|
159
|
+
* @returns {boolean} 是否删除成功
|
|
160
|
+
*/
|
|
161
|
+
del(name) {
|
|
162
|
+
return this.#map.delete(name);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* 清空全部管理器实例
|
|
167
|
+
* @returns {Admin} 管理器自身,便于链式调用
|
|
168
|
+
*/
|
|
169
|
+
clear() {
|
|
170
|
+
this.#map.clear();
|
|
171
|
+
return this;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* 获取所有管理器名称
|
|
176
|
+
* @returns {Iterator<string>} 管理器名称迭代器
|
|
177
|
+
*/
|
|
178
|
+
keys() {
|
|
179
|
+
return this.#map.keys();
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* 获取所有管理器实例
|
|
184
|
+
* @returns {Iterator<Object>} 管理器实例迭代器
|
|
185
|
+
*/
|
|
186
|
+
values() {
|
|
187
|
+
return this.#map.values();
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
module.exports = Admin;
|
package/package.json
CHANGED
|
@@ -1,6 +1,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mm_admin",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "管理器实例池模块,基于 Map 按名称缓存管理器实例,提供同步/异步获取、创建钩子、删除与清空(setClass/get/del/clear/keys/values)。",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"mm_mod",
|
|
7
|
+
"mm_infra",
|
|
8
|
+
"mm_common",
|
|
9
|
+
"超级美眉",
|
|
10
|
+
"管理器",
|
|
11
|
+
"实例池",
|
|
12
|
+
"admin"
|
|
13
|
+
],
|
|
14
|
+
"layer": "shared",
|
|
15
|
+
"group": "kernel",
|
|
16
|
+
"author": "邱文武",
|
|
17
|
+
"license": "ISC",
|
|
18
|
+
"main": "index.js",
|
|
19
|
+
"files": [
|
|
20
|
+
"index.js",
|
|
21
|
+
"lib",
|
|
22
|
+
"example"
|
|
23
|
+
],
|
|
24
|
+
"directories": {
|
|
25
|
+
"example": "example",
|
|
26
|
+
"lib": "lib"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"test": "jest --coverage",
|
|
30
|
+
"demo": "node example/demo.js",
|
|
31
|
+
"prepublishOnly": "npm test"
|
|
32
|
+
},
|
|
33
|
+
"devDependencies": {
|
|
34
|
+
"jest": "^30.5.2"
|
|
35
|
+
}
|
|
36
|
+
}
|