105 lines
6.0 KiB
Plaintext
105 lines
6.0 KiB
Plaintext
---
|
||
description: Node Core（Koa2+Sequelize）框架集成、启动与控制器约定；若项目含 framework/node-core-framework.js 则遵循本规范
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Node Core 规范
|
||
|
||
若项目根目录（或约定路径）存在 **`framework/node-core-framework.js`**（或等价 Node Core 打包产物），后端启动与路由须按本节执行。
|
||
|
||
## 本仓库路径对照
|
||
|
||
| 规范表述 | 本仓库 |
|
||
|---------|--------|
|
||
| 框架入口 | `./framework/node-core-framework.js` |
|
||
| 框架配置 | `./config/framework.config.js` |
|
||
| 业务后台控制器目录 | `api/controller_admin`（前缀 `/admin_api`，勿在键名里重复写前缀） |
|
||
| 小程序/开放端控制器 | `api/controller_front`（前缀 `/api`） |
|
||
| 手动注册/代理等自定义 | `api/controller_custom`（仅 `app.js` 的 `beforeInitApi` 内 `addRoutes`） |
|
||
| 模型关联 | `./config/model.associations.js` |
|
||
| 白名单 | `./config/config.js` → `allowUrls` |
|
||
| `beforeInitApi` 实现体 | `./config/before_init_api.js`（由 `framework.config.js` 挂到 `init` 参数） |
|
||
| 管理端通用工具（非业务域） | `api/utils/query_helpers.js`（分页/筛选/导出）、`api/utils/biz_audit.js`（审计） |
|
||
| 跨端/复杂业务 | `api/service/*`（如 `biz_auth_verify`、`biz_proxy_service`、`biz_subscription_logic`、`biz_token_logic`） |
|
||
|
||
---
|
||
|
||
# Framework 启动（`app.js`）
|
||
|
||
## 入口流程
|
||
|
||
1. `require('./framework/node-core-framework.js')` → `Framework.init({ ... })`
|
||
2. **配置**：展开 `require('./config/framework.config.js')`，勿在 `app.js` 内重复写数据库、端口等业务配置。
|
||
3. **模型关联**：传入 `businessAssociations: require('./config/model.associations.js')`。
|
||
4. **`beforeInitApi`**：在 `Framework.init` **resolve 之前**执行；本仓库逻辑在 **`config/before_init_api.js`**，由 **`config/framework.config.js`** 导出并随 `...config` 传入 `init`，**`app.js` 只负责 `Framework.init({ ...config, businessAssociations })`**。
|
||
- 动态转发路由：在 `beforeInitApi` 内 `require('./api/controller_custom/proxy_api')` 的 `buildProxyRoutes()`，再注册两套前缀：
|
||
- `framework.addRoutes('', proxyRoutes)` — 与 OpenAPI/Swagger 文档路径一致（如 `/admin/...`）
|
||
- `framework.addRoutes('/api', proxyRoutes)` — 兼容 `/api/admin/...`
|
||
- **不要**把代理路由写在 `api/controller_front`；自定义注册放在 `api/controller_custom`。
|
||
5. **`await framework.start(config.port.node)`**：真正监听 HTTP。
|
||
6. **定时任务**等依赖框架就绪的逻辑放在 `start()` 里、且 **`framework.start` 完成之后**再 `require`/`init`，例如 `middleware/schedule.js`。
|
||
|
||
## 错误处理
|
||
|
||
- `start()` 使用 `try/catch`；失败时打印错误并 `process.exit(1)`，避免进程无监听挂起。
|
||
|
||
## 修改启动行为时注意
|
||
|
||
- 新增 `addRoutes`：键格式与框架约定一致，如 `'POST /path': async (ctx) => { ... }`。
|
||
- 白名单路径在 `config/config.js` 的 `allowUrls`（框架层免 token）与业务层（如转发 Token 鉴权）是两段逻辑，改路由前缀时需同步 `allowUrls`。
|
||
|
||
---
|
||
|
||
## 路由体系
|
||
|
||
- **约定式控制器**：`framework.config.js` 的 `apiPaths` 指向目录，扫描导出；单条路径 = `prefix` + 控制器内声明的路径。
|
||
- **内置系统管理**：后台接口固定前缀 **`/admin_api`**（由框架注册系统控制器；本仓库业务管理接口在 `api/controller_admin`，同前缀）。
|
||
- **手动路由**：仅在 **`beforeInitApi`** 内调用 `framework.addRoutes(prefix, routes)`；`routes` 键名格式与控制器相同。不要在 `Framework.init()` 已结束后再注册同类路由（会晚于静态路由流水线，易 404）。
|
||
|
||
## 鉴权与白名单
|
||
|
||
- `allowUrls`：路径**子串**匹配则免框架层 admin/applet token；另有默认放行段（以框架 `middleware` 为准）。
|
||
- `apiPaths` 项可设 `authType`：`admin` → 校验 **`admin-token`**（`ctx.getAdminUserId()`）；`applet` → **`applet-token`**（`ctx.getPappletUserId()`）。
|
||
|
||
## 中间件时机
|
||
|
||
- `beforeInitApi(framework)`：在框架完成路由装配流水线中的**早阶段**执行，适合 `framework.addRoutes` 或与路由顺序相关的 `use`。
|
||
- `init` **之后**再往 `app` 追加的中间件通常位于路由之后，多数请求已被消费，一般仅兜底。
|
||
|
||
## 接口与命名（业务侧）
|
||
|
||
- 语义化 URL，**优先 POST** 做变更类接口；路径片段可与项目统一为 **snake_case**（如 `/order/create`）。
|
||
- JSON 响应优先用 Context 扩展：`ctx.success` / `ctx.fail` / `ctx.tokenFail`；参数可用 `ctx.get`（query+body 合并，body 覆盖 query，以框架实现为准）。
|
||
|
||
## 修改核心 / 打包注意
|
||
|
||
- 路由注册顺序以框架 `init` 内部为准；新增动态加载路径时若存在 webpack 打包，需与框架内 `__non_webpack_require__` 等行为一致。
|
||
|
||
## 控制器约定
|
||
|
||
### 导出形状
|
||
|
||
- 每个文件 `module.exports = { 'METHOD /path': handler, ... }`。
|
||
- **METHOD** 仅为 **`GET` 或 `POST`**，后接**一个空格**再写路径，例如：`POST /goods/create`、`GET /goods/detail/:id`。
|
||
- `handler` 建议为 **async** `(ctx, next) => { ... }`；需继续管道时 `await next()`。
|
||
|
||
### 管理端（本仓库）
|
||
|
||
- 文件在 **`api/controller_admin`**；对外完整路径 = **`/admin_api` + 键名中的路径**，键名里**不要**再写 `/admin_api`。
|
||
- 需登录：请求头 `admin-token: <jwt>`。
|
||
|
||
### 业务/开放端（本仓库）
|
||
|
||
- `api/controller_front`，`apiPaths` 中 `prefix: '/api'`，`authType: 'applet'`。
|
||
|
||
### 常见 Context API（以框架为准）
|
||
|
||
- 参数：`ctx.get('id')`、`ctx.getBody()`、`ctx.getQuery()`、`ctx.getPageSize()` 等。
|
||
- 响应：`ctx.success(data, msg)`、`ctx.fail(msg)`、`ctx.tokenFail()`、`ctx.json(code, message, data)`。
|
||
- 鉴权：`ctx.getAdminUserId()`、`ctx.getPappletUserId()`。
|
||
|
||
### 避免
|
||
|
||
- 不要用 **`PUT` / `DELETE`** 等作为导出键（框架只按 **GET/POST** 注册）。
|
||
- 不要把 **`addRoutes`** 散落到 `init` 完成后的随意位置；统一放 **`beforeInitApi`**。
|