Menuet Web 应用开发框架
Menuet Web 应用开发框架旨在提高 Web 应用开发效率,规范项目开发流程。
Menuet 基于 proding.net 的设计规范实现。
Menuet Web 应用开发框架具有以下特点:
- 自动实现业务分层:将各业务分层的模块的定义文件置于相应的路径下即可;
- 模块间调用通过注入的方式实现:如果模块A的业务逻辑依赖于模块B,那么只需将模块B的名称作为模块A定义函数的参数(即依赖注入),模块A即可调用模块B;
- 规范了模块之间的调用关系:例如只可向服务层的模块注入工具模块和数据模型,服务模块不可依赖其他服务;
- 使用 JSON Schema 对请求数据及响应数据进行校验;
- 可根据路由定义及 JSON Schema 定义自动生成 API 文档。
运行 Menuet Web 应用开发框架需要 Node.js v7.0.0 或以上版本。
配置依赖模块
使用 Menuet Web 应用开发框架前需要在工程的 package.json
文件的 dependencies
字段中添加 menuet
模块的依赖。
安装依赖包后即可使用 menuet
初始化工程。
$ npm install
初始化工程
在 package.json
中添加以下脚本:
执行该脚本,Menuet Web 应用开发框架将使用示例工程代码初始化当前工程,本说明文档将以该示例工程展开说明。
$ npm run init
注意:初始化后,工程目录下的文件将会被示例工程代码替换,包括
package.json
文件。开始正式开发前,请将示例工程的package.json
中的init
脚本配置删除。
默认工程结构
/ ├─ config │ ├─ development.json │ ├─ production.json │ └─ api-docs.json ├─ public │ └─ ** ├─ static │ └─ **.json ├─ views │ └─ *.ejs ├─ schemas │ ├─ **.json │ ├─ keywords.js │ └─ formats.js ├─ utils │ └─ *.js ├─ models │ └─ *.js ├─ services │ └─ *.js ├─ interceptors │ └─ *.js ├─ controllers │ └─ *.js ├─ resolvers │ ├─ default.js │ └─ error.js ├─ routes │ └─ *.json ├─ package.json └─ init.js
文件 | 说明 |
---|---|
/config/development.json |
开发环境配置文件 |
/config/production.json |
产品环境配置文件 |
/config/api-docs.json |
文档生成工具配置文件 |
/public/** |
静态资源文件 |
/static/** |
静态化文件 |
/view/*.ejs |
视图模板文件 |
/schemas/keywords.js |
自定义 JSON Schema 关键字定义文件,输出一个关键字与关键字定义的 Map,关键字定义请参考AJV: Defining custom keywords |
/schemas/formats.js |
自定义 JSON Schema 格式定义文件,输出一个格式名与格式正则表达式的 Map |
/schemas/default-keywords.json |
默认关键字配置 |
/schemas/**.json |
JSON Schema 定义文件 |
/utils/*.js |
工具模块定义文件,模块定义及调用方法详见下文 |
/models/*.js |
数据模型定义文件,数据模型定义及调用方法详见下文 |
/services/*.js |
服务模块定义文件,服务定义及调用方法详见下文 |
/interceptors/*.js |
拦截器定义文件,拦截器定义及调用方法详见下文 |
/controllers/*.js |
控制器定义文件,控制器定义及调用方法详见下文 |
/resolvers/default.js |
默认请求结果解析器定义文件 |
/resolvers/error.js |
错误结果解析器定义文件 |
/routes/*.js |
路由定义文件 |
/package.json |
包定义文件 |
/init.js |
工程初始化逻辑定义文件 |
工程结构可通过设置配置文件的
paths
字段更改,详见下文。
工程配置文件
请将工程配置文件置于工程的 /config
路径下,文件名为运行环境名称,如 development.json
、production.json
。
默认配置内容:
字段 | 说明 | 可选值/备注 |
---|---|---|
defaults.language |
默认语言 | en 、zh-cn 等 |
defaults.domain |
域名 | |
http.port |
HTTP 服务端口 | |
http.jsonParser |
JSON 解析中间件配置参数 | 参考链接:bodyParser.json([options]) |
http.urlencodedParser |
URL encoded 解析中间件配置参数 | 参考链接:bodyParser.urlencoded([options]) |
http.cookieParser |
Cookie 解析中间件 secret 参数 | |
http.allowCrossDomainAccess |
是否允许浏览器跨域访问 | |
http.router |
Express 路由器配置参数 | 参考链接:express.Router([options]) |
http.base |
API 接口的跟路径 | |
paths.public |
静态资源保存文件夹路径 | |
paths.static |
API 响应结果静态化文件保存文件夹路径 | |
paths.views |
EJS 模板保存文件夹路径 | |
paths.strings |
多语言字典文件保存文件夹路径 | 不同语言的字典文件名根据语言名称命名,如 en.json 、zh-cn.json 等 |
paths.schemas |
请求/响应数据 JSON Schema 文件保存路径,遵循 JSON Schema Draft-06 标准 |
参考连接:JSON schema |
paths.utils |
工具模块保存文件夹路径 | |
paths.models |
MongoDB 数据模型保存文件夹路径 | |
paths.services |
服务模块保存文件夹路径 | |
paths.interceptors |
拦截器定义文件保存文件夹路径 | |
paths.controllers |
控制器定义文件保存文件夹路径 | |
paths.defaultResolver |
正常结果解析器文件路径 | |
paths.errorResolver |
错误结果解析器文件路径 | |
paths.routes |
路由定义文件保存文件夹路径 | |
paths.init |
工程初始化文件路径 |
使用单实例 MongoDB 时添加以下配置内容:
字段 | 说明 | 可选值/备注 |
---|---|---|
mongo.host |
数据库服务器 IP 地址 | 配置产品环境时应使用内网 IP 地址 |
mongo.port |
mongod 进程端口,默认:27017 | |
mongo.db |
数据库名称 | |
mongo.username |
用户名 | |
mongo.password |
密码 |
使用 MongoDB 复制集时添加以下配置内容:
字段 | 说明 | 可选值/备注 |
---|---|---|
mongo.hosts.host |
数据库服务器 IP 地址 | 配置产品环境时应使用内网 IP 地址 |
mongo.hosts.port |
mongod 进程端口,默认:27017 | |
mongo.replicaSet |
复制集名称 | |
mongo.db |
数据库名称 | |
mongo.username |
用户名 | |
mongo.password |
密码 |
使用 Redis 时添加以下配置内容:
字段 | 说明 | 可选值/备注 |
---|---|---|
redis.host |
数据库服务器 IP 地址 | 配置产品环境时应使用内网 IP 地址 |
redis.port |
redis-server 进程端口,默认:6379 | |
redis.password |
密码 |
可以扩展配置文件的内容以供具体业务使用。
模块的业务分层及调用约束
根据业务分层,模块被分为以下几类:
模块 | 作用 | 可调用(注入)的模块 |
---|---|---|
工具(Utilities) | 用于实现与业务无关的功能,如图像压缩处理、数据加密等 | 工程配置信息、其他工具模块 |
数据模型(Models) | 定义实体的数据结构,实现对实体的操作逻辑 | 工程配置信息、工具模块 |
服务(Services) | 实现特定的业务逻辑 | 工程配置信息、工具模块、数据模型 |
拦截器(Interceptors) | 接收到客户端请求并完成路由后执行的处理,如权限检查、上传文件解析等 | 工程配置信息、工具模块、服务模块 |
控制器(Controllers) | 调用不同的服务完成特定的业务处理 | 工程配置信息、工具模块、服务模块 |
解析器(Resolvers) | 对控制器的执行结果进行解析、再组装,并返回给客户端,如 HTTP 状态码设置,错误消息封装等 | 工程配置信息、工具模块、服务模块 |
工程配置信息通过
$config
参数名注入。
定义工具(Utilities)
工具定义模块输出一个函数(工厂模式),该函数返回一个对象作为工具的实例。
工具模块的全局名称将为文件名驼峰化加 Util
的形式(例如下面例子中 /utils/crypto.js
生成的模块将被命名为 CryptoUtil
)。
若要自定义模块名称,可以在定义函数上添加
moduleName
符号属性,其值即为模块名称(例如下面例子中/utils/errors.js
生成的模块将被命名为Errors
)。
可以通过工具模块的名称向数据模型、服务、拦截器、控制器、解析器的定义函数注入工具模块。
// /utils/crypto.js'use strict'; const crypto = ; /** * 取得指定字符串指定摘要算法的摘要。 * * @param * @param * @param * @param * @returns */const digest = { if typeof base64 === 'string' charset = base64; base64 = false; string = string; return crypto ;}; /** * 数据加密工具生成器。 * * @returns */module { return /** * 生成字符串的 MD5 摘要。 * * @param * @param * @param * @returns */ { return ; } /** * 生成字符串的 SHA-384 摘要。 * * @param * @param * @param * @returns */ { return ; } ; };
// /utils/errors.js'use strict'; /** * 返回错误类。 * * @returns */module { /** * 登录认证失败错误。 * @extends */ { supermessage; thisname = 'AuthenticationError'; thisstatusCode = 401; } /** * 未登录错误。 * @extends */ { supermessage; thisname = 'UnauthorizedError'; thisstatusCode = 401; } return AuthenticationError UnauthorizedError ; }; moduleexportsSymbol = 'Errors';
定义数据模型(Models)
数据模型定义模块输出一个函数(工厂模式),该函数返回一个 Mongoose 的 Schema 实例,框架将使用该 Schema 实例注册一个 Mongoose 数据模型。
数据模型的全局名称将为文件名驼峰化加 Model
的形式(例如下面例子中的数据模型将被命名为 UserModel
)。
可以通过数据模型的名称向服务、拦截器、控制器、解析器的定义函数注入数据模型。
// /models/user.js'use strict'; const bcrypt = ; /** * 返回用户实体 Mongoose 数据模式。 * * @returns */module { let userSchema = // 姓名 name: String // 头像路径 avatar: String // 用户账号类型(admin:管理员;user:普通用户) type: dataType: String enum: 'admin' 'user' default: 'user' // 登录用户名 username: String // 登录密码 password: String // 账号创建时间 createAt: dataType: Date default: Datenow collection: 'users' typeKey: 'dataType' ; // 定义唯一索引 userSchemaindex username: 1 unique: true ; /** * 对登录密码加密。 * * @param * @returns */ const encryptPassword = { return bcrypt; }; // 保存用户登录账号信息前先对登录密码加密 userSchema; /** * 校验登录密码。 * * UserModel 的静态方法。 * @param * @param * @returns */ userSchemastatics { return bcrypt; }; return userSchema;};
定义服务(Services)
服务定义模块输出一个函数(工厂模式),该函数返回一个对象作为服务的实例。
数据模型的全局名称将为文件名驼峰化加 Service
的形式(例如下面例子中的服务将被命名为 UserService
)。
可以通过服务的名称向拦截器、控制器、解析器的定义函数注入数据模型。
// /services/user.js'use strict'; const jwt = ;const JWT_SECRET = 'your-json-web-token-secret'; /** * 生成 JSON Web Token。 * * @param * @returns */const signJWT = { return { jwt; };}; /** * 验证 JSON Web Token。 * * @param * @returns */const verifyJWT = { return { jwt; };}; /** * 返回用户账号服务实例。 * * @param * @returns */module { return /** * 创建用户账号。 * * @param * @param * @param * @param * @param * @returns */ async { return await userInfo; } /** * 用户登录认证。 * * @param * @param * @returns */ async { let userDoc = await UserModel ; if !userDoc || !UserModel throw '用户名或密码不正确'; userDocaccessToken = await ; return userDoc; } /** * 取得用户账号信息。 * * @returns */ async { return await UserModel; } /** * 验证访问令牌。 * * @param * @returns */ async { return await ; } /** * 更新用户账号信息。 * * @param * @param * @param * @returns */ async { await UserModel; } ; };
定义控制器(Controllers)
控制器定义模块输出一个对象,该对象的所有方法将作为请求处理器。
请求处理器的第一个参数为上下文(Context)对象,其他参数为注入参数(工具、服务)。
上下文对象的数据结构:
字段 | 类型 | 说明 |
---|---|---|
params |
对象 | 路径参数 |
query |
对象 | 查询参数 |
body |
对象 | 请求数据 |
Symbol.for('request') |
对象 | HTTP 请求实例 |
Symbol.for('response') |
对象 | HTTP 响应实例 |
在路由定义中,通过控制器定义文件名加控制器方法名指定路由的处理器(例如下面的 signUp
和 signIn
方法可分别通过 user.signUp
和 user.signIn
指定)。
// /controllers/user.js'use strict'; /** * 用户注册。 * * @param * @param * @returns */exports { return await UserService;}; /** * 用户登录。 * * @param * @param * @returns */exports { return await UserService;}; /** * 取得用户账号详细信息。 * * @param * @param * @returns */exports { return await UserService;}; /** * 设置用户头像。 * * @param * @param * @returns */exports { return await UserService;};
定义路由(Routes)
以下为用户业务 API 路由定义的示例(/routes/user.json
)。
字段 | 数据类型 | 是否必须 | 说明 |
---|---|---|---|
index |
整数 | 指定该业务在 API 文档中索引的顺序,未指定该字段时将不会生成相应业务的文档 | |
title |
字符串 | 业务名称 | |
routes |
对象数组 | 是 | 路由定义列表 |
routes.name |
字符串 | 是 | 接口名称 |
routes.description |
字符串 | 接口说明 | |
routes.method |
字符串 | 是 | 接受的请求方法,可选值:get 、post 、put 、patch 、delete 、options 、head |
routes.path |
字符串 | 是 | 请求路径,参照 Path examples |
routes.params |
字符串 | 路径参数数据模式定义文件路径 | |
routes.query |
字符串 | 查询参数数据模式定义文件路径 | |
routes.body |
字符串 | 请求数据模式定义文件路径 | |
routes.interceptors |
字符串数组或对象数组 | 请求拦截器名称或拦截器选项,参考下文的“定义拦截器”部分 | |
routes.interceptors.name |
字符串 | 请求拦截器名称 | |
routes.interceptors.options |
字符串 | 请求拦截器执行选项 | |
routes.handler |
字符串 | 是 | 请求处理器名称,参考上文的“定义控制器”部分 |
routes.response |
字符串 | 响应数据模式定义文件路径 |
定义请求数据及响应数据的数据模式(JSON Schema)
客户端请求数据(路径参数、查询参数、Body 数据)及服务器返回结果需要通过数据模式校验,若未指定数据模式则相应的数据将被替换为空对象。
本 Web 应用开发框架使用 Node.js 的 NPM 模块 AJV 对请求数据及响应数据进行校验,AJV 遵循 JSON Schema 标准。
默认 Schema(通过 $schema
属性设置)为 http://json-schema.org/draft-07/schema#
。
默认配置下,请将 JSON Schema 定义文件置于工程的 /schemas
路径下,路由定义中将通过文件路径引用 JSON Schema 定义(例如 /schemas/user/user.json
将通过 user/user
引用)。
上述“用户注册”接口的请求数据的数据模式定义示例(/schemas/user/sign-up-form.json
):
根据以上数据模式定义:
- 必须设置登录用户名及登录密码;
- 姓名为字符串,格式必须符合在
/schemas/formats.js
中定义的name
的格式;- 登录用户名为字符串,格式必须符合在
/schemas/formats.js
中定义的username
的格式,且长度必须大于等于 3 且小于等于 20;- 登录密码为字符串,长度必须大于等于 8 且小于等于 64。
如果请求数据不符合数据模式定义,请求将中止,并将返回数据校验错误给客户端;
否则,如果客户端提交了其他字段,这些字段将从请求数据中删除。
可在 /schemas/default-keywords.json
中为指定路径下的指定类型字段设置默认关键字,如:
可用关键字请参考 AJV Keywords
根据以上默认关键字设置:
/schemnas/request/
路径下的所有数据模式定义中的字符串类型的字段若未设置transform
关键字,那么其transform
关键字将被设置为["trim"]
定义拦截器(Interceptors)
可以通过在路由定义中添加拦截器设置实现在执行业务处理前执行如访问令牌校验、权限检查、上传文件接收等处理。
下面以设置用户头像为例。
首先定义两个拦截器,分别用于校验访问令牌和接收上传的头像文件数据:
拦截器的前两个参数
req
和options
是固定传入的参数,其他参数通过名称注入工程配置数据、已定义的工具或服务。
将从访问令牌解析得到的用户信息以符号
x-user-info
设置到请求数据中后,框架将会从请求数据中取得用户信息并可在控制器中通过context.user
取得用户信息。
// /interceptors/verify-access-token.js'use strict'; const USER_INFO = Symbol; /** * 检查访问令牌是否有效。 * 访问令牌通过 Authorization 请求头传递,格式为“Bearer 访问令牌”。 * * @see https://jwt.io/introduction/ * @param * @param * @param * @param * @returns */moduleexports = async { let accessToken = req || '' || 1; if !accessToken throw '尚未登录'; reqUSER_INFO = await UserService;};
上传文件接收拦截器使用
multer
模块解析 HTTP 请求中的文件数据。
// /interceptors/upload-image.js'use strict'; const promisify = promisify;const multer = ;const path = ;const moment = ; /** * 接收上传的文件。 * * @param * @param * @param * @param * @param */moduleexports = async { const uploadFile = ; await ; if !reqfile reqbodyoptionsfieldName = null; return; reqbodyoptionsfieldName = path; };
定义请求数据的数据模式(/schemas/user/set-avatar-form.json
):
路由配置:
通过以下配置,客户端调用
/user/avatar
接口时必须将有效的用户令牌设置到Authorization
请求头中。
定义解析器(Resolvers)
通过定义解析器可以对请求处理器返回的结果进行解析,如 HTTP 状态码设置、错误信息记录、错误处理等。
下面以错误处理为例:
// /resolvers/error.js'use strict'; /** * 错误解析器。 * * @param * @param * @param * @returns */moduleexports = async { resstatusCode = errorstatusCode || 400; delete errorstatusCode; // 当为 JSON schema 校验错误时,格式化返回的错误数据 if errorname === 'RequestDataValidationError' || errorname === 'ResponseDataValidationError' errorpaths = errorerrors || ; errormessage = '数据校验错误'; delete errorajv; delete errorvalidation; delete errorerrors; // 当为 Mongoose 数据模型校验错误时,格式化返回的错误数据 else if errorname === 'ValidationError' errorpaths = Object; errormessage = '数据校验错误'; delete error'_message'; delete errorerrors; return error ;};
应用初始化
在应用启动时如果需要对应用进行初始化(如创建必要路径、创建管理员用户账号等),可以在配置文件的 paths.init
字段指定的文件中实现初始化逻辑。
下面的示例实现了应用启动前创建管理员用户账号的逻辑:
// /init.js'use strict'; /** * 初始化应用。 * * @param */moduleexports = async { // 创建管理员用户账号 try await UserService; catch e if !ename === 'MongoError' && ecode === 11000 throw e; };
启动应用
在工程的 package.json
的 scripts
字段中添加以下脚本:
以下示例为使用 PM2 在生产环境启动的脚本设置:
使用 PM2 时需要配置 /app.json
文件(参考链接:PM2 Application Declararion):
以开发模式启动:
$ npm run start-debug
以生产模式启动:
$ npm run start
生成 API 文档
通过在 package.json
文件中添加脚本执行 menuet-docs
命令,可以根据路由定义生成 API 文档。
menuet-docs
命令接受以下参数:
--lang
:文档语言,如en
、zh-cn
--config
:文档配置文件路径,如config/api-docs.json
--output
:文档输出路径,如public/docs
脚本设置示例(/package.json
):
配置文件内容如下(/config/api-docs.json
):
执行脚本,生成 API 文档:
$ npm run docs
© 2017-present LiveBridge Information Technology Co., Ltd.