@dangao/bun-server 0.1.1 → 0.1.3
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/LICENSE +22 -0
- package/package.json +5 -4
- package/readme.md +187 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 dangaogit
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dangao/bun-server",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"types": "./dist/index.d.ts",
|
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
],
|
|
26
26
|
"files": [
|
|
27
27
|
"dist",
|
|
28
|
-
"
|
|
29
|
-
"
|
|
28
|
+
"readme.md",
|
|
29
|
+
"LICENSE"
|
|
30
30
|
],
|
|
31
31
|
"author": "dangaogit",
|
|
32
32
|
"license": "MIT",
|
|
@@ -45,7 +45,8 @@
|
|
|
45
45
|
"bundle": "bun build src/index.ts --target=bun --format=esm --outfile=dist/index.js --external reflect-metadata --external @dangao/logsmith",
|
|
46
46
|
"dts": "tsc -p tsconfig.build.json",
|
|
47
47
|
"build": "bun run clean && bun run bundle && bun run dts",
|
|
48
|
-
"prepare": "bun run build"
|
|
48
|
+
"prepare": "bun run build",
|
|
49
|
+
"publish": "cp ../../readme.md ../../LICENSE . && bun publish --access public && rm -f ./readme.md ./LICENSE"
|
|
49
50
|
},
|
|
50
51
|
"devDependencies": {
|
|
51
52
|
"typescript": "5.9.3",
|
package/readme.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# Bun Server
|
|
2
|
+
|
|
3
|
+
[](https://bun.sh/)
|
|
4
|
+
[](https://www.typescriptlang.org/)
|
|
5
|
+
[](#许可证)
|
|
6
|
+
|
|
7
|
+
> Bun Server 是一个运行在 Bun Runtime 上的高性能、装饰器驱动的 DI Web
|
|
8
|
+
> 框架，目标是为企业级应用提供即开即用的现代体验。
|
|
9
|
+
|
|
10
|
+
- [Bun Server](#@dangao/bun-server)
|
|
11
|
+
- [为什么选择 Bun Server](#为什么选择-@dangao/bun-server)
|
|
12
|
+
- [核心特性](#核心特性)
|
|
13
|
+
- [架构总览](#架构总览)
|
|
14
|
+
- [快速上手](#快速上手)
|
|
15
|
+
- [示例与扩展](#示例与扩展)
|
|
16
|
+
- [性能与 Benchmark](#性能与-benchmark)
|
|
17
|
+
- [文档与多语言支持](#文档与多语言支持)
|
|
18
|
+
- [路线图](#路线图)
|
|
19
|
+
- [工程规范](#工程规范)
|
|
20
|
+
- [贡献指南](#贡献指南)
|
|
21
|
+
- [许可证](#许可证)
|
|
22
|
+
- [其他语言](#其他语言)
|
|
23
|
+
|
|
24
|
+
## 为什么选择 Bun Server
|
|
25
|
+
|
|
26
|
+
- **原生 Bun**：充分利用 Bun Runtime 的高性能 I/O、原生 TypeScript
|
|
27
|
+
与极速包管理器。
|
|
28
|
+
- **现代 DX**：大量使用装饰器、元数据与
|
|
29
|
+
DI，让控制器、服务、路由、验证与中间件的编写极其顺滑。
|
|
30
|
+
- **轻量 +
|
|
31
|
+
可扩展**：松耦合的模块系统、扩展系统与日志框架，既可以快速起步，也能按需裁剪。
|
|
32
|
+
- **Monorepo 友好**：原生支持 Bun workspaces，使用 `workspace:*`
|
|
33
|
+
协议管理内部依赖，配合 catalog 统一版本，完美适配多包协作场景。
|
|
34
|
+
- **完整测试矩阵**：内置单元/集成测试、压力与基准测试用例，便于持续优化。
|
|
35
|
+
|
|
36
|
+
## 核心特性
|
|
37
|
+
|
|
38
|
+
- 🚀 **高性能 HTTP 栈**：基于 `Bun.serve`，提供轻量
|
|
39
|
+
`Application`、`Router`、`Context` 封装。
|
|
40
|
+
- 🧩
|
|
41
|
+
**依赖注入容器**：`Container`、`@Injectable()`、`@Inject()`、模块系统、生命周期管理与自动依赖计划缓存。
|
|
42
|
+
- 🧵
|
|
43
|
+
**中间件管道**：支持全局/控制器/方法级中间件，内置日志、错误处理、CORS、文件上传、静态资源等。
|
|
44
|
+
- ✅ **输入校验**：声明式验证装饰器，直连 `ValidationError` 与异常过滤器。
|
|
45
|
+
- 📡 **WebSocket**：`@WebSocketGateway`、`@OnMessage` 等装饰器级开发体验。
|
|
46
|
+
- 📚 **示例与文档**：多语言文档、基础/完整示例、基准脚本与最佳实践。
|
|
47
|
+
|
|
48
|
+
## 架构总览
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
┌───────────────────────────────┐
|
|
52
|
+
│ Application │
|
|
53
|
+
│ (Controllers / Modules / DI) │
|
|
54
|
+
└───────────────────────────────┘
|
|
55
|
+
↓
|
|
56
|
+
┌───────────────────────────────┐
|
|
57
|
+
│ Middleware Pipeline │
|
|
58
|
+
│ Logging / Error / Custom ... │
|
|
59
|
+
└───────────────────────────────┘
|
|
60
|
+
↓
|
|
61
|
+
┌───────────────────────────────┐
|
|
62
|
+
│ Router + Context + Response │
|
|
63
|
+
└───────────────────────────────┘
|
|
64
|
+
↓
|
|
65
|
+
┌───────────────────────────────┐
|
|
66
|
+
│ Bun Runtime │
|
|
67
|
+
└───────────────────────────────┘
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## 快速上手
|
|
71
|
+
|
|
72
|
+
### 环境要求
|
|
73
|
+
|
|
74
|
+
- Bun ≥ `1.3.3`
|
|
75
|
+
- Node.js / npm 只在极少数脚手架场景使用
|
|
76
|
+
|
|
77
|
+
### 安装依赖
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
bun install
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Hello World 控制器
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import "reflect-metadata";
|
|
87
|
+
import { Application, Controller, GET, Injectable } from "@dangao/bun-server";
|
|
88
|
+
|
|
89
|
+
@Injectable()
|
|
90
|
+
class HealthService {
|
|
91
|
+
public ping() {
|
|
92
|
+
return { status: "ok" };
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
@Controller("/api")
|
|
97
|
+
class HealthController {
|
|
98
|
+
public constructor(private readonly service: HealthService) {}
|
|
99
|
+
|
|
100
|
+
@GET("/health")
|
|
101
|
+
public check() {
|
|
102
|
+
return this.service.ping();
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const app = new Application({ port: 3100 });
|
|
107
|
+
app.getContainer().register(HealthService);
|
|
108
|
+
app.registerController(HealthController);
|
|
109
|
+
app.listen();
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### 常用脚本
|
|
113
|
+
|
|
114
|
+
> 代码位于 `packages/@dangao/bun-server/`，以下命令请在该目录执行。
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
bun --cwd=packages/@dangao/bun-server test # 运行测试
|
|
118
|
+
bun --cwd=benchmark run bench # 执行所有基准测试
|
|
119
|
+
bun --cwd=benchmark run bench:router # 仅运行路由基准
|
|
120
|
+
bun --cwd=benchmark run bench:di # 仅运行 DI 基准
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
> 直接在仓库根目录运行 `bun test`
|
|
124
|
+
> 会因为工作区结构导致无法找到源文件，请使用上面的命令或先进入
|
|
125
|
+
> `packages/@dangao/bun-server/`。
|
|
126
|
+
|
|
127
|
+
## 示例与扩展
|
|
128
|
+
|
|
129
|
+
- `examples/basic-app.ts`：最小可运行示例，覆盖 DI + Logger + Middleware。
|
|
130
|
+
- `examples/full-app.ts`：包含验证、文件上传、WebSocket、复杂控制器。
|
|
131
|
+
- `examples/multi-module-app.ts`：多模块示例，展示模块间的依赖关系和服务共享。
|
|
132
|
+
- `packages/@dangao/bun-server/src/extensions/`：官方扩展（如
|
|
133
|
+
LoggerExtension），可用于注册第三方能力。
|
|
134
|
+
|
|
135
|
+
## 性能与 Benchmark
|
|
136
|
+
|
|
137
|
+
`benchmark/` 目录提供可复现脚本：
|
|
138
|
+
|
|
139
|
+
| Script | 描述 |
|
|
140
|
+
| ----------------- | ------------------------------------------ |
|
|
141
|
+
| `router.bench.ts` | 静态/动态路由命中、handle 以及压力测试 |
|
|
142
|
+
| `di.bench.ts` | 单例解析、嵌套依赖解析、工厂解析与并发测试 |
|
|
143
|
+
|
|
144
|
+
运行方式：
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
bun benchmark/router.bench.ts
|
|
148
|
+
bun benchmark/di.bench.ts
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
或使用 `bun run bench*` 脚本批量执行，结果会以表格形式打印。
|
|
152
|
+
|
|
153
|
+
## 文档与多语言支持
|
|
154
|
+
|
|
155
|
+
- 中文默认文档位于 `docs/`
|
|
156
|
+
- `docs/api.md`
|
|
157
|
+
- `docs/guide.md`
|
|
158
|
+
- `docs/best-practices.md`
|
|
159
|
+
- `docs/migration.md`
|
|
160
|
+
- 英文草稿位于
|
|
161
|
+
`docs/en/`，与中文文件结构一致；如果缺失内容，请优先参考中文版本。
|
|
162
|
+
|
|
163
|
+
## 路线图
|
|
164
|
+
|
|
165
|
+
详细路线图、阶段目标与完成情况请查阅 [`.roadmap.md`](./.roadmap.md)。
|
|
166
|
+
|
|
167
|
+
## 工程规范
|
|
168
|
+
|
|
169
|
+
- **注释 & 日志**：统一使用英文，确保国际化友好。
|
|
170
|
+
- **Docs**：默认中文，同时在 `docs/en/` 提供英文版本。
|
|
171
|
+
- **基准脚本**：存放于 `benchmark/`，运行前请确保在 Bun 环境下执行。
|
|
172
|
+
|
|
173
|
+
## 贡献指南
|
|
174
|
+
|
|
175
|
+
1. Fork & 创建特性分支
|
|
176
|
+
2. 提交前运行 `bun test` 和相关 benchmark
|
|
177
|
+
3. 提交 PR 时请附带变更说明与必要的测试数据
|
|
178
|
+
|
|
179
|
+
欢迎通过 Issue / Discussion 反馈需求或性能瓶颈。
|
|
180
|
+
|
|
181
|
+
## 许可证
|
|
182
|
+
|
|
183
|
+
本项目基于 [MIT License](./LICENSE) 开源。
|
|
184
|
+
|
|
185
|
+
## 其他语言
|
|
186
|
+
|
|
187
|
+
- [English README](./readme_en.md)
|