java后端与js前端开发规范

Posted 2021-04-06 全栈阿布

JAVA 开发规范

v1.0.0 2019/09/06

本篇规范基于阿里巴巴、华为的开发手册，添加了我们团队的开发风格规范，补充了一些细节。感谢前人的经验和付出，让我们可以有机会站在巨人的肩膀上眺望星辰大海。

规范不是为了约束和禁锢大家的创造力，而是为了帮助大家能够在正确的道路上，尽可能的避免踩坑和跑偏。
规范可以让我们无论单枪匹马还是与众人同行的时候都能得心应手。
规范可以让我们在面对日益变态的需求和做代码接盘侠的时候，更优雅从容。

规则并不是完美的，通过约束和禁止在特定情况下的特性，可能会对代码实现造成影响。
但是我们制定规则的目的：为了大多数程序员小伙伴可以得到更多的好处，如果在团队实际运作中认为某个规则无法遵循或有更好的做法，希望大家可以共同改进该规范。

一、编程规范

1、好代码的原则

我们参考 Kent Beck 的简单设计四原则来指导我们的如何写出优秀的代码，如何有效地判断我们的代码是优秀的。

•通过所有测试（Passes its tests）：强调的是外部需求，这是代码实现最重要的•尽可能消除重复 (Minimizes duplication)：代码的模块架构设计，保证代码的正交性，保证代码更容易修改•尽可能清晰表达 (Maximizes clarity)：代码的可阅读性，保证代码是容易阅读的•更少代码元素 (Has fewer elements)：保证代码是简洁的，在简洁和表达力之间，我们更看重表达力

以上四个原则的重要程度依次降低， 这组定义被称做简单设计原则。

2、项目命名规范

全部采用小写方式， 以中划线分隔。

正例：mall-management-system / order-service-client / user-api

反例：mall_management-system / mallManagementSystem / orderServiceClient

3、TODO/FIXME 规范

TODO/TBD(to be determined) 注释一般用来描述已知待改进、待补充的修改点,并且加上作者名称。
FIXME 注释一般用来描述已知缺陷，它们都应该有统一风格，方便文本搜索统一处理。如：

// TODO <author-name>: 补充XX处理// FIXME <author-name>: XX缺陷

4、方法参数规范

无论是 controller，service，manager，dao 亦或是其他的代码，每个方法最多 3 个参数，如果超出 3 个参数的话，要封装成 javabean 对象。

1.方便他人调用，降低出错几率。尤其是当参数是同一种类型，仅仅依靠顺序区分，稍有不慎便是灾难性后果，而且排查起来也极其恶心。2.保持代码整洁、清晰度。当一个个方法里充斥着一堆堆参数的时候，再坚强的人，也会身心疲惫。

反例：

/*** 使用证书加密数据工具方法** @param param* @param password 加密密码* @param priCert 私钥* @param pubCert 公钥* @return 返回加密后的字符串*/public String signEnvelop(JdRequestParam param, String password, String priCert, String pubCert){}

5、注释规范

5-1、注释和代码一样重要

注释是我们披荆斩棘历经磨难翻越需求这座大山时，留下的踪迹和收获的经验教训，这些宝贵的知识除了证明我们曾经存在过，也提醒着后来的人们殷鉴不远、继往开来。

注释除了说明作用、逻辑之外。还有一个很重要的原因：当业务逻辑过于复杂，代码过于庞大的时候，注释就变成了一道道美化环境、分离与整理逻辑思路的路标。这是很重要的一点，它能有效得帮助我们免于陷入代码与业务逻辑的泥沼之中。

正例：

/*** 开始抽奖方法* 保存中奖信息、奖励用户积分等* @param luckDrawDTO* @return ResponseDTO 返回中奖信息*/public ResponseDTO<String> startLuckDraw(LuckDrawDTO luckDrawDTO) {
 // -------------- 1、校验抽奖活动基本信息 ------------------------ xxx伪代码一顿操作
 // -------------- 2、新增抽奖记录 ------------------------------- xxx伪代码一顿操作
 // -------------- 3、如果需要消耗积分，则扣除钢镚积分 ------------- xxx伪代码一顿操作
 // -------------- 4、获取奖品信息，开始翻滚吧 -------------------- xxx伪代码一顿操作
 return ResponseDTO.succ(luckDrawPrizeVO);}

5-2、注释和代码的一致性

注释并不是越多越好，当注释过多，维护代码的同时，还需要维护注释，不仅变成了一种负担，也与我们当初添加注释的初衷背道而驰。

首先：大家应该通过清晰的逻辑架构，好的变量命名来提高代码可读性；需要的时候，才辅以注释说明。注释是为了帮助阅读者快速读懂代码，所以要从读者的角度出发，按需注释。注释内容要简洁、明了、无二义性，信息全面且不冗余。

其次：无论是修改、复制代码时，都要仔细核对注释内容是否正确。只改代码，不改注释是一种不文明行为，破坏了代码与注释的一致性，会让阅读者迷惑、费解，甚至误解。

反例：

// 查询部门EmployeeDTO employee = employeeDao.listByDeptId(deptId);

5-3、方法注释

方法要尽量通过方法名自解释，不要写无用、信息冗余的方法头，不要写空有格式的方法头注释。

方法头注释内容可选，但不限于：功能说明、返回值，用法、算法实现等等。尤其是对外的方法接口声明，其注释，应当将重要、有用的信息表达清楚。

正例：

/** * 解析转换时间字符串为 LocalDate 时间类 * 调用前必须校验字符串格式 否则可能造成解析失败的错误异常 * * @param dateStr 必须是 yyyy-MM-dd 格式的字符串 * @return LocalDate */public static LocalDate parseYMD(String dateStr){}

反例：

/** * 校验对象 * * @param t * @return String */public static <T> String checkObj(T t);

反例中出现的问题：

•方法注释没有说明具体的作用、使用事项。•参数、返回值，空有格式没内容。这是非常重要一点，任何人调用任何方法之前都需要知道方法对参数的要求，以及返回值是什么。

二、项目规范

1、代码目录结构

统一的目录结构是所有项目的基础。

src 源码目录|-- common 各个项目的通用类库|-- config 项目的配置信息|-- constant 全局公共常量|-- handler 全局处理器|-- interceptor 全局连接器|-- listener 全局监听器|-- module 各个业务|-- |--- employee 员工模块|-- |--- role 角色模块|-- |--- login 登录模块|-- third 三方服务，比如redis, oss，微信sdk等等|-- util 全局工具类|-- Application.java 启动类

2、common 目录规范

common 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src 源码目录|-- common 各个项目的通用类库|-- |--- anno 通用注解，比如权限，登录等等|-- |--- constant 通用常量，比如 ResponseCodeConst|-- |--- domain 全局的 javabean，比如 BaseEntity,PageParamDTO 等|-- |--- exception 全局异常，如 BusinessException|-- |--- json json 类库，如 LongJsonDeserializer，LongJsonSerializer|-- |--- swagger swagger 文档|-- |--- validator 适合各个项目的通用 validator，如 CheckEnum，CheckBigDecimal 等

3、config 目录规范

config 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src 源码目录|-- config 项目的所有配置信息|-- |--- MvcConfig mvc的相关配置，如interceptor,filter等|-- |--- DataSourceConfig 数据库连接池的配置|-- |--- MybatisConfig mybatis的配置|-- |--- .... 其他

4、module 目录规范

module 目录里写项目的各个业务，每个业务一个独立的顶级文件夹，在文件里进行 mvc 的相关划分。其中，domain 包里存放 entity, dto, vo，bo 等 javabean 对象

src|-- module 所有业务模块|-- |-- role 角色模块|-- |-- |--RoleController.java controller|-- |-- |--RoleConst.java role相关的常量|-- |-- |--RoleService.java service|-- |-- |--RoleDao.java dao|-- |-- |--domain domain|-- |-- |-- |-- RoleEntity.java 表对应实体|-- |-- |-- |-- RoleDTO.java dto对象|-- |-- |-- |-- RoleVO.java 返回对象|-- |-- employee 员工模块|-- |-- login 登录模块|-- |-- email 邮件模块|-- |-- .... 其他

5、 domain 包中的 javabean 命名规范

1） javabean 的整体要求：

•不得有任何的业务逻辑或者计算•基本数据类型必须使用包装类型（Integer, Double、Boolean 等）•不允许有任何的默认值•每个属性必须添加注释，并且必须使用多行注释。•必须使用 lombok 简化 getter/setter 方法•建议对象使用 lombok 的 @Builder ，@NoArgsConstructor，同时使用这两个注解，简化对象构造方法以及set方法。

正例：

@Builder@NoArgsConstructor@Datapublic class DemoDTO {
 private String name;
 private Integer age;}
// 使用示例：
DemoDTO demo = DemoDTO.builder() .name("yeqiu") .age(66) .build();

2）数据对象；XxxxEntity，要求：

•以 Entity 为结尾（阿里是为 DO 为结尾）•Xxxx 与数据库表名保持一致•类中字段要与数据库字段保持一致，不能缺失或者多余•类中的每个字段添加注释，并与数据库注释保持一致•不允许有组合•项目内的日期类型必须统一，建议使用 java.util.Date，java.sql.Timestamp，java.time.LocalDateTime 其中只一。

3）传输对象；XxxxDTO，要求：

•不可以继承自 Entity•DTO 可以继承、组合其他 DTO，VO，BO 等对象•DTO 只能用于前端、RPC 的请求参数

3）视图对象；XxxxVO，要求：

•不可继承自 Entity•VO 可以继承、组合其他 DTO，VO，BO 等对象•VO 只能用于返回前端、rpc 的业务数据封装对象

4）业务对象 BO，要求：

•不可以继承自 Entity•BO 对象只能用于 service，manager，dao 层，不得用于 controller 层

三、MVC 规范

1、整体分层

•controller 层•service 层•manager 层•dao 层

2、 controller 层规范

1） 只允许在 method 上添加 RequestMapping 注解，不允许加在 class 上（为了方便的查找 url，放到 url 不能一次性查找出来）

正例：

@RestControllerpublic class DepartmentController {
 @GetMapping("/department/list") public ResponseDTO<List<DepartmentVO>> listDepartment() { return departmentService.listDepartment(); }

反例：

@RequestMapping ("/department")public class DepartmentController {
 @GetMapping("/list") public ResponseDTO<List<DepartmentVO>> listDepartment() { return departmentService.listDepartment(); }

2）不推荐使用 rest 命名 url， 只能使用 get/post 方法。url 命名上规范如下：

虽然 Rest 大法好，但是有时并不能一眼根据 url 看出来是什么操作，所以我们选择了后者，这个没有对与错，只有哪个更适合我们的团队。

/业务模块/子模块/动作

正例：

GET /department/get/{id} 查询某个部门详细信息POST /department/query 复杂查询POST /department/add 添加部门POST /department/update 更新部门GET /department/delete/{id} 删除部门

3）每个方法必须添加 swagger 文档注解 @ApiOperation ，并填写接口描述信息，描述最后必须加上作者信息 @author 哪吒 。

正例：

 @ApiOperation("更新部门信息 @author 哪吒") @PostMapping("/department/update") public ResponseDTO<String> updateDepartment(@Valid @RequestBody DeptUpdateDTO deptUpdateDTO) { return departmentService.updateDepartment(deptUpdateDTO); }

4）controller 负责协同和委派业务，充当路由的角色，每个方法要保持简洁：

•不做任何的业务逻辑操作•不做任何的参数、业务校验，参数校验只允许使用@Valid 注解做简单的校验•不做任何的数据组合、拼装、赋值等操作

正例：

 @ApiOperation("添加部门 @author 哪吒") @PostMapping("/department/add") public ResponseDTO<String> addDepartment(@Valid @RequestBody DepartmentCreateDTO departmentCreateDTO) { return departmentService.addDepartment(departmentCreateDTO); }

5）只能在 controller 层获取当前请求用户，并传递给 service 层。

因为获取当前请求用户是从 ThreadLocal 里获取取的，在 service、manager、dao 层极有可能是其他非 request 线程调用，会出现 null 的情况，尽量避免

 @ApiOperation("添加员工 @author yandanyang") @PostMapping("/employee/add") public ResponseDTO<String> addEmployee(@Valid @RequestBody EmployeeAddDTO employeeAddDTO) { LoginTokenBO requestToken = SmartRequestTokenUtil.getRequestUser(); return employeeService.addEmployee(employeeAddDTO, requestToken); }

3、 service 层规范

1）合理拆分 service 文件，如果业务较大，请拆分为多个 service。

如订单业务,所有业务都写到 OrderService 中会导致文件过大，故需要进行拆分如下：

•OrderQueryService 订单查询业务•OrderCreateService 订单新建业务•OrderDeliverService 订单发货业务•OrderValidatorService 订单验证业务

2）谨慎处理 @Transactional 事务注解的使用，不要简单对 service 的方法添加个 @Transactional 注解就觉得万事大吉了。应当合并对数据库的操作，尽量减少添加了@Transactional方法内的业务逻辑。
@Transactional 注解内的 rollbackFor 值必须使用异常的基类 Throwable.class

对于@Transactional 注解，当 spring 遇到该注解时，会自动从数据库连接池中获取 connection，并开启事务然后绑定到 ThreadLocal 上，如果业务并没有进入到最终的 操作数据库环节，那么就没有必要获取连接并开启事务，应该直接将 connection 返回给数据库连接池，供其他使用（比较难以讲解清楚，如果不懂的话就主动去问）。

反例：

 @Transactional(rollbackFor = Throwable.class) public ResponseDTO<String> upOrDown(Long departmentId, Long swapId) { // 验证 1 DepartmentEntity departmentEntity = departmentDao.selectById(departmentId); if (departmentEntity == null) { return ResponseDTO.wrap(DepartmentResponseCodeConst.NOT_EXISTS); } // 验证 2 DepartmentEntity swapEntity = departmentDao.selectById(swapId); if (swapEntity == null) { return ResponseDTO.wrap(DepartmentResponseCodeConst.NOT_EXISTS); } // 验证 3 Long count = employeeDao.countByDepartmentId(departmentId) if (count != null && count > 0) { return ResponseDTO.wrap(DepartmentResponseCodeConst.EXIST_EMPLOYEE); } // 操作数据库 4 Long departmentSort = departmentEntity.getSort(); departmentEntity.setSort(swapEntity.getSort()); departmentDao.updateById(departmentEntity); swapEntity.setSort(departmentSort); departmentDao.updateById(swapEntity); return ResponseDTO.succ(); }

以上代码前三步都是使用 connection 进行验证操作，由于方法上有@Transactional 注解，所以这三个验证都是使用的同一个 connection。

若对于复杂业务、复杂的验证逻辑，会导致整个验证过程始终占用该 connection 连接，占用时间可能会很长，直至方法结束，connection 才会交还给数据库连接池。

对于复杂业务的不可预计的情况，长时间占用同一个 connection 连接不是好的事情，应该尽量缩短占用时间。

正例：

 DepartmentService.java
 public ResponseDTO<String> upOrDown(Long departmentId, Long swapId) { DepartmentEntity departmentEntity = departmentDao.selectById(departmentId); if (departmentEntity == null) { return ResponseDTO.wrap(DepartmentResponseCodeConst.NOT_EXISTS); } DepartmentEntity swapEntity = departmentDao.selectById(swapId); if (swapEntity == null) { return ResponseDTO.wrap(DepartmentResponseCodeConst.NOT_EXISTS); } Long count = employeeDao.countByDepartmentId(departmentId) if (count != null && count > 0) { return ResponseDTO.wrap(DepartmentResponseCodeConst.EXIST_EMPLOYEE); } departmentManager.upOrDown(departmentSort,swapEntity); return ResponseDTO.succ(); }

 DepartmentManager.java
 @Transactional(rollbackFor = Throwable.class) public void upOrDown(DepartmentEntity departmentEntity ,DepartmentEntity swapEntity){ Long departmentSort = departmentEntity.getSort(); departmentEntity.setSort(swapEntity.getSort()); departmentDao.updateById(departmentEntity); swapEntity.setSort(departmentSort); departmentDao.updateById(swapEntity); }

将数据在 service 层准备好，然后传递给 manager 层，由 manager 层添加@Transactional 进行数据库操作。

3）需要注意的是：注解 @Transactional 事务在类的内部方法调用是不会生效的

反例：如果发生异常，saveData方法上的事务注解并不会起作用

@Servicepublic class OrderService{
 public void createOrder(OrderCreateDTO createDTO){ this.saveData(createDTO); }
 @Transactional(rollbackFor = Throwable.class) public void saveData(OrderCreateDTO createDTO){ orderDao.insert(createDTO); }}

Spring采用动态代理(AOP)实现对bean的管理和切片，它为我们的每个class生成一个代理对象。只有在代理对象之间进行调用时，可以触发切面逻辑。而在同一个class中，方法A调用方法B，调用的是原对象的方法，而不通过代理对象。所以Spring无法拦截到这次调用，也就无法通过注解保证事务了。简单来说，在同一个类中的方法调用，不会被方法拦截器拦截到，因此事务不会起作用。

解决方案：

1.可以将方法放入另一个类，如新增 manager层，通过spring注入，这样符合了在对象之间调用的条件。2.启动类添加 @EnableAspectJAutoProxy(exposeProxy = true)，方法内使用AopContext.currentProxy()获得代理类，使用事务。

SpringBootApplication.java
@EnableAspectJAutoProxy(exposeProxy = true)@SpringBootApplicationpublic class SpringBootApplication {}
OrderService.java
public void createOrder(OrderCreateDTO createDTO){ OrderService orderService = (OrderService)AopContext.currentProxy(); orderService.saveData(createDTO);}

4）service是具体的业务处理逻辑服务层，尽量避免将web层某些参数传递到service中。

反例：

public ResponseDTO<String> handlePinganRequest(HttpServletRequest request){ InputStreamReader inputStreamReader = new InputStreamReader(request.getInputStream(), "GBK"); BufferedReader reader = new BufferedReader(inputStreamReader); StringBuilder sb = new StringBuilder(); String str; while ((str = reader.readLine()) != null) { sb.append(str); } if(!JSON.isValid(msg)){ return ResponseDTO.wrap(ResponseCodeConst.ERROR_PARAM); } PinganMsgDTO PinganMsgDTO = JSON.parseObject(msg,PinganMsgDTO.class); // 示例结束}

反例中出现的问题：

•反例中把 HttpServletRequest 传递到service中，是为了获取Request流中的字符信息，然后才是真正的业务处理。按照分层的初衷：将代码、业务逻辑解耦，正确的做法应该是handlePinganRequest方法将String字符作为参数直接处理业务，将从Request中获取字符的操作放入controller中。•另一个坏处是不方便做单元测试，还得一个new一个HttpServletRequest并制造一个InputStream，然而这样做并不能模拟到真实的业务情景及数据。

4、 manager 层规范

manager 层的作用(引自《阿里 java 手册》)：

•对第三方平台封装的层，预处理返回结果及转化异常信息；•对 Service 层通用能力的下沉，如缓存方案、中间件通用处理；•与 DAO 层交互，对多个 DAO 的组合复用。

5、 dao 层规范

优先使用 mybatis-plus 框架。如果需要多个数据源操作的，可以选择使用 SmartDb 框架。

1）所有 Dao 继承自 BaseMapper

2）禁止使用 Mybatis-plus 的 Wrapper 条件构建器

3）禁止直接在 mybatis xml 中写死常量，应从 dao 中传入到 xml 中

3）建议不要使用星号 * 代替所有字段

正例：

 NoticeDao.java
 Integer noticeCount(@Param("sendStatus") Integer sendStatus);--------------------------------------------- NoticeMapper.xml
 <select id="noticeCount" resultType="integer"> select count(1) from t_notice where send_status = #{sendStatus} </select>

反例：

 NoticeDao.java
 Integer noticeCount();--------------------------------------------- NoticeMapper.xml
 <select id="noticeCount" resultType="integer"> select count(1) from t_notice where send_status = 0 </select>

3）dao层方法命名规范

•获取单个对象的方法用 get 做前缀。•获取多个对象的方法用 list 做前缀。•获取统计值的方法用 count 做前缀。•插入的方法用 save/insert 做前缀。•删除的方法用 remove/delete 做前缀。•修改的方法用 update 做前缀。

建议：dao层方法命名尽量以sql语义命名，避免与业务关联。

正例：

List<PerformanceDTO> listByMonthAndItemId(@Param("month") String month, @Param("itemId") Integer itemId);

反例：

List<PerformanceDTO> getInternalData(@Param("month") String month, @Param("itemId") Integer itemId);

反例中出现的不规范操作：

•get代表单个查询，批量查询的应该 list 开头。•命名与业务关联，局限了dao方法的使用场景和范围，降低了方法的复用性，造成他人困惑以及重复造轮子。

6、boolean类型的属性命名规范

类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。反例：定义为基本数据类型 Boolean isDeleted；的属性，它的方法也是 isDeleted()，RPC在反向解析的时候，“以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。

这是阿里巴巴开发手册中的原文，我们团队的规定是：boolean 类型的类属性和数据表字段都统一使用 flag 结尾。虽然使用 isDeleted，is_deleted 从字面语义上更直观，但是比起可能出现的潜在错误，这点牺牲还是值得的。

正例：

deletedFlag，deleted_flag，onlineFlag，online_flag

7、

四、数据库 规范

1 建表规范

表必备三字段：id, create_time, update_time

•id 字段 Long 类型，单表自增，自增长度为 1•create_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP•update_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP, On update CURRENT_TIMESTAMP

2 枚举类表字段注释需要将所有枚举含义进行注释

修改或增加字段的状态描述，必须要及时同步更新注释。
如下表的 sync_status 字段 同步状态 0 未开始 1同步中 2同步成功 3失败。

正例：

CREATE TABLE `t_change_data` ( `id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, `sync_status` TINYINT(3) UNSIGNED NOT NULL DEFAULT '0' COMMENT '同步状态 0 未开始 1同步中 2同步成功 3失败', `sync_time` DATETIME NULL DEFAULT NULL COMMENT '同步时间', `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `update_time` DATETIME NULL DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`change_data_id`))

反例：

CREATE TABLE `t_change_data` ( `id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, `sync_status` TINYINT(3) UNSIGNED NOT NULL DEFAULT '0' COMMENT '同步状态 ', `sync_time` DATETIME NULL DEFAULT NULL COMMENT '同步时间', `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `update_time` DATETIME NULL DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`change_data_id`))

3 合理结合业务给表字段添加索引和唯一索引

具体索引规范请参照《阿里巴巴 Java 开发手册》索引规约

五、其他

1、代码提交规范

•提交前应该冷静、仔细检查一下，确保没有忘记加入版本控制或不应该提交的文件。•提交前应该先编译一次（idea里ctrl+F9），防止出现编译都报错的情况。•提交前先更新pull一次代码，提交前发生冲突要比提交后发生冲突容易解决的多。•提交前检查代码是否格式化，是否符合代码规范，无用的包引入、变量是否清除等等。•提交时检查注释是否准确简洁的表达出了本次提交的内容。

2、maven项目

•pom禁止出现相同 groupId，artifactId 的依赖配置。•项目名称应该与 artifactId 保持一致。•定期检查jar包依赖关系，及时排除解决冲突的jar包。

3、保持项目整洁

使用git，必须添加 .gitignore 忽略配置文件。
不要提交与项目无关的内容文件：idea配置、target包等。

前端 JS 项目开发规范

规范的目的是为了编写高质量的代码，让你的团队成员每天得心情都是愉悦的，大家在一起是快乐的。

引自《阿里规约》的开头片段：

----现代软件架构的复杂性需要协同开发完成，如何高效地协同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

一、编程规约

(一)命名规范

1.1.1 项目命名

全部采用小写方式， 以中划线分隔。

正例：mall-management-system

反例：mall_management-system / mallManagementSystem

1.1.2 目录命名

全部采用小写方式， 以中划线分隔，有复数结构时，要采用复数命名法， 缩写不用复数

正例： scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc

反例： script / style / demo_scripts / demoStyles / imgs / docs

【特殊】VUE 的项目中的 components 中的组件目录，使用 kebab-case 命名

正例： head-search / page-loading / authorized / notice-icon

反例： HeadSearch / PageLoading

【特殊】VUE 的项目中的除 components 组件目录外的所有目录也使用 kebab-case 命名 正例： page-one / shopping-car / user-management

反例： ShoppingCar / UserManagement

1.1.3 JS、CSS、SCSS、html、PNG 文件命名

全部采用小写方式， 以中划线分隔

正例： render-dom.js / signup.css / index.html / company-logo.png

反例： renderDom.js / UserManagement.html

1.1.4 命名严谨性

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用

正例：henan / luoyang / rmb 等国际通用的名称，可视同英文。

反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

杜绝完全不规范的缩写，避免望文不知义：

反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。

(二)HTML 规范 （Vue Template 同样适用）

1.2.1 HTML 类型

推荐使用 HTML5 的文档类型申明：. （建议使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的属性，比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分有限）。

•规定字符编码•IE 兼容模式•规定字符编码•doctype 大写

正例：

<!DOCTYPE html><html> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta charset="UTF-8" /> <title>Page title</title> </head> <body> <img alt="Company" /> </body></html>

1.2.2 缩进

缩进使用 2 个空格（一个 tab）

嵌套的节点应该缩进。

1.2.3 分块注释

在每一个块状元素，列表元素和表格元素后，加上一对 HTML 注释。注释格式

<!-- 英文 中文 start >

<!-- 英文 中文 end > 正例：

<body> <!-- header 头部 start --> <header> <div class="container"> <a href="#"> <!-- 图片会把a标签给撑开，所以不用设置a标签的大小 --> <img /> </a> </div> </header> <!-- header 头部 end --></body>

1.2.4 语义化标签

HTML5 中新增很多语义化标签，所以优先使用语义化标签，避免一个页面都是 div 或者 p 标签

正例

<header></header><footer></footer>

反例

<div> <p></p></div>

1.2.5 引号

使用双引号(" ") 而不是单引号(' ') 。

正例： <div class="news-div"></div>

反例： <div class='news-div'></div>

(三) CSS 规范

1.3.1 命名

•类名使用小写字母，以中划线分隔•id 采用驼峰式命名•scss 中的变量、函数、混合、placeholder 采用驼峰式命名

ID 和 class 的名称总是使用可以反应元素目的和用途的名称，或其他通用的名称，代替表象和晦涩难懂的名称

不推荐：

.fw-800 { font-weight: 800;}
.red { color: red;}

推荐:

.heavy { font-weight: 800;}
.important { color: red;}

1.3.2 选择器

1)css 选择器中避免使用标签名 从结构、表现、行为分离的原则来看，应该尽量避免 css 中出现 HTML 标签，并且在 css 选择器中出现标签名会存在潜在的问题。

2)很多前端开发人员写选择器链的时候不使用 直接子选择器（注：直接子选择器和后代选择器的区别）。有时，这可能会导致疼痛的设计问题并且有时候可能会很耗性能。然而，在任何情况下，这是一个非常不好的做法。如果你不写很通用的，需要匹配到 DOM 末端的选择器， 你应该总是考虑直接子选择器。

不推荐:

.content .title { font-size: 2rem;}

推荐:

.content > .title { font-size: 2rem;}

1.3.3 尽量使用缩写属性

不推荐：

border-top-style: none;font-family: palatino, georgia, serif;font-size: 100%;line-height: 1.6;padding-bottom: 2em;padding-left: 1em;padding-right: 1em;padding-top: 0;

推荐：

border-top: 0;font: 100%/1.6 palatino, georgia, serif;padding: 0 1em 2em;

1.3.4 每个选择器及属性独占一行

不推荐：

button{ width:100px;height:50px;color:#fff;background:#00a0e9;}

推荐：

button{ width:100px; height:50px; color:#fff; background:#00a0e9;}

1.3.5 省略0后面的单位

不推荐：

div{ padding-bottom: 0px; margin: 0em;}

推荐：

div{ padding-bottom: 0; margin: 0;}

1.3.6 避免使用ID选择器及全局标签选择器防止污染全局样式

不推荐：

#header{ padding-bottom: 0px; margin: 0em;}

推荐：

.header{ padding-bottom: 0px; margin: 0em;}

(四) LESS 规范

1.4.1 代码组织

1)将公共less文件放置在style/less/common文件夹

例:// color.less,common.less

2)按以下顺序组织

1、@import; 2、变量声明; 3、样式声明;

@import "mixins/size.less";
@default-text-color: #333;
.page { width: 960px; margin: 0 auto;}

1.4.2 避免嵌套层级过多

将嵌套深度限制在3级。对于超过4级的嵌套，给予重新评估。这可以避免出现过于详实的CSS选择器。避免大量的嵌套规则。当可读性受到影响时，将之打断。推荐避免出现多于20行的嵌套规则出现

不推荐：

.main{ .title{ .name{ color:#fff } }}

推荐：

.main-title{ .name{ color:#fff }}

(五) javascript 规范

1.5.1 命名

1) 采用小写驼峰命名 lowerCamelCase，代码中的命名均不能以下划线，也不能以下划线或美元符号结束

反例： _name / name_ / name$

2) 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

正例： localValue / getHttpMessage() / inputUserId

**其中 method 方法命名必须是 动词 或者 动词+名词 形式**

正例：saveShopCarData /openShopCarInfoDialog

反例：save / open / show / go

**特此说明，增删查改，详情统一使用如下 5 个单词，不得使用其他（目的是为了统一各个端）**

add / update / delete / detail / get

附：函数方法常用的动词:

get 获取/set 设置,add 增加/remove 删除create 创建/destory 移除start 启动/stop 停止open 打开/close 关闭,read 读取/write 写入load 载入/save 保存,create 创建/destroy 销毁begin 开始/end 结束,backup 备份/restore 恢复import 导入/export 导出,split 分割/merge 合并inject 注入/extract 提取,attach 附着/detach 脱离bind 绑定/separate 分离,view 查看/browse 浏览edit 编辑/modify 修改,select 选取/mark 标记copy 复制/paste 粘贴,undo 撤销/redo 重做insert 插入/delete 移除,add 加入/append 添加clean 清理/clear 清除,index 索引/sort 排序find 查找/search 搜索,increase 增加/decrease 减少play 播放/pause 暂停,launch 启动/run 运行compile 编译/execute 执行,debug 调试/trace 跟踪observe 观察/listen 监听,build 构建/publish 发布input 输入/output 输出,encode 编码/decode 解码encrypt 加密/decrypt 解密,compress 压缩/decompress 解压缩pack 打包/unpack 解包,parse 解析/emit 生成connect 连接/disconnect 断开,send 发送/receive 接收download 下载/upload 上传,refresh 刷新/synchronize 同步update 更新/revert 复原,lock 锁定/unlock 解锁check out 签出/check in 签入,submit 提交/commit 交付push 推/pull 拉,expand 展开/collapse 折叠begin 起始/end 结束,start 开始/finish 完成enter 进入/exit 退出,abort 放弃/quit 离开obsolete 废弃/depreciate 废旧,collect 收集/aggregate 聚集

3) 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

正例： MAX_STOCK_COUNT

反例： MAX_COUNT

1.5.2 代码格式

1) 使用 2 个空格进行缩进

正例：

if (x < y) { x += 10;} else { x += 1;}

2) 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

说明：任何情形，没有必要插入多个空行进行隔开。

1.5.3 字符串

统一使用单引号(‘)，不使用双引号(“)。这在创建 HTML 字符串非常有好处：

正例:

let str = 'foo';let testDiv = '<div id="test"></div>';

反例:

let str = 'foo';let testDiv = "<div id='test'></div>";

1.5.4 对象声明

1)使用字面值创建对象

正例： let user = {};

反例： let user = new Object();

2) 使用字面量来代替对象构造器

正例：

var user = { age: 0, name: 1, city: 3};

反例：

var user = new Object();user.age = 0;user.name = 0;user.city = 0;

1.5.5 使用 ES6,7

必须优先使用 ES6,7 中新增的语法糖和函数。这将简化你的程序，并让你的代码更加灵活和可复用。

必须强制使用 ES6, ES7 的新语法，比如箭头函数、await/async ， 解构， let ， for...of 等等

1.5.6 括号

下列关键字后必须有大括号（即使代码块的内容只有一行）：if, else, for, while, do, switch, try, catch, finally, with。

正例：

if (condition) { doSomething();}

反例：

if (condition) doSomething();

1.5.7 undefined 判断

永远不要直接使用 undefined 进行变量判断；使用 typeof 和字符串'undefined'对变量进行判断。

正例：

if (typeof person === 'undefined') { ...}

反例：

if (person === undefined) { ...}

1.5.8 条件判断和循环最多三层

条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但是谨记不要写太长的三目运算符。如果超过 3 层请抽成函数，并写清楚注释。

1.5.9 this 的转换命名

对上下文 this 的引用只能使用'self'来命名

1.5.10 慎用 console.log

因 console.log 大量使用会有性能问题，所以在非 webpack 项目中谨慎使用 log 功能

二、Vue 项目规范

(一) Vue 编码基础

vue 项目规范以 Vue 官方规范 （https://cn.vuejs.org/v2/style-guide/） 中的 A 规范为基础，在其上面进行项目开发，故所有代码均遵守该规范。

请仔仔细细阅读 Vue 官方规范，切记，此为第一步。

2.1.1. 组件规范

1) 组件名为多个单词。

组件名应该始终是多个单词组成（大于等于 2），且命名规范为KebabCase格式。这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。

正例：

export default { name: 'TodoItem' // ...};

反例：

export default { name: 'Todo', // ...}export default { name: 'todo-item', // ...}

2) 组件文件名为 pascal-case 格式

正例：

components/|- my-component.vue

反例：

components/|- myComponent.vue|- MyComponent.vue

3) 基础组件文件名为 base 开头，使用完整单词而不是缩写。

正例：

components/|- base-button.vue|- base-table.vue|- base-icon.vue

反例：

components/|- MyButton.vue|- VueTable.vue|- Icon.vue

4) 和父组件紧密耦合的子组件应该以父组件名作为前缀命名

正例：

components/|- todo-list.vue|- todo-list-item.vue|- todo-list-item-button.vue|- user-profile-options.vue （完整单词）

反例：

components/|- TodoList.vue|- TodoItem.vue|- TodoButton.vue|- UProfOpts.vue （使用了缩写）

5) 在 Template 模版中使用组件，应使用 PascalCase 模式，并且使用自闭合组件。

正例：

<!-- 在单文件组件、字符串模板和 JSX 中 --><MyComponent /><Row><table :column="data"/></Row>

反例：

<my-component /> <row><table :column="data"/></row>

6) 组件的 data 必须是一个函数

当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。因为如果直接是一个对象的话，子组件之间的属性值会互相影响。

正例：

export default { data () { return { name: 'jack' } }}

反例：

export default { data: { name: 'jack' }}

7) Prop 定义应该尽量详细

•必须使用 camelCase 驼峰命名•必须指定类型•必须加上注释，表明其含义•必须加上 required 或者 default，两者二选其一•如果有业务需要，必须加上 validator 验证

正例：

 props: { // 组件状态，用于控制组件的颜色 status: { type: String, required: true, validator: function (value) { return [ 'succ', 'info', 'error' ].indexOf(value) !== -1 } }, // 用户级别，用于显示皇冠个数 userLevel：{ type: String, required: true }}

8) 为组件样式设置作用域

正例：

<template> <button class="btn btn-close">X</button></template>
<!-- 使用 `scoped` 特性 --><style scoped> .btn-close { background-color: red; }</style>

反例：

<template> <button class="btn btn-close">X</button></template><!-- 没有使用 `scoped` 特性 --><style> .btn-close { background-color: red; }</style>

9) 如果特性元素较多，应该主动换行。

正例：

<MyComponent foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" />

反例：

<MyComponent foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c"/>

2.1.2. 模板中使用简单的表达式

组件模板应该只包含简单的表达式，复杂的表达式则应该重构为计算属性或方法。复杂表达式会让你的模板变得不那么声明式。我们应该尽量描述应该出现的是什么，而非如何计算那个值。而且计算属性和方法使得代码可以重用。

正例：

<template> <p>{{ normalizedFullName }}</p></template>
// 复杂表达式已经移入一个计算属性computed: { normalizedFullName: function () { return this.fullName.split(' ').map(function (word) { return word[0].toUpperCase() + word.slice(1) }).join(' ') }}

反例：

<template> <p> {{ fullName.split(' ').map(function (word) { return word[0].toUpperCase() + word.slice(1) }).join(' ') }} </p></template>

2.1.3 指令都使用缩写形式

指令推荐都使用缩写形式，(用 : 表示 v-bind: 、用 @ 表示 v-on: 和用 # 表示 v-slot:)

正例：

<input @input="onInput" @focus="onFocus">

反例：

<input v-on:input="onInput" @focus="onFocus">

2.1.4 标签顺序保持一致

单文件组件应该总是让标签顺序保持为 <template> 、<script>、 <style>

正例：

<template>...</template><script>...</script><style>...</style>

反例：

<template>...</template><style>...</style><script>...</script>

2.1.5 必须为 v-for 设置键值 key

2.1.6 v-show 与 v-if 选择

如果运行时，需要非常频繁地切换，使用 v-show ；如果在运行时，条件很少改变，使用 v-if。

2.1.7 script 标签内部结构顺序

components > props > data > computed > watch > filter > 钩子函数（钩子函数按其执行顺序） > methods

2.1.8 Vue Router 规范

1) 页面跳转数据传递使用路由参数

页面跳转，例如 A 页面跳转到 B 页面，需要将 A 页面的数据传递到 B 页面，推荐使用 路由参数进行传参，而不是将需要传递的数据保存 vuex，然后在 B 页面取出 vuex 的数据，因为如果在 B 页面刷新会导致 vuex 数据丢失，导致 B 页面无法正常显示数据。

正例：

let id = ' 123';this.$router.push({ name: 'userCenter', query: { id: id } });

2) 使用路由懒加载（延迟加载）机制

 { path: '/uploadAttachment', name: 'uploadAttachment', meta: { title: '上传附件' }, component: () => import('@/view/components/uploadAttachment/index.vue') },

3) router 中的命名规范

path、childrenPoints 命名规范采用kebab-case命名规范（尽量vue文件的目录结构保持一致，因为目录、文件名都是kebab-case，这样很方便找到对应的文件）

name 命名规范采用KebabCase命名规范且和component组件名保持一致！（因为要保持keep-alive特性，keep-alive按照component的name进行缓存，所以两者必须高度保持一致）

// 动态加载export const reload = [ { path: '/reload', name: 'reload', component: Main, meta: { title: '动态加载', icon: 'icon iconfont' },
 children: [ { path: '/reload/smart-reload-list', name: 'SmartReloadList', meta: { title: 'SmartReload', childrenPoints: [ { title: '查询', name: 'smart-reload-search' }, { title: '执行reload', name: 'smart-reload-update' }, { title: '查看执行结果', name: 'smart-reload-result' } ] }, component: () => import('@/views/reload/smart-reload/smart-reload-list.vue') } ] }];

4) router 中的 path 命名规范

path除了采用kebab-case命名规范以外，必须以 / 开头，即使是children里的path也要以 / 开头。如下示例

* 目的：

经常有这样的场景：某个页面有问题，要立刻找到这个vue文件，如果不用以/开头，path为parent和children组成的，可能经常需要在router文件里搜索多次才能找到，而如果以/开头，则能立刻搜索到对应的组件 *

{ path: '/file', name: 'File', component: Main, meta: { title: '文件服务', icon: 'ios-cloud-upload' }, children: [ { path: '/file/file-list', name: 'FileList', component: () => import('@/views/file/file-list.vue') }, { path: '/file/file-add', name: 'FileAdd', component: () => import('@/views/file/file-add.vue') }, { path: '/file/file-update', name: 'FileUpdate', component: () => import('@/views/file/file-update.vue') } ] }

(二) Vue 项目目录规范

2.2.1 基础

vue 项目中的所有命名一定要与后端命名统一。

比如权限：后端 privilege, 前端无论 router , store, api 等都必须使用 privielege 单词！

2.2.2 使用 Vue-cli 脚手架

使用 vue-cli3 来初始化项目，项目名按照上面的命名规范。

2.2.3 目录说明

目录名按照上面的命名规范，其中 components 组件用大写驼峰，其余除 components 组件目录外的所有目录均使用 kebab-case 命名。

src 源码目录|-- api 所有api接口|-- assets 静态资源，images, icons, styles等|-- components 公用组件|-- config 配置信息|-- constants 常量信息，项目所有Enum, 全局常量等|-- directives 自定义指令|-- filters 过滤器，全局工具|-- datas 模拟数据，临时存放|-- lib 外部引用的插件存放及修改文件|-- mock 模拟接口，临时存放|-- plugins 插件，全局使用|-- router 路由，统一管理|-- store vuex, 统一管理|-- themes 自定义样式主题|-- views 视图目录| |-- role role模块名| |-- |-- role-list.vue role列表页面| |-- |-- role-add.vue role新建页面| |-- |-- role-update.vue role更新页面| |-- |-- index.less role模块样式| |-- |-- components role模块通用组件文件夹| |-- employee employee模块

1) api 目录

•文件、变量命名要与后端保持一致。•此目录对应后端 API 接口，按照后端一个 controller 一个 api js 文件。若项目较大时，可以按照业务划分子目录，并与后端保持一致。•api 中的方法名字要与后端 api url 尽量保持语义高度一致性。•对于 api 中的每个方法要添加注释，注释与后端 swagger 文档保持一致。

正例：

后端 url：EmployeeController.java

/employee/add/employee/delete/{id}/employee/update

前端：employee.js

 // 添加员工 addEmployee: (data) => { return postAxios('/employee/add', data) }, // 更新员工信息 updateEmployee: (data) => { return postAxios('/employee/update', data) }, // 删除员工 deleteEmployee: (employeeId) => { return postAxios('/employee/delete/' + employeeId) },

2) assets 目录

assets 为静态资源，里面存放 images, styles, icons 等静态资源，静态资源命名格式为 kebab-case

|assets|-- icons|-- images| |-- background-color.png| |-- upload-header.png|-- styles

3) components 目录

此目录应按照组件进行目录划分，目录命名为 KebabCase，组件命名规则也为 KebabCase

|components|-- error-log| |-- index.vue| |-- index.less|-- markdown-editor| |-- index.vue| |-- index.js|-- kebab-case

4) constants 目录

此目录存放项目所有常量，如果常量在 vue 中使用，请使用 vue-enum 插件(https://www.npmjs.com/package/vue-enum)

目录结构：

|constants|-- index.js|-- role.js|-- employee.js

例子：employee.js

export const EMPLOYEE_STATUS = { NORMAL: { value: 1, desc: '正常' }, DISABLED: { value: 1, desc: '禁用' }, DELETED: { value: 2, desc: '已删除' }};
export const EMPLOYEE_ACCOUNT_TYPE = { QQ: { value: 1, desc: 'QQ登录' }, WECHAT: { value: 2, desc: '微信登录' }, DINGDING: { value: 3, desc: '钉钉登录' }, USERNAME: { value: 4, desc: '用户名密码登录' }};
export default { EMPLOYEE_STATUS, EMPLOYEE_ACCOUNT_TYPE};

5) router 与 store 目录

这两个目录一定要将业务进行拆分，不能放到一个 js 文件里。

router 尽量按照 views 中的结构保持一致

store 按照业务进行拆分不同的 js 文件

6) views 目录

•命名要与后端、router、api 等保持一致•components 中组件要使用 PascalCase 规则

|-- views 视图目录| |-- role role模块名| | |-- role-list.vue role列表页面| | |-- role-add.vue role新建页面| | |-- role-update.vue role更新页面| | |-- index.less role模块样式| | |-- components role模块通用组件文件夹| | | |-- role-header.vue role头部组件| | | |-- role-modal.vue role弹出框组件| |-- employee employee模块| |-- behavior-log 行为日志log模块| |-- code-generator 代码生成器模块

2.2.4 注释说明

整理必须加注释的地方

•公共组件使用说明•api 目录的接口 js 文件必须加注释•store 中的 state, mutation, action 等必须加注释•vue 文件中的 template 必须加注释，若文件较大添加 start end 注释•vue 文件的 methods，每个 method 必须添加注释•vue 文件的 data, 非常见单词要加注释

2.2.5 其他

1) 尽量不要手动操作 DOM

因使用 vue 框架，所以在项目开发中尽量使用 vue 的数据驱动更新 DOM，尽量（不到万不得已）不要手动操作 DOM，包括：增删改 dom 元素、以及更改样式、添加事件等。

2) 删除无用代码

因使用了 git/svn 等代码版本工具，对于无用代码必须及时删除，例如：一些调试的 console 语句、无用的弃用功能代码。