RuoYi-Vue/docs/standards/java-coding-standards.md

# RuoYi-Vue Java 编码规范

## 1. 命名规范

### 1.1 类名
- 使用大驼峰命名（PascalCase）
- 示例：`SysUserController`、`AccountServiceImpl`

### 1.2 方法名
- 使用小驼峰命名（camelCase）
- 动词开头：`getUserList`、`addUser`、`deleteUser`

### 1.3 变量名
- 使用小驼峰命名
- 布尔类型使用 is/has/can 前缀：`isEnabled`、`hasPermission`

### 1.4 常量名
- 全大写，下划线分隔：`MAX_PAGE_SIZE`、`DEFAULT_STATUS`

### 1.5 包名
- 全小写，点分隔：`com.ruoyi.system.controller`

## 2. 注释规范

### 2.1 类注释
```java
/**
 * 用户管理 Controller
 * 
 * @author ruoyi
 * @since 2026-06-28
 */
@RestController
@RequestMapping("/system/user")
public class SysUserController extends BaseController {
```

### 2.2 方法注释
```java
/**
 * 查询用户列表
 * 
 * @param user 用户查询条件
 * @return 用户列表分页数据
 */
@ApiOperation("查询用户列表")
@GetMapping("/list")
public TableDataInfo list(SysUser user) {
    startPage();
    List<SysUser> list = userService.selectUserList(user);
    return getDataTable(list);
}
```

## 3. 代码格式

### 3.1 缩进
- 使用 4 个空格缩进
- 不使用 Tab

### 3.2 行长度
- 每行不超过 120 字符

### 3.3 空行
- 方法之间留 1 个空行
- 逻辑块之间留 1 个空行

## 4. 异常处理

### 4.1 业务异常
```java
if (user == null) {
    throw new ServiceException("用户不存在", HttpStatus.USER_NOT_FOUND);
}
```

### 4.2 不要吞没异常
```java
// ✗ 错误
try {
    // ...
} catch (Exception e) {
    // 空 catch
}

// ✓ 正确
try {
    // ...
} catch (Exception e) {
    log.error("操作失败: {}", e.getMessage(), e);
    throw new ServiceException("操作失败");
}
```

## 5. 事务管理

### 5.1 事务注解
```java
@Transactional(rollbackFor = Exception.class)
public void addUser(SysUser user) {
    // ...
}
```

## 6. 最佳实践

- 使用 `@Autowired` 构造器注入
- 优先使用 `final` 修饰不可变字段
- 避免魔法数字，使用常量
- 方法不超过 50 行
- 类不超过 500 行