跳到主要内容Java 项目全局配置规则 (Always Apply) | 极客日志JavaAIjava
Java 项目全局配置规则 (Always Apply)
综述由AI生成档定义了 Java 项目的全局编码规范与最佳实践,涵盖命名、Spring Boot 架构、异常处理、日志、数据库、性能、安全、设计原则、Git 及文档维护。旨在统一开发标准,提升代码质量与可维护性,适用于 Cursor AI 全局配置参考。
RustyLab21 浏览 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,说明类的用途、作者、日期
- 方法注释: 使用 JavaDoc,说明方法用途、参数、返回值、异常
- 复杂逻辑: 使用单行或多行注释说明业务逻辑
- 避免无意义的注释,代码应自解释
Spring Boot 项目规范
项目结构
src/main/java/com/example/project/
├── controller/
├── service/
│ └── impl/
├── mapper/
├── entity/
├── dto/
├── vo/
├── config/
├── exception/
├── util/
└── constant/
分层架构
- Controller 层: 只负责接收请求、参数校验、调用 Service、返回响应
- Service 层: 处理业务逻辑,不直接操作数据库
- Mapper 层: 只负责数据库操作,不包含业务逻辑
- 避免跨层调用,Controller 不直接调用 Mapper
依赖注入
- 优先使用构造器注入,避免使用
@Autowired 字段注入
private final UserService userService;
public UserController(UserService userService) {
this.userService = userService;
}
@Autowired
private UserService userService;
RESTful API 规范
- 使用标准 HTTP 方法:GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)
- URL 使用小写,多个单词用连字符分隔:
/api/user-orders
- 使用复数形式:
/api/users 而非 /api/user
- 版本控制:
/api/v1/users
- 统一返回格式:
{
"code": 200,
"message": "success",
"data": {...}
}
异常处理
异常分类
- 使用自定义业务异常继承
RuntimeException
- 创建全局异常处理器
@ControllerAdvice
- 不要捕获后不处理或只打印日志
异常处理示例
@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("系统异常"));
}
}
日志规范
日志级别
- ERROR: 系统错误,需要立即处理
- WARN: 警告信息,可能存在问题
- INFO: 关键业务流程信息
- DEBUG: 调试信息,生产环境关闭
日志使用
- 使用 SLF4J + Logback
- 使用占位符而非字符串拼接:
log.info("用户 ID: {}", userId)
- 异常日志必须包含堆栈信息:
log.error("处理失败", e)
- 避免在循环中打印日志
- 日志中不包含敏感信息(密码、身份证、银行卡等)
- 生产环境日志级别设置为 INFO,开发环境可以使用 DEBUG
日志最佳实践
log.info("用户 {} 执行了 {} 操作", username, operation);
log.info("用户 " + username + " 执行了 " + operation + " 操作");
if (log.isDebugEnabled()) {
log.debug("详细信息:{}", expensiveOperation());
}
log.error("处理订单失败,订单 ID: {}", orderId, e);
log.error("处理订单失败:" + e.getMessage());
数据库规范
MyBatis 使用
- 优先使用注解方式,复杂 SQL 使用 XML
- 避免使用
SELECT *,明确指定字段
- 使用
#{} 防止 SQL 注入,避免使用 ${}
- 分页查询使用 PageHelper
事务管理
- Service 层方法添加
@Transactional 注解
- 只读操作使用
@Transactional(readOnly = true)
- 注意事务传播行为和隔离级别
性能优化
通用原则
- 避免 N+1 查询问题
- 合理使用缓存(Redis)
- 大数据量操作使用分页
- 异步处理耗时操作
- 使用连接池管理数据库连接
代码优化
- 使用 Stream API 处理集合,但注意性能(小数据量时 for 循环可能更快)
- 避免在循环中进行数据库操作(使用批量查询)
- 合理使用线程池,不要频繁创建线程
- 及时关闭资源,使用 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<>();
- 选择合适的集合类型
- 需要快速随机访问:
ArrayList
- 频繁插入删除:
LinkedList
- 不允许重复:
HashSet
- 需要排序:
TreeSet 或 TreeMap
- 线程安全:
ConcurrentHashMap
空值处理
public Optional<User> findUserById(Long id) {
User user = userMapper.selectById(id);
return Optional.ofNullable(user);
}
public List<User> listUsers() {
List<User> users = userMapper.selectAll();
return users != null ? users : Collections.emptyList();
}
public List<User> listUsers() {
return userMapper.selectAll();
}
安全规范
OWASP Top 10 防护
- SQL 注入防护: 使用参数化查询(
#{}),避免字符串拼接 SQL
- XSS 防护: 对用户输入进行 HTML 转义,使用
@JsonIgnore 防止敏感信息泄露
- CSRF 防护: 使用 Spring Security 的 CSRF Token
- 认证和授权: 使用 Spring Security 或 Shiro 进行权限控制
- 敏感数据加密: 密码使用 BCrypt,身份证等使用 AES 加密
输入验证
- 所有用户输入必须校验: 前端校验 + 后端校验(双重保障)
- 白名单验证: 优先使用白名单而非黑名单
private static final Set<String> ALLOWED_TYPES = Set.of("image/jpeg", "image/png", "image/gif");
if (!ALLOWED_TYPES.contains(file.getContentType())) {
throw new BusinessException("不支持的文件类型");
}
数据校验
- 使用
@Valid 和 @Validated 进行参数校验
- 在 DTO 中使用 JSR-303 注解:
@NotNull, @NotBlank, @Size 等
@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;
}
API 安全
- 使用 HTTPS: 生产环境必须使用 HTTPS
- 限流防刷: 使用 Redis + AOP 实现接口限流
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
int limit() default 10;
}
- Token 管理: JWT Token 设置合理的过期时间(如 2 小时)
- 重要操作记录: 登录、修改密码、删除数据等操作记录操作日志
文件上传安全
- 限制文件类型: 白名单验证文件类型
- 限制文件大小: 防止大文件攻击
- 文件名处理: 使用 UUID 重命名,防止路径遍历攻击
public String uploadFile(MultipartFile file) {
String contentType = file.getContentType();
if (!ALLOWED_TYPES.contains(contentType)) {
throw new BusinessException("不支持的文件类型");
}
if (file.getSize() > 5 * 1024 * 1024) {
throw new BusinessException("文件大小不能超过 5MB");
}
String originalFilename = file.getOriginalFilename();
String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
String newFilename = UUID.randomUUID().toString() + extension;
return saveFile(file, newFilename);
}
代码质量
SOLID 设计原则
- 单一职责原则 (SRP): 一个类只负责一项职责,避免类的功能过于复杂
public class UserService {
public void saveUser(User user) {}
public void sendEmail(String email) {}
public void generateReport() {}
}
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) {}
}
- 里氏替换原则 (LSP): 子类可以替换父类且不影响程序正确性
- 接口隔离原则 (ISP): 客户端不应依赖它不需要的接口
- 依赖倒置原则 (DIP): 依赖于抽象而不是具体实现
代码质量工具
- Checkstyle: 检查代码风格和编码规范
- PMD: 检测代码中的潜在问题(未使用的变量、空的 catch 块等)
- SpotBugs: 静态分析工具,查找代码中的 bug
- SonarQube: 代码质量管理平台,提供全面的代码分析
基本要求
- 方法长度不超过 50 行(理想情况 20-30 行)
- 方法参数不超过 5 个(超过时考虑使用对象封装)
- 圈复杂度不超过 10
- 避免重复代码(DRY 原则),提取公共方法
- 使用设计模式解决常见问题
- 避免深层嵌套(不超过 3 层)
- 类的大小不超过 500 行
命名最佳实践
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() {}
代码审查
- 提交前自我审查代码
- 确保代码可读性和可维护性
- 添加必要的单元测试(测试覆盖率 > 80%)
- 确保没有警告和错误
- 使用代码审查工具(如 SonarQube)
- 团队 Code Review,至少一人审核
版本控制
Git 规范
- Commit 信息规范 (Conventional Commits):
feat: 新功能 - feat: 添加用户登录功能
fix: 修复 Bug - fix: 修复用户无法登出的问题
docs: 文档更新 - docs: 更新 API 文档
style: 代码格式调整(不影响功能) - style: 格式化代码
refactor: 重构(不增加功能也不修复 Bug) - refactor: 重构用户服务层
perf: 性能优化 - perf: 优化查询性能
test: 测试相关 - test: 添加用户服务单元测试
chore: 构建过程或辅助工具的变动 - chore: 更新依赖版本
Git 分支管理
- 主分支 (main/master): 生产环境代码,只接受合并请求
- 开发分支 (develop): 开发环境代码
- 功能分支 (feature/xxx): 新功能开发
- 修复分支 (hotfix/xxx): 紧急修复
- 发布分支 (release/xxx): 发布准备
Git 最佳实践
- 避免提交敏感信息(密码、密钥、Token 等)
- 使用
.gitignore 忽略不必要的文件
- 提交前进行代码审查和测试
- 定期同步主分支代码,避免冲突
- 小步提交,每次提交只做一件事
- 使用有意义的分支名称:
feature/user-login、fix/order-bug
代码审查清单
- 代码是否符合编码规范
- 是否有明显的 Bug 或逻辑错误
- 是否有安全隐患
- 是否有性能问题
- 是否有充分的单元测试
- 是否有必要的注释和文档
- 是否有代码重复
- 是否考虑了边界情况和异常处理
项目文档规范
核心文档要求
项目必须维护一份核心架构文档,用于描述项目的整体框架和功能模块,确保团队成员和 AI 辅助工具能够快速理解项目结构。
文档创建
- 文档位置: 项目根目录
- 文档名称:
项目框架和功能.md 或 项目功能模块分析.md
- 强制性: 该文档为项目必备文件,与
README.md 同等重要
文档内容规范
- 项目概述
- 项目名称、简介、主要功能
- 技术栈(Spring Boot、MyBatis、Redis 等)
- 项目定位与业务领域
- 项目架构
- 整体架构设计(分层架构、微服务等)
- 模块划分与职责说明
- 核心目录结构说明
示例: biz/
└── module/
common/
runner/
- 核心功能模块
- 列出所有主要功能模块
- 每个模块的职责描述
- 模块间的依赖关系
- 关键业务流程说明
- 数据库设计
- 技术要点
- 使用的关键技术或框架
- 特殊的技术实现方案
- 性能优化措施
- API 接口概览
文档初始化
- 分析代码库: 深入分析现有代码结构、包结构、类命名规范
- 识别模块: 识别所有功能模块(通过 controller、service、entity 等)
- 梳理架构: 理解项目的分层架构和技术栈
- 生成文档: 基于分析结果生成初始版本文档
- 审核完善: 与团队一起审核并完善文档内容
文档使用规范
开发前必读
- 新成员入职: 第一时间阅读该文档,了解项目全貌
- 开始新功能: 开发任何新功能前,先查阅文档了解相关模块
- Bug 修复: 修复 Bug 前,通过文档定位相关模块和依赖
- AI 辅助开发: AI 工具在接手任务前,应首先读取该文档理解项目架构
文档优先原则
工作流程:
1. 阅读项目文档 → 了解整体架构
2. 定位相关模块 → 查看具体代码
3. 理解业务逻辑 → 开始开发
4. 完成开发 → 更新文档(如有变更)
文档维护规范
必须同步更新的场景
- 架构变更
- 新增、删除或重命名模块
- 调整目录结构
- 修改分层架构设计
- 引入新的技术栈或框架
- 功能变更
- 数据库变更
- API 变更
更新流程
代码变更 → 同步更新文档 → Code Review 时检查文档 → 提交代码和文档
- ❌ 只修改代码,不更新文档
- ❌ 等到项目结束再统一更新文档
- ❌ 文档与代码不一致
- ✅ 代码和文档在同一个 Commit 中提交
- ✅ 使用 Git Commit 信息说明文档变更:
feat: 添加用户模块 + 更新项目文档
- ✅ Code Review 时同时审查代码和文档的一致性
文档地位与重要性
基础性文件
- 该文档是理解项目的第一入口
- 与
README.md 和 pom.xml 同等重要
- 文档缺失或过期将严重影响开发效率
质量要求
- 准确性: 文档内容必须与代码实现保持一致
- 时效性: 文档必须实时反映当前项目状态
- 完整性: 涵盖所有核心模块和功能
- 可读性: 结构清晰,易于理解
文档审查
在 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 进行身份认证
...
最佳实践
- 保持简洁: 文档应聚焦架构和模块,避免过度详细的代码级说明
- 定期审查: 每个迭代结束后,审查文档是否需要更新
- 版本管理: 文档纳入 Git 版本控制,保留变更历史
- 团队共识: 团队达成共识,将文档维护作为开发流程的一部分
- 工具辅助: 可以使用 AI 工具辅助生成和更新文档,但需人工审核
相关免费在线工具
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online