seven-cloudapp-frame-node

Koa 中间件框架，专为淘宝小程序云开发场景打造。封装 MongoDB / Redis / 阿里云 OSS / 淘宝 TOP API / 日志 / 定时触发器等通用能力，开箱即用。

特性

• MongoDB 增强集合操作（EnhancedCollection）：自动 ObjectId、SQL 日志、防止空条件删除
• Redis 连接池 + 共享复用（middleware/redis.js）
• 阿里云 OSS 文件上传/下载（middleware/file.js）
• 淘宝 TOP API 调用封装（utils/api/topClient.js）
• 日志中间件 支持写入 MySQL 或 Redis（utils/logger.js）
• 定时触发器 基于 cron 表达式自动调用本地接口（middleware/timing_trigger.js）
• 请求/响应：自动合并 query + body 到 ctx.data，handler 返回值直接作为响应体
• 错误处理：统一捕获 + 应用级错误事件

安装

npm install seven-cloudapp-frame-node
# 或者
yarn add seven-cloudapp-frame-node

要求：Node.js >= 14，Koa 2.x（作为 peerDependency）。

快速开始

const Koa = require('koa');
const { createMiddleware } = require('seven-cloudapp-frame-node');

// 你的配置对象
const config = {
  project_name: 'my_project',
  port: 3000,
  app_key: 'your_taobao_app_key',
  app_secret: 'your_taobao_app_secret',
  database: {
    connectionString: 'mongodb://user:pass@host:port/?directConnection=true',
    db: 'your_db',
  },
  redis: { host: '127.0.0.1', port: 6379, password: '', db: 0 },
  oss_config: {
    ak_id: 'your_oss_ak_id',
    ak_secret: 'your_oss_ak_secret',
    end_point: 'oss-cn-zhangjiakou',
    bucket_name: 'your_bucket',
    demain: 'https://oss-cn-zhangjiakou.aliyuncs.com/',
  },
  logger: {
    storage: {
      engine: 'mysql',  // 或 'redis'
      config: { host: '127.0.0.1', port: 3306, user: 'root', passwd: 'pass', db: 'log_db' },
      level_setting: [
        { storage: true, level: 'http',  key: 'python_log_http_tb' },
        { storage: true, level: 'sql',   key: 'python_log_sql_tb' },
        { storage: true, level: 'info',  key: 'python_log_info_tb' },
        { storage: true, level: 'error', key: 'python_log_error_tb' },
      ],
    },
  },
  timing_trigger_config: [
    // { route: '/cron/demo', is_async: false, cron: '0 * * * * *' }
  ],
};

const app = new Koa({ proxy: true });
app.use(createMiddleware(config));

app.listen(config.port, () => {
  console.log(`Server running on port ${config.port}`);
});

中间件加载顺序

createMiddleware(config) 会按下面顺序挂载：

1. koa-bodyparser — body 参数解析
2. before — 合并 query + body 到 ctx.data，初始化 ctx.openId / ctx.cloud._options 等
3. logger — 请求日志，挂载 ctx.logger
4. db — MongoDB 连接，挂载 ctx.cloud.db.collection
5. taobao_api — 淘宝 TOP API，挂载 ctx.cloud.topApi.invoke
6. file — 阿里云 OSS，挂载 ctx.cloud.file.uploadFile / downloadFile
7. error_handler — 统一错误捕获
8. after — 将 handler 返回值赋给 ctx.body

单独使用某个中间件

每个中间件都可以独立引入：

const {
  before, after, errorHandler,
  redis, timingTrigger,
} = require('seven-cloudapp-frame-node');

// 不需要 config 的直接用
app.use(before);
app.use(after);
app.use(errorHandler);

// 需要 config 的调用工厂函数
const db = require('seven-cloudapp-frame-node').db(config);
app.use(db);

// redis 工具方法
const { redis_init } = redis;
const client = await redis_init(ctx, { host: '127.0.0.1', port: 6379 }, true);

// 定时触发器
await timingTrigger(3000, config.timing_trigger_config);

ctx 上挂载的能力

中间件运行后，ctx 上会有以下字段：

| 字段 | 类型 | 说明 | |---|---|---| | ctx.data | Object | 合并自 query + body 的参数 | | ctx.requestId | String | 请求 ID（来自参数 request_id） | | ctx.openId | String | 用户 openId（来自参数 open_id） | | ctx.userNick | String | 用户昵称（来自参数 user_nick） | | ctx.env | String | 环境，默认 test | | ctx.cloud._options.handler | String | 当前 handler 名（路径最后一段） | | ctx.cloud.db.collection(name) | Object | EnhancedCollection 实例 | | ctx.cloud.topApi.invoke(params) | Promise | 调用淘宝 TOP API | | ctx.cloud.file.uploadFile(dict) | Promise | 上传文件流到 OSS | | ctx.cloud.file.downloadFile(dict) | Promise | 从 OSS 下载文件流 | | ctx.logger.logging_link(msg, level, extra) | Promise | 记录链路日志 | | ctx.logger.logging_link_info(msg, extra) | Promise | info 级别日志 | | ctx.logger.logging_link_error(msg, extra) | Promise | error 级别日志 |

EnhancedCollection API

const col = ctx.cloud.db.collection('user_info_tb');

// 查询
const list = await col.find({ status: 1 }, { sort: { create_date: -1 }, limit: 10 });
const count = await col.count({ status: 1 });

// 写入
const newId = await col.insertOne({ name: '张三', age: 18 });
const newIds = await col.insertMany([{ name: '李四' }, { name: '王五' }]);

// 更新
const affected = await col.updateOne({ _id: 'xxx' }, { $set: { age: 19 } });
const affectedMany = await col.updateMany({ status: 0 }, { $set: { status: 1 } });

// 删除（空条件会抛错，防止误删全表）
const deleted = await col.deleteOne({ _id: 'xxx' });
const deletedMany = await col.deleteMany({ status: 0 });

// 聚合
const result = await col.aggregate([
  { $match: { status: 1 } },
  { $group: { _id: '$city', count: { $sum: 1 } } },
]);

淘宝 TOP API 调用

// 在你的 handler 里：
const info = await ctx.cloud.topApi.invoke({
  api: 'taobao.open.trades.sold.get',
  data: {
    fields: 'tid,status,total_fee',
    type: 'fixed',
    page_size: 20,
    page_no: 1,
    session: '用户的session',
  },
});

配置参考

| 字段 | 类型 | 说明 | |---|---|---| | project_name | String/Number | 项目标识，用于日志 | | port | Number | 服务端口 | | app_key | String | 淘宝开放平台 AppKey | | app_secret | String | 淘宝开放平台 AppSecret | | database.connectionString | String | MongoDB 连接串 | | database.db | String | MongoDB 数据库名 | | redis | Object | Redis 配置 { host, port, password, db } | | oss_config | Object | 阿里云 OSS 配置 | | logger.storage.engine | String | mysql 或 redis | | logger.storage.config | Object | 日志存储连接配置 | | logger.storage.level_setting | Array | 日志级别与存储 key 配置 | | timing_trigger_config | Array | 定时触发器配置 |

License

ISC