聊聊 Web 开发时的一些基本规范

kpmark 发布于

最后更新于

已访问：次

长文警告

本人对此的认知有限，故本文只会聊一些最基本的规范

鉴于作者并没有实际的企业开发经验，部分涉及合作规范的内容基本来自于腾讯、阿里等开发者平台及一些技术论坛，难免有纸上谈兵的嫌疑

有不同意见的朋友，或者已经在企业入职的朋友，欢迎通过邮箱等方式联系作者进行探讨

Git

Git是一款免费且开源的分布式版本控制系统，旨在以高速和高效的方式处理从小型到超大型的各类项目。除去基本的版本管理，还可以借助 ssh等协议做到方便、安全的文件传输及代码共享

这里会简单介绍一些我认为比较重要的Git使用规范

Commit

是的，使用Git最重要的一件事就是进行版本控制，而git commit -m "<信息>"命令就是提交当前更改的重要方式、

而 Commit 中信息的编写规范非常重要，可以非常直观的提供此次更改内容的变化情况，尤其是在与合作者协同开发的情况下，可以帮助他人一眼看出你的改动内容，是代码写完之后非常重要的一项流程

[!WARNING]

存在不包含相关信息的 commit 命令，这里为了诸位的身心健康，不做介绍

有的同学可能会说了，我写完代码很累了，还要写 commit 不是折磨人吗？

想象一下，当您早上打开仓库开始工作，看的同事 commit 长成下面这样，您的血压会不会飙升

  • fix
  • 修改 bug
  • 设计页面
  • 2.12
  • 添加用户个性化设置功能, 实现用户主题与图片定制功能, 添加四个新API端点, 实现文件管理和Token验证......(此处省略一万字)

心脏强大的同学，或者说完全不关心别人干了什么的同学可能觉得这样无伤大雅，但是为了世界和平，我必须在这里介绍一下规范的 commit 写法，并推荐大家按照规范合理的编写自己的 commit

当然有些同学可能在一些大的开源项目中看到如下提交

image-20250219182243281

注意这里的提交是回应相关 issue 的，详细信息应转至对应页面查看

Angular 规范

目前最受开发人员肯定的规范是前端框架Angular提出的Angular 提交信息规范

这里给出提交格式

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

每次提交必须包括页眉(header)内容，其余正文body和页脚footer视改动情况定

每次提交不超过100个字符

这里简单介绍一些type字段类型

  • build：对构建系统或者外部依赖项进行了修改
  • docs：对文档进行了修改
  • feat：增加新的特征
  • fix：修复bug
  • refactor：既不是修复bug也不是添加特征的代码重构

更多详细信息可以参看连接给出的官方文档
这里搬运一些规范的Angular提交信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
feat(UserProfile): add user profile editing feature

This commit introduces a new feature that allows users to edit their profiles
directly from the user interface. The motivation behind this change is to
enhance user interaction and provide a more seamless experience.

Previously, users had to navigate to a separate editing page to update their
profile information. With this new feature, users can now make changes
efficiently from their profile page, eliminating unnecessary steps in the
workflow.

Changes included in this commit:
- Added a new 'Edit Profile' button on the user profile page.
- Implemented frontend components for profile editing.
- Updated backend API to handle profile updates securely.

By streamlining the profile editing process, we aim to improve overall user
satisfaction and make our application more user-friendly. This enhancement is
in response to user feedback, addressing the need for a more intuitive and
accessible way to modify profile details.

Closes #234
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
fix(Validation): correct input validation logic

This commit addresses an issue related to input validation logic in the
application. Previously, the validation process was not handling certain edge
cases correctly, leading to unexpected behavior in specific scenarios.

To resolve this issue, the validation logic has been revised to properly
handle various input scenarios. This ensures that user input is thoroughly
validated, reducing the likelihood of errors in the application.

The changes made in this commit include:
- Correcting boundary checks for user input.
- Improving error messages for better user guidance.

These adjustments align with our commitment to delivering a robust and
reliable application experience.

Closes #123

个人理解

有的同学可能会说了，小体量项目没必要写的这么规范吧，随便写写不就行了？

[!WARNING]

以下内容仅代表我个人观点，若有不同意见，欢迎联系作者进行友好交流

如果同事或者队友明确表示不在意的话，请自便

其余情况，我个人建议您的提交起码包括以下内容

1
2
3
4
5
git commit -m "一句话交代大致工作

- 详细条目1
- 详细条目2
 - 子条目21"

其中，若提交能够被简短的一句话描述，可省略详细后续内容(务必确保您的工作能被简短的一句话完全概括)

其中，若改动内容较多 ，建议可以稍微详细的对后续条目进行编写(务必确保您的工作不能被简短的一句话完全概括)

这里给出作者的 commit 以供参考

1
2
3
4
5
6
7
8
9
10
11
修复查询帖子 bug 逻辑，新增用户历史发布 API
- 修复查询帖子(GET /search)空列表问题
 - 修复空列表重复响应200状态码
 - 新增响应 count 字段表示当前页数量

- 新增用户历史发布接口(GET /user-history)
  - 支持分页查询
  - 包含帖子总数、当前页数量统计
  - 返回帖子详情及关联图片

- 增改相关 API 文档

可视化查看工具

Git的基本操作是命令行命令，虽然对于基本的提交，拉取，推送之类的命令支持良好，但是当你需要查看具体改动的时候，命令行操作实在是相当不方便

这里提供几个不需要特意下载的可视化工具

Github

Github作为世界上最大的开源代码托管平台，其名称中的Git已然彰显了其与Git的密切关系

这里以Tencent/puerts: PUER(普洱) Typescript. Let’s write your game in UE or Unity with TypeScript.仓库为例稍作演示

在仓库的代码主页，你能很轻松的看到 commit 标识

image-20250219175958659

点击左上角 Commit，进入提交详情

image-20250219180049708

这里已经能很详细的看到提交结果了，我们再点进详情页

image-20250219182439638

这里的红绿色块非常明显的提示了相应的增改内容

Vs code

你说的对，但是 vs code 内置了一款Git可视化工具，可以辅助进行更改的提交，推送

还有好用的冲突管理器，让你不用再Git默认的Vim编辑器中进行冲突的更改

img

这里给出官方使用文档Visual Studio Code 中的 Git 简介

README

一个好的项目，必然有一份好的README，无论这份README是面向开发者还是使用者，都应该进行认真地进行撰写

一份好的README是项目标配，然而其作用并非彰显该项目的专业性或满足自己的展示欲，您的README应该以解决开发者或使用者可能存在的疑惑为目的

古早的游戏文件中，常常能看见txt格式的README文件，直到现在有些游戏仍然使用html网页文件来进行项目描述

然而在如今的开源项目中，通常使用markdown语法来撰写README.md文件，GitHub 要求开源项目必须包含 README.md，否则会显示警告提示

那么，一份完整的项目README应该说明哪些内容呢？

  • 软件定位及基本功能
  • 运行代码的方法：环境、启动命令…
  • 简要使用说明
  • 代码目录结构说明
  • 常见问题说明

作为一份完整的README，其还包括一些在代码早期开发中不需要填写的内容

  • 版权和许可信息
  • 作者列表
  • 社区介绍
  • 联系信息
  • 法律声明

协作规范-以前后端为例

[!WARNING]

再次声明，以下内容纯为主观理解，本人学识浅薄，经验不足，如有更高明的见解，欢迎探讨

虽然国内以阿里巴巴为首的互联网大厂似乎开始主推全栈工程师，但是现在开发中前后端分离的概念仍为很多企业所用

这里的前后端不仅仅指 Web 开发，我们可以将其理解为一种架构，与设计模式等等类似。前端负责交互与展示，后端负责数据处理与逻辑提供

这里我给出一个互联网黄金时期关于前后端分离争论的帖子，我看完受益匪浅

为什么我不喜欢「前后端分离」（个人观点，欢迎来喷） - V2EX

这里，我给出一个 Web 前后端合作的基本流程

准备阶段

需求、需求、还是需求

一个产品，一个项目，其诞生必然有其目的，是为了解决某种问题的

所以在敲定分工、技术栈以及项目框架之前，最重要的就是将项目的需求敲定

谁来敲定需求呢？项目经理、产品经理、或者企划负责人、团队 leader…

不管怎样，敲定一个产品所需的所有需求，是至关重要的

只有这一步做完善了，基本不需要改动了，才建议继续之后的流程

技术栈与项目框架

先考虑团队成员的技术栈掌握情况，敲定项目所需的具体技术栈，并明确哪些已经掌握、哪些需要学习

团队 leader，理应对敲定的技术栈有一定程度的了解（尤其是在需求是他提出的情况下），起码基本知道每个技术栈实现什么样的功能

然后，在动手之前，敲定项目框架

好的项目框架可以有效的应对突发情况的发生，例如需求的突然增加（常见于讨厌甲方），不可攻破的技术壁障，以及人员的突然缺失

项目框架，在我的理解下，应该在需求确定的情况下，与具体技术栈结合，按功能分出大致模块，并明确分工

例如，我在前端明确有几个页面，什么逻辑模块，后端明确数据库与框架的结合模式，是否使用ORM，是否设计Redis缓存层

在全员明确大致的项目框架后，才建议进行下一步流程

不建议有以下情况发生

  • 在对项目从开发到部署的总流程没有基本了解的情况下参与项目
  • 在对项目需求没有完全理解的情况下敲定技术栈
  • 在最后敲定技术栈和项目框架的会议上对需求存有疑惑
  • 在项目开发工作正式启动的前一天修改大量需求并修改技术栈
  • 在没有完成准备阶段任何一步的前提下进入以下任一阶段

接口设计

在早期互联网前后端分离开发中，鉴于前端技术和浏览器性能的限制，一般是以后端为主敲定 API，最后前端使用后端提供的既有的 API进行开发

显而易见的，这样做的坏处是大大限制的项目功能的实现和前端的开发空间

在现在成熟的前端框架如React或全栈框架NEXT.js出现后，前后端分离开发转向并行开发

项目设计是团队合作，良好的公约是团队并行开发的基础

以 Web 项目为例，前后端沟通的桥梁大部分是基于Http或Https的 API 接口

前端需要接口才能获得数据库数据，后端需要接口才能提供数据与相应逻辑

为了使前后端并行开发能够顺利的进行，全员应在开发之前敲定基于需求的接口设计

  • 负责需求的成员应再次明确并重申需要实现的需求
  • 前后端成员应尤其商讨需要哪些 API，包括接口名与接口功能
  • 讨论结束后，应完成一份基本的API 文档，包括接口名称，基本参数属性等内容

之后的并行开发应围绕该 API 文档启动，前端可根据文档自行Mock数据进行开发，后端应围绕文档进行数据库设计，路由分配等开发工作

不建议有以下情况发生

  • 在未敲定 API 文档的情况下启动开发工作

技术方案评审

这在一些企业团队中似乎相当常见，在最终开发之前再次进行技术方案评审，确保各方在需求的认知上统一，并且双方就接口字段可行性做进一步确认

并行开发

[!NOTE]

在开始正式的开发工作前，请对以上步骤进行再次确认，以确保良好的合作体验

必要时应就需求、技术栈与项目框架和接口编写相关文档

一个合作项目的开发，准备阶段永远是最重要的，毕竟良好的开始与开发范式可以疏通合作时的各种障碍

相反，急急忙忙的启动必然导致磕磕绊绊的进度，毕竟开发中遇到的70%的“技术问题”都有先例可依，而需求的频繁变更，框架的摇摆不定，分工的模糊不清却会拖成恶疾

这里，建议您遵循以下规范与建议

  • 确保您具备良好的代码规范

  • 确保您具备良好的编写commit和README.md的能力

  • 确保您具有良好的视力与文本阅读能力

  • 关注合作者的提交，尤其是项目 README的更改，因为这通常直接关联项目合作

  • 保持精力、信心与良好的学习效率

  • 保证足够的工作时长

  • 会使用DeepSeek R1、GPT o3-mini-high或cladue 3.5 sonnet

不建议有以下情况发生

  • 对新技术栈的畏难
  • 自我感动与满足
  • 不关注合作者的提交，尤其是项目 README的更改，因为这通常直接关联项目合作
  • 过量或过少的工作时长

开发环境联调

通常，在具备完整的工作流程的前提下，最后步骤是前后端自测完成之后在开发环境上完成接口联调

然而，在以下情况下，建议将此流程提前

  • 大版本更新
  • 新项目模块加入
  • 不具备良好的项目规划
  • 赶 ddl

总结

以上内容均为我个人主观、浅薄、片面且幼稚的理解，如不能认同，欢迎联系我进行探讨，或者忽略此文章，不要让他坏了您的好心情

kpmark

kpmark

天堂大雪纷纷，一人踏雪无痕

60
2
14
TOC
  1. 1. Git
    1. 1.1. Commit
      1. 1.1.1. Angular 规范
      2. 1.1.2. 个人理解
    2. 1.2. 可视化查看工具
      1. 1.2.1. Github
      2. 1.2.2. Vs code
  2. 2. README
  3. 3. 协作规范-以前后端为例
    1. 3.1. 准备阶段
      1. 3.1.1. 需求、需求、还是需求
      2. 3.1.2. 技术栈与项目框架
    2. 3.2. 接口设计
    3. 3.3. 技术方案评审
    4. 3.4. 并行开发
    5. 3.5. 开发环境联调
    6. 3.6. 总结
NOTICE

别碰 Frp，别碰 Frp，别碰 Frp

CATEGORYS
TAGS
Android CSP Git Github Linux NodeJS TypeScript eda go music web 后端 算法 虚拟机