【杂谈】开发规范

若有错误，欢迎留言

1. 目录结构

项目目录结构

├── log
├── src
│   ├── main
│   │   ├── java
│   │   │   ├── common                 -- 通用类
│   │   │   │   ├── annotation         -- 自定义注解
│   │   │   │   ├── constant           -- 常量
│   │   │   │   ├── enums              -- 枚举
│   │   │   │   ├── exception          -- 自定义错误
│   │   │   │   └── utils              -- 通用工具，静态方法
│   │   │   ├── framework              -- 框架相关
│   │   │   │   ├── aspect             -- 拦截器
│   │   │   │   ├── config             -- 全局设置
│   │   │   │   ├── datasource         -- 数据源
│   │   │   │   └── filter             -- 过滤器
│   │   │   ├── modules                -- 业务模块
│   │   │   └── quartz                 -- 定时任务
│   │   └── resources
│   │       ├── mapper                 -- mybatis持久化映射
│   │       └── application.yml
│   └── test
│       ├── java
│       └── resources
├── target
└── pom.xml

module目录结构

├── web
│   ├── controller            -- web页面controller，包括移动适配【例：CourseController, CourseAdminController】
│   │   └──mob                -- 移动后台Api controller【例：CourseMobController】
│   ├── helper                -- 共享业务逻辑bean【例：CourseControllerHelper】
│   ├── utils                 -- 模块内工具，静态方法
│   ├── constants             -- 业务模块web层常量
│   ├── aop
│   └── fitler
├── biz
│   ├── manager               -- web端应用业务逻辑接口【例：CourseManager】
│   │   ├── mob               -- 移动端应用业务逻辑接口【例：CourseMobManager】
│   │   │   └── vo            -- 移动端应用业务逻辑数据模型【例：CourseMobVo】
│   │   ├── constants
│   │   ├── vo                -- web端接口与内部应用业务逻辑数据模型【例：CourseVo】
│   │   ├── impl              -- 所有应用业务逻辑实现【例：CourseManagerImpl】
│   │   ├── helper            -- 共享业务逻辑bean【例：CourseManagerHelper】
│   │   ├── utils             -- 静态方法
│   │   ├── jms               -- jms消息发送、接口处理代理逻辑类
│   │   └── aop 
│   └── service               -- 模块service原子业务接口【例：CourseService】
│       ├── share             -- 共享给外部的service原子业务接口【例：CourseShareService】
│       │   └──dto            -- 共享给外部的service接口dto【例：CourseShareDto】
│       ├── constants         -- 原子业务层常量
│       ├── dto               -- 仅供内部manager使用的dto
│       ├── impl              -- 模块service原子业务实现【例：CourseServiceImpl】
│       ├── utils             -- 静态方法
│       ├── helper            -- 共享业务逻辑bean【例：CourseServiceHelper】
│       └── aop
└── dao                       -- rdb dao接口【例：CourseDao】
    ├── impl                  -- rdb dao实现【例：CourseDaoImpl】
    ├── domain                -- rdb数据库domain【例：Course】
    ├── doc                   -- doc数据库dao接口【例：CourseDocDao】
    │   ├── impl              -- doc数据库dao实现【例：CourseDocDaoImpl】
    │   └── domain            -- doc数据库domain【例：CourseDoc】
    ├── utils                 -- 静态方法
    ├── constants             -- domain层常量
    └── aop

2. URL和方法命名

RESTFUL URL命名规范

简单的 CRUD URI：

方法	URL	功能
GET	/users	获取用户列表
GET	/users/:id	获取单个用户
POST	/users	创建一个用户
PUT	/users/:id	替换，如不存在则创建
PATCH	/users:id	修改
DELETE	/users:id	删除

级联的资源的 URI：

方法	URL	功能
GET	/users/:id/products	获取指定 Id 用户下的产品列表
GET	/users/:id/products/:id	获取指定 Id 用户下指定的产品
POST	/users/:id/products	在指定 Id 用户下，创建一个产品
PUT	/users/:id/products/:id	在指定 Id 用户下，替换产品
PATCH	/users/:id/products/:id	修改指定 Id 的用户下指定的产品
DELETE	/users/:id/products/:id	删除指定 Id 的用户下指定的产品

方法命名规范

Mapper

操作	例子
增加	add
删除	delete
逻辑删除	remove
修改	update
查询	query
搜索	search

Service

操作	例子	备注
增加	add
获取	get	获取到单条记录
删除	delete
逻辑删除	remove
更新	update	更新存在的记录
保存	save	更新，不存在则新增
查询	query	根据id等简单条件查询
搜索	search	根据时间范围或模糊搜索

Rest

操作	例子	备注
增加	add
获取	get	获取到单条记录
删除	delete
更新	update	更新存在的记录
保存	save	更新，不存在则新增
查询	query	根据id等简单条件查询
搜索	search	根据时间范围或模糊搜索

3. 数据库

基础规范

场景：MySql 大并发量、大数据量的互联网业务

1. 使用InnoDB存储引擎
   支持事务、行级锁、并发性能更好、CPU及内存缓存页优化使得资源利用率更高

2. 使用UTF8字符集
   万国码，无需转码，无乱码风险，节省空间

3. 数据表、数据字段必须加入中文注释

4. 禁止使用存储过程、视图、触发器、Event
   高并发大数据的互联网业务，架构设计思路是“解放数据库CPU，将计算转移到服务层”，并发量大的情况下，这些功能很可能将数据库拖死，业务逻辑放到服务层具备更好的扩展性，能够轻易实现“增机器就加性能”。数据库擅长存储与索引，CPU计算还是上移吧

5. 禁止存储大文件或者大照片
   为何要让数据库做它不擅长的事情？大文件和照片存储在文件系统，数据库里存URI

命名规范

1. 库名、表名、字段名全部小写，单词间通过'_'间隔

2. 表名t_xxx，非唯一索引名idx_xxx，唯一索引名uniq_xxx

3. 主键命名为'id'

表设计规范

1. 单实例表数目必须小于500

2. 单表列数目必须小于30

3. 表必须有主键，例如自增主键
   a）主键递增，数据行写入可以提高插入性能，可以避免page分裂，减少表碎片提升空间和内存的使用
   b）主键要选择较短的数据类型， Innodb引擎普通索引都会保存主键的值，较短的数据类型可以有效的减少索引的磁盘空间，提高索引的缓存效率
   c） 无主键的表删除，在row模式的主从架构，会导致备库夯住

4. 禁止使用外键，如果有外键完整性约束，需要应用程序控制
   外键会导致表与表之间耦合，update与delete操作都会涉及相关联的表，十分影响sql 的性能，甚至会造成死锁。高并发情况下容易造成数据库性能，大数据高并发业务场景数据库使用以性能优先

5. 必须包含4个审计字段且不能为空。created_at、updated_at、created_by、updated_by。

字段设计规范

1. 字段必须定义为NOT NULL并且提供默认值
   a）null的列使索引/索引统计/值比较都更加复杂，对MySQL来说更难优化
   b）null 这种类型MySQL内部需要进行特殊处理，增加数据库处理记录的复杂性；同等条件下，表中有较多空字段的时候，数据库的处理性能会降低很多
   c）null值需要更多的存储空，无论是表还是索引中每行中的null的列都需要额外的空间来标识
   d）对null 的处理时候，只能采用is null或is not null，而不能采用=、in、<、<>、!=、not in这些操作符号。如：where name!=’shenjian’，如果存在name为null值的记录，查询结果就不会包含name为null值的记录

2. 禁止使用TEXT、BLOB类型
   会浪费更多的磁盘和内存空间，非必要的大量的大字段查询会淘汰掉热数据，导致内存命中率急剧降低，影响数据库性能

3. 禁止使用小数存储货币
   使用整数吧，小数容易导致钱对不上

4. 禁止使用ENUM，可使用TINYINT代替
   a）增加新的ENUM值要做DDL操作
   b）也许以为自己定义的是字符串，但ENUM的内部实际存储就是整数

字段长度规则

名称类	类型	长度	备注
账号类	varchar	100	如email，username
状态类	tinyint		如订单状态等，范围：0到255
名称类	varchar	200	中文名称，如产品名
手机电话	varchar	20
描述简介	varchar	500
网址类	varchar	500	如url

索引设计规范

1. 单表索引建议控制在5个以内

2. 单索引字段数不允许超过5个

3. 禁止在更新十分频繁、区分度不高的属性上建立索引
   a）更新会变更B+树，更新频繁的字段建立索引会大大降低数据库性能
   b）“性别”这种区分度不大的属性，建立索引是没有什么意义的，不能有效过滤数据，性能与全表扫描类似

4. 建立组合索引，必须把区分度高的字段放在前面

SQL使用规范

1. *禁止使用SELECT ，只获取必要的字段，需要显示说明列属性
   a）读取不需要的列会增加CPU、IO、NET消耗
   b）不能有效的利用覆盖索引
   c）使用SELECT *容易在增加或者删除字段后出现程序BUG

2. 禁止使用INSERT INTO t_xxx VALUES(xxx)，必须显示指定插入的列属性
   容易在增加或者删除字段后出现程序BUG

3. 禁止使用属性隐式转换
   SELECT uid FROM t_user WHERE phone=13812345678 会导致全表扫描，而不能命中phone索引

4. 禁止在WHERE条件的属性上使用函数或者表达式
   SELECT uid FROM t_user WHERE from_unixtime(day)>='2017-02-15' 会导致全表扫描
   正确的写法是：SELECT uid FROM t_user WHERE day>= unix_timestamp('2017-02-15 00:00:00')

5. 禁止负向查询，以及%开头的模糊查询
   a）负向查询条件：NOT、!=、<>、!<、!>、NOT IN、NOT LIKE等，会导致全表扫描
   b）%开头的模糊查询，会导致全表扫描

6. 禁止大表使用JOIN查询，禁止大表使用子查询
   会产生临时表，消耗较多内存与CPU，极大影响数据库性能

7. 禁止使用OR条件，必须改为IN查询
   旧版本Mysql的OR查询是不能命中索引的，即使能命中索引，为何要让数据库耗费更多的CPU帮助实施查询优化呢

8. 应用程序必须捕获SQL异常，并有相应处理