项目默认编码格式统一为UTF-8格式,语法采用ES6+语法
注释符号后要有一个空格
函数/方法注释放置于函数/方法的上方,主要描述函数/方法功能以及参数类型,参数和返回值说明
/**
* 功能
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值 返回值说明
*/
对代码做简要说明 // 功能简要说明
每段代码应放在一个代码块中。块内的代码都应该统一地缩进一个单位。
使用2个空格作为一个缩进单位。
代码块的开始符号要放在行尾,不可单独一行;代码块结束符号要单独一行。
function demo() { // 代码块开始符号
// ...
} // 代码块结束符号
不同功能或多个代码块之间,使用空白行分隔
/**
* 方法1
*/
function demo1() {
}
/**
* 方法2
*/
function demo1() {
...... // 代码块1
...... // 代码块2
}
全部使用英文单词
尽量使用const代替let 若变量需要改变才使用let 固定常量为全大写,其余使用首字母小写的驼峰命名法
使用首字母小写的驼峰命名
一般情况使用单引号,若字符串拼接,使用"``"和"${}"
不用分号
库的安装和项目的初始化全部使用yarn
egg-init 项目名 --type=simple
yarn install
$ yarn add 库名
$ yarn dev
$ yarn start
向package.json中的scripts键添加一个值
"scripts": {
......
"docker": "egg-sequelize db:migrate && egg-scripts start",
......
}
.
├── app.js
├── app
│ ├── router.js
│ ├── controller
│ ├── extend
│ ├── middleware
│ ├── service
│ ├── public
│ ├── view
│ ├── router
│ ├── io (自建socket.io目录)
│ │ ├── middleware
│ │ └── controller
│ └── model (自建Sequelize目录)
├── config
│ ├── plugin.js
│ ├── config.default.js
│ └── config.prod.js
├── migrations(自建Sequelize目录)
├── logs
└── test
└── app
├── middleware
└── controller
以上目录约定如下:
所有代码均在'use strict'严格模式下开发
包含四个对象对应的文件,以及一个helper工具类
1.代码格式
'use strict'
module.exports = {
/**
* 方法说明
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值名 返回值说明
*/
方法名(参数) {
// 处理逻辑
return 返回值
},
get 属性名() {
// 属性相关逻辑
return 属性
},
set 属性名(值) {
this.set(键, 值)
},
}
2.application.js
对应Application对象
访问方式:
3.context.js
对应context对象
访问方式:
4.request.js
对应request.js对象
访问方式:
5.response.js
对应response.js对象
访问方式:
6.helper.js
工具类,将请求成功和请求失败返回封装的函数以及错误码的封装写到里面
访问方式:
const { app } = this.ctx;
const ctx = app.createAnonymousContext();
ctx.helper.ROOTURL //此变量即可调用
封装状态码,将其解释写在helper里,方便调用
module.exports = {
errorCode: {
200: '请求成功。客户端向服务器请求数据,服务器返回相关数据',
201: '资源创建成功。客户端向服务器提供数据,服务器创建资源',
202: '请求被接收。但处理尚未完成',
204: '客户端告知服务器删除一个资源,服务器移除它',
206: '请求成功。但是只有部分回应',
400: '请求无效。数据不正确,请重试',
401: '请求没有权限。缺少API token,无效或者超时',
403: '用户得到授权,但是访问是被禁止的。',
404: '发出的请求针对的是不存在的记录,服务器没有进行操作。',
406: '请求失败。请求头部不一致,请重试',
410: '请求的资源被永久删除,且不会再得到的。',
422: '请求失败。请验证参数',
500: '服务器发生错误,请检查服务器。',
502: '网关错误。',
503: '服务不可用,服务器暂时过载或维护。',
504: '网关超时。',
}
}
在Controller中响应客户端时,使用
this.ctx.body = {
code: 400,
message: this.ctx.helper.errorCode[400],
data:{
error:'err'
}
}
封装请求成功的方法
module.exports= {
success: ({ ctx, code=200, res=null }) => {
ctx.status = 200
ctx.body = {
code: code,
message: ctx.helper.errorCode[code],
data: res
}
}
}
封装请求失败的方法
module.exports = {
fail: ({ ctx, code=500, res=null }) => {
ctx.status = 200
ctx.body = {
code: code,
message: ctx.helper.errorCode[code],
data: {
error: res
}
}
}
}
请求封装使用例子
ctx.helper.success({ ctx, code:200, res:'success' })
ctx.helper.fail({ ctx, code:500, res:'fail' })
1.plugin.js
引入第三方插件
代码格式:
exports.插件名 = {
enable: true,
package: '库名'
}
例如:
exports.jwt = {
enable: true,
package: 'egg-jwt'
}
2.config.{{env}}.js 访问方式:
'use strict'
module.exports = appInfo => {
const config = exports = {}
// 全局变量
config.变量名=''
// 插件名
config.插件名= {
// 相关配置
}
}
例如:
'use strict'
module.exports = appInfo => {
const config = exports = {}
// redis 配置
config.redis = {
client: {
port: process.env.RS_PORT || 6379,
host: process.env.RS_HOST || '0.0.0.0',
password: process.env.RS_PASSWORD || '',
db: 0,
}
}
}
中间件。对于一些错误拦截,请求处理,需要使用中间件完成。
配置方法:
config.middleware = ['demoMiddleware']
module.exports = app => {
const demo = app.middleware.demoMiddleware()
app.router.get('/url', demo, app.controller.demo)
}
代码格式:
'use strict'
module.exports = () => {
return async function 方法名(ctx, next) {
await next()
// 相关逻辑
}
}
例如:
'use strict'
module.exports = () => {
return async function notFoundHandler(ctx, next) {
await next()
if (ctx.status === 404 && !ctx.body) {
ctx.body = { error: 'Not Found' }
}
}
}
处理错误信息的中间件
'use strict'
module.exports = (option, app) => {
return async function(ctx, next) {
try {
await next()
} catch (err) {
app.emit('error', err, this)
const status = err.status || 500
// 生产环境下不将错误内容返回给客户端
const error = status === 500 && app.config.env === 'prod'
? '服务器错误,请联系管理员!'
: err.message
ctx.helper.fail({ctx, code:status, res:error})
if(status === 422) {
ctx.helper.fail({ctx, code:status, res:err.errors})
}
}
}
}
保持Controller中逻辑简洁,以及业务逻辑的独立性,抽象出的Service可以被多个Controller调用。比如封装数据库操作的方法,API请求封装,第三方服务调用等。
访问方式:
'use strict'
const Service = require('egg').Service
class 类名 extends Service {
/**
* 方法说明
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值名 返回值说明
*/
async 方法名(参数名) {
// 方法逻辑
return 返回值
}
}
方法例子如下:
/**
* 添加礼物
* @param {string} livecode 编号
* @return {int} giftnum 礼物数量
*/
async addGift(livecode) {
const { app } = this
const giftnum = await this.ctx.model.query(`UPDATE live SET gift=gift+1 WHERE livecode='${livecode}'`)
return giftnum
}
三种功能,处理restful接口用户传来的参数;模板渲染;请求代理
访问方式:
'use strict'
const Controller = require('egg').Controller
class 首字母大写的文件名+Controller extends Controller {
async 方法名() {
// 相关逻辑
ctx.body = {
// 返回给restful api接口的请求者
}
}
}
例如:
'use strict'
const Controller = require('egg').Controller
class HomeController extends Controller {
async index() {
const {ctx} = this
if(ctx.isAuthenticated) {
ctx.body = {
user: ctx.user
}
} else {
ctx.body = {
user: 'fail'
}
}
}
}
module.exports = HomeController
描述请求的URL与controller建立的联系。将各个路由分离开来,分别放入router文件夹,并在router.js中引入
代码格式:
'use strict'
/**
* @param {Egg.Application} app - egg application
*/
module.exports = app => {
const { router, controller } = app
router.操作('/URL路径', 中间件1, ...中间件n, controller.文件名.方法)
}
例如:
'use strict'
/**
* @param {Egg.Application} app - egg application
*/
module.exports = app => {
const { router, controller } = app
const roleCheck = app.middleware.roleCheck()
router.get('/user', app.jwt, roleCheck, controller.user.getAllUser)
}
带参路由,两种形式,以及获取参数的方式:
// router.js
router.get('/user/:id', controller.user.info)
// controller
const { ctx } = this
const { id } = ctx.request.params
// router.js
router.get('/user?id=1&age=1', controller.user.msg)
// controller
const { ctx } = this
const { id, age } = ctx.query
开发的时候关闭csrf,防止无法请求接口
// csrf关闭
config.security = {
csrf: {
enable: false
}
}
$ yarn add egg-sequelize mysql2
在plugin.js中启用Sequlize
exports.sequelize = {
enable: true,
package: 'egg-sequelize'
}
在config.{{env}}.js中配置数据库连接.账户相关的信息,开发状态下将信息填入config.local.js;部署环境下,将信息填入config.prod.js
config.sequelize = {
dialect: 'mysql',
database: process.env.DB_DATABASE || '数据库名',
host: process.env.DB_HOST || 'IP地址',
port: process.env.DB_PORT || '数据库端口号',
username: process.env.DB_USER || '数据库用户名',
password: process.env.DB_PASSWORD || '数据库密码',
timezone: '+08:00'
}
在package.json中配置数据库迁移命令
"scripts": {
...
"migrate:new": "egg-sequelize migration:create",
"migrate:up": "egg-sequelize db:migrate",
"migrate:down": "egg-sequelize db:migrate:undo"
}
开发过程中配置自动同步数据库(仅开发模式),在app.js中写入
module.exports = app => {
if(app.config.env === 'local') {
app.beforeStart(async () => {
await app.model.sync({force:true})
})
}
}
文档参考:https://demopark.github.io/sequelize-docs-Zh-CN/models-definition.html
'use strict'
module.exports = app => {
const {类型} = app.Sequelize
const 首字母大写的表名 = app.model.define('表名', {
字段名: {
type: 类型,
// 其他属性
// 是否是唯一
unique: true,
// 定义主键
primaryKey: true,
// 自增
autoIncrement: true,
// 校验
validate: {
is: ["^[a-z]+$",'i'], // 只允许字母
is: /^[a-z]+$/i, // 与上一个示例相同,使用了真正的正则表达式
not: ["[a-z]",'i'], // 不允许字母
isEmail: true, // 检查邮件格式 (foo@bar.com)
isUrl: true, // 检查连接格式 (http://foo.com)
isIP: true, // 检查 IPv4 (129.89.23.1) 或 IPv6 格式
isIPv4: true, // 检查 IPv4 (129.89.23.1) 格式
isIPv6: true, // 检查 IPv6 格式
isAlpha: true, // 只允许字母
isAlphanumeric: true, // 只允许使用字母数字
isNumeric: true, // 只允许数字
isInt: true, // 检查是否为有效整数
isFloat: true, // 检查是否为有效浮点数
isDecimal: true, // 检查是否为任意数字
isLowercase: true, // 检查是否为小写
isUppercase: true, // 检查是否为大写
notNull: true, // 不允许为空
isNull: true, // 只允许为空
notEmpty: true, // 不允许空字符串
equals: 'specific value', // 只允许一个特定值
contains: 'foo', // 检查是否包含特定的子字符串
notIn: [['foo', 'bar']], // 检查是否值不是其中之一
isIn: [['foo', 'bar']], // 检查是否值是其中之一
notContains: 'bar', // 不允许包含特定的子字符串
len: [2,10], // 只允许长度在2到10之间的值
isUUID: 4, // 只允许uuids
isDate: true, // 只允许日期字符串
isAfter: "2011-11-05", // 只允许在特定日期之后的日期字符串
isBefore: "2011-11-05", // 只允许在特定日期之前的日期字符串
max: 23, // 只允许值 <= 23
min: 23, // 只允许值 >= 23
isCreditCard: true, // 检查有效的信用卡号码
// 也可以自定义验证:
isEven(value) {
if (parseInt(value) % 2 != 0) {
throw new Error('Only even values are allowed!')
// 我们也在模型的上下文中,所以如果它存在的话,
// this.otherField会得到otherField的值。
}
}
}
}
},{
// 配置表名
tableName: '表名',
// 不添加时间戳属性 (updatedAt, createdAt)
timestamps: true,
// 不删除数据库条目,但将新添加的属性deletedAt设置为当前日期(删除完成时)。
// paranoid 只有在启用时间戳时才能工作
paranoid: true,
// 不使用驼峰样式自动添加属性,而是下划线样式,因此updatedAt将变为updated_at
underscored: true,
// 禁用修改表名; 默认情况下,sequelize将自动将所有传递的模型名称(define的第一个参数)转换为复数。 如果你不想这样,请设置以下内容
freezeTableName: true,
// 不使用createdAt
createdAt: false,
// 我想 updateAt 实际上被称为 updateTimestamp
updatedAt: 'updateTimestamp',
})
首字母大写的表名.associate = function() {
// 表关联
}
return 首字母大写的表名
}
例如:
'use strict'
module.exports = app => {
const {STRING} = app.Sequelize
const Role = app.model.define('role', {
name: {
type: STRING,
unique: true,
allowNull: false
}
}, {
timestamps: true,
tableName: 'role',
underscored: false
})
Role.associate = function() {
app.model.Role.hasMany(app.model.UserRole)
}
return Role
}
一般在Service中进行数据库操作,常用方法有findOne, findAll, create, destory, update等。文档参考:https://demopark.github.io/sequelize-docs-Zh-CN/models-usage.html
例子:
const result = await this.ctx.service.role.create({
name: name
})
$ yarn add egg-redis
在plugin.js中启用Sequlize
exports.redis = {
enable: true,
package: 'egg-redis'
}
在config.{{env}}.js中配置数据库连接
config.redis = {
client: {
port: process.env.RS_PORT || 'Redis主机端口号',
host: process.env.RS_HOST || 'Redis主机地址',
password: process.env.RS_PASSWORD || '',
db: '缓存数据库名称',
}
}
具体方法和redis原生方法基本一致,原生api地址:https://www.cheatography.com/tasjaevan/ cheat-sheets/redis/
调用方法:
$ yarn add egg-socket.io uws
在plugin.js中启用Sequlize
exports.io = {
enable: true,
package: 'egg-socket.io'
}
在config.{{env}}.js中配置数据库连接
config.io = {
init: {
wsEngine: 'uws' // 使用uws
},
namespace: {
'命名空间路径': {
connectionMiddleware: ['中间件名称'], // 处理客户端连接与断开连接时的中间件
packetMiddleware: ['中间件名称'] // 处理客户端发送信息到服务端时的中间件
}
},
redis: {
host: process.env.RS_HOST || 'Redis主机地址',
port: process.env.RS_PORT || 'Redis主机端口号'
}
}
新建名为io的文件夹,并在其中分别建立两个文件夹controller和middleware,控制器和中间件的文件命名格式以及编码格式与eggjs的一样目录如下:
io
├── controller
└── middleware
通过io.of设置命名空间,route()方法第一个参数是订阅的话题,第二个是使用的控制器
app.io.of('/').route('new message', io.controller.chat.newMessage)
const {参数} = this.socket.handshake.query
this.ctx.socket.join('房间') // 加入房间
this.ctx.socket.id
this.app.io.of('/').adapter.clients([房间], (err, clients) => {
})
const nsp = this.app.io.of('/')
$ yarn add egg-validate
在plugin.js中启用validate
exports.validate = {
enable: true,
package: 'egg-validate'
}
validate有两个参数,第一个是需要校验的参数,另一个是需要校验的对象。
const { user } = this.ctx.request.body
this.ctx.validate({
username: { type: 'string', required: true },
password: { type: 'string', required: true }
}, user)
$ yarn add egg-view-nunjucks
在plugin.js中启用nunjucks
exports.nunjucks = {
enable: true,
package: 'egg-view-nunjucks'
}
在config.default.js中配置渲染引擎
config.view = {
mapping: {
'.nj':'nunjucks'
}
}
config.view = {
defaultExtension: '.nj'
}
Context对象存在三个接口使用模板引擎,使用renderString时需要指定模板引擎,如果定义了defaultViewEngine这里可以省略:
async test() {
const ctx = this.ctx
await ctx.render('index',{data:[
{id: 1, name: "test"},
{id: 2, name: "test"},
{id: 3, name: "test"},
{id: 4, name: "test"},
{id: 5, name: "test"}
]})
}
router.get('/', controller.home.test);
<div class="wrap">
<button class="btn btn-warning">test</button>
{% for item in data %}
<div>{{item.name}}</div>
{% endfor%}
</div>
exports.static = true;
feature
基本格式(全为英文)
例子:
master 迁出develop分支 -> develop分支迁出feature功能分支 -> 提交pr审查代码 -> 提交QA -> 合并到develop -> 合并到master
使用git cz代替git commit 插件地址:https://github.com/commitizen/cz-cli
$ npm install -g commitizen
$ commitizen init cz-conventional-changelog --save --save-exact
$ git add .
$ git cz
src
或者 test
文件的更改对负责的模块单独建立文件夹,将接口存放进去。将接口请求后的数据格式与约定返回的数据格式做对比。
请求方法 | 功能 |
---|---|
GET | 获取资源 |
POST | 新增资源 |
PUT | 更新整个资源 |
PATCH | 更新个别资源 |
DELETE | 删除资源 |
状态码 | 定义 |
---|---|
200 | 请求成功。客户端向服务器请求数据,服务器返回相关数据 |
201 | 资源创建成功。客户端向服务器提供数据,服务器创建资源 |
202 | 请求被接收。但处理尚未完成 |
204 | 客户端告知服务器删除一个资源,服务器移除它 |
状态码 | 错误描述 |
---|---|
400 | 请求无效。数据不正确,请重试 |
401 | 请求没有权限。缺少API token,无效或者超时 |
403 | 请求未被授权。当前权限无法获取指定的资源 |
404 | 请求失败。请求资源不存在 |
406 | 请求失败。请求头部不一致,请重试 |
422 | 请求失败。请验证参数 |
状态码 | 定义 |
---|---|
500 | 服务器发生错误,请检查服务器 |
502 | 网关错误 |
503 | 服务不可用,服务器暂时过载或维护 |
504 | 网关超时 |
具体而定
RESTful API的所有操作都是针对特定资源进行的。资源就是URL所表示的,URL需要符合以下规范:
{
"data": {
"键":"值"
}
}
例子:
{
"data": {
"username":"klren",
"password":"123456"
}
}
正常返回
{
"code": "状态码",
"msg":"状态描述",
"data":"具体内容"
}
例子:
{
"code": 200,
"msg": "success",
"data": {
"username": "klren",
"email":"klren@qq.com"
}
}
错误返回
{
"code": "错误状态码",
"msg": "错误信息",
"data": {
"error": "错误详情",
}
}
例子:
{
"code": "400",
"msg": "数据格式错误",
"data": {
"error": "格式错误"
}
}
采用'?'符号进行这些操作
使用唯一的查询参数进行过滤 例子:
使用sort,后面跟着键名和排序方式 例子:
使用limit和offset,后面跟具体数字。limit后面跟每页最多数据量,offset后面跟数据起始位。 请求例子:
{
"code":200,
"message":'success',
"data":{
"total": 0,
"pageIndex": 1,
"pageSize": 10,
"list":[{},{},{}...]
}
}