写在开头

非原创，仅用于自身学习系统设计

文集目录

链接

1.规范制定

现代软件应用的开发大多都是多人协作完成的，正因如此，常遇到以下问题：

• 代码风格不同
• 目录很乱，相同的功能被放在不同目录，或者一个目录根本不知道要完成什么功能
• 接口不统一
• 错误码不规范，如同类错误有不同错误码，增加理解难度

为了不让应用看起来杂乱无章，难以维护，我们需要在设计阶段、写代码前定制一个规范来约束开发者

1.1规范类型

我们总结上述难题，根据是否跟代码相关，分为非编码类规范和编码类规范 image.png

1.2开源规范

知道就行（只有开源项目才会用到开源协议），如果我们需要遵循一个开源协议，那么GO项目的开发也需要遵循这个协议，开源协议中会规定使用开源软件时的权利和责任，即使用者可以做什么，不可以做什么。开源协议种类很多，乌克兰程序员Paul Bagwell总结如下 image.png

1.3 文档规范

1.3.1 README文档及规范

README文档是项目的门面，是开发者学习项目时的第一个阅读的文档，会放在跟目录下，主要用于介绍项目功能、安装、部署和使用，所以可以被规范。
ps :在线readme生成工具readm.so

1.3.2项目文档

项目文档包括一切需要文档化的内容，通常集中放置在/docs目录下，因此我们可以事先规划并创建好目录，用来存放不同文档。不同的项目有不同的文档需求，在指定规范时，可以考虑两类文档：

• 开发文档：用来说明项目的开发流程，如搭建开发环境，构建二进制文件、测试部署等
• 用户文档：即软件的使用文档，如api文档，sdk文档，安装文档

1.3.3API接口规范文档

又称API文档，一般由后台开发编写，用来描述组件提供的API及调用方法，接口文档有四种编写方式 image.png

一个规范的API接口文档，通常需要包含：

• 一个完整的API接口介绍文档
• API接口变更历史文档
• 通用说明
• 数据结构说明
• 错误码描述
• API接口使用文档：又包含接口描述、请求方法、请求参数、输出参数和请求示例

1.3.4版本规范

建议把所有组件都加入版本机制：

• 方便定位问题：通过版本号可以很明确知道组件版本，从而定位到功能和问题
• 发布组件时携带版本号，让使用者知道项目进度和功能增减

目前业界主流是语义化版本规范SemVer，版本格式为

主版本号.次版本号.修订号(X.Y.Z)

• 主版本号：当做了不兼容的API的修改时递增，主版本号为0的软件处于开发初始阶段（实际开发时也推荐使用0.1.0作为第一个开发版本），1.0.0被界定为第一个稳定版本。主版本号递增时，次版本号和修订号必须归零。
• 次版本号：当做了向下兼容的功能性新增及修改时递增，一个不成文的约定是偶数为稳定版本，奇数为开发版本。
• 修订号：当做了向下兼容的问题修正，递增

image.png
还有一种是 image.png

• 先行版本：顾名思义，未正式发布，不稳定
• 编译版本： 一般是编译器在编译过程中自动生成

1.3.5 Commit规范

即commit message ，一个好的commit规范至关重要:

• 方便快速浏览历史，清晰知道每个commit的变更内容
• 可以基于message 过滤查找

git log --oneline --grep "^hello|^hhhh"

• 可以基于规范化的commit生成change log
• 可以依赖某些类型的commit message触发构建或发布流程，如type类型为feat/fix触发CI流程
• 确定语义化版本的版本号

在开发时，我们建议使用开源社区中比较成熟的规范 image.png

以Angluar为例

image.png
image.png
Angluar的commit包含三部分,header、body和footer：

<type> [option]:<desc>

[optional body]

[optional footer]

1.3.6Commit相关的3个重要内容

1. 提交频率。个人项目随意，多人项目，随意的commit 只会让其变得难以理解。何时进行commit最好？一种是，只要对项目进行了修改，通过测试就commit，另一种是规定一个时间，定期提交能尽可能减少丢失的代码量。
2. 合并提交
   上面两种情况在开发完一个完整的功能后，可以最后合并所有commit(建议把新的commit合并到主干时，只保留2-3个)

git rebase -i 

这个命令十分重要

3. 修改commit message

• 修改最近一次

git commit --amend

• 修改某次

git rebase -i 

1.3.6 目录规范

目录规范通常指项目由哪些目录组成，每个目录下存放什么文件、实现什么功能、各个目录的依赖关系等

• 平铺式目录结构：
  即在项目根目录下存放项目代码，整个目录结构看起来是一层的，适合代码是框架/库时

• 结构式目录结构：
  典型的比如project-layout