# 编码规范

## 🎯 通用原则

1. **可读性优先** - 代码是写给人看的，顺便给机器执行
2. **DRY 原则** - Don't Repeat Yourself
3. **单一职责** - 一个类/方法只做一件事
4. **开闭原则** - 对扩展开放，对修改关闭

---

## 📝 Java 编码规范

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 类名 | 大驼峰 | `UserService`, `OrderController` |
| 方法名 | 小驼峰 | `getUserById()`, `createOrder()` |
| 变量名 | 小驼峰 | `userName`, `orderList` |
| 常量 | 全大写下划线 | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
| 包名 | 全小写 | `com.rui.service.user` |

### 代码格式

```java
// 正确的类定义
@Service
public class UserServiceImpl implements IUserService {
    
    private final UserMapper userMapper;
    private final RedisUtil redisUtil;
    
    // 构造器注入（推荐）
    public UserServiceImpl(UserMapper userMapper, RedisUtil redisUtil) {
        this.userMapper = userMapper;
        this.redisUtil = redisUtil;
    }
    
    // 方法注释
    /**
     * 根据ID获取用户信息
     * @param userId 用户ID
     * @return 用户信息
     */
    @Override
    public UserDTO getUserById(Long userId) {
        // 先查缓存
        UserDTO user = redisUtil.get("user:" + userId);
        if (user != null) {
            return user;
        }
        
        // 再查数据库
        User entity = userMapper.selectById(userId);
        if (entity == null) {
            throw new BizException("用户不存在");
        }
        
        // 转换并缓存
        user = convertToDTO(entity);
        redisUtil.set("user:" + userId, user, 3600);
        
        return user;
    }
}
```

### 注释规范

```java
/**
 * 用户服务实现类
 * 
 * @author pigeon
 * @since 2024-01-01
 */
@Service
public class UserServiceImpl {
    
    /**
     * 获取用户详情
     * 
     * @param userId 用户ID，不能为空
     * @return 用户详情DTO
     * @throws BizException 用户不存在时抛出
     */
    public UserDetailDTO getDetail(Long userId) {
        // ...
    }
}
```

---

## 🌐 TypeScript/Vue 编码规范

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 组件名 | 大驼峰 | `UserTable.vue`, `OrderForm.vue` |
| 组合式函数 | use前缀 | `useUser()`, `useOrder()` |
| 类型定义 | 大驼峰 | `UserDTO`, `OrderFormData` |
| 常量 | 全大写下划线 | `API_BASE_URL`, `PAGE_SIZE` |
| 变量/函数 | 小驼峰 | `userList`, `getUserList()` |

### 组件规范

```vue
<script setup lang="ts">
/**
 * 用户管理组件
 * 
 * @description 展示用户列表，支持增删改查
 * @author pigeon
 */
import { ref, onMounted } from 'vue'
import type { UserDTO } from '@/types'

// Props 定义
interface Props {
  deptId?: number
}

const props = withDefaults(defineProps<Props>(), {
  deptId: undefined
})

// Emits 定义
const emit = defineEmits<{
  refresh: []
}>()

// 响应式数据
const userList = ref<UserDTO[]>([])
const loading = ref(false)

// 方法
async function loadUserList() {
  loading.value = true
  try {
    const res = await userApi.getList({ deptId: props.deptId })
    userList.value = res.data
  } finally {
    loading.value = false
  }
}

// 生命周期
onMounted(() => {
  loadUserList()
})
</script>
```

---

## 🗄️ 数据库规范

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 表名 | 下划线、复数 | `sys_user`, `cashier_order` |
| 字段名 | 下划线 | `user_name`, `created_at` |
| 索引名 | idx_前缀 | `idx_user_name` |
| 外键 | fk_前缀 | `fk_order_user` |

### 必备字段

```sql
-- 所有表必须包含以下字段
CREATE TABLE example_table (
    id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
    -- 业务字段
    name VARCHAR(100) NOT NULL COMMENT '名称',
    
    -- 审计字段（由框架自动填充）
    create_by VARCHAR(64) COMMENT '创建者',
    create_time DATETIME COMMENT '创建时间',
    update_by VARCHAR(64) COMMENT '更新者',
    update_time DATETIME COMMENT '更新时间',
    deleted TINYINT DEFAULT 0 COMMENT '删除标志（0-正常，1-删除）',
    tenant_id BIGINT COMMENT '租户ID',
    
    -- 索引
    INDEX idx_name (name)
) COMMENT='示例表';
```

### MyBatis Plus 查询规范

**优先使用 `LambdaQueryWrapper`，避免使用字符串字段名的 `QueryWrapper`。**

```java
// ❌ 错误示例：使用字符串字段名，容易拼写错误，重构时容易遗漏
new QueryWrapper<User>().eq("user_name", username)
                       .like("phone", phone);

// ✅ 正确示例：使用 LambdaQueryWrapper，类型安全，重构友好
new LambdaQueryWrapper<User>()
    .eq(User::getUserName, username)
    .like(User::getPhone, phone);
```

**优势：**
- **类型安全**：编译期检查，字段不存在会报错
- **防误写**：避免字符串拼写错误
- **重构友好**：IDE 重构时自动更新引用
- **可读性**：直接看到实体字段，更清晰

---

## 🔒 安全规范

1. **SQL 注入防护** - 使用 MyBatis 参数绑定，禁止字符串拼接 SQL
2. **XSS 防护** - 前端转义输出，后端校验输入
3. **敏感信息** - 密码必须加密存储，日志中禁止输出敏感信息
4. **接口鉴权** - 所有接口必须校验权限（白名单除外）

---

## 🧪 测试规范

### Java 测试

```java
@SpringBootTest
class UserServiceTest {
    
    @Autowired
    private IUserService userService;
    
    @Test
    @DisplayName("根据ID查询用户-正常情况")
    void getUserById_Success() {
        // Given
        Long userId = 1L;
        
        // When
        UserDTO user = userService.getUserById(userId);
        
        // Then
        assertThat(user).isNotNull();
        assertThat(user.getId()).isEqualTo(userId);
    }
    
    @Test
    @DisplayName("根据ID查询用户-用户不存在")
    void getUserById_NotFound() {
        // Given
        Long userId = 999L;
        
        // Then
        assertThrows(BizException.class, () -> {
            userService.getUserById(userId);
        });
    }
}
```

---

## 📝 Git 提交规范

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

<body>

<footer>
```

### Type 类型

| 类型 | 说明 |
|------|------|
| feat | 新功能 |
| fix | 修复 bug |
| docs | 文档更新 |
| style | 代码格式（不影响功能） |
| refactor | 重构 |
| test | 测试相关 |
| chore | 构建/工具相关 |

### 示例

```bash
feat(cashier): 添加订单退款功能

- 支持部分退款
- 支持原路退回
- 添加退款记录表

Closes #123
```

---

> **最后提醒**：编码规范是为了团队协作，请务必遵守！