项目规范规则配置参考：一、目标统一团队编码风格，提升可读性和维护性减少低级错误和潜在 Bug 提高协作效率，便于

规则配置参考：

# 项目规范

- 使用 TypeScript
- 代码风格遵循 ESLint 配置
- 所有函数需要添加注释
- 测试覆盖率需达到 80% 以上

一、目标

统一团队编码风格，提升可读性和维护性
减少低级错误和潜在 Bug
提高协作效率，便于 Code Review 和自动化流程集成

二、技术栈约定（示例）

类别	推荐技术
语言	JavaScript (ES6+) / TypeScript（推荐）
框架	React / Vue / Node.js（根据项目定）
包管理	npm / yarn / pnpm
构建工具	Vite / Webpack / Rollup
代码格式化	Prettier
代码检查	ESLint
Git 提交	Commitlint + Husky（可选）
版本控制	Git

✅ 建议优先使用 TypeScript 提升类型安全。

三、代码风格规范

1. 变量与声明

使用 const / let，禁止使用 var
优先使用 const，仅在需要重新赋值时用 let
所有变量必须先声明再使用

// ✅ 正确
const userName = "Alice";
let count = 0;

// ❌ 错误
var oldStyle = true;
name = "Bob"; // 未声明

2. 命名规则

类型	规则	示例
变量、函数	驼峰命名法（camelCase）	`getUserInfo`, `isLoading`
常量	全大写 + 下划线（UPPER_CASE）	`MAX_RETRY_COUNT`
类、构造函数	大驼峰（PascalCase）	`class UserProfile {}`
私有成员	前缀 `_`（约定俗成）	`_privateMethod()`
类型/接口（TS）	PascalCase	`interface UserConfig {}`

3. 字符串

使用单引号 '，除非字符串中包含单引号
拼接字符串使用模板字符串（反引号 ` `${}` `）

// ✅
const message = `Hello, ${name}`;
const path = '/api/users';

// ❌
const msg = "Hello " + name;

4. 对象与数组

使用字面量创建对象和数组
属性简写、计算属性合理使用
解构赋值提升可读性

// ✅
const user = { name, age };
const [first, second] = list;
const { username, email } = userInfo;

// ❌ 不推荐
const obj = new Object();
const arr = new Array();

5. 函数

优先使用箭头函数（尤其是回调）
普通函数用于方法定义或需绑定 this 的场景
参数默认值代替 || 判断

// ✅
const fetchUser = async (id = 1) => { ... };
list.map(item => item.name);

// ❌
function() { ... }.bind(this)
if (!id) id = 1;

6. 异步处理

使用 async/await 替代 .then().catch()
必须用 try/catch 包裹异步操作
不要忽略 Promise 的错误

// ✅
try {
  const res = await api.getData();
} catch (err) {
  console.error('请求失败:', err);
}

// ❌
fetch('/api').then(...).catch(...) // 嵌套深，不易读

7. 比较与条件判断

使用严格相等：=== 和 !==
避免隐式类型转换
条件判断尽量简洁

// ✅
if (status === 'active') { ... }

// ❌
if (status == 1) { ... }

四、目录结构建议（通用）

src/
├── components/        # 通用组件（React/Vue）
├── pages/             # 页面级组件
├── utils/             # 工具函数
│   ├── request.js     # 封装的 HTTP 请求
│   └── helpers.js     # 格式化、校验等
├── services/          # API 接口服务层
├── store/             # 状态管理（Redux/Vuex/Pinia）
├── assets/            # 静态资源（图片、字体）
├── styles/            # 公共样式
├── routes/            # 路由配置
├── constants/         # 常量定义
└── App.js             # 主应用入口

💡 根据框架调整，如 Vue 项目可用 views/ 替代 pages/

五、代码质量保障

1. ESLint 配置（`.eslintrc.js` 示例）

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:import/recommended'
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module'
  },
  rules: {
    'no-var': 'error',
    'prefer-const': 'error',
    'eqeqeq': ['error', 'always'],
    'curly': 'error'
  }
};

2. Prettier 配置（`.prettierrc`）

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

3. 编辑器集成

安装 VS Code 插件：

- ESLint
- Prettier

开启保存时自动格式化：

// settings.json
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
  "source.fixAll.eslint": true
}

六、Git 提交规范

1. 分支命名

分支类型	命名规则	示例
主分支	`main` / `master`	`main`
开发分支	`develop`	`develop`
功能分支	`feat/功能名`	`feat/user-login`
修复分支	`fix/问题描述`	`fix/header-bug`
发布分支	`release/v1.2.0`	`release/v1.3.0`

2. 提交信息格式（Conventional Commits）

格式：<type>(<scope>): <description>

类型	说明
`feat`	新功能
`fix`	修复 bug
`docs`	文档更新
`style`	格式调整（不影响逻辑）
`refactor`	重构代码
`perf`	性能优化
`test`	测试相关
`chore`	构建或工具变更

✅ 示例：

feat(login): add social login buttons
fix(header): prevent overflow on mobile
refactor(api): split user service into modules

❌ 错误：

update file
fixed something

✅ 推荐使用 Commitlint + Husky 自动校验提交格式。

七、注释与文档

1. 注释原则

函数必须有注释说明用途、参数、返回值
复杂逻辑添加行内注释
避免无意义注释（如 i++ // i 加 1）

/**
 * 获取用户信息
 * @param {number} userId - 用户 ID
 * @returns {Promise<Object>} 用户数据
 */
async function fetchUserInfo(userId) { ... }

2. 文件头部注释（可选）

/**
 * @fileOverview 用户登录模块
 * @author zhangsan
 * @since 2025-04-05
 */

八、测试规范（推荐）

类型	工具建议	要求
单元测试	Jest / Vitest	核心工具函数覆盖率 ≥ 80%
组件测试	React Testing Library / Vue Test Utils	关键交互需覆盖
E2E 测试	Cypress / Playwright	主流程自动化验证

✅ 建议：每个新功能都应配套测试用例。

九、安全性注意事项

防止 XSS：对用户输入进行转义或使用框架的安全机制
避免 eval() 和 new Function()
敏感信息不硬编码在前端（如 API Key）
使用 HTTPS 加载资源
第三方库定期审计（可用 npm audit）

十、部署与 CI/CD 建议

使用 GitHub Actions / GitLab CI / Jenkins 实现自动化构建
流程建议：

1. 提交代码 → 触发 CI
2. 运行 Lint + Test
3. 构建打包
4. 部署到预发布环境
5. 手动确认后上线生产

# .github/workflows/deploy.yml 示例片段
- run: npm run lint
- run: npm run test
- run: npm run build

十一、附录：推荐工具清单

用途	工具
代码格式化	Prettier
语法检查	ESLint
提交校验	Commitlint + Husky
包依赖分析	BundlePhobia / depcheck
类型检查	TypeScript
日志调试	`console.log` → 生产移除（可用 `vite-plugin-remove-console`）

十二、结语

“规范不是束缚，而是自由的护栏。”
—— 统一的规范让团队走得更快、更稳。

请所有开发者遵守本规范。如有例外情况，需在 PR 中说明并获得团队认可。

📄 文档输出建议：

存为 PROJECT_GUIDE.md 放入项目根目录
配合 .eslintrc, .prettierrc, commitlint.config.js 等配置文件一起使用
新成员入职必读

✅ 下一步建议：
你可以将此规范导出为 PDF 或 Wiki 页面，并在项目初始化时集成以下脚本：

# 初始化 husky 和 commitlint（示例）
npx husky-init
npm install --save-dev @commitlint/config-conventional @commitlint/cli
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

是否需要我为你生成一个可下载的 Markdown 文件 或 PDF 版本？也可以根据你的项目类型（React/Vue/Node）定制专属规范模板。欢迎继续提问！

项目规范