NodeJS编码规范
ghostxbh 9/28/2021 NodejsStandard
NodeJS编码规范
# 一、编码规范
- 所有项目默认格式统一为
UTF-8 - 使用javascript/typescript语言编码
- 轻量级框架选用Express/Koa/Fast/Meteor，企业级框架选用Egg/Nest，实用通讯选用Socket.io
# 1.1 注释规范
- 核心业务、通用业务的接口或者类上面必须有注释，示例：
/**
* @date: 2021/09/28
* @author: ghostxbh
* @desc: 程序节点，此为所有扩展节点的继承父级
*/
class ProgramNode {
constructor(api, model){
this.api = api;
this.model = model;
}
/**
* 获取节点标题
* @param {string} name 传入名称
* @param {参数类型} 参数 参数描述
*
* @return {string} name 标题名称
* @return {返回类型} 返回参数 返回描述
*/
getTitle(name);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
- 主要业务逻辑的代码必须有相关流程注释，单行开头需要空格，示例：
// 获取接口名称
const apiName = this.api.getName();
1
2
2
- 提供给外部/对接使用的SDK、API、npm库需要有日期、版本注释、作者(ghostxbh)，示例：
/**
* @date 2021/09/28
* @version v0.1.0
* @author ghostxbh
*/
class SDK {
// 提供对外业务...
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 1.2 代码目录结构
+ demo-server
+ logs
+ docs
+ src
+ config
+ exception
+ extend
+ middleware
+ router
+ service
+ utils
+ test
- app.js
- package.json
- README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1.3 命名规范
# 1.3.1 文件命名
- 统一使用英文小写命令。
- 多个描述英文之间使用
-符合连接。 - 如需要标明文件用途，可命名为
xxx.service.js。 - 不允许使用拼音和中文命名。
- 示例：
user.service.js、user-dept-relation.service.js。
# 1.3.2 函数、方法命名
- 方法与函数的命名需要见名知意。
- 使用首字母小写的驼峰命名法，示例：
getOrderById()。也可以使用下划线命名法，示例：get_order_by_id()。选择其中一种统一风格。 - 通用函数/方法使用
_命名开头，示例：_getSession()。
# 1.3.3 常量、变量命名
- 常量使用全英文大写，多个语义之间用
_连接，示例：GLOBEL_CONFIG。 - 变量必须要有关键词接收，建议使用
const替代var，若是代码需要使用let。 - 变量使用首字母小写的驼峰命名法，示例：
userAge。 - 变量需要见名知意，不允许使用拼音和中文命名。
- 非必要尽量写全变量，如len、max、min等。
- boolean类型变量使用is / has开头。
# 1.4 符号规范
# 1.4.1 引号规范
- 字符串统一使用单引号''，需要拼接使用英文模式下的
~字符，如：${param}。
# 1.4.2 分号
- 完整的代码片段需要以分号结尾，示例：
const user = this.session.getUser();。
# 1.4.3 逗号
- 数组变量、对象变量存在子元素都需要以逗号结尾，示例：
const user = {
name: '小明',
age: 18,
no: '1009918',
};
1
2
3
4
5
2
3
4
5
# 1.5 严格模式
所有代码均在'use strict'严格模式下开发
# 二、RESTful API 规范
# 2.1 请求协议
| 协议头 | 描述 | 应用 |
|---|---|---|
| http | 网络请求 | 接口数据、页面请求 |
| https | ssl网络请求 | 接口数据、页面请求 |
# 2.2 请求动作
| 请求方法 | 功能 |
|---|---|
| GET | 获取资源 |
| POST | 新增资源 |
| PUT | 更新整个资源 |
| PATCH | 更新个别资源 |
| DELETE | 删除资源 |
# 2.3 API版本号
通过版本号可以区分api的版本
通过/api/v1/**代表v1版本
通过/api/v2/**代表v2版本
注意：API分2种，内部服务/客户端使用，第三方调用的情况。
内部使用按照 请求动作 正常使用，第三方调用只允许提供GET/POST请求动作的API接口。
# 2.4 URL路径
RESTful API的所有操作都是针对特定资源进行的。资源就是URL所表示的，URL需要符合以下规范：
- 只能是名词不能是动词，必须是小写字符
- 不可使用下划线'_'，可以使用连字符'-'
- CRUD不可出现在URL中
- 参数列表要用encode
- 避免层级过深的URI，尽量使用查询参数代替路径中的实体导航，如GET
/user?sex=female&age=30
具体形式如下：
/api/{资源名}/{描述名}/api/{资源名}/{对象id}/{描述名}
示例：
- GET http://www.demo.com/api/v1/user/1 获取用户1的信息
- POST http://www.demo.com/api/v1/user/login 登录
- PUT http://www.demo.com/api/v1/user/1 更新用户1的全部信息
- DELETE http://www.demo.com/api/v1/user/1 删除用户1
- PATCH http://www.demo.com/api/v1/user/1 更新用户1部分信息
- GET http://www.demo.com/api/v1/user/1/role 获取用户1的权限信息
特殊情况：
GET查询条件过多时，可选择使用POST请求提交数据
# 2.5 请求体和响应体
- 请求格式
{
"data": {
// 请求数据
}
}
1
2
3
4
5
2
3
4
5
- 响应格式
{
"success": true, // 响应状态
"code": 200, // 响应编码
"message": "ok", // 响应信息
"data": {
// 响应数据
}
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 2.6 分页与排序
使用page的分页参数
使用sort做排序参数字段
使用params做条件筛选对象
- 响应
{
"success": true, // 响应状态
"code": 200, // 响应编码
"message": "ok", // 响应信息
"data": {
// 响应数据
},
"condition": { // 参数对象
"page": { // 分页对象
"pageNo": 1,
"pageSize": 10,
"count": 225,
"total": 23
},
"sort": { // 排序对象
"age": 1,
"createTime": -1
},
"params": { // 条件对象
"name": "小明"
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 2.7 状态码
所有返回状态码均使用英文提示 禁止出现中文提示
- 成功状态码
| 状态码 | 定义 |
|---|---|
| 200 | 请求成功。客户端向服务器请求数据，服务器返回相关数据 |
| 201 | 资源创建成功。客户端向服务器提供数据，服务器创建资源 |
| 202 | 请求被接收。但处理尚未完成 |
| 204 | 客户端告知服务器删除一个资源，服务器移除它 |
- 错误状态码
| 状态码 | 定义 |
|---|---|
| 400 | 请求无效。数据不正确，请重试 |
| 401 | 请求没有权限。缺少API token，无效或者超时 |
| 403 | 请求未被授权。当前权限无法获取指定的资源 |
| 404 | 请求失败。请求资源不存在 |
| 406 | 请求失败。请求头部不一致，请重试 |
| 422 | 请求失败。请验证参数 |
- 服务器错误状态码
| 状态码 | 定义 |
|---|---|
| 500 | 服务器发生错误，请检查服务器 |
| 502 | 网关错误 |
| 503 | 服务不可用，服务器暂时过载或维护 |
| 504 | 网关超时 |
- 自定义状态码
示业务而定
# 2.8 请求格式
- Content-Type:
application/json数据发送 - Content-Type:
multipart/form-data文件上传
收录时间: 2021-09-28