编码规范性定义分享

1、编程规范

本篇规范基于阿里巴巴、华为的开发手册，在此之上进行归纳整理，欢迎共同改进该规范。

1.1、命名规范

命名的关键是能准确达意 ，减少不必要的英文缩写，拼音简写

• 项目命名：全部小写，多个单词以中划线分隔；
• 类命名：驼峰命名，首字母大写；
• 方法命名：驼峰命名；
• 变量命名：局部变量采取驼峰命名，全局及常量全部大写，多个单词以下划线分隔；

1.2、缩进规范

使用两个空格、或一个tab键进行缩进 。

1.3、方法传参规范

一个方法参数不超过3个参数，超过3个需要构建javabean实体进行传输。

1.4、注释规范

• TODO/FIXME：用来描述待改进和已知缺陷，格式应保持一致

// TODO @auther: 处理xx
// FIXME @auther: xx缺陷

• 类注释需要包含作者、时间、和描述信息

/**
* @auther admin
* @date 2022-04-22 14:05:00
* @description 集合工具类
*/
public class CollectionUtils{
}

• 方法注释需要简述方法作用，参数、返回值

/**
* 通过登录token获取用户
* @param token 登录后返回的token
* @return Principal 返回登录后的完整用户信息
*/
public Principal getPrincipal(String token) {
}

• 代码间禁止使用尾注释，对于复杂逻辑需要做分隔

public void login(LoginDto dto) {
    /*-------------------------1、token是否存在--------------------------*/
    do something
    /*-------------------------2、token有效性验证------------------------*/
    do something
    /*-------------------------3、tokens刷新----------------------------*/
    do something    
}

2、MVC规范

2.1、整体分层

• controller 层
• service 层
• mapper 层

2.2、controller规范

• requestMapping应写在方法上，方法上的mapping可以一次取出；
• 正例：

@RestController
public class UserController {

    @GetMapping("/api/user/list")
    public R<List<UserrVO>> list() {
        return userService.list();
    }
}

• 反例：

@RestController
@RequestMapping("/api/user")
public class UserController {

    @GetMapping("/list")
    public R<List<UserrVO>> list() {
        return userService.list();
    }
}

• 使用restful进行api构建，增删改查对应的方法操作为post、delete、put、get；
• controller层不应出现主体逻辑，只处理参数检验、请求的分发、委派和结果响应。

2.3、service规范

• 过于庞大的service需要进行拆分，按照功能职责进行区分，例如：UserService中与登录用户相关的部分可以拆分为处理登录用户业务的LoginUserService和用于用户管理的UserService；
• service应该具有较好的逻辑分层，理想情况下对于产品只进行迭代，对于客开只进行拓展，在功能研发时需要对技术方案进行评审，防止相关逻辑界限不明、过分耦合；
• 使用声明式事务 @Transaction时 需要指定rollbackFor，声明事务的方法调用另一个事务方法时，启动类需要开启@EnableAspectJAutoProxy(exposeProxy = true)，同时方法内使用代理类使事务生效

 UserService userService = (UserService)AopContext.currentProxy();

2.4、mapper规范

• 查询中不建议使用 * 代替所有字段查询
• 3表及以上关联查询需要在xml中编写
• 不建议使用注解型sql
• sql中禁止使用写死的常量作为条件

3、表设计规范

良好的逻辑设计和物理设计是高性能的基石，应该根据系统将要执行的查询语句来设计schema。

3.1、基本类型选取

• 时间类型：yyyyMMddHHmmss 时间存储使用datetime，如果只是 HHmmss 使用time存储；
• 主键：使用数值型列作为主键，不建议使用字符型列；
• 字符型：可空长度不确定场景使用可变长的varchar进行存储 ，不为空长度固定使用char进行存储。

3.2、表命名

命名全部小写，以下划线 _ 进行分隔，使用两表名连接表示两表间关系。

//用户表
create table sys_user();
//角色表
create table sys_role();
//用户角色表
create table sys_user_role();

3.3、枚举

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

3.4、索引建立

• 普通索引：不使用物理外键构建表间关系，通过查询时建立的普通索引构建逻辑关系；
• 唯一索引：具有唯一性的列构建唯一索引，减少逻辑代码；
• 联合索引：对于多个业务场景下经常使用的多条件查询构建联合索引，最左列离散度最高；

3.5、范式和反范式

• 范式操作多建立于写多的场景，
• 反范式操作（冗余设计）多建立于读多的场景。

3.6、优化

• 设计表时区分记录表与关系表，关系型的表可以多使用缓存进行查询优化