Java 开发规范，包含命名约定、异常处理、Spring Boot 最佳实践等

Java 开发规范参考来源: Google Java Style Guide、阿里巴巴 Java 开发手册工具链命名约定类型规则示例包名全小写，域名反转 com.example.project 类名大驼峰，名词/名词短语 UserService , HttpClient 方法名小驼峰，动词开头 findById , isValid 常量全大写下划线分隔 MAX RETRY COUNT 布尔返回值 is/has/can 前缀 isActive() , hasPermission() 类成员顺序 DTO/VO 类规范规则说明 ❌ 禁止手写 getter/setter DTO、VO、Request、Response 类一律使用 Lombok ✅ 使用 @Data 普通 DTO ✅ 使用 @Value 不可变 DTO ✅ 使用 @Builder 字段较多时配合使用 ⚠️ Entity 类慎用 @Data JPA Entity 的 equals/hashCode 会影响 Hibernate 代理批量查询规范规则说明 ❌ 禁止 IN 子句超过 500 个参数 SQL 解析开销大，执行计划不稳定 ✅ 超过时分批查询每批 500，合并结果 ✅ 封装通用工具方法避免每处手写分批逻辑 N+1 查询防范规则说明 ❌ 禁止循环内调用 Repository/Mapper stream/forEach/for 内每次迭代触发一次查询 ✅ 循环外批量查询，结果转 Map 查询次数从 N 降为 1（或 distinct 数）常见 N+1 场景及修复模式：场景循环内（❌）循环外（✅） count repo.countByXxx(id) repo.countByXxxIn(ids) → Map<id, count findById repo.findById(id) repo.findByIdIn(ids) → Map<id, entity exists repo.existsByXxx(id) repo.findXxxIn(ids) → Set<id + set.contains() 并发安全规范规则说明 ❌ 禁止 read modify write 先读余额再写回，并发下丢失更新 ❌ 禁止 check then act 无兜底先检查再操作，并发下条件失效 ✅ 使用原子更新 SQL UPDATE SET balance = balance + :delta WHERE id = :id ✅ 或使用乐观锁 @Version 字段 + 重试机制 ✅ 唯一索引兜底防重复插入的最后防线异常处理空值处理并发编程测试规范 (JUnit 5) Spring Boot 规范 Auth Filter 降级原则规则说明 ✅ optional auth 路径遇到无效/过期/不完整 token 时降级为匿名访问不应返回 401/403 ❌ 禁止部分凭证用户体验差于匿名用户如：临时 token 在公开接口返回 403 循环依赖防范（Spring Boot 3.x） Spring Boot 3.x 默认禁止构造器循环依赖。从大 Service 拆分子 Service 时必须检查依赖方向。处理方式优先级适用场景提取公共方法到独立工具类 ✅ 首选纯工具方法（如 resolveTenantIds） @Lazy 字段注入 ⚠️ 应急确实需要双向调用 Function< 回调 ⚠️ 备选灵活但增加复杂度详见 refactor safety skill 陷阱 5 分页参数规范（Spring Data JPA） Spring Data JPA 分页索引从 0 开始。重构分页参数时必须确保前后端索引基准一致。规则说明全栈统一 0 based 前端、Controller、Service、JPA 全部使用 0 based 索引 Controller 默认值必须是 0 @RequestParam(defaultValue = "0") int page Service 直接使用 page PageRequest.of(page, size) ，不要 page 1 重构检查清单： [ ] 前端调用传递 page: 0 （第 1 页） [ ] Controller 默认值是 0 [ ] Service 使用 PageRequest.of(page, size) （不减 1） [ ] 测试 page=0 和 page=1 都能正常返回数据输入校验规范规则说明 ❌ 禁止 @RequestBody 不加 @Valid 所有请求体必须校验 ✅ DTO 字段加约束注解 @NotBlank 、 @Size 、 @Pattern 等 ✅ 数值字段加范围约束 @Min 、 @Max 、 @Positive 等 ✅ 分页参数加上限 size 必须 @Max(100) 防止大量查询 ✅ 枚举/状态字段白名单校验自定义校验器或 @Pattern 常见 DTO 字段校验速查：字段类型必须注解说明数量 quantity @NotNull @Min(1) 防止 0 或负数（负数可导致反向操作）金额 amount/price @NotNull @Positive 或 @DecimalMin("0.01") 分页 size @Min(1) @Max(100) 防止 size=999999 拖垮数据库分页 page @Min(1) 页码从 1 开始百分比 rate @Min(0) @Max(100) 视业务定义范围性能优化陷阱解决方案 N+1 查询见「N+1 查询防范」章节循环拼接字符串使用 StringBuilder 频繁装箱拆箱使用原始类型流未指定集合初始容量 new ArrayList< (size) 第三方 API HTTP 客户端选型规则说明 ❌ 避免 RestTemplate 默认客户端调用国内平台 API 默认 HttpURLConnection 的 POST 请求与微信/支付宝等 CDN 存在兼容性问题（已知触发 412/403） ✅ 优先用 java.net.http.HttpClient （JDK 11+）现代 HTTP 客户端，无 CDN 兼容性问题 ✅ 或配置 HttpComponentsClientHttpRequestFactory 让 RestTemplate 底层走 Apache HttpClient 诊断特征：HTTP 错误 + body 为空 + response headers 极简（只有 Connection/Content Length）= CDN 层拦截，不是 API 本身的响应。同一 API 的 GET 正常但 POST 异常时，优先怀疑 HTTP 客户端兼容性。 Native SQL 规范别名避免 MySQL 保留字 @Query(nativeQuery = true) 中的列别名如果是 MySQL 保留字，会导致语法错误。高频踩坑保留字： year month , order , status , key , value , name , type , date , time , rank , range , rows , column , user , role , group 规则说明 ✅ 使用短别名或缩写 ym , ord status , cnt ✅ 或用反引号转义 year month ❌ 禁止直接用保留字做别名 as year month 、 as order 、 as rank 日志规范详细参考文件内容 references/java style.md 命名约定、异常处理、Spring Boot、测试规范 references/collections.md 不可变集合（Guava）、字符串分割 references/concurrency.md 线程池配置、CompletableFuture 超时 references/concurrency db patterns.md Get Or Create 并发、N+1 防范、原子更新、Redis+DB 一致性 references/code patterns.md 卫语句、枚举优化、策略工厂模式 references/date time.md 日期加减、账期计算、禁止月末对齐 references/http client.md 第三方 API HTTP 客户端选型、CDN 兼容性问题 📋 本回复遵循： java dev [具体章节]

java-dev