后端代码规范
| 版本 | 日期 | 描述 | 作者 |
|---|---|---|---|
| v1.0 | 2019-04-05 | 完成go代码编写规范 | gitgiter |
| v2.0 | 2019-04-13 | 完成数据库设计规范 | gitgiter |
| v3.0 | 2019-04-14 | 完成接口设计规范 | gitgiter |
| v3.1 | 2019-04-14 | 增加重要性前缀标签 | gitgiter |
go语言编写规范
优秀的命名应当是一贯的、短小的、精确的
尽量使用专门的工具进行实时的代码规范监督，且工具应统一。目前推荐：vscode的go插件。如无法统一便按标准库源码规范编写，几个主要的注意点如下：
命名规范
- 变量名、函数参数名：
- 【强制】采用驼峰命名；
- 【强制】无特殊情况首字母一律小写；
- 【强制】不要以下划线开头；
- 【强制】必须使用简洁、有意义的名称；
- 【建议】没有明显关系的变量分行声明，不要因为只是类型一样方便声明而挤到一行；
- 【强制】如果无法一眼看出含义，请使用注释；
- 【建议】变量名的注释也尽量简洁，写在变量名之上，且注释与上文代码或其他注释以换行隔开，与被注释的变量之间不换行；
- 【建议】函数参数名的注释一律写在函数注释中；
- 函数名：
- 【强制】采用驼峰命名；
- 【强制】首字母一律大写；
- 【强制】不要以下划线开头；
- 【强制】必须使用简洁、有意义的名称；
- 【强制】函数名与后面的左圆括号之间不空格；
- 【强制】右圆括号与左花括号之间空格且花括号不换行；
- 【强制】右花括号单独一行；
- 结构体名：
- 【强制】采用驼峰命名；
- 【强制】首字母一律大写；
- 【强制】不要以下划线开头；
- 【强制】必须使用简洁、有意义的名称，尽量使用单个单词；
- 【强制】struct关键字后的左花括号不换行；
- 【强制】右花括号单独一行；
- 结构体成员变量名：
- 【强制】采用驼峰命名；
- 【强制】首字母一律大写，否则数据无法访问；
- 【强制】不要以下划线开头；
- 【强制】必须使用简洁、有意义的名称，尽量体现为一个属性；
- 【强制】每个成员变量单独一行，且必须有注释，在被注释变量之上，与前面的变量换行隔开，与被注释变量之间不换行；
- 包名：
- 【强制】使用小写，尽量是单个单词或短语；
- 【强制】一律不使用下划线；
- 【强制】保持与目录名称一致；
- 【强制】必须使用简洁、有意义的名称；
- 【强制】尽量和标准库不要冲突；
注释规范
- 【强制】言简意赅，可读性好；
- 【建议】针对性强，相同内容不重复注释；
- 【强制】单行注释使用 // ，且 // 后应有空格；
- 【强制】多行使用 /*/ ，且 / 与 */ 分别独立一行，中间行的 * 后要带空格；
- 【强制】与上文不相关的代码或注释以换行隔开，与被注释的内容不换行；
- 【建议】不要在某一句代码后面（右边）使用注释，特别简短（1~3个单词）的例外；
- 【强制】统一使用英文注释；
其他
- 【强制】内置函数如while、for、if-else的左花括号不换行，其中else与if的右花括号同行；
- 【强制】同一个变量名不要在不同上下文中使用；
- 【强制】变量名不得与函数名冲突；
- 【强制】import使用圆括号统一导入，左圆括号不换行，右圆括号单独一行，不引入没有使用的包；
- 【强制】一个函数不要含有太长的代码
- 【建议】如果逻辑确实较多且有明显的逻辑块或者局部代码复用度高，可以进一步将逻辑块抽象出新的函数；
- 【建议】如果逻辑确实角度且逻辑块之间有明显的顺序关系，各个逻辑块可以换行隔开，逻辑块首行必须有注释；
- 【强制】单行代码尽量不要太长，要求在一屏里显示全，如需使用横向滚轮则为过长；
- 【建议】应优先考虑简短单行代码长度，如确实过长才使用换行处理，
- 【建议】应避免使用 functionA(functionB(xxx,xxx), functionC(xxx), xxx, functionD(xxx)) 的嵌套调用方式，容易导致单行代码过长且不方便debug；
- 【建议】如函数参数过多（如5个及以上），可以采用多行调用
functionA( xxxx, xxxx, xxxx, xxxx, xxxx, xxxx ) - 【建议】如存在多行赋值代码，应保证等号对齐；
- 【强制】缩进一律使用空格，不能用tab，可在编辑器中设置用 4个空格 代替tab；
- 【强制】逗号后面要空格；
- 【强制】算符左右两边都需要空格；
数据库规范
- 参考：MySQL数据库规范（详细）。
提炼（有所修改和增加）
基础规范
- 【强制】使用utf-8字符集，如果有字段需要存储emoji表情之类的，则需要将字段或表设置成utf8mb4。
- 【强制】数据表、数据字段必须加入 英文 注释。
- 【建议】避免存储大文件或者大图片，能URL尽量URL。
命名规范
- 【强制】库名、表名、字段名：小写字母，下划线风格，禁止数字开头，禁止两个下划线中间只出现数字，禁止复数名词。例如：正例：getter_admin，task_config，level3_name 反例：GetterAdmin，taskConfig，level_3_name。
- 【强制】均采用英文字符，不可用中文命名，更不要包含空格。
- 【强制】命名中不允许出现MYSQL数据库中的保留字。如desc、range、match、delayed等，请参考MySQL官方保留字。
- 【强制】索引命名格式为：索引类型_字段名。
- 【强制】保持字段名和类型的一致性，在命名字段并为其指定数据类的时候一定要保证一致性。假如数据类型在一个表里是整数，那在另一个表里也应是整数，不能是其他类型。
- 【强制】数据库名、表名、字段名必须有意义，一目了然。尽量使用某些单词或短语及其常用缩写。
- 【建议】数据库名、表名、字段名长度适中。3~10个字符为宜。至多使用一个下划线进行连词。
表设计规范
- 【强制】单实例表数目必须小于500，单表列数目必须小于30。
- 【建议】无特殊情况下，建议显式指定一个无业务用途的自增unsigned bigint型主键。
- 【强制】把字段定义为NOT NULL并且提供默认值。
- 【建议】小数类型用decimal，禁止使用float和double。
- 【建议】表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsigned tinyint( 1表示是，0表示否)。
- 【建议】如果存储的字符串长度几乎相等，使用char定长字符串类型。
- 【建议】字段允许适当冗余，以提高性能，但是必须考虑数据同步的情况。
SQL使用规范
- 【强制】禁用select *，必须指定列。
- 【强制】insert语句需指定列。
- 【强制】禁止使用属性隐式转换。
- 【强制】应用程序必须捕获SQL异常，并有相应处理。
- 【建议】禁止负向查询，以及%开头的模糊查询。
- 【建议】禁止大表使用JOIN查询，禁止大表使用子查询。
- 【建议】禁止使用OR条件，必须改为IN查询。
接口规范
- 【强制】使用restful api风格。
- 【强制】每种url代表一种资源。
- 【强制】不能采用 “动词+宾语” 的请求方法。
- 【强制】url中不出现动词，只有名词。
- 单数名词 + id 表示获取某个资源。
- 复数名词表示获取对应资源列表。
- 【强制】使用的名词应易于理解，可以体现出该url对应的资源。
- 【强制】动词在请求类型中体现，如Get、Post、Delete、Put等。
- Get：从服务端获取资源或资源列表。
- Post：创建一个新的资源。
- Put：完整地更新一个已有资源。
- Patch：部分地更新一个已有资源。
- Delete：删除一个资源。
- 【强制】url中不出现动词，只有名词。
- 【强制】至少支持最常见的请求方式，如Get、Post。
- 【建议】使用json传递数据。
- 【强制】避免多级url。
- 【强制】返回时必须指明状态码。尤其是容易发生错误时。
- 【建议】状态码越精确越好。至少要对应五大类：
- 1xx: 相关信息
- 2xx: 操作成功
- 3xx: 重定向
- 4xx: 客户端错误
- 5xx: 服务端错误
- 【参考】：status codes
- 【建议】状态码越精确越好。至少要对应五大类：