befly 3.10.17 → 3.10.19

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.
Files changed (218) hide show
  1. package/README.md +83 -307
  2. package/dist/befly.config.d.ts +7 -0
  3. package/{befly.config.ts → dist/befly.config.js} +8 -31
  4. package/dist/checks/checkApi.d.ts +1 -0
  5. package/{checks/checkApi.ts → dist/checks/checkApi.js} +10 -27
  6. package/dist/checks/checkHook.d.ts +1 -0
  7. package/{checks/checkHook.ts → dist/checks/checkHook.js} +10 -19
  8. package/dist/checks/checkMenu.d.ts +7 -0
  9. package/{checks/checkMenu.ts → dist/checks/checkMenu.js} +15 -50
  10. package/dist/checks/checkPlugin.d.ts +1 -0
  11. package/{checks/checkPlugin.ts → dist/checks/checkPlugin.js} +10 -19
  12. package/dist/checks/checkTable.d.ts +6 -0
  13. package/{checks/checkTable.ts → dist/checks/checkTable.js} +16 -40
  14. package/dist/configs/presetFields.d.ts +4 -0
  15. package/{configs/presetFields.ts → dist/configs/presetFields.js} +1 -1
  16. package/dist/configs/presetRegexp.d.ts +145 -0
  17. package/{utils/regex.ts → dist/configs/presetRegexp.js} +8 -31
  18. package/dist/hooks/auth.d.ts +5 -0
  19. package/{hooks/auth.ts → dist/hooks/auth.js} +5 -9
  20. package/dist/hooks/cors.d.ts +9 -0
  21. package/{hooks/cors.ts → dist/hooks/cors.js} +2 -12
  22. package/dist/hooks/parser.d.ts +12 -0
  23. package/{hooks/parser.ts → dist/hooks/parser.js} +27 -42
  24. package/dist/hooks/permission.d.ts +12 -0
  25. package/{hooks/permission.ts → dist/hooks/permission.js} +11 -22
  26. package/dist/hooks/validator.d.ts +9 -0
  27. package/{hooks/validator.ts → dist/hooks/validator.js} +5 -12
  28. package/dist/lib/asyncContext.d.ts +21 -0
  29. package/dist/lib/asyncContext.js +27 -0
  30. package/dist/lib/cacheHelper.d.ts +95 -0
  31. package/{lib/cacheHelper.ts → dist/lib/cacheHelper.js} +43 -103
  32. package/dist/lib/cacheKeys.d.ts +23 -0
  33. package/{lib/cacheKeys.ts → dist/lib/cacheKeys.js} +5 -10
  34. package/dist/lib/cipher.d.ts +153 -0
  35. package/{lib/cipher.ts → dist/lib/cipher.js} +23 -44
  36. package/dist/lib/connect.d.ts +91 -0
  37. package/{lib/connect.ts → dist/lib/connect.js} +46 -87
  38. package/dist/lib/dbDialect.d.ts +87 -0
  39. package/{lib/dbDialect.ts → dist/lib/dbDialect.js} +32 -112
  40. package/dist/lib/dbHelper.d.ts +204 -0
  41. package/{lib/dbHelper.ts → dist/lib/dbHelper.js} +73 -230
  42. package/dist/lib/dbUtils.d.ts +68 -0
  43. package/{lib/dbUtils.ts → dist/lib/dbUtils.js} +49 -123
  44. package/dist/lib/jwt.d.ts +13 -0
  45. package/{lib/jwt.ts → dist/lib/jwt.js} +11 -32
  46. package/dist/lib/logger.d.ts +32 -0
  47. package/{lib/logger.ts → dist/lib/logger.js} +201 -278
  48. package/dist/lib/redisHelper.d.ts +185 -0
  49. package/{lib/redisHelper.ts → dist/lib/redisHelper.js} +95 -139
  50. package/dist/lib/sqlBuilder.d.ts +160 -0
  51. package/{lib/sqlBuilder.ts → dist/lib/sqlBuilder.js} +131 -277
  52. package/dist/lib/sqlCheck.d.ts +23 -0
  53. package/{lib/sqlCheck.ts → dist/lib/sqlCheck.js} +24 -41
  54. package/dist/lib/validator.d.ts +45 -0
  55. package/{lib/validator.ts → dist/lib/validator.js} +43 -60
  56. package/dist/loader/loadApis.d.ts +12 -0
  57. package/{loader/loadApis.ts → dist/loader/loadApis.js} +7 -17
  58. package/dist/loader/loadHooks.d.ts +8 -0
  59. package/{loader/loadHooks.ts → dist/loader/loadHooks.js} +5 -19
  60. package/dist/loader/loadPlugins.d.ts +8 -0
  61. package/{loader/loadPlugins.ts → dist/loader/loadPlugins.js} +8 -20
  62. package/dist/main.d.ts +26 -0
  63. package/{main.ts → dist/main.js} +39 -78
  64. package/dist/paths.d.ts +93 -0
  65. package/{paths.ts → dist/paths.js} +6 -19
  66. package/dist/plugins/cache.d.ts +14 -0
  67. package/{plugins/cache.ts → dist/plugins/cache.js} +4 -11
  68. package/dist/plugins/cipher.d.ts +10 -0
  69. package/{plugins/cipher.ts → dist/plugins/cipher.js} +1 -5
  70. package/dist/plugins/config.d.ts +10 -0
  71. package/dist/plugins/config.js +6 -0
  72. package/dist/plugins/db.d.ts +14 -0
  73. package/{plugins/db.ts → dist/plugins/db.js} +5 -13
  74. package/dist/plugins/jwt.d.ts +10 -0
  75. package/{plugins/jwt.ts → dist/plugins/jwt.js} +2 -7
  76. package/dist/plugins/logger.d.ts +28 -0
  77. package/{plugins/logger.ts → dist/plugins/logger.js} +2 -7
  78. package/dist/plugins/redis.d.ts +14 -0
  79. package/{plugins/redis.ts → dist/plugins/redis.js} +4 -9
  80. package/dist/plugins/tool.d.ts +79 -0
  81. package/{plugins/tool.ts → dist/plugins/tool.js} +7 -30
  82. package/dist/router/api.d.ts +14 -0
  83. package/dist/router/api.js +107 -0
  84. package/dist/router/static.d.ts +9 -0
  85. package/{router/static.ts → dist/router/static.js} +17 -31
  86. package/dist/scripts/ensureDist.d.ts +1 -0
  87. package/dist/scripts/ensureDist.js +80 -0
  88. package/dist/sync/syncApi.d.ts +3 -0
  89. package/{sync/syncApi.ts → dist/sync/syncApi.js} +33 -53
  90. package/dist/sync/syncCache.d.ts +2 -0
  91. package/{sync/syncCache.ts → dist/sync/syncCache.js} +1 -6
  92. package/dist/sync/syncDev.d.ts +6 -0
  93. package/{sync/syncDev.ts → dist/sync/syncDev.js} +27 -60
  94. package/dist/sync/syncMenu.d.ts +14 -0
  95. package/{sync/syncMenu.ts → dist/sync/syncMenu.js} +61 -121
  96. package/dist/sync/syncTable.d.ts +151 -0
  97. package/{sync/syncTable.ts → dist/sync/syncTable.js} +168 -375
  98. package/{types → dist/types}/api.d.ts +12 -51
  99. package/dist/types/api.js +4 -0
  100. package/{types → dist/types}/befly.d.ts +32 -223
  101. package/dist/types/befly.js +4 -0
  102. package/{types → dist/types}/cache.d.ts +7 -15
  103. package/dist/types/cache.js +4 -0
  104. package/dist/types/cipher.d.ts +27 -0
  105. package/dist/types/cipher.js +7 -0
  106. package/{types → dist/types}/common.d.ts +8 -33
  107. package/dist/types/common.js +5 -0
  108. package/{types → dist/types}/context.d.ts +3 -5
  109. package/dist/types/context.js +4 -0
  110. package/{types → dist/types}/crypto.d.ts +0 -3
  111. package/dist/types/crypto.js +4 -0
  112. package/dist/types/database.d.ts +138 -0
  113. package/dist/types/database.js +4 -0
  114. package/dist/types/hook.d.ts +15 -0
  115. package/dist/types/hook.js +6 -0
  116. package/dist/types/jwt.d.ts +75 -0
  117. package/dist/types/jwt.js +4 -0
  118. package/dist/types/logger.d.ts +47 -0
  119. package/dist/types/logger.js +6 -0
  120. package/dist/types/plugin.d.ts +14 -0
  121. package/dist/types/plugin.js +6 -0
  122. package/dist/types/redis.d.ts +71 -0
  123. package/dist/types/redis.js +4 -0
  124. package/{types/roleApisCache.ts → dist/types/roleApisCache.d.ts} +0 -2
  125. package/dist/types/roleApisCache.js +8 -0
  126. package/dist/types/sync.d.ts +92 -0
  127. package/dist/types/sync.js +4 -0
  128. package/dist/types/table.d.ts +34 -0
  129. package/dist/types/table.js +4 -0
  130. package/dist/types/validate.d.ts +67 -0
  131. package/dist/types/validate.js +4 -0
  132. package/dist/utils/arrayKeysToCamel.d.ts +13 -0
  133. package/{utils/arrayKeysToCamel.ts → dist/utils/arrayKeysToCamel.js} +4 -4
  134. package/dist/utils/calcPerfTime.d.ts +4 -0
  135. package/{utils/calcPerfTime.ts → dist/utils/calcPerfTime.js} +3 -3
  136. package/dist/utils/configTypes.d.ts +1 -0
  137. package/dist/utils/configTypes.js +1 -0
  138. package/dist/utils/convertBigIntFields.d.ts +11 -0
  139. package/{utils/convertBigIntFields.ts → dist/utils/convertBigIntFields.js} +5 -9
  140. package/dist/utils/cors.d.ts +8 -0
  141. package/{utils/cors.ts → dist/utils/cors.js} +1 -3
  142. package/dist/utils/disableMenusGlob.d.ts +13 -0
  143. package/{utils/disableMenusGlob.ts → dist/utils/disableMenusGlob.js} +9 -29
  144. package/dist/utils/fieldClear.d.ts +11 -0
  145. package/{utils/fieldClear.ts → dist/utils/fieldClear.js} +15 -33
  146. package/dist/utils/genShortId.d.ts +10 -0
  147. package/{utils/genShortId.ts → dist/utils/genShortId.js} +1 -1
  148. package/dist/utils/getClientIp.d.ts +6 -0
  149. package/{utils/getClientIp.ts → dist/utils/getClientIp.js} +1 -7
  150. package/dist/utils/importDefault.d.ts +1 -0
  151. package/dist/utils/importDefault.js +29 -0
  152. package/dist/utils/isDirentDirectory.d.ts +2 -0
  153. package/{utils/isDirentDirectory.ts → dist/utils/isDirentDirectory.js} +3 -8
  154. package/dist/utils/keysToCamel.d.ts +10 -0
  155. package/{utils/keysToCamel.ts → dist/utils/keysToCamel.js} +4 -5
  156. package/dist/utils/keysToSnake.d.ts +10 -0
  157. package/{utils/keysToSnake.ts → dist/utils/keysToSnake.js} +4 -5
  158. package/dist/utils/loadMenuConfigs.d.ts +5 -0
  159. package/{utils/loadMenuConfigs.ts → dist/utils/loadMenuConfigs.js} +22 -49
  160. package/dist/utils/pickFields.d.ts +4 -0
  161. package/{utils/pickFields.ts → dist/utils/pickFields.js} +2 -5
  162. package/dist/utils/process.d.ts +24 -0
  163. package/{utils/process.ts → dist/utils/process.js} +2 -18
  164. package/dist/utils/processFields.d.ts +4 -0
  165. package/{utils/processFields.ts → dist/utils/processFields.js} +4 -8
  166. package/dist/utils/regex.d.ts +145 -0
  167. package/{configs/presetRegexp.ts → dist/utils/regex.js} +8 -31
  168. package/dist/utils/response.d.ts +20 -0
  169. package/{utils/response.ts → dist/utils/response.js} +27 -48
  170. package/dist/utils/scanAddons.d.ts +17 -0
  171. package/{utils/scanAddons.ts → dist/utils/scanAddons.js} +4 -38
  172. package/dist/utils/scanConfig.d.ts +26 -0
  173. package/{utils/scanConfig.ts → dist/utils/scanConfig.js} +22 -59
  174. package/dist/utils/scanFiles.d.ts +30 -0
  175. package/{utils/scanFiles.ts → dist/utils/scanFiles.js} +25 -65
  176. package/dist/utils/scanSources.d.ts +10 -0
  177. package/{utils/scanSources.ts → dist/utils/scanSources.js} +16 -39
  178. package/dist/utils/sortModules.d.ts +28 -0
  179. package/{utils/sortModules.ts → dist/utils/sortModules.js} +24 -64
  180. package/dist/utils/sqlLog.d.ts +14 -0
  181. package/{utils/sqlLog.ts → dist/utils/sqlLog.js} +2 -14
  182. package/package.json +15 -32
  183. package/.gitignore +0 -0
  184. package/bunfig.toml +0 -3
  185. package/docs/README.md +0 -98
  186. package/docs/api/api.md +0 -1921
  187. package/docs/guide/examples.md +0 -926
  188. package/docs/guide/quickstart.md +0 -354
  189. package/docs/hooks/auth.md +0 -38
  190. package/docs/hooks/cors.md +0 -28
  191. package/docs/hooks/hook.md +0 -838
  192. package/docs/hooks/parser.md +0 -19
  193. package/docs/hooks/rateLimit.md +0 -47
  194. package/docs/infra/redis.md +0 -628
  195. package/docs/plugins/cipher.md +0 -61
  196. package/docs/plugins/database.md +0 -189
  197. package/docs/plugins/plugin.md +0 -986
  198. package/docs/reference/addon.md +0 -510
  199. package/docs/reference/config.md +0 -573
  200. package/docs/reference/logger.md +0 -495
  201. package/docs/reference/sync.md +0 -478
  202. package/docs/reference/table.md +0 -763
  203. package/docs/reference/validator.md +0 -620
  204. package/lib/asyncContext.ts +0 -43
  205. package/plugins/config.ts +0 -13
  206. package/router/api.ts +0 -130
  207. package/tsconfig.json +0 -54
  208. package/types/database.d.ts +0 -541
  209. package/types/hook.d.ts +0 -25
  210. package/types/jwt.d.ts +0 -118
  211. package/types/logger.d.ts +0 -65
  212. package/types/plugin.d.ts +0 -19
  213. package/types/redis.d.ts +0 -83
  214. package/types/sync.d.ts +0 -398
  215. package/types/table.d.ts +0 -216
  216. package/types/validate.d.ts +0 -69
  217. package/utils/configTypes.ts +0 -3
  218. package/utils/importDefault.ts +0 -21
@@ -1,510 +0,0 @@
1
- # Addon 插件包开发
2
-
3
- > 可复用的功能模块,包含 API、表、插件、视图
4
-
5
- ## 目录
6
-
7
- - [概述](#概述)
8
- - [Addon 结构](#addon-结构)
9
- - [创建 Addon](#创建-addon)
10
- - [发布 Addon](#发布-addon)
11
- - [使用 Addon](#使用-addon)
12
- - [命名规范](#命名规范)
13
- - [API 路由](#api-路由)
14
- - [表定义](#表定义)
15
- - [插件开发](#插件开发)
16
- - [视图与菜单](#视图与菜单)
17
- - [官方 Addon](#官方-addon)
18
- - [FAQ](#faq)
19
-
20
- ---
21
-
22
- ## 概述
23
-
24
- Addon 是 Befly 的可复用功能模块,一个 Addon 可以包含:
25
-
26
- | 目录 | 说明 | 自动加载 |
27
- | ---------- | ---------- | -------- |
28
- | `apis/` | API 接口 | ✅ |
29
- | `tables/` | 表定义 | ✅ |
30
- | `plugins/` | 自定义插件 | ✅ |
31
- | `views/` | 前端页面 | ✅ |
32
- | `styles/` | 样式文件 | 手动引入 |
33
-
34
- **加载顺序**:Addon 的资源会在项目资源之前加载,项目可以覆盖 Addon 的配置。
35
-
36
- ---
37
-
38
- ## Addon 结构
39
-
40
- ### 标准目录结构
41
-
42
- ```
43
- @befly-addon/admin/
44
- ├── apis/ # API 接口
45
- │ ├── admin/ # 管理员相关
46
- │ │ ├── login.ts
47
- │ │ ├── logout.ts
48
- │ │ └── info.ts
49
- │ ├── role/ # 角色管理
50
- │ │ ├── list.ts
51
- │ │ └── update.ts
52
- │ └── menu/ # 菜单管理
53
- │ └── list.ts
54
- ├── tables/ # 表定义
55
- │ ├── admin.json # 管理员表
56
- │ ├── role.json # 角色表
57
- │ └── menu.json # 菜单表
58
- ├── plugins/ # 自定义插件
59
- │ └── email.ts # 邮件插件
60
- ├── views/ # 前端视图
61
- │ ├── login_1/ # 登录页
62
- │ │ └── index.vue
63
- │ └── permission/ # 权限管理
64
- │ └── index.vue
65
- ├── styles/ # 样式文件
66
- │ └── variables.scss
67
- ├── package.json # 包配置
68
- └── README.md # 文档
69
- ```
70
-
71
- ### package.json 配置
72
-
73
- ```json
74
- {
75
- "name": "@befly-addon/admin",
76
- "version": "1.0.0",
77
- "title": "管理后台",
78
- "description": "Befly - 管理后台功能组件",
79
- "type": "module",
80
- "private": false,
81
- "publishConfig": {
82
- "access": "public",
83
- "registry": "https://registry.npmjs.org"
84
- },
85
- "main": "package.json",
86
- "exports": {
87
- ".": "./package.json",
88
- "./styles/*": "./styles/*"
89
- },
90
- "files": ["apis", "plugins", "styles", "tables", "views", "package.json", "README.md"],
91
- "keywords": ["befly", "addon"],
92
- "dependencies": {
93
- "befly": "^3.9.0",
94
- "befly-vite": "^1.1.0"
95
- }
96
- }
97
- ```
98
-
99
- ---
100
-
101
- ## 创建 Addon
102
-
103
- ### 1. 初始化目录
104
-
105
- ```bash
106
- mkdir my-addon
107
- cd my-addon
108
- bun init
109
- ```
110
-
111
- ### 2. 修改 package.json
112
-
113
- ```json
114
- {
115
- "name": "@befly-addon/my-addon",
116
- "version": "1.0.0",
117
- "title": "我的插件",
118
- "type": "module",
119
- "main": "package.json",
120
- "files": ["apis", "tables", "plugins", "views"]
121
- }
122
- ```
123
-
124
- ### 3. 创建 API
125
-
126
- `apis/hello/world.ts`:
127
-
128
- ```typescript
129
- import type { ApiRoute } from "befly/types/api";
130
-
131
- export default {
132
- name: "Hello World",
133
- method: "GET",
134
- auth: false,
135
- handler: async (befly, ctx) => {
136
- return Yes("Hello from my-addon!");
137
- }
138
- } as ApiRoute;
139
- ```
140
-
141
- ### 4. 创建表定义
142
-
143
- `tables/example.json`:
144
-
145
- ```json
146
- {
147
- "title": "标题|string|2|100||true",
148
- "content": "内容|text|0|10000",
149
- "sort": "排序|number|0|9999|0"
150
- }
151
- ```
152
-
153
- ### 5. 本地测试
154
-
155
- 在项目中链接本地 Addon:
156
-
157
- ```bash
158
- # 在 addon 目录
159
- bun link
160
-
161
- # 在项目目录
162
- bun link @befly-addon/my-addon
163
- ```
164
-
165
- ---
166
-
167
- ## 发布 Addon
168
-
169
- ### 1. 检查配置
170
-
171
- 确保 `package.json` 包含:
172
-
173
- ```json
174
- {
175
- "name": "@befly-addon/your-addon-name",
176
- "publishConfig": {
177
- "access": "public"
178
- },
179
- "files": ["apis", "tables", "plugins", "views"]
180
- }
181
- ```
182
-
183
- ### 2. 登录 npm
184
-
185
- ```bash
186
- npm login
187
- ```
188
-
189
- ### 3. 发布
190
-
191
- ```bash
192
- npm publish
193
- ```
194
-
195
- ---
196
-
197
- ## 使用 Addon
198
-
199
- ### 安装
200
-
201
- ```bash
202
- bun add @befly-addon/admin
203
- ```
204
-
205
- ### 自动加载
206
-
207
- 安装后,Befly 会自动扫描并加载:
208
-
209
- - `node_modules/@befly-addon/*/apis/` 下的所有 API
210
- - `node_modules/@befly-addon/*/tables/` 下的所有表定义
211
- - `node_modules/@befly-addon/*/plugins/` 下的所有插件
212
- - `node_modules/@befly-addon/*/views/` 下的所有视图
213
-
214
- ### 手动引入样式
215
-
216
- ```typescript
217
- // main.ts 或 vite.config.js
218
- import "@befly-addon/admin/styles/variables.scss";
219
- ```
220
-
221
- ---
222
-
223
- ## 命名规范
224
-
225
- ### 包名
226
-
227
- - 格式:`@befly-addon/{addon-name}`
228
- - 示例:`@befly-addon/admin`、`@befly-addon/cms`
229
-
230
- ### 表名前缀
231
-
232
- Addon 的表自动添加 `addon_{name}_` 前缀:
233
-
234
- | Addon | 表文件 | 数据库表名 |
235
- | ------- | -------------- | ------------------- |
236
- | `admin` | `role.json` | `addon_admin_role` |
237
- | `admin` | `menu.json` | `addon_admin_menu` |
238
- | `cms` | `article.json` | `addon_cms_article` |
239
-
240
- ### API 路由前缀
241
-
242
- Addon 的 API 自动添加 `/addon/{name}/` 前缀:
243
-
244
- | Addon | API 文件 | 路由 |
245
- | ------- | --------------------- | ----------------------------------- |
246
- | `admin` | `apis/admin/login.ts` | `POST /api/addon/admin/admin/login` |
247
- | `admin` | `apis/role/list.ts` | `POST /api/addon/admin/role/list` |
248
-
249
- ---
250
-
251
- ## API 路由
252
-
253
- ### 文件结构
254
-
255
- ```
256
- apis/
257
- ├── admin/
258
- │ ├── login.ts → /api/addon/{name}/admin/login
259
- │ ├── logout.ts → /api/addon/{name}/admin/logout
260
- │ └── info.ts → /api/addon/{name}/admin/info
261
- └── role/
262
- ├── list.ts → /api/addon/{name}/role/list
263
- └── update.ts → /api/addon/{name}/role/update
264
- ```
265
-
266
- ### API 定义示例
267
-
268
- ```typescript
269
- import type { ApiRoute } from "befly/types/api";
270
-
271
- export default {
272
- name: "管理员登录",
273
- method: "POST",
274
- auth: false,
275
- desc: "管理员邮箱密码登录",
276
- fields: {
277
- email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
278
- password: { name: "密码", type: "string", min: 6, max: 100 }
279
- },
280
- required: ["email", "password"],
281
- handler: async (befly, ctx) => {
282
- // 使用 addon 表时需要完整表名
283
- const adminRes = await befly.db.getOne({
284
- table: "addon_admin_admin",
285
- fields: ["id", "email", "password", "nickname"],
286
- where: { email: ctx.body.email }
287
- });
288
-
289
- const admin = adminRes.data;
290
-
291
- // ... 业务逻辑
292
-
293
- return Yes("登录成功", { token: token });
294
- }
295
- } as ApiRoute;
296
- ```
297
-
298
- ---
299
-
300
- ## 表定义
301
-
302
- ### 文件格式
303
-
304
- 表定义使用 JSON 格式,与项目表定义一致:
305
-
306
- ```json
307
- {
308
- "email": "邮箱|string|5|100||true|@email",
309
- "password": "密码|string|6|100||true",
310
- "nickname": "昵称|string|2|50|用户",
311
- "role_id": "角色ID|number|1||",
312
- "last_login_at": "最后登录|number|0||"
313
- }
314
- ```
315
-
316
- ### 表名转换
317
-
318
- | 定义文件 | 数据库表名 |
319
- | ------------------------- | --------------------------- |
320
- | `tables/admin.json` | `addon_{name}_admin` |
321
- | `tables/role.json` | `addon_{name}_role` |
322
- | `tables/userProfile.json` | `addon_{name}_user_profile` |
323
-
324
- ### 在代码中使用
325
-
326
- ```typescript
327
- // 使用完整表名
328
- await befly.db.getList({
329
- table: "addon_admin_role", // addon_{name}_{table}
330
- fields: ["id", "name", "code"]
331
- });
332
- ```
333
-
334
- ---
335
-
336
- ## 插件开发
337
-
338
- ### 插件定义
339
-
340
- `plugins/email.ts`:
341
-
342
- ```typescript
343
- import type { Plugin } from "befly/types/plugin";
344
-
345
- export interface EmailConfig {
346
- host: string;
347
- port: number;
348
- user: string;
349
- pass: string;
350
- }
351
-
352
- const emailPlugin: Plugin = {
353
- after: ["config"], // 依赖 config 插件
354
- async handler(befly) {
355
- const config = befly.config.get("email") as EmailConfig;
356
-
357
- return {
358
- async send(to: string, subject: string, html: string) {
359
- // 发送邮件逻辑
360
- }
361
- };
362
- }
363
- };
364
-
365
- export default emailPlugin;
366
- ```
367
-
368
- ### 插件命名
369
-
370
- - 插件名称由文件名决定(自动转小驼峰)
371
- - `email.ts` → `befly.email`
372
- - `myPlugin.ts` → `befly.myPlugin`
373
-
374
- ### 使用插件
375
-
376
- ```typescript
377
- // 在 API 中使用
378
- export default {
379
- name: "发送邮件",
380
- handler: async (befly, ctx) => {
381
- await befly.email.send(ctx.body.to, "欢迎注册", "<h1>欢迎使用</h1>");
382
- return Yes("发送成功");
383
- }
384
- } as ApiRoute;
385
- ```
386
-
387
- ---
388
-
389
- ## 视图与菜单
390
-
391
- ### 视图结构
392
-
393
- ```
394
- views/
395
- ├── login_1/ # 使用 layout 1
396
- │ └── index.vue # 页面组件(definePage 声明菜单元信息)
397
- ├── permission/
398
- │ ├── index.vue
399
- │ ├── role/ # 子菜单
400
- │ │ └── index.vue
401
- │ └── menu/
402
- │ └── index.vue
403
- ```
404
-
405
- ### definePage(meta) 配置
406
-
407
- 在 `views/**/index.vue` 中使用 `definePage()` 声明菜单元信息:
408
-
409
- ```vue
410
- <script setup>
411
- definePage({
412
- meta: {
413
- title: "权限管理",
414
- order: 10
415
- }
416
- });
417
- </script>
418
- ```
419
-
420
- ### 目录命名规则
421
-
422
- - `name_1/` → 使用 `layouts/1.vue` 布局
423
- - `name_2/` → 使用 `layouts/2.vue` 布局
424
- - `name/` → 使用默认布局
425
-
426
- ---
427
-
428
- ## 官方 Addon
429
-
430
- ### @befly-addon/admin
431
-
432
- 管理后台基础功能:
433
-
434
- | 功能 | API | 表 |
435
- | ---------- | -------------- | ------------------------- |
436
- | 管理员管理 | `admin/*` | `addon_admin_admin` |
437
- | 角色管理 | `role/*` | `addon_admin_role` |
438
- | 菜单管理 | `menu/*` | `addon_admin_menu` |
439
- | API 管理 | `api/*` | `addon_admin_api` |
440
- | 字典管理 | `dict/*` | `addon_admin_dict` |
441
- | 登录日志 | `loginLog/*` | `addon_admin_login_log` |
442
- | 操作日志 | `operateLog/*` | `addon_admin_operate_log` |
443
- | 邮件日志 | `email/*` | `addon_admin_email_log` |
444
- | 系统配置 | `sysConfig/*` | `addon_admin_sys_config` |
445
-
446
- **安装**:
447
-
448
- ```bash
449
- bun add @befly-addon/admin
450
- ```
451
-
452
- ---
453
-
454
- ## FAQ
455
-
456
- ### Q: 如何覆盖 Addon 的 API?
457
-
458
- A: 在项目中创建同路径的 API 文件,项目 API 优先级高于 Addon。
459
-
460
- ### Q: 如何禁用 Addon 的某个插件?
461
-
462
- A: 在配置文件中设置:
463
-
464
- ```json
465
- {
466
- "disablePlugins": ["email"]
467
- }
468
- ```
469
-
470
- ### Q: 如何在 Addon 中访问项目配置?
471
-
472
- A: 通过 `befly.config` 访问:
473
-
474
- ```typescript
475
- const dbConfig = befly.config.get("db");
476
- const customConfig = befly.config.get("myAddon");
477
- ```
478
-
479
- ### Q: Addon 之间可以互相依赖吗?
480
-
481
- A: 可以,在 `package.json` 中声明依赖:
482
-
483
- ```json
484
- {
485
- "dependencies": {
486
- "@befly-addon/admin": "^1.0.0"
487
- }
488
- }
489
- ```
490
-
491
- ### Q: 如何本地开发调试 Addon?
492
-
493
- A: 使用 `bun link`:
494
-
495
- ```bash
496
- # 在 addon 目录
497
- bun link
498
-
499
- # 在项目目录
500
- bun link @befly-addon/my-addon
501
-
502
- # 修改 addon 代码后会自动生效
503
- ```
504
-
505
- ### Q: Addon 的视图如何与项目视图合并?
506
-
507
- A: Addon 视图会自动合并到路由系统中:
508
-
509
- - Addon 视图路由前缀:`/addon/{name}/`
510
- - 菜单会自动同步到 `addon_admin_menu` 表