1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598<!--
* @Author: chenzhongsheng
* @Date: 2023-02-13 17:02:26
* @Description: Coding something
-->
<p align="center">
<img src='https://shiyix.cn/images/sener.png' width='120px'/>
</p>
<p align="center">
<a href="https://www.github.com/theajack/sener/stargazers" target="_black">
<img src="https://img.shields.io/github/stars/theajack/sener?logo=github" alt="stars" />
</a>
<a href="https://www.github.com/theajack/sener/network/members" target="_black">
<img src="https://img.shields.io/github/forks/theajack/sener?logo=github" alt="forks" />
</a>
<a href="https://www.npmjs.com/package/sener" target="_black">
<img src="https://img.shields.io/npm/v/sener?logo=npm" alt="version" />
</a>
<a href="https://www.npmjs.com/package/sener" target="_black">
<img src="https://img.shields.io/npm/dm/sener?color=%23ffca28&logo=npm" alt="downloads" />
</a>
<a href="https://www.jsdelivr.com/package/npm/sener" target="_black">
<img src="https://data.jsdelivr.com/v1/package/npm/sener/badge" alt="jsdelivr" />
</a>
</p>
<p align="center">
<a href="https://github.com/theajack" target="_black">
<img src="https://img.shields.io/badge/Author-%20theajack%20-7289da.svg?&logo=github" alt="author" />
</a>
<a href="https://www.github.com/theajack/sener/blob/master/LICENSE" target="_black">
<img src="https://img.shields.io/github/license/theajack/sener?color=%232DCE89&logo=github" alt="license" />
</a>
<a href="https://fastly.jsdelivr.net/gh/theajack/sener/dist/sener.latest.min.js"><img src="https://img.shields.io/bundlephobia/minzip/sener.svg" alt="Size"></a>
<a href="https://github.com/theajack/sener/search?l=javascript"><img src="https://img.shields.io/github/languages/top/theajack/sener.svg" alt="TopLang"></a>
<a href="https://github.com/theajack/sener/issues"><img src="https://img.shields.io/github/issues-closed/theajack/sener.svg" alt="issue"></a>
<a href="https://www.github.com/theajack/sener"><img src="https://img.shields.io/librariesio/dependent-repos/npm/sener.svg" alt="Dependent"></a>
</p>
<h3>🚀 简单易用、功能强大、高可扩展的nodejs http服务器</h3>
**[在线Demo](https://stackblitz.com/github/sener-js/sener-demo?file=index.js) | [文档](https://theajack.github.io/sener/) | [English](https://github.com/theajack/sener) | [更新日志](https://github.com/theajack/cnchar/blob/master/scripts/version.cn.md) | [反馈](https://github.com/theajack/sener/issues/new) | [Gitee](https://gitee.com/theajack/sener) | [留言板](https://theajack.github.io/message-board/?app=sener)**
## 1. 特性
1. 简单高效的架构，全ts编写，高度友好的ts声明支持
2. 支持高度自定义和高可扩展的中间件体系，采用洋葱模型，丰富的路由hooks
内置中间件：
内置中间件为sener包中自带的中间 但是使用时也需要手动引入
1. router：简单高可扩展的路由规则
2. cookie：用于cookie获取和注入
3. session：用于session获取和注入（依赖cookie）
4. env：用于注入和使用环境变量
5. cors：支持跨域请求
6. ip-monitor：用于对请求ip进行风控拦截
7. validator：支持验证入参和参数类型定义
独立中间件：
使用独立中间需要安装对应的独立包
1. json：支持json文件用于数据存储
2. static：支持静态文件目录
3. form：支持formdata解析和文件上传
4. config：支持高度灵活的参数配置和动态变更与监听
5. log：支持灵活的日志体系，支持日志级别控制
6. mysql：支持mysql连接
7. mongodb：支持mongodb连接，collocation的封装
8. rpc：远程调用支持，支持客户端和服务端使用，支持注入请求的x-trace-id
## 2. 基础使用
```
npm i sener
```
最简demo:
```js
import {Sener} from 'sener';
new Sener();
```
options:
```js
new Sener({
port: 9000, // port: default value is 9000
middlewares: [], // Sener middlewares
});
```
### 最佳实践
1. 使用ebuild-cli
```
npm i ebuild-cli -g
ebuild init <Project name>
cd <Project name>
npm i
```
在随后的模式选择中 选择 sener 即可
2. 从[github地址](https://github.com/theajack/sener-best-practice)上拷贝
```
git clone https://github.com/theajack/sener-best-practice.git
```
## 3. 中间件
### 3.1 router
路由中间件
```js
import {Sener, Router} from 'sener';
const router = new Router({
'/demo': ({ query }) => {
// or: 'get:/demo': ({ query }) => { // get: prefix can be ignored
query.message = 'from get';
return { data: query };
// Custom headers or statusCode
// return { data: query, headers: {}, statusCode: 200 };
},
'post:/demo': async ({ body }) => {
body.message = 'from post'
return { data: body };
},
});
new Sener({
middlewares: [router],
});
```
### 3.2 json
使用json文件进行数据存储
```
npm i sener sener-json
```
```js
import {Sener, Router} from 'sener';
import {Json} from 'sener-json';
const router = new Router({
'/data': ({ query, read }) => {
// 'data' is json file name
return { data: read('data') };
},
'post:/data': async ({ body, write }) => {
const { data, save, id } = write('aa');
body.message = 'from post'
data.push({...body, id: id()}); // Add increment id
save(); // save it, THIS Method must be called
return { data };
},
});
new Sener({
middlewares: [router, new Json()],
});
```
可选参数：
```js
new Json({
dir: '', // directory for save json files. default value is ''
format: false, // Whether to format the JSON file. Default value: The development environment is false and the production environment is true
})
```
### 3.3 cors
```
npm i sener sener-cors
```
支持跨域请求的中间件
```js
import {Sener, Cors} from 'sener';
new Sener({
middlewares: [new Cors()],
// new Cors(header); Or Set your custom headers
});
```
可选参数
```js
new Cors({
// headers: Set your custom headers
})
```
### 3.4 static
支持静态资源的中间件
```
npm i sener sener-static
```
```js
import {Sener} from 'sener';
import {Static} from 'sener-static';
new Sener({
middlewares: [new Static()],
// new Static({dir}); dir default value is ./public
});
```
可选参数：
```js
new Static({
dir: './public', // Static directory, default value is ./public
})
```
### 3.5 form
支持form表单和文件上传的中间件
```
npm i sener sener-form
```
```js
import {Sener, Router} from 'sener';
import {Form} from 'sener-form';
const router = new Router({
'post:/upload': ({ formData, files }) => {
return { formData, files }
},
});
new Sener({
middlewares: [new Form(), router],
// new Form({dir}); dir default value is ./public
});
```
可选参数
```js
new Form({
dir: './public/upload', // File upload directory, default value is ./public/upload
})
```
### 3.6 log
支持日志打印和控制的中间件
```
npm i sener sener-log
```
```js
import {Sener, Router} from 'sener';
import {Log} from 'sener-log';
const router = new Router({
'get:/test': ({ query, logger }) => {
logger.log('msg', 'payload')
return { data: query }
},
});
new Sener({
middlewares: [new Log(), router],
});
```
声明文件
```ts
class Logger {
log(msg: string | IMessageData, payload?: any, type?: TLogType): void;
get traceid (): string;
refreshDurationStart(): void;
refreshTraceId(): void;
}
interface IMessageData {
msg?: string;
payload?: any;
type?: 'error' | 'log' | 'warn' | 'info';
level?: number;
extend?: object;
}
```
可选参数
```js
new Log({
dir: ''， // 存储日志文件的目录。默认值为“”，使用根目录
useConsole: false, // 是否启用控制台.log服务运行时打印日志。不建议打开生产环境。默认值为 false
maxRecords: 10000, // 单个日志文件的最大存储记录数，默认值为 10000
level: -1, // 日志打印级别，级别小于此数字的日志将不打印
// level?: ()=>number // 级别也可以是一种动态获取级别值的方法，通常与配置中间件结合使用
})
```
### 3.7 config
支持灵活使用 JSON 配置文件的中间件
```
npm i sener sener-config
```
```js
import {Sener, Router} from 'sener';
import {Config} from 'sener-config';
const router = new Router({
'get:/test': ({ query, config, writeConfig, onConfigChange }) => {
const level = config.level;
level(); // read config
level(5); // write config
writeConfig('level', 5) // write config with writeConfig
onConfigChange(({key, value, prev}) => { // on config change
console.log(key, value, prev);
})
return { data: query }
},
});
const config = new Config();
// Use config instance
config.onConfigChange(({key, value, prev}) => { // on config change
console.log(key, value, prev);
});
config.data.level(); // read config
config.data.level(5); // write config
config.writeConfig('level', 2); // write config with writeConfig
new Sener({
middlewares: [config, router],
});
```
options
```ts
new Config({
dir: '', // 用于保存配置文件的目录。默认值为“”
initial: {}, // 初始化配置文件列表，key表示文件名(不需要带.json后缀)，值表示配置内容。默认值为 {_default: {}}
format: false, // 是否格式化 JSON 文件。默认值：开发环境为假，生产环境为真
})
```
### 3.8 mysql
支持mysql连接的中间件
```
npm i sener sener-mysql
```
```js
import {Sener, Router} from 'sener';
import {Mysql} from 'sener-mysql';
const router = new Router({
'get:/test': async ({ query, querySql, mysqlConn }) => {
const { results, fields } = await querySql('select * from user');
// Or use mysqlConn
return { data: query }
},
});
const mysql = new Mysql({
// 详情请参考 [mysql](https://www.npmjs.com/package/mysql)
}
mysql.connection;
new Sener({
middlewares: [mysql, router],
});
```
详情请参考 [mysql](https://www.npmjs.com/package/mysql)
### 3.8.1 封装
SQL中间件封装了对表的基本操作，使得开发者可以使用API便捷的操作数据表，详情请[参考文档](https://theajack.github.io/sener-docs/doc/mysql.html)
### 3.9 mongodb
支持mongodb连接的中间件
```
npm i sener sener-mongodb
```
```js
import {Sener, Router} from 'sener';
import {Mongo} from 'sener-mongodb';
const router = new Router({
'get:/test': async ({ query, queryMongoDB, mongoClient }) => {
const {db, close} = await queryMongoDB('user');
// do something
// Or use mongoClient
return { data: query }
},
});
const mongodb = new Mongo({
// 详情请参考 [mongodb](https://www.npmjs.com/package/mongodb)
})
mongodb.client;
new Sener({
middlewares: [mongodb, router],
});
```
详情请参考 [mongodb](https://www.npmjs.com/package/mongodb)
#### 3.9.1 封装
mongodb中间件封装了对col的基本操作，使得开发者可以使用API便捷的操作数据表，详情请[参考文档](https://theajack.github.io/sener-docs/doc/mongodb.html)
### 3.10 rpc middleware
rpc 中间件作用是对部署在不同服务器或者同一服务器不同端口上的服务进行远程调用，可以让开发者像函数调用一样像远程服务发起请求
也可用于web客户端像服务端发起请求的场景
该中间还会向请求中注入 x-trace-id header来保证同一次访问调用的接口有相同的tracid，与log中间件配合使用可以很有效的定位问题
```
npm i sener sener-rpc
```
#### 3.10.1 服务端使用
1. 使用配置
```js
import {Sener, Router} from 'sener';
import {RPC} from 'sener-rpc';
const router = new Router({
'get:/test': async ({ query, rpc }) => {
const list = rpc.comment.get('/message', {page: 1}); // url and query
// use rpc.comment.request for more details
return { data: {query, list} }
},
});
new Sener({
middlewares: [new RPC({
user: 'http://localhost:3000', // user 服务的访问base地址
comment: 'http://localhost:3001', // comment 服务的访问base地址
}), router],
});
```
2. 使用createServices函数
```js
import {Sener, Router} from 'sener';
import {RPC, Request} from 'sener-rpc';
class CommentRequest extends Request {
getList ({ app = 'common', index = 1 }: {
app?: string
index?: number
} = {}) {
return this.get('/message', {
app,
index,
size: 10,
});
}
}
function createServices(traceid = '') {
const base = (port: number) => `http://localhost:${port}`;
return {
comment: new CommentRequest({ base: base(3001), traceid }),
};
}
const router = new Router({
'get:/test': async ({ query, rpc }) => {
const list = rpc.comment.getList();
return { data: {query, list} }
},
});
new Sener({
middlewares: [new RPC(createServices), router],
});
```
#### 3.10.1 客户端使用
1. npm 安装使用
```
npm i sener-rpc
```
```js
import {WebRPC} from 'sener-rpc/dist/web.umd';
// 1. 单个服务可以传入base地址
const comment = new WebRPC('http://localhost:3001');
await comment.get('/message', {page: 1});
// 2. 多个服务传入map
const rpc = new WebRPC({
user: 'http://localhost:3000', // user 服务的访问base地址
comment: 'http://localhost:3001', // comment 服务的访问base地址
});
await rpc.comment.get('/message', {page: 1});
// 3. 使用继承方式
class Comment extends WebRPC {
getList ({ app = 'common', index = 1 }: {
app?: string
index?: number
} = {}) {
return this.get('/message', {
app,
index,
size: 10,
});
}
}
await (new Comment()).getList();
```
2. cdn 使用
```html
<script src='https://cdn.jsdelivr.net/npm/sener-rpc'></script>
<script>
SenerRpc.WebRPC
</script>
```
## 其他
1. Dir
Sener 默认将所有数据文件存储在 ~/sener-data 文件夹中
```js
let BASE_SENER_DIR = path.resolve(homedir(), './sener-data')
```
如果想要修改这个目录，请使用sener静态属性
```ts
Sener.Dir = 'xxxxx'
```
2. Version
获取版本号
```ts
Sener.Version
```
## 自定义中间件
文档将持续完善中
现在请参考 [中间件包](https://github.com/theajack/sener/blob/master/packages)