egg初始化搭建swagger项目

安装node

• 至Node.js 官网下载长期支持版本（LTS结尾的版本）

安装你喜欢的编辑器

• Visual studio code、
• Atom
• …

初始化项目

创建一个文件夹，打开命令提示符 cmd

npm init

设置完成之后，生成package.json文件

输入安装 egg 命令

npm install egg --save

输入安装 egg-dev 命令

npm install egg-bin --save-dev

修改 package.json

 "scripts": {
    "dev": "egg-bin dev  -port 7001" // port为端口，默认为7001
 },

基本目录结构（需手动创建）

项目名称
├── app
│ ├── controller（控制器）
│ │ └── home.js
│ ├── service（业务逻辑）
│ ├── extend（公共方法）
│ ├── contract（返回值约束）
│ └── router.js（路由）
├── config（配置）
│ └── config.default.js（配置项，项目基本配置，数据库的链接，egg-swagger-doc配置）
│ └── plugin.js（第三方插件配置，引用，开启状态）
└── package.json

输入安装 egg-sequelize 命令

npm install --save egg-sequelize // 链接数据库插件 
npm install egg-sequelize-auto --save-dev // 对照数据库自动生成相应的models插件
npm install mysql2 --save // 数据库插件

数据库选择

• 数据库建议使用HaoSql，数据库管理软件建议使用SQLyog

配置 sequelize 插件

//app/config/config.default.js
module.exports.keys = "Render"; // 配置项目关键字

exports.sequelize = {
    dialect: 'mysql',   // 数据库类型，支持 mysql,sqlite,mssql,pgsql,oracle
    host: "localhost",  // 数据库服务器地址
    port: 3306, // 数据库连接端口号
    database: "library", // 数据库名称
    username: "root",   // 数据库登录用户名
    password: "haosql",   // 数据库登录密码
    define: {
        freezeTableName: true, // 阻止数据表名变为复数
        timestamps: false // 阻止model生成createAt和updateAt字段
    }
};

// app/config/plugin.js
// 配置 egg-sequelize 插件信息
exports.sequelize = {
    enable: true, // 默认启用
    package: 'egg-sequelize' // 指定启用的包名称
}

修改package.json

 "scripts": {
    "dev": "egg-bin dev  -port 7001"
    "dbinit": "egg-sequelize-auto -o ./app/model -h localhost -p 3306 -d library -u root -x haosql" 
 },

egg-sequelize-auto 指令解释

• -o：模型生成的文件夹路劲
• -h ：数据库地址
• -d ：数据库名
• -u ：用户名
• -x ：密码
• -p：端口号

生成对照数据库相应的models

npm run dbinit // 此指令名称是自定义

• 数据库模型的创建，会经常报错。

输入安装 egg-swagger-doc

npm i egg-swagger-doc --save // 自动生成接口描述配置

配置 egg-swagger-doc

// config/config.default.js
exports.swaggerdoc = {
    dirScanner: './app/controller', // 配置自动扫描的控制器路径
    // 接口文档的标题，描述或其它
    apiInfo: {
        title: 'Render',  // 接口文档的标题
        description: 'swagger-ui for Render document.',   // 接口文档描述
        version: '1.0.0',   // 接口文档版本
    },
    schemes: ['http', 'https'], // 配置支持的协议
    consumes: ['application/json'], // 指定处理请求的提交内容类型（Content-Type），例如application/json, text/html
    produces: ['application/json'], // 指定返回的内容类型，仅当request请求头中的(Accept)类型中包含该指定类型才返回
    securityDefinitions: {  // 配置接口安全授权方式
        // apikey: {
        //   type: 'apiKey',
        //   name: 'clientkey',
        //   in: 'header',
        // },
        // oauth2: {
        //   type: 'oauth2',
        //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
        //   flow: 'password',
        //   scopes: {
        //     'write:access_token': 'write access_token',
        //     'read:access_token': 'read access_token',
        //   },
        // },
    },
    enableSecurity: false,  // 是否启用授权，默认 false（不启用）
    // enableValidate: true,    // 是否启用参数校验，默认 true（启用）
    routerMap: true,    // 是否启用自动生成路由，默认 true (启用)
    enable: true,   // 默认 true (启用)
};

// config/plugin.js
// 配置 egg-swagger-doc 插件信息
module.exports.swaggerdoc = {
    enable: true,   // 启用 swagger-ui 默认启用
    package: 'egg-swagger-doc', // 指定 第三方插件 包名称
};

创建业务逻辑层

// app/service/home.js
const { Service } = require('egg'); //拿到 egg 对象的Service基类

• 所有的业务逻辑都在业务层设置完成，在控制层只是调用相应的方法即可

// app/service/home.js
class HomeService extends Service{
    constructor(ctx,tableName){
        super(ctx); // 继承上下文
        this.tableName = tableName; 
        this.datebase = this.ctx.model[tableName]; // 根据表名获得相应的数据模型
    }

    /**
     * 根据id主键查询数据
     * @param {*} id 
     */
    async getById(id){
        const entity = await this.datebase.findByPk(id); // 根据id主键查询数据
        return entity; //将结果集返回
    }
}
module.exports = HomeService; //将业务逻辑暴露

创建控制器（api接口）

// app/controller/home.js
const { Controller } = require('egg'); //解构出 Controller 基类

// app/controller/home.js
/**
 * @controller HomeService home接口
 */
class HomeController extends Controller{
    /**
    * @summary 根据Id获取信息
    * @description 根据Id获取信息
    * @router get /v1/book/getBook
    * @request query integer Id ID
    * @response 200 JsonResult 操作结果
    */
    async getBook(){
        const { ctx,service } = this; //解构出应用上下文和业务逻辑
        const id = ctx.query.Id; //获取参数
        const result = await service.home.getById(id); //使用业务逻辑层的方法返回值
        ctx.body = result; //JsonResult 返回结果必须进行处理
    }
}
module.exports = HomeController;

配置接口返回值的约束（必须配置）

//app/contract/type.js
module.exports = {
        // 默认接口类型
        JsonResult: { //@response 200 JsonResult 操作结果，名字与相应结果对应
            success: { type: 'boolean' },    // 结果
            results: { type: 'string' }     // 服务器返回的数据
        },
}

配置路由router.js

// app/router.js
module.exports = app => { //ES6
    app.router.redirect('/', '/swagger-ui.html' , 302); //重定向到swagger-ui.html
}

项目搭建完成

npm run dev //运行

总结

• 项目搭建流程，主要是egg相关的各个插件
• egg、egg-bin、egg-sequelize、egg-swagger-doc、egg-sequelize-auto
• 数据库 mysql2
• 在package.json配置命令行，运行。
• 在config中引用配置插件信息
• 生成数据库模型、创建业务逻辑层，创建控制层，创建返回值约束
• 业务逻辑层尽量使用sql语句来编写，操作灵活，清晰。
• 需要熟练sql语言，链表查询，条件查询等较复杂的逻辑。