鸭梨公共文档

主题

开发规范与最佳实践 ​

1. 版本控制规范 ​

1.1 语义化版本（Semantic Versioning） ​

语义化版本规范（SemVer）是一个简单的版本号命名规则，格式为：主版本号.次版本号.修订号。

版本号递增规则：

  • 主版本号（MAJOR）：当你做了不兼容的 API 修改
  • 次版本号（MINOR）：当你做了向下兼容的功能性新增
  • 修订号（PATCH）：当你做了向下兼容的问题修正

示例：

text
1.0.0    # 第一个正式版本
1.0.1    # 修复 bug
1.1.0    # 新增功能，向下兼容
2.0.0    # 重大更新，不兼容旧版本

先行版本号：

text
1.0.0-alpha      # 内部测试版
1.0.0-beta       # 公开测试版
1.0.0-rc.1       # Release Candidate（候选版本）
1.0.0            # 正式版

版本优先级：

text
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

参考：语义化版本

1.2 Git Commit 规范 ​

Conventional Commits ​

text
<type>(<scope>): <subject>

<body>

<footer>

类型（type）：

  • feat：新功能
  • fix：修复 bug
  • docs：文档更新
  • style：代码格式（不影响代码运行）
  • refactor：重构
  • perf：性能优化
  • test：测试相关
  • chore：构建过程或辅助工具的变动
  • ci：CI 配置文件和脚本的变动
  • revert：回滚

示例：

bash
git commit -m "feat(auth): 添加用户登录功能"
git commit -m "fix(api): 修复用户信息接口返回错误"
git commit -m "docs: 更新 README 文档"
git commit -m "refactor: 重构用户模块代码"

1.3 分支管理策略 ​

Git Flow ​

text
main            # 主分支，只包含稳定版本
  └── develop   # 开发分支
       ├── feature/xxx    # 功能分支
       ├── release/x.x.x  # 发布分支
       └── hotfix/xxx     # 热修复分支

工作流程：

  1. 从 develop 创建 feature 分支开发新功能
  2. 完成后合并回 develop
  3. 准备发布时创建 release 分支
  4. 测试通过后合并到 main 和 develop
  5. 紧急修复在 hotfix 分支进行

2. 代码生成工具 ​

2.1 Plop ​

Plop 是一个小型的代码生成器，用于自动化创建项目文件。

安装：

bash
npm install --save-dev plop

配置文件 plopfile.js：

javascript
module.exports = function (plop) {
  plop.setGenerator('component', {
    description: '创建 Vue 组件',
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: '组件名称：'
      }
    ],
    actions: [
      {
        type: 'add',
        path: 'src/components/{{pascalCase name}}.vue',
        templateFile: 'templates/component.hbs'
      }
    ]
  });
};

模板文件 templates/component.hbs：

vue
<template>
  <div class="{{kebabCase name}}">
    {{ name }} Component
  </div>
</template>

<script setup lang="ts">
// {{ name }} 组件逻辑
</script>

<style scoped>
.{{kebabCase name}} {
  /* 样式 */
}
</style>

使用：

bash
npx plop component

参考：plop 中文文档

3. GitHub Actions ​

3.1 基础配置 ​

创建 .github/workflows/ci.yml：

yaml
name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run tests
      run: npm test
      
    - name: Build
      run: npm run build

3.2 自动部署 ​

yaml
name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Build and Deploy
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        folder: dist
        branch: gh-pages

3.3 定时任务 ​

yaml
name: Scheduled Task

on:
  schedule:
    # 每天 UTC 时间 0:00 执行
    - cron: '0 0 * * *'

jobs:
  task:
    runs-on: ubuntu-latest
    
    steps:
    - name: Run task
      run: echo "定时任务执行"

3.4 使用 Secrets ​

yaml
- name: Deploy to server
  env:
    SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
    SERVER_HOST: ${{ secrets.SERVER_HOST }}
  run: |
    # 使用 secrets 进行部署

在仓库设置中添加 Secrets：Settings → Secrets and variables → Actions

参考资料：

4. 代码规范工具 ​

4.1 ESLint ​

JavaScript/TypeScript 代码检查工具。

bash
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

配置文件 .eslintrc.js：

javascript
module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended'
  ],
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error'
  }
}

4.2 Prettier ​

代码格式化工具。

bash
npm install --save-dev prettier

配置文件 .prettierrc：

json
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80
}

4.3 Husky + lint-staged ​

在 Git 提交前自动检查代码。

bash
npm install --save-dev husky lint-staged
npx husky install

配置 package.json：

json
{
  "lint-staged": {
    "*.{js,ts,vue}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

添加 Git Hook：

bash
npx husky add .husky/pre-commit "npx lint-staged"

5. 文档规范 ​

5.1 README 模板 ​

markdown
# 项目名称

简短描述项目的功能和用途。

## 特性

- 功能 1
- 功能 2
- 功能 3

## 安装

\```bash
npm install
\```

## 使用

\```bash
npm run dev
\```

## 配置

环境变量说明...

## 贡献

贡献指南...

## 许可证

MIT

5.2 API 文档 ​

使用工具自动生成 API 文档：

  • JSDoc：JavaScript
  • TypeDoc：TypeScript
  • Swagger：REST API
  • GraphQL：GraphQL API

6. 相关资源 ​