项目规范(1)
2024-06-30 本文已影响0人
温岭夹糕
写在开头
非原创，仅用于自身学习系统设计
文集目录
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个重要内容
- 提交频率。个人项目随意，多人项目，随意的commit 只会让其变得难以理解。何时进行commit最好？一种是，只要对项目进行了修改，通过测试就commit，另一种是规定一个时间，定期提交能尽可能减少丢失的代码量。
- 合并提交
上面两种情况在开发完一个完整的功能后，可以最后合并所有commit(建议把新的commit合并到主干时，只保留2-3个)
git rebase -i
这个命令十分重要
- 修改commit message
- 修改最近一次
git commit --amend
- 修改某次
git rebase -i
1.3.6 目录规范
目录规范通常指项目由哪些目录组成，每个目录下存放什么文件、实现什么功能、各个目录的依赖关系等
-
平铺式目录结构：
即在项目根目录下存放项目代码，整个目录结构看起来是一层的，适合代码是框架/库时 -
结构式目录结构：
典型的比如project-layout
