代码风格规范
核心原则
代码风格必须保持一致性，使用自动化工具（Biome、gofmt）进行格式化。
允许的做法
缩进和空格
- 使用 2 空格缩进（TypeScript/JavaScript）
- 使用 Tab 缩进（Go 语言，遵循 gofmt）
- 使用 一致的空格规则
typescript
// ✅ 正确 - TypeScript
function calculateTotal(items: Product[]) {
return items.reduce((sum, item) => {
return sum + item.price;
}, 0);
}go
// ✅ 正确 - Go
func CalculateTotal(items []Product) float64 {
total := 0.0
for _, item := range items {
total += item.Price
}
return total
}行宽限制
- 遵循 120 字符行宽限制（TypeScript/Go）
- 使用 换行保持可读性
typescript
// ✅ 正确 - TypeScript
const user = await getUserById(userId, { includeProfile: true, includeOrders: false });
// 超过 120 字符时换行
const result = await processComplexOperation(
param1,
param2,
{ option1: true, option2: false, option3: 'value' }
);go
// ✅ 正确 - Go
user, err := userService.GetUserByID(userID, &GetUserOptions{IncludeProfile: true})注释规范
- 使用 注释说明"为什么"，而非"是什么"
- 使用 JSDoc/GoDoc 格式编写函数文档
- 使用 单行注释
//，避免 多行注释/* */
typescript
// ✅ 正确 - 说明原因
// 使用 setTimeout 避免阻塞主线程
setTimeout(() => {
processHeavyTask();
}, 0);
/**
* 根据 ID 获取用户信息
* @param id - 用户 ID
* @returns 用户对象，不存在时返回 null
*/
async function getUserById(id: number): Promise<User | null> {
// ...
}go
// ✅ 正确 - Go 文档注释
// GetUserByID 根据 ID 获取用户信息
// 如果用户不存在，返回 nil
func GetUserByID(id int64) (*User, error) {
// ...
}空行使用
- 使用 空行分隔逻辑块
- 使用 空行分隔函数定义
- 避免 过多的空行（连续空行不超过 1 行）
typescript
// ✅ 正确
function processOrder(order: Order) {
// 验证订单
if (!validateOrder(order)) {
throw new Error('Invalid order');
}
// 计算金额
const total = calculateTotal(order.items);
// 保存订单
return saveOrder({ ...order, total });
}导入语句
- 使用 分组导入（标准库、第三方、本地）
- 使用 字母顺序排序
typescript
// ✅ 正确 - TypeScript
import { useState, useEffect } from 'react'; // React
import axios from 'axios'; // 第三方库
import { UserService } from '@/services'; // 本地模块
import type { User } from '@/types';go
// ✅ 正确 - Go
import (
"context"
"fmt"
"time"
"github.com/labstack/echo/v4"
"gorm.io/gorm"
"your-project/models"
"your-project/services"
)禁止的做法
- 禁止 手动格式化代码（使用工具）
- 禁止 行尾空格
- 禁止 文件末尾缺少换行符
- 避免 嵌套层级超过 4 层
typescript
// ❌ 错误 - 嵌套过深
if (user) {
if (user.isActive) {
if (user.hasPermission) {
if (user.canEdit) {
// 操作
}
}
}
}
// ✅ 正确 - 提前返回
if (!user || !user.isActive) return;
if (!user.hasPermission || !user.canEdit) return;
// 操作工具配置
TypeScript/JavaScript - Biome
json
{
"formatter": {
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 100
}
}Go - gofmt
bash
# 自动格式化
gofmt -w .特殊规则
字符串
- 使用 单引号（TypeScript）
- 使用 模板字符串进行拼接
typescript
// ✅ 正确
const message = 'Hello';
const greeting = `Welcome, ${userName}!`;分号
- 使用 分号结尾（TypeScript）
- 禁止 分号（Go 语言自动插入）
typescript
// ✅ 正确 - TypeScript
const name = 'Alice';
const age = 25;