# fs_template_api_2.0

**Repository Path**: bocinpity/fs_template_api_2.0

## Basic Information

- **Project Name**: fs_template_api_2.0
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @peace/template_front_server

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

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

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

## 安装
说明如何安装和配置项目。

```bash
npm init peace
```

选择 `service` 模板进行初始化

## 使用

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

### 启动服务

确保 Node.js 和 npm 已安装。

```bash
npm start
```

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

### 项目配置

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

#### 默认配置 `default.js`

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

#### Seq模型关系配置 `modelResolve.js`

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

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

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

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

```bash
npm run seq-automate
```

### 控制器

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

### 路由

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

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

```javascript
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]` 的最后一个参数可以配置为对象，用于配置接口的文档信息。
```javascript
{
    content: '接口说明', // 接口说明
    visible: false      // 是否在后续应用中展示
}
```

### Koa 中间件

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

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

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

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

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

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

### Sequelize 模型

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


### 定时任务

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

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

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

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

   ```javascript
      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：项目所有配置参数。

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

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

### 工具函数

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

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

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

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

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

   ```javascript
   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                     //                  
│   ├── modelResolve.js                //
│   └── sequelize-automate.js          //
├── logs                               // 日志
├── .editorconfig                      // 代码风格配置
├── .gitignore                         // git 忽略配置
├── .npmrc                             // npm 配置
├── Dockerfile                         // Docker 构建配置
├── jenkinsfile                        // Jenkins 构建配置
├── package.json                          
├── README.md                          // 项目说明
```


## 贡献
说明如何贡献代码和提交问题。

### 提交问题
如果你在使用过程中遇到问题，可以通过 [GitHub Issues](https://gitee.com/yuan_yi/fs_template_api_2.0/issues) 提交问题。请提供详细的信息以帮助我们理解和解决问题。

### 贡献代码
1. Fork 本仓库。
2. 创建一个新的分支：`git checkout -b feature-branch`。
3. 提交你的修改：`git commit -am 'Add new feature'`。
4. 推送到分支：`git push origin feature-branch`。
5. 创建一个 Pull Request。

我们会尽快审核你的 Pull Request，并与您讨论任何需要改进的地方。感谢你的贡献！