aiquery2/api

@peace/template_front_server

基于 Nodejs 20+，Koa 2.x 的 Web 服务模板【API】。

简介

本项目以核心包 @peace/node_server 封装服务内容。

提供日常工作所需的变量配置、ORM 配置、自定义鉴权、定时任务、跨平台数据请求、工具函数配置、常用工具预置等相关内容。

使用

使用前可参阅下方 目录结构 了解项目结构

启动服务

确保 Node.js 和 npm 已安装。

npm start

建议使用 vscode 的 运行和调试（F5）快捷键启动服务，更可方便配置环境变量

项目配置

项目配置文件位于 config 目录下，可根据实际需求进行配置。

默认配置 default.js

配置内容均已在 default.js 中预置和注释说明，可根据实际需求进行修改。

Seq模型关系配置 modelResolve.js

Sequelize 模型关系配置文件，用于配置模型之间的外键关联关系。

Sequelize 自动化模型生成配置 sequelize-automate.js

Sequelize 自动化模型生成配置文件，用于生成数据库表和模型的映射关系models文件。

配置后可通过以下命令生成模型文件：

npm run seq-automate

控制器

控制器应编写于 app/controllers 目录下。

路由

路由应编写于 app/routes 目录下。

可以从 const { middlewares: { auth } } = app 获取预置的鉴权中间件。

const auth = require('../controllers/auth');

module.exports = function (app, router, conf) {
    const { middlewares: { auth: authenticator } } = app

    router.put('/eg', authenticator, auth.eg, { content: '实例', visible: false });
};

其中 router[method] 的最后一个参数可以配置为对象，用于配置接口的文档信息。

{
    content: '接口说明', // 接口说明
    visible: false      // 是否在后续应用中展示
}

Koa 中间件

Koa 中间件应编写于 app/middlewares 目录下。

预置 Auth （auth.js） 中间件，符合一般项目鉴权方式，可根据实际需求进行修改。

• 编写中间件：

  每一个文件为一个中间件，需暴露一个中间件函数，接受 ctx 和 next 两个参数。

  module.exports = async (ctx, next) => {
     // do something
     await next();
  };
  

• 使用中间件： 中间件会被挂载在 app.middlewares 对象上，使用文件名作为键名，可通过以下方式获取：

  ctx?.app.middlewares[中间件文件名];
  

Sequelize 模型

Sequelize 模型应编写于 app/models 目录下。

定时任务

基于 node-schedule 的定时任务功能，二次封装。

定时任务应编写于 app/schedules 目录下。

• 编写定时任务：

  每一个文件为一个定时任务，需暴露一个函数，接受 app 和 conf 两个参数。

  • app：Koa 实例。
  • conf：项目所有配置参数。

     module.exports = {
        conf: {
           interval: '0 */1 * * * *',      // 定时任务执行时间
           /**
               *  *    *    *    *    *    *
                 ┬    ┬    ┬    ┬    ┬    ┬
                 │    │    │    │    │    │
                 │    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
                 │    │    │    │    └───── month (1 - 12)
                 │    │    │    └────────── day of month (1 - 31)
                 │    │    └─────────────── hour (0 - 23)
                 │    └──────────────────── minute (0 - 59)
                 └───────────────────────── second (0 - 59, OPTIONAL)
           */
           immediate: false,                // 是否立即执行
           env: ['dev', 'prod'],           // 指定运行环境
           disabled: false                  // 是否禁用 
        },
        callback: function async (app, conf) {
           console.log('@peace schedule');
        },
     };
  
  

  定时任务函数在项目初始化时即被初始化，并挂在在 app.schedules 对象上，可根据需要在适当的时候重新调整运行策略（除 disabled=true 的配置外）

服务功能

封装与外部系统（如 API、数据库、第三方服务）交互的业务逻辑。

• 业务相关性强：直接与具体的业务需求或外部服务挂钩。
• 副作用：可能会引发网络请求、修改数据库、或依赖其他外部系统。
• 模块化：每个服务文件通常对应一个具体的领域或外部系统。

服务类功能应编写于 app/services 目录下。

• 编写服务类功能函数：

  每一个文件为一个功能服务，需暴露一个函数，接受 app 和 conf 两个参数。

  • app：Koa 实例。
  • conf：项目所有配置参数。

  module.exports = async (app, conf) => {
     // do something
  };
  

  服务类功能函数一般在项目初始化时即被调用，可在函数内部实现具体的业务初始化或挂载逻辑。

工具函数

存放与业务逻辑无关的通用工具函数或模块，可以在整个项目中广泛复用。

• 通用性强：函数或模块不依赖具体的业务逻辑。
• 无副作用：通常不会引入状态或直接与外部系统（如 API、数据库）交互。
• 范围广泛：适用于多个功能模块或项目。

工具类函数应编写于 app/utils 目录下。

• 编写工具类功能函数：

  每个文件可以暴露多个工具类函数，可根据实际需求进行导出。

  module.exports.具体函名称 = (params) => {
     // do something
  };
  

• 使用工具类功能函数： 各工具类功能函数会被挂载在 app.fs.utils 对象上，可通过以下方式获取：

  ctx?.app.fs.utils[工具类功能函数名];
  

入口文件

入口文件为 app/index.js，在项目初始化的最后阶段调用，传入app、 router和conf三个参数，可进行其他自定义应用。

构建

项目提供了 Docker 构建配置文件 Dockerfile 和 Jenkins 构建配置文件 jenkinsfile，根据实际需求进行修改配置。

目录结构

├── .vscode                            // vscode 相关配置
|   ├── launch.json                    // 启动命令配置，包含环境变量
|   └── settings.json
├── app
│   ├── controller                     // 控制器：接口函数
│   ├── middlewares                    // Koa 中间件
│   ├── models                         // Sequelize 模型定义
│   ├── routes                         // 路由
│   ├── schedules                      // 定时任务
│   ├── services                       // 服务类功能函数
│   ├── utils                          // 工具类功能函数
│   └── index.js                       // 入口文件
├── config                             // 项目配置
│   ├── default.js                     // config
│   ├── modelRelation.js               // 存放 sequelize Model 关联关系代码
│   └── sequelize-automate.js          //
├── logs                               // 日志
├── .editorconfig                      // 代码风格配置
├── .gitignore                         // git 忽略配置
├── .npmrc                             // npm 配置
├── Dockerfile                         // Docker 构建配置
├── jenkinsfile                        // Jenkins 构建配置
├── package.json                          
├── README.md                          // 项目说明