鸭梨公共文档

主题

01. 项目开发规范 ​

1. 编辑器规范 ​

项目文件的行尾等需要跨平台兼容，项目的根目录必须提供 .editorconfig 文件，这是一个 TOML 文件，样例如下：

toml
[*]
indent_size = 2
indent_style = space
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false
  • 缩进使用空格（禁止 Tab 缩进），遵循对应项目常见约定，如 HTML/JS 使用 2 个空格，Python/Rust 使用 4 个空格
  • 行尾一律使用 LF，并使用 UTF-8 编码

建议禁用 Git 自动行尾转换，以避免不必要的问题。

解决行尾不一致问题

Windows 下的 Git 默认会将行尾转换为 CRLF，而 Linux 下的 Git 默认会将行尾转换为 LF。这样会导致在 Windows 下编辑的文件在 Linux 下会出现行尾不一致的问题。

建议全局关闭 Git 的自动转换行尾：

bash
git config --global core.autocrlf false

如果编辑器已经安装 EditorConfig 插件，建议在 .editorconfig 中设置行尾为 lf：

toml
[*]
end_of_line = lf

在 VS Code 中，可设置 .vscode/settings.json 来确保行尾一致：

json
{
  "files.eol": "\n"
}

在 JetBrains 系列 IDE 中，可设置 File | Settings | Editor | Code Style | Line Separator 为 Unix and macOS (\n)。

插件支持

如果 IDE 没有原生的 EditorConfig 支持，可以安装对应的插件。如 VSCode 的 EditorConfig for VS Code 或 JetBrains 的 EditorConfig 插件。

2. 代码仓库规范 ​

代码仓库使用 Git 管理。活动代码一律在开发分支上开发，main 分支作为主分支，由管理员管理，不允许使用 master 分支。

  • 禁止在主分支上进行强制提交，每位开发者都有单独开发分支，各种分支的作用如下：
    • main：主分支，用于生产环境
    • dev-*：开发分支，最新的开发环境
    • feat-*：特性分支，用于开发新功能
    • fix-*：用于修复 Bug 和线上问题热更新
    • release-*：用于发布新版本和预发布测试
    • test-*：用于测试环境
    • patch-*：用于补丁发布，通常应用于已经发布的版本的小修复或改进
  • 使用 约定式提交规范，禁止使用中文简单描述
  • 项目管理人员定期进行代码审查和 Code review，退回的代码必须整改后重新提交
  • 发布上线的正式版本必须打上对应的 Tag，Tag 格式为 v1.x.x，和项目内版本号保持一致

3. 忽略文件规范 ​

项目必须提供 .gitignore 以用于忽略不需要的文件。

  • 如果项目模板没有忽略文件，则推荐使用 GitHub 推荐的忽略文件
  • 严禁忽略前端包管理器生成的版本锁文件（如 pnpm-lock.yaml 或 yarn.lock 文件）
  • 对于环境文件必须忽略，默认环境文件为 .env，项目中的环境配置必须提供足够的说明和示例（如 .env.example 文件）
  • 严禁将密钥等机密信息提交 Git，机密信息需要使用环境变量或使用 Kubernetes Secret 管理

4. 构建和 CI 文件规范 ​

Web 项目开发，任何开发者有义务维护一份项目的构建脚本和/或 Docker 构建文件。

  • 对于简单的单体项目，需要提供 Dockerfile
  • 对于完整的、有环境要求的项目，则必须提供能完整构建的 docker-compose.yml
  • 对于自动化部署的项目，要求提供特定的 CI/CD 配置文件，如 .gitlab-ci.yml 或 .github/workflows/*.yml
  • 构建文件或脚本中不能包含任何机密信息
  • 关于完整的构建规范，请参考 构建脚本编写规范

5. 项目文档规范 ​

项目的 README.md 必须提供项目的使用说明，包括环境依赖、如何启动、如何部署等。

  • 项目文档必须由 MarkDown 编写，如果需要编写与项目有关的文档，必须放在 docs/ 目录下；
  • 如果项目文档需要提供在线访问，或者项目文档描述了多个项目，则需要单独创建一个项目文档仓库；
  • 文档的编写规范请参考 文档编写规范。

6. 附加原则 ​

这些原则不是强制性的，但是在项目中应该尽量遵守，以提升项目的可维护性和健壮性。

  1. 让你的依赖保持最新。如果你不更新，你使用的版本和最新版本的差异会增加。这种日益增加的差异会让之后更新依赖更加困难。