代码规范

规范分类

● 代码格式
● 命名规范
● 注释规范
● 其他注意
● 数据库规范
● 接口规范
● 测试规范

代码格式

强制：

1. 代码缩进为4个空格，每行最大长度为79
2. import 一次导入一个模块
3. 使用两个空行分割fun和class，使用一个空行分割class中的method
4. 空格规则：
   a. 在二元运算符两边都要有空格。二元运算包括：算术(+ - * / ** )、赋值(=，+=，-=)、比较( ==, <, >, !=, in, not in, is, is not)、逻辑运算(and or not)、位运算(& | ! ~ >> <<)。
   b. 函数的参数时=两侧不需要空格
   c. 逗号后面要加空格，例外：但是如果后面是小括号则不用
   d. 冒号前不加空格，冒号后要加空格。例外：切片里前后都不用加空格
5. 使用枚举类型进行条件筛选时，必须使用==、in、!=运算符，禁止使用<、>。
6. 注释的# 与注释内容之间有且只有一个空格

推荐：

1. 代码中的数字不要意义不明，有些特殊意义的数字可以写在常量文件中并备注。如 if plan_id in [1, 4] 这里的1 4 给人意义不明
2. 单个方法总行数不得超过80行
3. 出现三处及以上功能相同的代码，要考虑重构复用
4. 避免使用函数内 import 解决循环依赖,以 import 整个路径形式解决，同时要知道函数内加载包会使运行缓慢
5. 0表示否/无/失败的意思，而1表示有/对/成功的意思，我们在app/constants 中定义YES和NO常量，用来表示布尔值
6. 避免在函数内声明函数，每次运行时都会给内置函数分配内存且垃圾回收，影响执行效率
7. 批量处理时，使用try来保证发生错误不对后续处理造成影响

命名

强制：

1. 包名文件名以小写+下划线命名，类名以大写开头驼峰命名，函数名以小写+下划线命名
2. 命名下划线最多不超过四个，命名长度不要超过25个字符
3. 代码中的命名不能以 $ 符号开始和结束，尽量少的以特殊符号命名
4. 代码中禁止使用拼音与英文混合的方式，更不允许直接使用中文命名
5. 常量名全部大写，单词间用下划线隔开
6. 在可接受的长度范围内，变量名能把它所指向的内容描述的越精确越好，尽量不要用那些过于宽泛的词来作变量名 ---正例：user_checkin_date ---反例：date
7. 使用is，has， allow，use等开头来命名表示boolean类型的元素

推荐：

1. 命名尽可能的统一，避免出现相同意义不同写法的命名 ---反例：一个课程命名为xxclass,一个为xxcourse
2. 变量名称不用太短，但是可以使用 i，j， k放在迭代器或生成式中使用

注释

强制

1. 逻辑复杂，难以理解，脚本代码等情况必须要有注释
2. 临时性解决，未来可删除的代码，必须有TODO注释 如：# TODO：代码临时迁移，10-12后删除
3. 函数注释在函数内第一行写，注释超过四行要使用"""xxx""" 去注释
   ---使用：def fun(): # 这是注释def fun2(): """ 注释1 注释2 注释3 注释4 """
4. 函数注释必须说明函数作用和特殊说明 ---使用：def get_user_info(user_id): # 获取用户基本信息def get_user_info(user_id): """parma: user_id int 用户ID return: dict 用户基本信息 获取用户基本信息 注：Date信息格式为String """
5. 代码修改修复，要同步更新注释

推荐

1. 注释不是越长越好，简单易懂，支持中文和英文
2. 注释掉代码需在上方说明，否则可以直接删除无用代码

其他

1. 根据MVC架构，项目的views模块中的代码尽量不要做逻辑处理
2. 项目相关的配置应放在configs目录下，业务相关的配置应放在业务module内（例如constants.py）
3. 函数返回时，如果有错误直接报错，不要返回把错误作为返回值返回
4. 推荐清理不再使用的代码段或者配置信息

MySQL数据库

思想

1. 评估是否扩展表结构，扩展后的优点和缺点
2. 确定好扩展带来的风险，扩展的最优方案
3. 在执行扩展指令或者JOB时，减少对用户产生的影响，放在用户低峰期去执行
4. 数据量大的表，尽可能和多人协商出一个扩展方案

强制

1. 必须在代码中体现table_name
2. 表名不使用复数名词
3. 禁用保留字作为表名，建议不要作为字段名，MySQL保留字文档： https://dev.mysql.com/doc/refman/8.0/en/keywords.html
4. 禁止使用float和double字段存储数据
5. 设计表必须满足1NF，JSON字段除外
6. 表中出现别的表的主键ID必须以_id结尾，且必须设置对应的类型
7. 表中出现其他表出现的字段，必须和其他表字段类型相同
8. 业务具有唯一特性字段，即使存在多个字段也必须建立唯一索引
9. varchar字段上加索引需要指定索引长度，如无法指定长度不要在varchar字段加索引
10. 使用is_xxx方式命名字段，表示布尔值，且只取0，1。定义为tinyint, peewee对应的为 BooleanField 使用：
    # 正确 is_checkin = peewee.BooleanField(default=False)
    # 错误 status = peewee.BooleanField(default=False)
11. 尽量不使用BigInt去存储数据，目前已知的BigInt类型的有 user_id
12. smallint 长度为65535。保存枚举数据时可以使用smallint， peewee对应的为 SmallIntegerField
13. 查询超过1000条数据时，使用分页查询
14. 执行DDL前依据数据量级、操作类型评估风险，然后决定执行策略。依据风险大小可以选择直接执行，流量低峰期执行或复制表+双写等操作
15. 不允许创建外键，需求外键逻辑的场景应使用代码实现

推荐

1. 接口中不要直接count/sum/average整表，可以使用缓存或者表达式计算假数据等方式
2. 一行中出现的varchar长度最多为65535，在使用时确定好自己使用varchar的长度，及时换成TextField
3. 用户数据表尽可能设计的简洁，设计好每一个字段
4. CharField字段默认max_length=255, 使用时根据需求设置127， 1023等
5. 查询频率高，代码逻辑复杂，考虑添加缓存缓解数据库压力
6. 插入数据时，需要被校验的字段，使用validates装饰器
7. 某些不必填写的内容，使用default取默认值
8. 有order_by使用场景，请注意使用索引的有序性，最左原则
9. 建立组合索引时，区分度最高的在最左边
10. 大批量的分页查询，避免使用limit offset（peewee）语句，建议记录上一次查询的主键，下次查询使用主键作为条件查询
11. 分页查询不再返回count字段
12. 当索引的字段超过三个时，使用hash创建唯一索引标识
13. 创建索引时避免有如下极端误解：1）宁滥勿缺。认为一个查询就需要建一个索引。2）宁缺勿滥。认为索引会消耗空间、严重拖慢更新和新增速度。3）抵制惟一索引。认为业务的惟一性一律需要在应用层通过“先查后插”方式解决
14. 改变表结构时先把命令全部写好，在操作时直接复制运行避免出问题

错误捕获

可以通过预先检查进行规避就不要通过异常捕获来处理
异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低
对大段代码进行 try-catch，这是不负责任的表现，异常捕获的颗粒度是行。catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。
捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之。如果不想处理它或不能处理，请将该异常抛给它的调用者。
不能在 finally 块中使用 return，finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句
在代码中使用"抛异常"或"返回错误码"，对于公司外的 http/api 开放接口必须使用"错误码"

个人总结

错误捕获原则：错误捕获越精细越好，颗粒度要以行为单位，每次捕获一行代码的错误

尽量减少局部变量，可以写在函数中变量要写在函数中。前提是不能让函数膨胀
类中使用超过2次变量考虑抽象出来封装成一个类的属性，方便统一修改

数据库更新要使用save方法，save的同时会更新update_at，同时save要指明字段
批量插入要使用批量的方法，不能用循环插入

底层函数要通用，不要携带调用方的业务信息。如数据库里的函数要通用，不能只给某一个调用方创建一个函数
区分前端和后端错误，对于前端传入的找不到的错误抛给前端