jfexmd 0.0.1

package/.prompt

@@ -0,0 +1,13 @@
+# 项目名称: exmd
+# 用途: EXMD 核心后端服务与业务接口
+# 主要技术: Node.js, Express/Koa (以项目实际依赖为准)
+# 目录约定:
+# - controller/: 请求入口与参数校验
+# - services/: 业务逻辑与数据处理
+# - models/: 数据模型/ORM
+# - router/: 路由注册与中间件
+# 开发建议:
+# - 变更前先定位对应路由与服务层
+# - 严格保留公共错误码与响应结构
+# - 新增接口需补充单元/集成测试
+# 运行与调试: 参考 README 或 package.json scripts

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.0.38 - 2026-02-11
+
+### Baseline
+
+- framework hardening and extensibility baseline completed through v0.4

package/README.MD

@@ -0,0 +1,649 @@
+# exmd内核
+
+```exmd```的核心代码，包含以下功能：
+
+**核心能力**
+1. ```startProject``` 启动项目（返回 Promise\<server\>，支持手动 shutdown）
+2. ```BaseModel``` model基类（含事务、参数化 SQL）
+3. ```migrate``` 数据库表转model
+4. ```asyncdb``` model转数据库表
+5. ```renderRequestType``` controller 方法请求配置（请求类型、swagger 描述、必填校验、限流、中间件、钩子）
+6. ```handleClientAdapter``` 持久层适配器，指定数据源并操作对应 model
+7. ```ResultVo``` 返回结果集合
+8. ```AuthController``` 内置登录注册 controller（bcrypt 密码、JWT、验证码）
+9. ```UploadController``` 内置文件上传控制器
+
+**扩展与工具**
+- 插件机制（```createPluginManager```、```createRequestLogPlugin```）
+- 数据源注册中心（```createDatasourceRegistry```，支持扩展多数据库）
+- 可观测性（```createMetricsRegistry```、/health、/ready、/metrics）
+- 安全中间件（```createApiKeyMiddleware```、```createHmacSignatureMiddleware```）
+- 配置迁移与弃用告警（```applyConfigMigrations```）
+
+**业务层**
+
+获得可操作数据库的模型:
+
+```js
+// 自定义的model:flow
+const Flow = require('./models/flow')
+let dataSourceKey = ogisticServiceData.authDataSourceKey
+const client = handleClientAdapter(ogisticServiceData, dataSourceKey)
+const flow = new Flow(client, ogisticServiceData)
+```
+
+简化使用也可以直接使用exmd引出的:
+
+```js
+// 自定义的model:flow
+const Flow = require('./models/flow')
+const { getModelInstance } = require('../../exmd')
+const flow = getModelInstance(ogisticServiceData)
+```
+
+
+
+**数据源配置**
+
+默认支持 postgresql，可通过 `createDatasourceRegistry` 扩展其他数据库类型
+
+```javascript
+module.exports = {
+  // 数据库1
+  postgresql1: {
+    type: 'postgresql',
+    data: {
+      user: 'bserverx',
+      database: 'bserver',
+      password: 'bserverx123',
+      host: 'localhost',
+      port: '5432',
+      poolSize: 5,
+      poolIdleTimeout: 30000,
+      reapIntervalMillis: 10000
+    }
+  }
+}
+```
+
+**启动项目**
+
+```javascript
+startProject({
+  /**
+   * 是否开启调试模式
+   * 调试模式将会打印sql
+   * 调试模式下不会发送邮件
+   */
+  isDebugger: true,
+  /**
+   * api地址路由配置
+   */
+  router,
+  /**
+   * 数据源
+   */
+  Datasource,
+  /**
+   * 用户model
+   */
+  authUserModel: UserModel, // 可选, 不传使用内置默认model
+  /**
+   * 登录注册使用的数据源对应key
+   */
+  authDataSourceKey: 'postgresql1',
+  /**
+   * 注册邮箱使用的内容模板
+   * 没有配置将会使用默认模板
+   * @param {*} code 
+   * @returns 
+   */
+  authEmailContent: (code) => {
+    return `
+      <p>您好：</p>
+      <p>您的验证码是：<strong style="color:orangered;">${code}</strong></p>
+      <p>嘿嘿</p>
+    `
+  },
+  /**
+   * 登录注册验证码超时时间
+   */
+  authEmailCodeMaxTime: '1minute', 
+  // 一个邮箱最多允许绑定多少个用户
+  authEmailBindUserMax: 3,
+  // token生成私钥(生产环境必填; 支持 EXMD_AUTH_PRIVATE_KEY 环境变量; 调试模式可缺省)
+  authPrivateKey: 'abc123',
+  // hour/minute/second
+  authTokenTime: '1minute',
+  /**
+   * 发邮件库，
+   * 目前只支持 tencenmail
+   */
+  emailLib: 'tencenmail',
+  /**
+   * 邮箱配置
+   */
+  emailConfig,
+  /**
+   * 返回数据的结果集合模板
+   */
+  ResultVo,
+  // swagger的路径配置
+  swaggerUrl: '/swagger/data',
+  // 文件上传的保存路径
+  uploadBaseUrl: '/Users/wujianfei/test-upload-files',
+  /**
+   * 文件上传模块划分, 必须传
+   * 上传的文件路径：基础路径下 文件名称: [模块名称_时间戳]，
+   * 比如default下的文件名称：
+   * test1_1657007903331.mp4
+   */
+  uploadFileDirectorys: [{
+    name: 'test1'
+  }, {
+    name: 'default'
+  }],
+  // 文件限制配置
+  uploadLimits: {
+    fileSize: 10 * 1024 * 1024 * 1024
+  },
+  /**
+   * 全局中间件(按顺序执行)
+   * 签名: async (req, res, context) => {}
+   */
+  middlewares: [
+    async (req, res) => {
+      req.customMark = 'ok'
+    }
+  ],
+  /**
+   * 全局生命周期钩子
+   */
+  hooks: {
+    beforeAuth: [
+      async (req, res, context) => {
+        // 鉴权前
+      }
+    ],
+    afterAuth: [],
+    beforeHandler: [],
+    afterHandler: []
+  }
+})
+```
+
+**接口级校验/限流/中间件**
+
+`renderRequestType` 支持更细粒度的接口配置:
+
+```javascript
+exports.login = renderRequestType({
+  fun: login,
+  type: 'POST',
+  desc: '登录',
+  requiredFields: ['username', 'password'],
+  rateLimit: { max: 10, windowMs: 60 * 1000 },
+  middlewares: [
+    async (req, res) => {
+      // 路由级逻辑
+    }
+  ],
+  hooks: {
+    beforeHandler: [
+      async (req, res, context) => {
+        // 进入controller前
+      }
+    ],
+    afterHandler: [
+      async (req, res, context) => {
+        // controller执行后
+      }
+    ]
+  }
+})
+```
+
+**安全基线（v0.1）**
+
+- **SQL 参数化**：BaseModel 增删改查统一使用参数化查询，避免 SQL 注入
+- **密码哈希**：登录/注册使用 bcrypt，兼容历史 MD5 并自动升级
+- **JWT 配置**：生产环境必须配置 `authPrivateKey` 或 `EXMD_AUTH_PRIVATE_KEY`
+- **请求校验**：`renderRequestType` 支持 `requiredFields` 必填校验
+- **限流**：登录/注册/验证码接口内置限流，可配置 `rateLimit`
+- **全局错误处理**：统一异常中间件，返回 `ResultVo` 并记录日志
+- **请求追踪**：每个请求自动注入 `X-Request-Id`，便于日志排查
+
+**配置校验和日志**
+
+框架会在 `startProject` 启动时自动校验:
+- `router` 必须是非空数组
+- `Datasource` 必须是非空对象，且每个数据源都包含 `type/data`
+
+如果不传 `logger`，框架会默认创建结构化日志器；也可以通过 `createLogger` 自定义:
+
+```javascript
+const { startProject, createLogger } = require('exmd')
+
+startProject({
+  // ...
+  logger: createLogger({ level: 'info' }),
+  // 慢查询阈值(ms)
+  slowQueryThresholdMs: 200
+})
+```
+
+**插件机制（v0.4）**
+
+`startProject` 支持 `plugins`，插件可实现这些生命周期:
+- `setup({ config, datasourceRegistry })`
+- `onConfig({ config, datasourceRegistry })`
+- `onDbReady({ dbClient, datasourceRegistry })`
+- `onServerReady({ app, server, port, swaggerUrl })`
+
+插件支持 `priority` 字段（数值越大越先执行）。
+
+插件错误策略通过 `pluginErrorStrategy` 配置:
+- `fail-fast`（默认）: 任一插件失败，启动流程中断
+- `continue`: 记录错误并继续执行后续插件
+
+```javascript
+const plugin = {
+  name: 'example-plugin',
+  setup({ datasourceRegistry }) {
+    datasourceRegistry.register('mockdb', (cfg) => {
+      return Promise.resolve({
+        query: () => Promise.resolve({ rowCount: 0, rows: [] })
+      })
+    })
+  },
+  onServerReady({ port }) {
+    console.log('server ready', port)
+  }
+}
+
+startProject({
+  // ...
+  plugins: [plugin],
+  pluginErrorStrategy: 'continue'
+})
+```
+
+框架内置了一个官方插件模板 `createRequestLogPlugin`:
+
+```javascript
+const { startProject, createRequestLogPlugin } = require('exmd')
+
+startProject({
+  // ...
+  plugins: [
+    createRequestLogPlugin({
+      level: 'info',
+      priority: 10
+    })
+  ]
+})
+```
+
+也可以直接手动创建并注入数据源注册器:
+
+```javascript
+const { startProject, createDatasourceRegistry } = require('exmd')
+const datasourceRegistry = createDatasourceRegistry()
+datasourceRegistry.register('postgresql', postgresqlConnect)
+datasourceRegistry.register('mockdb', connectMock)
+
+startProject({
+  // ...
+  datasourceRegistry
+})
+```
+
+**事务能力**
+
+`BaseModel` 支持事务执行:
+
+```javascript
+const flow = new Flow(client, ogisticServiceData)
+await flow.withTransaction(async (txFlow) => {
+  await txFlow.addItem({ name: 'a' })
+  await txFlow.updateItemById('id-1', { name: 'b' })
+})
+```
+
+**限流增强**
+
+`rateLimit` 支持 `keyBy` 维度:
+- `ip`（默认）
+- `user`（优先取 `req.exmdAuth.username/id`）
+- `ip_user`
+
+```javascript
+exports.login = renderRequestType({
+  fun: login,
+  type: 'POST',
+  rateLimit: { max: 10, windowMs: 60 * 1000, keyBy: 'user' }
+})
+```
+
+`startProject` 还支持注入自定义限流存储:
+
+```javascript
+const { startProject, createMemoryRateLimitStore } = require('exmd')
+
+startProject({
+  // ...
+  rateLimitStore: createMemoryRateLimitStore()
+})
+```
+
+**发布质量（v0.5）**
+
+1) 配置迁移提示（含移除版本）
+
+当前支持自动迁移并告警的旧配置键：
+- `middlewareList -> middlewares`
+- `pluginErrorMode -> pluginErrorStrategy`
+- `dbSlowQueryThreshold -> slowQueryThresholdMs`
+- `datasourceAdapterRegistry -> datasourceRegistry`
+
+2) 弃用告警（warn once）
+
+同一个弃用键只会提示一次，避免刷屏。
+
+3) changelog 生成脚本
+
+```shell
+npm run changelog:gen -- --version 1.0.39 --title "v0.5 发布" --changes "feat: 发布质量能力|docs: README更新"
+```
+
+默认会更新项目根目录 `CHANGELOG.md`，也可通过 `--file` 指定文件。
+
+**可观测性（v0.6）**
+
+框架默认注入 `metrics` 注册器，包含计数指标：
+- `http_request_total`
+- `http_error_total`
+- `db_slow_query_total`
+
+并内置端点（可在 `startProject` 自定义路径）：
+- `healthPath`，默认 `/health`
+- `readinessPath`，默认 `/ready`
+- `metricsPath`，默认 `/metrics`
+
+可选配置：
+- `readinessDeepCheck: true` 时，`/ready` 会对所有数据源执行 `select 1`
+- `enableMetricsEndpoint: false` 可关闭 `/metrics` 暴露
+
+```javascript
+const { startProject, createMetricsRegistry } = require('exmd')
+
+startProject({
+  // ...
+  metrics: createMetricsRegistry(),
+  healthPath: '/health',
+  readinessPath: '/ready',
+  metricsPath: '/metrics',
+  readinessDeepCheck: true
+})
+```
+
+**运维增强（v0.7）**
+
+1) readiness draining
+
+进入优雅停机后，`/ready` 会返回 `503`，并标记失败原因为 `draining`。
+
+2) graceful shutdown
+
+服务在 `SIGINT/SIGTERM` 下默认自动执行优雅停机：
+- 停止接收新请求
+- 关闭 DB 客户端
+- 执行插件钩子 `onShutdown`
+
+可选配置：
+- `autoHandleProcessSignals: false` 禁用自动信号处理
+- `shutdownTimeoutMs` 优雅停机超时（默认 `10000ms`）
+
+`startProject` 返回 `Promise<server>`，可手动触发停机：
+
+```javascript
+const server = await startProject({
+  // ...
+  shutdownTimeoutMs: 15000
+})
+
+await server.shutdown('manual')
+```
+
+**安全增强二期（v0.8）**
+
+1) CORS 白名单配置
+
+```javascript
+startProject({
+  // ...
+  cors: {
+    allowOrigins: ['https://a.example.com', 'https://b.example.com'],
+    allowMethods: 'GET,POST,PUT,DELETE,OPTIONS',
+    allowHeaders: 'Content-Type, authorization, x-api-key, x-signature, x-timestamp',
+    allowCredentials: true
+  }
+})
+```
+
+2) Helmet 可配置化
+
+```javascript
+startProject({
+  // ...
+  helmetEnabled: true,
+  helmetOptions: {
+    contentSecurityPolicy: {
+      directives: {
+        scriptSrc: ["'self'"]
+      }
+    }
+  }
+})
+```
+
+3) API Key / 签名中间件模板
+
+```javascript
+const {
+  createApiKeyMiddleware,
+  createHmacSignatureMiddleware
+} = require('exmd')
+
+exports.createOrder = renderRequestType({
+  fun: createOrder,
+  type: 'POST',
+  middlewares: [
+    createApiKeyMiddleware({ keys: ['k1', 'k2'] }),
+    createHmacSignatureMiddleware({ secret: 'your-secret' })
+  ]
+})
+```
+
+**文件上传和登录模块使用**
+
+可参考提供的后端模板项目中的路由，看注释即可
+
+```javascript
+const { AuthController, UploadController } = require('../../exmd')
+const router = [
+  {
+    url: '/bserve/',
+    controller: UploadController
+  },
+  {
+    url: '/bserve/',
+    controller: AuthController
+  }
+  ...自己定义的controller
+]
+```
+
+**ResultVo**
+
+可以根据该ResultVo自定义
+
+```javascript
+/**
+ * 返回实体类
+ * @param {*} params 
+ */
+function ResultVo(params) {
+  const { status, data, message } = params
+  if (status === undefined) {
+    throw new Error('status is undefined')
+  }
+  if (data === undefined && message === undefined) {
+    throw new Error('both and data are undefined')
+  }
+  return {
+    status,
+    data,
+    message
+  }
+}
+ResultVo.prototype.swaggerDescription = {
+  status: '状态 0正常',
+  data: '',
+  message: '异常信息'
+}
+module.exports = ResultVo
+```
+
+**UserModel**
+
+可以根据该model自定义模板放到models目录下
+
+```javascript
+const { BaseModel } = require('../../exmd')
+const fieldsMap = {
+  id: {
+    type: 'uuid',
+    length: 16,
+    lengthvar: -1,
+    notnull: true,
+    comment: null,
+    isPrimary: true,
+    pk_name: 'omuser_pkey'
+  },
+  username: {
+    type: 'text',
+    length: -1,
+    lengthvar: -1,
+    notnull: true,
+    comment: null
+  },
+  password: {
+    type: 'text',
+    length: -1,
+    lengthvar: -1,
+    notnull: true,
+    comment: null
+  },
+  email: {
+    type: 'text',
+    length: -1,
+    lengthvar: -1,
+    notnull: true,
+    comment: null
+  },
+  fullName: {
+    type: 'text',
+    length: -1,
+    lengthvar: -1,
+    notnull: true,
+    comment: null
+  },
+  isactive: {
+    type: 'int4',
+    length: 4,
+    lengthvar: -1,
+    notnull: true,
+    comment: null
+  },
+  realname: {
+    type: 'text',
+    length: -1,
+    lengthvar: -1,
+    notnull: false,
+    comment: null
+  }
+}
+
+function omuser() {
+  const vm = this
+  BaseModel.apply(vm, arguments)
+  vm.fields = fieldsMap
+  vm.tableName = 'omuser'
+}
+
+;(function () {
+  const TempFun = function () {}
+  TempFun.prototype = BaseModel.prototype
+  omuser.prototype = new TempFun()
+})()
+
+module.exports = omuser
+
+```
+
+**默认UserModel**
+
+未传`authUserModel`时，框架会使用内置默认模型`DefaultAuthUserModel`，
+表名为`omuser`，字段如下（仅`username/password/email`为必填）：
+
+```javascript
+{
+  id: { type: 'uuid', isPrimary: true },
+  username: { type: 'varchar', length: 64, notnull: true },
+  password: { type: 'varchar', length: 64, notnull: true },
+  email: { type: 'varchar', length: 128, notnull: true },
+  fullName: { type: 'varchar', length: 128 },
+  isactive: { type: 'int4' }
+}
+```
+
+**startProject 配置项汇总**
+
+| 分类 | 配置项 | 说明 |
+|------|--------|------|
+| 基础 | router, Datasource, ResultVo | 必填 |
+| 认证 | authUserModel, authDataSourceKey, authPrivateKey, authTokenTime | JWT 与用户模型 |
+| 邮件 | emailLib, emailConfig, authEmailContent, authEmailCodeMaxTime, authEmailBindUserMax | 验证码与注册 |
+| 上传 | uploadBaseUrl, uploadFileDirectorys, uploadLimits | 文件上传 |
+| 工程化 | logger, middlewares, hooks, pluginErrorStrategy | 日志、中间件、钩子 |
+| 插件 | plugins, datasourceRegistry | 插件与数据源扩展 |
+| 安全 | rateLimitStore, cors, helmetEnabled, helmetOptions | 限流、CORS、Helmet |
+| 可观测 | metrics, healthPath, readinessPath, metricsPath, readinessDeepCheck, enableMetricsEndpoint | 健康检查与指标 |
+| 运维 | shutdownTimeoutMs, autoHandleProcessSignals | 优雅停机 |
+
+**构建**
+```shell
+npm run build
+```
+
+**提交所有代码**
+```shell
+npm run push:all
+```
+
+**发布**
+```shell
+npm run publish:exmd
+npm run publish:aux
+```
+
+**Changelog 生成**
+```shell
+npm run changelog:gen -- --version 1.0.39 --title "发布说明" --changes "feat: 功能1|fix: 修复1"
+```
+
+源码仓库已提交申请中，请耐心等待
+
+
+

package/bin/build-aux.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+targetFile_1="./dist/auxiliary/package.json"
+targetFile_2="./dist/auxiliary//README.MD"
+sourceFile="./resource-pack/auxiliary/*"
+npm run build &&
+if [ -f "${targetFile_1}" ]; then rm -rf "${targetFile_1}"; fi && 
+if [ -f "${targetFile_2}" ]; then rm -rf "${targetFile_2}"; fi && 
+cp ./resource-pack/auxiliary/* dist/auxiliary &&
+echo "完成文件拷贝"

package/bin/build.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+# webpack打包
+./node_modules/.bin/webpack --mode=production &&
+# 创建目录
+if [ ! -d dist/auxiliary ]; then mkdir -p dist/auxiliary; fi &&
+# 迁移辅文件
+mv ./dist/exmd/src/auxiliary.js ./dist/auxiliary/index.js &&
+# 拷贝package.json
+cp ./package.json ./dist/exmd/package.json &&
+cp ./resources/index.d.ts ./dist/exmd/index.d.ts

package/bin/check-node.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+NODE_VERSION="$(node -v 2>/dev/null)"
+if [ $? -ne 0 ]; then
+  echo "只支持16版本"
+  exit 1
+fi
+
+case "$NODE_VERSION" in
+  v16.*)
+    exit 0
+    ;;
+  *)
+    echo "只支持16版本"
+    exit 1
+    ;;
+esac

package/bin/copy-to-publish.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+name="~/发布包/exmd-dist"
+if [ ! -d name ]; then rm -rf name; fi
+cp -r ./dist ~/发布包
+mv ~/发布包/dist ~/发布包/exmd-dist
+echo "拷贝完成，发布路径是：${name}"
+unset name