Java 项目全局配置规则 (Always Apply) | 极客日志

JavaAIjava

Java 项目全局配置规则 (Always Apply)

综述由AI生成档定义了 Java 项目的全局编码规范与最佳实践，涵盖命名、Spring Boot 架构、异常处理、日志、数据库、性能、安全、设计原则、Git 及文档维护。旨在统一开发标准，提升代码质量与可维护性，适用于 Cursor AI 全局配置参考。

RustyLab发布于 2026/3/24更新于 2026/5/721 浏览

Java 项目全局配置规则 (Always Apply)

alwaysApply: true

Java 项目全局规则 (Always Apply)

编码规范

命名规范

类名: 使用 PascalCase（大驼峰），如 UserService, OrderController
方法名: 使用 camelCase（小驼峰），如 getUserById, processOrder
变量名: 使用 camelCase，如 userName, orderList
常量名: 使用 UPPER_SNAKE_CASE，如 MAX_SIZE, DEFAULT_TIMEOUT
包名: 全小写，使用点分隔，如 com.example.project.service
接口名: 不使用 I 前缀，直接使用有意义的名称，如 UserService 而非 IUserService
实现类: 可使用 Impl 后缀，如 UserServiceImpl

代码风格

使用 4 个空格缩进，不使用 Tab
左大括号不换行，右大括号独占一行
方法之间空一行
逻辑块之间适当空行以提高可读性
每行代码不超过 120 字符
import 语句按字母顺序排列，不使用通配符 *

注释规范

类注释: 使用 JavaDoc，说明类的用途、作者、日期

/**
 * 用户服务类
 *
 * @author 作者名
 * @date 2025-12-09
 */

方法注释: 使用 JavaDoc，说明方法用途、参数、返回值、异常

/**
 * 根据用户 ID 获取用户信息
 *
 * @param userId 用户 ID
 * @return 用户信息
 * @throws UserNotFoundException 用户不存在时抛出
 */

复杂逻辑: 使用单行或多行注释说明业务逻辑
避免无意义的注释，代码应自解释

Spring Boot 项目规范

项目结构

src/main/java/com/example/project/
├── controller/ # 控制器层
├── service/ # 服务层
│   └── impl/ # 服务实现
├── mapper/ # 数据访问层（MyBatis）
├── entity/ 
├── dto/ 
├── vo/ 
├── config/ 
├── exception/ 
├── util/ 
└── constant/

// 推荐
private final UserService userService;
public UserController(UserService userService) {
    this.userService = userService;
}

// 不推荐
@Autowired
private UserService userService;

{
  "code": 200,
  "message": "success",
  "data": {...}
}

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<Result> handleBusinessException(BusinessException e) {
        return ResponseEntity.ok(Result.error(e.getMessage()));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Result> handleException(Exception e) {
        log.error("系统异常", e);
        return ResponseEntity.ok(Result.error("系统异常"));
    }
}

// 推荐：使用占位符
log.info("用户 {} 执行了 {} 操作", username, operation);

// 不推荐：字符串拼接
log.info("用户 " + username + " 执行了 " + operation + " 操作");

// 推荐：条件日志
if (log.isDebugEnabled()) {
    log.debug("详细信息：{}", expensiveOperation());
}

// 推荐：异常日志包含堆栈
log.error("处理订单失败，订单 ID: {}", orderId, e);

// 不推荐：只记录异常消息
log.error("处理订单失败：" + e.getMessage());

// 推荐：try-with-resources 自动关闭资源
try (InputStream is = new FileInputStream("file.txt");
     BufferedReader reader = new BufferedReader(new InputStreamReader(is))) {
    String line = reader.readLine();
}

// 不推荐：手动关闭资源
InputStream is = null;
try {
    is = new FileInputStream("file.txt");
} finally {
    if (is != null) {
        is.close();
    }
}

// 推荐：已知大小时指定初始容量
List<String> list = new ArrayList<>(100);
Map<String, Object> map = new HashMap<>(16);

// 不推荐：使用默认容量
List<String> list = new ArrayList<>();

// 推荐
public Optional<User> findUserById(Long id) {
    User user = userMapper.selectById(id);
    return Optional.ofNullable(user);
}
// 使用 userService.findUserById(1L).map(User::getUsername).orElse("匿名用户");

// 推荐
public List<User> listUsers() {
    List<User> users = userMapper.selectAll();
    return users != null ? users : Collections.emptyList();
}

// 不推荐
public List<User> listUsers() {
    return userMapper.selectAll(); // 可能返回 null
}

// 推荐：白名单验证
private static final Set<String> ALLOWED_TYPES = Set.of("image/jpeg", "image/png", "image/gif");
if (!ALLOWED_TYPES.contains(file.getContentType())) {
    throw new BusinessException("不支持的文件类型");
}

@Data
public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    @Pattern(regexp = "^[a-zA-Z0-9_]{4,20}$", message = "用户名只能包含字母、数字和下划线，长度 4-20")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 8, max = 20, message = "密码长度必须在 8-20 之间")
    private String password;
}

@Service
public class PasswordService {
    private final BCryptPasswordEncoder encoder = new BCryptPasswordEncoder();

    public String encodePassword(String rawPassword) {
        return encoder.encode(rawPassword);
    }

    public boolean matches(String rawPassword, String encodedPassword) {
        return encoder.matches(rawPassword, encodedPassword);
    }
}

log.info("用户登录：username={}", username); // 正确
log.info("用户登录：password={}", password); // 错误！不要记录密码

@Data
public class UserVO {
    private Long id;
    private String username;
    // 不包含 password 字段
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
    int limit() default 10; // 每分钟最多请求次数
}

public String uploadFile(MultipartFile file) {
    // 1. 验证文件类型
    String contentType = file.getContentType();
    if (!ALLOWED_TYPES.contains(contentType)) {
        throw new BusinessException("不支持的文件类型");
    }
    // 2. 验证文件大小（5MB）
    if (file.getSize() > 5 * 1024 * 1024) {
        throw new BusinessException("文件大小不能超过 5MB");
    }
    // 3. 使用 UUID 重命名
    String originalFilename = file.getOriginalFilename();
    String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
    String newFilename = UUID.randomUUID().toString() + extension;
    // 4. 保存文件
    return saveFile(file, newFilename);
}

// 不推荐：一个类承担多个职责
public class UserService {
    public void saveUser(User user) {}
    public void sendEmail(String email) {} // 应该独立为 EmailService
    public void generateReport() {} // 应该独立为 ReportService
}

// 推荐：职责分离
public class UserService {
    public void saveUser(User user) {}
}
public class EmailService {
    public void sendEmail(String email) {}
}

// 使用接口和多态实现扩展
public interface PaymentStrategy {
    void pay(BigDecimal amount);
}
public class AlipayPayment implements PaymentStrategy {
    public void pay(BigDecimal amount) {}
}
public class WechatPayment implements PaymentStrategy {
    public void pay(BigDecimal amount) {}
}

// 不推荐
int d; // 经过的天数

// 推荐
int daysSinceCreation;
int daysSinceModification;

// 不推荐
if (status == 1) {}

// 推荐
private static final int STATUS_ACTIVE = 1;
if (status == STATUS_ACTIVE) {}

// 不推荐
public void process() {}

// 推荐
public void sendEmailToUser() {}
public void calculateTotalPrice() {}

示例： biz/ # 业务逻辑模块
└── module/ # 各业务子模块
common/ # 公共组件模块
runner/ # 应用启动模块

工作流程：
1. 阅读项目文档 → 了解整体架构
2. 定位相关模块 → 查看具体代码
3. 理解业务逻辑 → 开始开发
4. 完成开发 → 更新文档（如有变更）

代码变更 → 同步更新文档 → Code Review 时检查文档 → 提交代码和文档

# 项目框架和功能
## 项目概述
项目名称：XXX 系统
技术栈：Spring Boot 2.x + MyBatis + MySQL + Redis
项目简介：...
## 项目架构
### 整体架构
三层架构：Controller → Service → Mapper
### 模块划分
- biz: 核心业务模块
- common: 公共组件
- runner: 应用启动
## 核心功能模块
### 1. 用户管理模块
- 位置：biz/module/user
- 功能：用户注册、登录、权限管理
- 核心类：UserController, UserService
### 2. 订单管理模块
...
## 数据库设计
### 核心表
- user: 用户表
- order: 订单表
...
## 技术要点
- 使用 Redis 实现分布式缓存
- 使用 JWT 进行身份认证
...