全栈开发规范手册

一. 代码规范

1. Service/DAO 层方法命名规约

1）获取单个对象的方法用 get 做前缀。

2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。

3）获取统计值的方法用 count 做前缀。

4）插入的方法用 save/insert 做前缀。

5）删除的方法用 remove/delete 做前缀。

6）修改的方法用update 做前缀。

摘自:

Java开发手册【泰山版】

2. SQL语句规范

1）SQL 语句中表的别名前加 as，并且以 t1、t2、t3、...的顺序依次命名。

select t1.name from table_first as t1, table_second as t2 where t1.id=t2.id;

摘自:

Java开发手册【泰山版】

二. 接口规范

项目接口是基于REST构建的API也就是RESTful架构风格设计。

在RESTful架构中，每个URL代表一种资源，所以不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"，所以API中的名词也应该使用复数。

最佳案例

https://youlai.store/users GET 获取所有用户信息
https://youlai.store/users/1 GET 获取标识为1用户信息
https://youlai.store/users/1 DELETE 删除标识为1用户信息
https://youlai.store/users/1 Patch 更新标识为1用户部分信息,包含在body中
https://youlai.store/users POST 添加新的用户
https://youlai.store/users/me GET 获取当前用户信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

参考:

RESTful API 设计指南

三. Git规范

1. Commit message的格式规范

Commit message 包括三个字段：type（必需）、scope（可选）和subject（必需）。

<type>(<scope>): <subject>

1).type

type用于说明 commit 的类别，规范使用以下标识。

feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style：格式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是修改bug的代码变动）
test：增加测试
chore：构建过程或辅助工具的变动
revert：回滚到上一个版本
merge：代码合并
sync：同步主线或分支的Bug

2).scope

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

3). subject

subject是 commit 目的的简短描述，不超过50个字符。

最佳案例

 git commit -m docs(README.md):分支修改项目说明文档

格式化Commit message的好处

1). 快速预览历史

git log <last tag> HEAD --pretty=format:%s

2). 快速过滤查找

git log <last release> HEAD --grep feature

3). commit生成Change log

Change Log 是发布新版本时，用来说明与上一个版本差异的文。

参考:

Commit message 和 Change log 编写指南

2. 分支开发主干发布模式

禁止在主干直接修改代码，需在开发分支开发并在测试环境测试通过之后由相关人员同步到主干

最佳案例

[master] > git fetch origin dev
[master] > git checkout dev

[dev] > git add .
[dev] > git commit -m docs(README.md):分支修改项目说明文档
[dev] > git push origin dev
[dev] > git checkout master

[master] > git merge dev
[master] > git push origin master