# 开发规范

> **文档版本**: v1.0.0
> **创建日期**: 2026-05-25
> **适用范围**: FischerX 项目开发人员

## 目录

- [代码规范](#代码规范)
- [Git 规范](#git-规范)
- [PR 规范](#pr-规范)

---

## 代码规范

### TypeScript 规范

#### 类型定义

- 使用 `type` 定义对象类型，使用 `interface` 定义类接口或需要扩展的类型
- 始终使用严格的类型检查，避免使用 `any`
- 优先使用联合类型和字面量类型

```typescript
// 好的做法
type User = {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user' | 'guest';
};

interface Repository {
  findById(id: string): Promise<User | null>;
  save(user: User): Promise<User>;
}

// 避免
type User = any;
```

#### 命名规范

- 类型名使用 PascalCase
- 常量使用 UPPER_SNAKE_CASE
- 变量和函数使用 camelCase
- 类使用 PascalCase
- React 组件使用 PascalCase

```typescript
// 类型
type UserProfile = { ... };

// 常量
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

// 变量和函数
const userName = 'John';
function calculateTotal(price: number, quantity: number): number { ... }

// 类
class UserService { ... }

// React 组件
function UserProfileCard() { ... }
```

#### 文件组织

- 一个文件一个主要导出
- 使用 index.ts 作为模块入口
- 按功能组织文件，而不是按类型

```
// 好的做法
user/
├── index.ts
├── types.ts
├── service.ts
├── repository.ts
└── hooks.ts
```

---

### React/Next.js 规范

#### 组件设计

- 使用函数组件，避免类组件
- 组件文件使用 `.tsx` 扩展名
- 组件名与文件名保持一致

```tsx
// components/UserCard.tsx
interface UserCardProps {
  user: User;
  onEdit?: (user: User) => void;
}

export function UserCard({ user, onEdit }: UserCardProps) {
  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
      {onEdit && <button onClick={() => onEdit(user)}>Edit</button>}
    </div>
  );
}
```

#### Hooks 规范

- 自定义 Hook 以 `use` 开头
- Hook 应该只负责单一职责
- 使用 React Query 进行数据获取
- 使用 Zustand 进行状态管理

```tsx
// hooks/useUser.ts
import { useQuery } from '@tanstack/react-query';
import { userApi } from '@/lib/api';

export function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => userApi.getById(userId),
    enabled: !!userId,
  });
}
```

#### 表单处理

- 使用 React Hook Form
- 使用 Zod 进行验证
- 显示友好的错误信息

```tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';

const formSchema = z.object({
  name: z.string().min(2, 'Name too short'),
  email: z.string().email('Invalid email'),
});

type FormValues = z.infer<typeof formSchema>;

function UserForm() {
  const form = useForm<FormValues>({
    resolver: zodResolver(formSchema),
  });

  const onSubmit = (data: FormValues) => {
    console.log(data);
  };

  return <form onSubmit={form.handleSubmit(onSubmit)}>{/* ... */}</form>;
}
```

#### 样式规范

- 使用 Tailwind CSS
- 组件内部样式放在 `className` 中
- 复杂样式使用 `clsx` 或 `tailwind-merge`

```tsx
import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

function cn(...inputs: any[]) {
  return twMerge(clsx(inputs));
}

function Button({
  children,
  variant = 'primary',
  className,
}: {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'danger';
  className?: string;
}) {
  const variants = {
    primary: 'bg-blue-600 text-white hover:bg-blue-700',
    secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
    danger: 'bg-red-600 text-white hover:bg-red-700',
  };

  return (
    <button
      className={cn(
        'px-4 py-2 rounded font-medium transition-colors',
        variants[variant],
        className
      )}
    >
      {children}
    </button>
  );
}
```

---

### NestJS 规范

#### 模块结构

- 按功能组织模块
- 每个模块包含 Controller、Service、Module
- 使用 Prisma 作为数据访问层

```
user/
├── user.module.ts
├── user.controller.ts
├── user.service.ts
├── dto/
│   ├── create-user.dto.ts
│   └── update-user.dto.ts
└── entities/
    └── user.entity.ts
```

#### 控制器规范

- Controller 只负责请求/响应处理
- 业务逻辑委托给 Service
- 使用 DTO 进行验证
- 使用 Swagger 装饰器生成文档

```typescript
import { Controller, Get, Post, Body, Param, UseGuards } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';

@ApiTags('users')
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @ApiOperation({ summary: 'Create user' })
  @ApiResponse({ status: 201, description: 'User created' })
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }

  @Get(':id')
  @UseGuards(JwtAuthGuard)
  @ApiOperation({ summary: 'Get user by ID' })
  findOne(@Param('id') id: string) {
    return this.userService.findOne(id);
  }
}
```

#### 服务规范

- Service 包含业务逻辑
- 使用依赖注入
- 抛出业务异常

```typescript
import { Injectable, NotFoundException } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { CreateUserDto } from './dto/create-user.dto';
import * as bcrypt from 'bcrypt';

@Injectable()
export class UserService {
  constructor(private prisma: PrismaService) {}

  async create(createUserDto: CreateUserDto) {
    const hashedPassword = await bcrypt.hash(createUserDto.password, 10);

    return this.prisma.user.create({
      data: {
        ...createUserDto,
        password: hashedPassword,
      },
    });
  }

  async findOne(id: string) {
    const user = await this.prisma.user.findUnique({ where: { id } });
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }
}
```

#### DTO 规范

- 使用 class-validator 进行验证
- 使用 class-transformer 进行转换
- DTO 放在 dto 目录下

```typescript
import { IsEmail, IsString, MinLength } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty()
  @IsString()
  @MinLength(2)
  name: string;

  @ApiProperty()
  @IsEmail()
  email: string;

  @ApiProperty()
  @IsString()
  @MinLength(8)
  password: string;
}
```

---

## Git 规范

### 分支策略

我们使用 Git Flow 工作流：

```
main (生产环境)
  └── develop (开发环境)
        ├── feature/feature-name (功能分支)
        ├── bugfix/bug-name (修复分支)
        ├── hotfix/hotfix-name (紧急修复)
        └── release/release-x.y.z (发布分支)
```

#### 分支说明

| 分支类型 | 命名规范 | 说明 |
|---------|---------|------|
| main | `main` | 生产环境代码，始终稳定 |
| develop | `develop` | 开发环境代码，集成新功能 |
| feature | `feature/xxx-yyy` | 新功能开发 |
| bugfix | `bugfix/xxx-yyy` | Bug 修复 |
| hotfix | `hotfix/xxx-yyy` | 生产环境紧急修复 |
| release | `release/x.y.z` | 发布准备 |

#### 创建分支

```bash
# 从 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/user-authentication

# 从 main 创建紧急修复分支
git checkout main
git pull origin main
git checkout -b hotfix/critical-login-bug
```

---

### 提交规范

我们使用 Conventional Commits 规范：

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

<body>

<footer>
```

#### Type 类型

| 类型 | 说明 |
|-----|------|
| feat | 新功能 |
| fix | Bug 修复 |
| docs | 文档更新 |
| style | 代码格式调整 |
| refactor | 重构 |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建/工具相关 |

#### Scope 范围

- `web`: Web 应用
- `admin`: 管理后台
- `api`: API 服务
- `ui`: UI 组件库
- `core`: 核心业务包
- `types`: 类型定义
- `utils`: 工具函数
- `config`: 配置

#### 提交示例

```bash
# 新功能
git commit -m "feat(web): add user login page"

# Bug 修复
git commit -m "fix(api): handle null user in authentication"

# 文档更新
git commit -m "docs: update quick start guide"

# 重构
git commit -m "refactor(ui): restructure button component"

# 带正文的提交
git commit -m "feat(web): add password reset

- Add password reset form
- Add email verification
- Update API client

Closes #123"
```

---

## PR 规范

### PR 流程

1. 创建分支并开发
2. 提交代码
3. 推送分支到远程
4. 创建 Pull Request
5. CI 检查
6. 代码审查
7. 修改（如果需要）
8. 合并

### PR 模板

```markdown
## 描述
简要描述这个 PR 的改动。

## 类型
- [ ] feat (新功能)
- [ ] fix (Bug 修复)
- [ ] docs (文档更新)
- [ ] style (代码格式)
- [ ] refactor (重构)
- [ ] perf (性能优化)
- [ ] test (测试)
- [ ] chore (构建/工具)

## 改动范围
- [ ] apps/web
- [ ] apps/admin
- [ ] services/api
- [ ] packages/ui
- [ ] packages/core
- [ ] packages/types
- [ ] packages/utils
- [ ] 其他: ___

## 测试
- [ ] 单元测试已添加/更新
- [ ] 集成测试已添加/更新
- [ ] E2E 测试已添加/更新
- [ ] 手动测试已完成

## 截图（如果适用）
添加 UI 变化的截图。

## 相关 Issue
Closes #123, #456

## 检查清单
- [ ] 代码符合项目规范
- [ ] 已添加必要的测试
- [ ] 文档已更新
- [ ] CI 检查通过
```

### 代码审查清单

审查者应该检查以下内容：

#### 功能正确性
- [ ] 代码实现了预期功能
- [ ] 边界情况已处理
- [ ] 错误处理正确

#### 代码质量
- [ ] 代码清晰易读
- [ ] 命名有意义
- [ ] 没有重复代码
- [ ] 复杂度适中

#### 性能
- [ ] 没有明显的性能问题
- [ ] 数据库查询优化
- [ ] 缓存使用合理

#### 安全
- [ ] 输入已验证
- [ ] 没有 SQL 注入风险
- [ ] 敏感数据已保护
- [ ] 权限控制正确

#### 测试
- [ ] 测试覆盖充分
- [ ] 测试可以通过
- [ ] 测试有意义

#### 文档
- [ ] 代码注释充分
- [ ] API 文档已更新
- [ ] 使用文档已更新

### 合并策略

- **Squash Merge**: 功能分支合并到 develop，保持提交历史整洁
- **Rebase Merge**: 保持线性历史
- **Merge Commit**: 保留完整提交历史（用于 main 分支）

```bash
# Squash 合并示例
git checkout develop
git merge --squash feature/user-authentication
git commit -m "feat(web): add user authentication"
```

---

## 最佳实践提示

### 开发工作流

1. **开始工作前**
   ```bash
   git checkout develop
   git pull origin develop
   ```

2. **创建分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **定期提交**
   ```bash
   git add .
   git commit -m "feat: your commit message"
   ```

4. **推送到远程**
   ```bash
   git push -u origin feature/your-feature-name
   ```

5. **创建 PR**
   - 在 GitHub/GitLab 上创建 PR
   - 填写 PR 模板
   - 请求审查

6. **更新分支**
   ```bash
   git checkout develop
   git pull origin develop
   git checkout feature/your-feature-name
   git rebase develop
   ```

### 避免常见错误

- ❌ 不要直接提交到 main 或 develop
- ❌ 不要提交大文件（使用 Git LFS）
- ❌ 不要提交敏感信息（API 密钥、密码等）
- ❌ 不要忽略测试失败
- ✅ 保持提交小而专注
- ✅ 写有意义的提交信息
- ✅ 及时更新文档

---

## 下一步

- [最佳实践](./best-practices.md) - 学习最佳实践
- [常见问题](./troubleshooting.md) - 查看常见问题
- [贡献指南](./contributing.md) - 了解如何贡献

---

> **文档维护**: 本文档由开发团队维护，如有问题或建议请提交 Issue。
> **最后更新**: 2026-05-25