跳到主要内容

代码规范：别让代码变成屎山

代码是写给人看的，顺便让机器执行。——Harold Abelson

为什么代码规范很重要？​

你可能觉得："代码能跑就行，管它格式干嘛？"

错。原因有两个：

1. 你会和别人合作​

想象一下，你和朋友一起做饭。你切菜用厘米，他用英寸。你放盐用勺，他用"少许"。能做出好菜才怪。

代码规范就是大家约定好的"度量衡"——确保所有人的代码看起来像一个人写的。

2. AI 也需要清晰的代码​

AI 工具（Cursor、Copilot）在生成代码时，会参考你已有的代码风格。如果你的代码乱七八糟，AI 生成的代码也会跟着乱。

保持一致的代码风格 = AI 更容易理解你的意图 = 生成更准确的代码

命名规范​

命名是代码可读性的基础。三种最常见的命名风格：

camelCase（驼峰命名）​

首字母小写，后面的单词首字母大写：

const userName = "张三";
const isLoggedIn = true;
function getUserInfo() { }
function handleSubmitForm() { }

用途：JavaScript/TypeScript 的变量、函数

PascalCase（帕斯卡命名）​

每个单词首字母大写：

const UserProfile = () => { };
class ShoppingCar { }
interface ButtonProps { }
type UserType = { };

用途：React 组件、类名、接口、类型

snake_case（蛇形命名）​

单词之间用下划线连接：

user_name = "张三"
is_logged_in = True
def get_user_info(): pass

用途：Python、数据库字段名、环境变量

命名速查表​

语言/场景风格例子
JS/TS 变量camelCaseuserName
JS/TS 函数camelCasegetUserInfo()
React 组件PascalCaseUserProfile
常量UPPER_SNAKEAPI_BASE_URL
CSS 类名kebab-caseuser-card
数据库字段snake_casecreated_at
环境变量UPPER_SNAKEDATABASE_URL

好名字 vs 坏名字​

// ❌ 坏命名
const d = new Date();
const x = users.filter(u => u.a > 18);
function calc(a, b) { return a * b * 0.1; }

// ✅ 好命名
const currentDate = new Date();
const adultUsers = users.filter(user => user.age > 18);
function calculateTax(price, quantity) { return price * quantity * 0.1; }

命名原则：

  • 名字要表达意图，不要怕长
  • 布尔值用 is、has、can 开头
  • 函数名用动词开头：get、set、handle、create、delete

ESLint + Prettier 配置​

ESLint 检查代码质量，Prettier 统一代码格式。两者配合，代码自动保持规范。

安装​

npm install -D eslint prettier eslint-config-prettier eslint-plugin-prettier

ESLint 配置（Next.js）​

创建 .eslintrc.json：

{
  "extends": [
    "next/core-web-vitals",
    "prettier"
  ],
  "rules": {
    "no-unused-vars": "warn",
    "no-console": "warn",
    "prefer-const": "error",
    "no-var": "error"
  }
}

Prettier 配置​

创建 .prettierrc：

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

保存时自动格式化​

在 VS Code 的 settings.json 中添加：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

这样每次按 Ctrl+S，代码自动格式化 + 自动修复 lint 问题。

.editorconfig​

.editorconfig 确保不同编辑器使用相同的格式设置：

root = true

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

[*.md]
trim_trailing_whitespace = false

把这个文件放在项目根目录，提交到 Git。团队成员用不同编辑器也能保持一致。

Next.js 项目文件夹结构​

好的文件夹结构让项目一目了然：

my-app/
├── src/
│   ├── app/                  # Next.js App Router 页面
│   │   ├── layout.tsx        # 全局布局
│   │   ├── page.tsx          # 首页
│   │   ├── login/
│   │   │   └── page.tsx      # 登录页
│   │   └── api/              # API 路由
│   │       └── users/
│   │           └── route.ts
│   ├── components/           # 可复用组件
│   │   ├── ui/               # 基础 UI 组件
│   │   │   ├── Button.tsx
│   │   │   └── Input.tsx
│   │   └── layout/           # 布局组件
│   │       ├── Header.tsx
│   │       └── Footer.tsx
│   ├── lib/                  # 工具函数和配置
│   │   ├── db.ts             # 数据库连接
│   │   ├── auth.ts           # 认证逻辑
│   │   └── utils.ts          # 通用工具函数
│   ├── hooks/                # 自定义 Hooks
│   │   └── useUser.ts
│   ├── types/                # TypeScript 类型定义
│   │   └── index.ts
│   └── styles/               # 样式文件
│       └── globals.css
├── public/                   # 静态资源
│   └── images/
├── .env.local                # 环境变量
├── .gitignore
├── next.config.js
├── package.json
├── tsconfig.json
└── README.md

文件命名规范​

  • 组件文件：PascalCase——Button.tsx、UserProfile.tsx
  • 工具文件：camelCase——useUser.ts、formatDate.ts
  • 页面文件：固定为 page.tsx（Next.js 约定）
  • 样式文件：camelCase 或 kebab-case

注释的艺术​

什么时候该写注释​

// ✅ 解释"为什么"而不是"是什么"
// 需要延迟 300ms，因为 Stripe 的 SDK 加载需要时间
await new Promise(resolve => setTimeout(resolve, 300));

// ✅ 解释复杂的业务逻辑
// 折扣规则：满 200 减 30，满 500 减 100，VIP 额外 9 折
function calculateDiscount(amount, isVip) { }

// ✅ 标记待办事项
// TODO: 后续需要添加短信验证码功能

// ✅ 警告信息
// WARNING: 不要修改这个值，会影响所有现有用户的密码
const SALT_ROUNDS = 10;

什么时候不该写注释​

// ❌ 注释说的是显而易见的事
// 获取用户名
const userName = getUser().name;

// ❌ 注释比代码还长
// 这个函数的作用是遍历数组，然后检查每一项的 type 属性，
// 如果 type 等于 'active'，就把它加到结果数组里
const activeItems = items.filter(item => item.type === 'active');

// ❌ 注释掉的代码（直接删掉，Git 会帮你记住）
// oldFunction();
// const temp = doSomething();

原则：好代码自己会说话。如果需要大量注释，说明代码写得不够清晰。

用 .cursorrules 规范 AI 生成代码​

.cursorrules 文件放在项目根目录，告诉 Cursor AI 你的代码风格偏好：

# 项目规范

## 技术栈
- Next.js 14+ (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Supabase

## 代码风格
- 使用函数式组件，不用 class 组件
- 使用 const，不用 let 和 var
- 组件使用 PascalCase，变量使用 camelCase
- 优先使用 Server Components，需要交互时才用 Client Components
- 每个文件只导出一个组件

## 命名规范
- 页面文件：page.tsx
- 布局文件：layout.tsx
- 组件文件：PascalCase.tsx
- Hook 文件：useXxx.ts
- 工具函数：camelCase.ts

## 错误处理
- 使用 try/catch 处理异步操作
- 给用户友好的错误提示，不要暴露技术细节
- 使用 toast 通知用户操作结果

## 注释
- 复杂逻辑必须写注释
- 组件顶部用 JSDoc 写功能说明
- 不写显而易见的注释

有了这个文件，AI 生成的代码会更贴合你的项目风格。

代码审查清单（Code Review Checklist）​

即使你是一个人开发，也建议用这个清单检查自己的代码：

基础检查​

  • 代码能正常运行吗？
  • 有没有 console.log 残留？
  • 有没有未使用的变量和导入？
  • 命名是否清晰易懂？

代码质量​

  • 有没有重复代码？能不能提取成函数/组件？
  • 函数是否太长？（超过 50 行考虑拆分）
  • 错误处理是否完善？
  • 有没有硬编码的值？（应该用常量或环境变量）

安全检查​

  • 有没有暴露敏感信息？（API key、密码）
  • 用户输入有没有验证？
  • 有没有 SQL 注入或 XSS 风险？

性能检查​

  • 有没有不必要的重复渲染？（React）
  • 大列表有没有分页或虚拟滚动？
  • 图片有没有优化？（压缩、懒加载）

提交检查​

  • commit message 是否规范？
  • 是否有不必要的文件被提交？（.env、node_modules）
  • 代码是否通过 ESLint 检查？

Commit Message 规范​

好的提交信息让 Git 历史一目了然：

# 格式：类型: 简短描述

# ✅ 好的 commit message
feat: 添加用户登录功能
fix: 修复首页加载缓慢的问题
docs: 更新 README 安装说明
style: 统一代码格式
refactor: 重构认证模块
chore: 升级 Next.js 到 14.1

# ❌ 坏的 commit message
update
fix bug
修改
asdfgh
类型用途
feat新功能
fix修复 bug
docs文档
style格式（不影响功能）
refactor重构
chore杂务
test测试

小结​

  • 命名要清晰——代码是写给人看的
  • 配置 ESLint + Prettier——保存时自动格式化
  • 文件夹结构要统一——好找、好维护
  • 注释写"为什么"——不写"是什么"
  • 用 .cursorrules 规范 AI——生成更一致的代码
  • 提交前用清单检查——养成好习惯

代码规范不是束缚，是帮助你写出更好代码的工具。当规范变成习惯，你就不再需要刻意遵守了。