建设小型网站价钱,柳市做网站制作,北京建站优化,唐河网站制作公司开发中的那些规范 俗话说#xff1a;无规矩不成方圆。生活如此、软件开发也如此。 来聊一聊开发中有哪些地方需要规范。 为什么需要规范
现在开发一个应用基本上都是多人协作#xff0c;一旦涉及到多人#xff0c;必然不同的开发者的开发习惯、编码方式都是有所不同的…开发中的那些规范 俗话说无规矩不成方圆。生活如此、软件开发也如此。 来聊一聊开发中有哪些地方需要规范。 为什么需要规范
现在开发一个应用基本上都是多人协作一旦涉及到多人必然不同的开发者的开发习惯、编码方式都是有所不同的如果没有一个统一的规范就会造成非常多的问题
代码风格不一目录杂乱无章接口不统一偏后端例如 修改用户定的接口为 /v1/users修改密钥的接口 /v1/secret?nameusername 错误码不统一
因此我们需要一个好的规范来约束开发者以便保证大家开发的是“一个项目”。
有哪些规范
整体来讲我根据规范是否涉及到代码将其分为了两大类
非编码类规范 开源规范文档规范CommitMessage 规范版本规范 编码类规范 目录规范代码规范接口规范偏后端日志规范错误码规范
开源规范
目前其实在整个业界并没有一个官方的开源规范但是当我们决定要将我们的代码进行开源的时候实际上是有一些隐式的规则需要我们去遵循的。
较高的单元覆盖率 当我们要将我们的项目进行开源的时候那么项目肯定是经过了单元测试Mocha、Jest、Vitest要求单元测试的覆盖率达到一个较高的标准例如 90%。这样不仅仅保证了你的项目的健壮性而且非常有利于第三方开发者。 避免敏感信息外漏 要确保整个代码库和提交记录不能出现内部 IP、密码、密钥这一类信息否则会造成安全隐患 及时反馈 当我们的开源项目被其他开发者提了 PR、Issue、评论的时候一定要及时的去处理。 及时更新 我们自身也要针对该开源项目及时的去更新功能、修复 Bug。针对一些已经结项、不维护的项目需要及时的对项目进行归档、还要在项目描述中加以说明
另外还有一点需要了解常见的开源协议。常见的开源协议有 MIT、Apache具体如下表所示
开源协议特点适用场景GPLGNU General Public License它是最严格的开源协议之一。如果你使用了 GPL 授权的代码那么你的项目也必须采用 GPL。这意味着你必须开源自己的代码并且任何衍生的作品也必须使用 GPL。对于那些希望他们的代码和衍生作品始终保持开源的项目来说这是一个很好的选择。MPLMozilla Public LicenseMPL 是一种温和的开源协议。它允许在同一个项目中混合使用 MPL 和非 MPL 代码但是任何修改 MPL 代码的部分必须保持开源。对于想要某些部分代码保持开源同时允许与私有代码结合的项目。LGPLLesser General Public License比 GPL 宽松。如果你使用了 LGPL 授权的库你的项目不需要开源只要你对这个库所做的修改开源即可。常用于库和框架使它们能够被更广泛地应用于各种软件项目中。Apache License提供了很大的自由度包括商业使用。你可以修改和分发代码无需公开源代码。它还明确了对专利的授权。对于那些希望代码被广泛使用包括在商业产品中并且希望提供一定的法律保护的项目。BSDBerkeley Software DistributionLicense非常宽松几乎没有什么限制。你可以自由使用、修改和重新分发代码甚至在商业软件中。不过该协议禁止用开源代码作者/机构名字和原来产品名字来做市场推广。适用于几乎所有类型的项目特别是那些希望代码被尽可能广泛地使用的项目。MIT License也是一种非常宽松的许可证和 BSD 类似。允许你做几乎任何你想做的事只要在复制或分发时包含许可证原文。对于那些希望简单、灵活地授权其代码的项目。 在上表中所罗列出来的协议从上往下依次从严格到宽松 或者可以参考 Choose an open source licensehttps://choosealicense.com/
目前前端常用的协议就是 BSD、MIT、Apache
协议项目MITjQuery、React、Lodash、Vue、Angular、ESLintBSDYeoman、node-inspectorApacheEcharts、Less.js、math.js、TypeScript
另外就算你的项目不打算开源你也应该尽量的去按照项目的开源规范去建设你的项目。开源项目一般在 代码质量、文档规范、目录结构、接口等等地方都要求比较高。
文档规范
文档也是咱们在进行软件交付的时候一个非常重要的组成部分。
一个项目需要编写哪些文档这些文档又应该如何进行编写
一个项目中比较重要的几类文档如下
README 文档待办清单变更日志API 文档根据项目类型而定
README 文档
README 文档是其他开发者在看你项目的时候会阅读到的第一个文档该文档一般放置于项目的根目录下面。
README 文档的好坏直接影响了其他开发者在阅读了解你项目的时候的一个阅读体验。
一个合格的 README 文档需要包含以下三个方面
项目的介绍使用者指南贡献者指南
下面是一份 README 文档的标准模板
# 项目名称!-- 写一段简短的话来介绍项目 --## 功能特性!-- 描述该项目的核心功能点 --## 软件架构可选!-- 可以描述一下项目的架构 --## 快速开始### 依赖检查!-- 描述该项目的依赖比如比较重要的依赖包、工具或者其他依赖项 --### 构建!-- 描述如何构建项目 --### 运行!-- 描述如何运行该项目 --## 使用指南!-- 描述如何使用该项目 --## 如何贡献!-- 告诉其他开发者如何给该项目贡献代码 --## 社区可选!-- 如果存在社区可以简单介绍一下社区相关内容 --## 关于作者!-- 写上简短的项目作者介绍 --## 谁在用可选!-- 可以列出使用该项目的其他有影响力的项目算是给项目打一个广告 --## 许可证!-- 这里链接上该项目的开源许可证 --待办清单
用于记录即将要发布的内容或者未来的计划。
在我们的项目里面添加一个待办清单有两个好处
告诉项目的使用者未来会有哪些功能为我们自己做一个备忘提醒我们自己未来要交付的功能有哪些
一般就用 Markdown 来写就可以了[x] 和 [ ] 在 Markdown 语法里面是复选框的形式能够很好的表现待办事项
# 计划列表这是一个 TODO 列表包含了 jstoolpack 未来可能添加或改进的功能。## 数组方法- [x] 添加一个方法用于在数组中查找指定元素的索引值。## 字符串方法- [x] 完成字符串截取方法
- [ ] 检测一个字符串是否是 URL 的方法。## 函数方法- [x] debounce 方法
- [ ] throttle 方法## 通用- [ ] 添加一个方法用于将两个数组合并为一个对象。## 测试- [x] 编写更多的测试用例覆盖所有的函数和方法。## 文档- [x] 完善 README 文件包括更多的使用示例和 API 文档。
- [ ] 添加一个 CONTRIBUTING 文件包含贡献指南和代码风格规范。## 其他- [ ] 添加一个 CHANGELOG 文件记录每个版本的变化。
- [ ] 增加 CI/CD 功能包括自动化测试和持续集成。
- [ ] 发布到更多的包管理器如 NPM 和 Yarn。
- [ ] 改进代码的性能和可读性。
- [ ] 添加更多的函数和方法以满足不同的开发需求。变更日志
变更日志主要是用来记录每一次变更的详细内容添加变更日志文档有两个好处
方便使用者了解版本升级所带来的变化特别是 Breaking Change也开发者自己做一个备忘
变更日志一般会记录
版本号变更时间具体的变更内容
示例如下
# 变更日志所有版本的变化都记录在这个文件中。本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 标准。## [1.0.0](https://github.com/) - 2022-01-01### 新增- 添加了一个 range 方法用于生成指定范围内的数字数组。
- 添加了一个 truncate 方法用于截断字符串并添加省略号。
- 添加了一个 debounce 方法用于在一定时间内防止函数被重复调用。
- 添加了一个 throttle 方法用于在一定时间内限制函数的调用次数。### 修复- 修复了一个在某些情况下会导致 debounce 和 throttle 方法失效的 bug。### 改进- 改进了代码的结构和文档。
- 改进了测试覆盖率和代码质量。## [0.1.0](https://github.com/) - 2021-12-01### 新增- jstoolpack 项目的第一个版本。
- 添加了一个 range 方法用于生成指定范围内的数字数组。
- 添加了一个 truncate 方法用于截断字符串并添加省略号。### 改进- 改进了代码的结构和文档。
- 改进了测试覆盖率和代码质量。API 文档
API 文档取决于你的项目类型如果你的项目是第三方库或者组件库那么就需要提供 API 文档。
根据你代码库的功能的多少在创建 API 文档的时候有三种方案可选
功能较少可以直接写到 README 文件里面内容较多可以单独写一个 API 的文件来介绍 API数量非常非常多需要考虑专门做一个网站来提供详细的文档 Vuepress、Vitepress、Docusaurus
CommitMessage 规范
在进行代码开发的时候经常会涉及到代码的提交这个时候就需要书写 CommitMessage。
CommitMessage 在书写的时候也需要遵循一定的规范。关于 CommitMessage 规范当然可以自己去制定一套但是更加建议采用开源社区中提供的一些 CommitMesage 规范。
开源社区提供的 CommitMesage 规范很多husky、jQuery、Angular、Ember、JSHint 这些技术都带来它们相应的 CommitMessage 规范。
今天晚上主要介绍 Angular 的提交规范https://www.conventionalcommits.org/en/v1.0.0-beta.4/
在 Angular 规范中CommitMessage 分为三个部分Header、Body、Footer具体的格式如下
type[optional scope]: subject!-- 空行 --[optional body]!-- 空行 --[optional footer]Header
这个部分只有一行包括三个字段type必填、scope可选和 subject必填
type
主要用于说明 CommitMessage 的类型这里又分为两种类型
Development这一类类型一般是项目管理类的更新这一类更新是不会影响用户和生产环境的代码的。 例如 CI 流程、构建方式等这一类修改这一类修改通常也意味着可以免测试发布 Production这一类修改会影响生产环境的代码 因此针对这一类代码的修改我们一定要谨慎需要做好充分的测试
下面的表是 Angular 规范中所罗列出来的常见的类型和所属类别
类型类别说明featProduction新增功能fixProduction修复缺陷prefProduction提高代码性能的变更styleDevelopment代码格式类的变更例如格式化了代码删除了空行等refactorProduction其他代码类的变更这些变更不属于 feat、fix、pref 和 style例如简化代码、重命名变量名、删除冗余代码等testDevelopment新增测试用例或更新现有的测试用例ciDevelopment持续集成和部署相关的改动例如修改了 Jenkins、GitLab CI 等 CI 配置文件docsDevelopment文档类的更新包括修改用户文档、开发文档等choreDevelopment其他类型例如修改了构建流程、依赖管理或者辅助工具的变动等。
scope
主要是用于指明会影响应用的哪个部分。
subject
一个针对这一次提交的简短的描述信息
简洁明了一般来讲就是一句话动词开头描述你这一次提交做了什么事情add、fix、update、remove
下面是一些符合上面所讲规范的示例
修改用户界面的错误
fix(UI): 修复登录界面的布局问题添加新的用户认证功能
feat(auth): 实现基于Token的认证机制改进后端 API 的性能
perf(api): 优化数据库查询效率修复一个错误
fix: 修复导航栏响应式布局问题文档更新
docs: 更新README文件添加部署指南Body
Header 部分是对 commit 做一个高度的概括那么 Body 就进行更加具体的描述。
Body 的形式是比较自由示例如下
feat(login): 实现新的登录流程为了提高用户体验和安全性我们重新设计了登录流程。新的流程包括以下改变- 引入了 OAuth 2.0 认证使用户可以通过 Google 账号登录。
- 优化了登录表单的布局现在在移动设备上显示更为友好。
- 增加了验证码功能以防止自动化的恶意登录尝试。这些改变旨在使登录过程更加流畅同时提高了账户的安全性。新的 OAuth 认证方式简化了用户的登录步骤而对移动布局的优化则确保了在各种设备上的可用性。Body 虽然说形式比较自由但是一般会描述这么几个方面的信息
描述更改的背景详细罗列出具体的改变解释这些改变的目的和好处
Footer
footer 主要是两个目的。
一是关闭相关的 issue
Closes #123, #124在 CommitMessage 中书写关闭了哪些 issue 的 footer 有一个好处能够在以后 PR 的时候自动关闭这些 issue。
在 Github 这样的平台如何 CommitMessage 中带有 Closes、Fixes 等关键字后面有 issue 的编号那么在之后进行 PR 合并的时候会自动关闭相关联的 issue。
不兼容的变更breaking change
BREAKING CHANGE: 更改了身份验证 API 的接口结构。旧的接口 /api/auth/login 现在变更为 /api/user/login。更新了所有的调用点以适应这一变更。如果你在你的代码中直接使用了这个接口请更新为新的接口地址。版本规范
目前业界比较主流的是 语义化版本规范来自于 Github 所推出的。
整体的格式主版本号.次版本号.修订号 x. y .z 主版本在做了不兼容的 API 的时候会递增。次版本一般是在当前版本中做了新增功能时递增。不成文规定偶数一般为稳定版本奇数为开发版本。修订号针对某一个 bug 进行修复了之后递增
除了上面的表示方式你可能还会看到 整体的格式变为主版本号 .次版本号 .修订号[- 先行版本号][ 版本编译元数据] 先行版本号该版本还不稳定最终还没有确定下来仅仅是一个预览。 1.0.0-alpha 1.0.0-alpha.1 1.0.0-0.3.7 1.0.0-x.7.z.92
以一连串以句点分隔的标识符 编译版本号在编译器编译的过程中自动生成的。 1.0.0-alpha001 1.0.02013031344700 1.0.0-betaexp.sha.5114f85
一般以 号开头后面就是编译版本号
关于语义化版本号具体规则可以参阅https://semver.org/lang/zh-CN/
关于最佳实践
在实际开发的时候建议使用 0.1.0 作为你的第一个开发版本号当我们的版本是一个稳定的版本并且第一次对外发布的时候那么版本号可以定为 1.0.0按照 Angular Commit Message 提交规范来看的话版本的的确定 fix 类型的 commit 修订号 1feat 类型的 commit 次版本号 1带有 Breaking Change 的 commit 可以主版本号 1
编码类规范
1. 代码规范
阿里https://github.com/alibaba/f2e-spec?tabreadme-ov-file腾讯https://imweb.github.io/rule/
上面的规范虽然很有名但是也算是内部规范。在整个业界讨论得比较多Airbnb 和 Google 所推出规范。
Airbnb
可读性和一致性风格指南强调代码的可读性和一致性。它包含了关于空格、缩进、换行、命名约定等的详细规则以确保代码的整洁和一致性。ES6 和更新的语法指南特别关注于使用最新的 JavaScript 特性比如 ES6ECMAScript 2015及以后版本的语法包括箭头函数、模板字符串、解构赋值等。最佳实践它还包括了许多编程最佳实践比如避免使用 var 声明变量优先使用 const 和 let以及如何编写模块化和可重用的代码。代码组织指南还涵盖了有关代码结构和组织的建议比如文件结构、模块导入等。易于集成Airbnb 的 JavaScript 风格指南可以很容易地与代码质量工具如 ESLint、Prettier集成以自动检查和格式化代码确保遵守规范。
官网https://github.com/airbnb/javascript
Google
Google 推出的代码规范叫做 Google JavaScript Style Guide
官网https://google.github.io/styleguide/jsguide.html
除了上面介绍的两套规范以外我们开发的时候还有两个常用的工具
ESLintESLint 本身并非一个编程风格的指南是一个 JS 代码质量和风格的检查工具。Prettier该工具主要是负责做格式化它是属于 opinionated 类型的工具与之对应的是 unopinionated opinionated :内部已经内置了一套最佳实践要求你按照它的方式走不要想东想西的。 spring boot、Ruby on Rails、thinkPHP、Angular unopinionated特点就是允许用户 DIY提供了一定的灵活性和自定义性 express 关于 ESLint 和 Prettier 之间的冲突问题
在 google 规范中推荐字符串使用单引号以分号结束语句。
prettier 设置的是格式化规则为双引号不要分号。
因此产生冲突。
eslint-config-prettier关闭所有 prettier 和 eslint 工具中会发生冲突的规则。eslint-plugin-prettier该插件的作用是将 prettier 的格式化规则作为 ESLint 规则来进行检查。
Vue 代码规范
实际上在 Vue 官网是提供了代码指南的。
官网https://vuejs.org/style-guide/
2. 目录规范
下面给出一个常见的项目目录示例以 Vue 项目为例
my-app|-- src| |-- assets # 静态资源图片、样式表、字体等| |-- components # 可重用的 UI 组件| |-- views # 页面级组件或称为“容器”组件| |-- layouts # 应用布局组件| |-- router # 路由配置对于 SPA 类型的应用| |-- store # 状态管理例如 Vuex/Redux 的相关代码| |-- services # 服务例如 API 交互| |-- utils # 实用工具函数和助手| |-- App.vue # 根 Vue 组件对于 Vue 应用| |-- main.js # 应用的主入口文件|-- public| |-- index.html # 主 HTML 文件| |-- favicon.ico # 网站图标|-- tests| |-- unit # 单元测试| |-- e2e # 端到端测试|-- /node_modules # 项目依赖文件夹|-- package.json # 项目的依赖、脚本和配置|-- README.md # 项目的 README 文件|-- .gitignore # Git 忽略文件配置|-- .eslintrc.js # ESLint 配置|-- .prettierrc.js # Prettier 配置# 其他可能的配置或文件|-- .browserslistrc # 浏览器兼容性配置|-- .env # 环境变量配置|-- config # 项目配置文件|-- dist # 构建后的输出目录|-- docs # 项目文档|-- .vscode # VS Code 配置如果是 monorepo 方式的项目目录又会有一些不同
假设是使用 pnpm workspace 来搭建的 monorepo
my-monorepo-app|-- packages| |-- package1 # 子项目 1| | |-- src| | |-- package.json| |-- package2 # 子项目 2| | |-- src| | |-- package.json| |-- shared # 共享代码或组件| |-- src| |-- package.json|-- package.json # Monorepo 根级别的 package.json|-- pnpm-workspace.yaml # pnpm 工作区配置文件|-- pnpm-lock.yaml # pnpm 锁文件|-- README.md|-- .gitignore|-- .eslintrc.js # ESLint 配置|-- .prettierrc.js # Prettier 配置# 其他配置文件包只要使用包管理工具npm、yarn、pnpm初始化后了的目录就是一个包 库只要使用版本控制工具初始化后的目录就是一个库 monorepo一个仓库里面多个包 好处提取公共值 公共的 ESlint、prettier 的配置公共的依赖公共的构建流程 multirepo一个包就对应一个仓库
3. 测试的规范
常见的测试
单元测试测试一个应用里面的最小单元函数、组件常见的测试框架 Jest、Mocha、Vitest集成测试E2E 测试视觉回归测试
1. 测试的独立性
每个测试案例都应该独立于其他测试不依赖其他测试的状态或者结果。
避免使用共享的数据或者状态
Good Case
describe(Calculator tests, () {it(should add two numbers, () {expect(add(2, 3)).toBe(5);});it(should subtract two numbers, () {expect(subtract(5, 2)).toBe(3);});
});Bad Case
let result 0;describe(Calculator tests with shared state, () {it(should add two numbers, () {result add(2, 3);expect(result).toBe(5);});it(should subtract two numbers based on previous result, () {result subtract(result, 2); // 依赖上一个测试的结果expect(result).toBe(3);});
});2. 测试命名
测试用例的命名应该是清晰的描述了该测试用例的目的和行为。
Good Case
describe(User authentication, () {it(should log in with valid credentials, () {// ...});it(should reject login with invalid credentials, () {// ...});
});Bad Case
describe(User login, () {test(test1, () {// ... 无描述性命名});test(test2, () {// ... 无描述性命名});
});3. 边界测试
在测试的时候特别针对于函数需要测试边界以及一些特殊情况空输入、非法参数并且每个测试用例只测试一个行为或者一个功能点。
Good Case
describe(String reverser, () {it(should reverse a non-empty string, () {expect(reverseString(hello)).toBe(olleh);});it(should handle an empty string, () {expect(reverseString()).toBe();});
});Bad Case
describe(String reverser, () {it(should reverse strings and handle empty string, () {expect(reverseString(hello)).toBe(olleh);expect(reverseString()).toBe(); // 混合了两个测试案例});
});4. 依赖隔离
因为我们是单元测试单元测试强调的是要和外部隔离如果要测试的单元涉及到外部的连接发送请求、访问数据库使用 mock 进行模拟屏蔽掉外部的影响
Good Case
it(should send user data, () {const mockApi jest.fn();sendUserData({ id: 1, name: John }, mockApi);expect(mockApi).toHaveBeenCalledWith({ id: 1, name: John });
});Bad Case
it(should send user data, () {sendUserData({ id: 1, name: John }, realApiCall); // 使用真实API// ... 测试依赖外部API的响应
});5. 测试反馈
使用清晰的断言来提供反馈信息
Good Case
it(should fail to withdraw with insufficient balance, () {expect(() withdraw(account, 100)).toThrow(Insufficient balance);
});Bad Case
it(should fail to withdraw, () {expect(() withdraw(account, 100)).toThrow(); // 缺少具体的错误信息验证
});
