SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场java-dev

java-dev

编程与开发

查看项目

更新于 10-15 18:26

技能介绍

用途

本技能是一套 Java 开发规范集合，用于统一后端代码风格、规避常见并发与性能陷阱，并给出 Spring Boot 场景下的最佳实践。参考来源为 Google Java Style Guide 与阿里巴巴 Java 开发手册。

主要能力

工具链命令

Maven：

mvn clean compile                    # 编译
mvn test                             # 运行测试
mvn verify                           # 运行所有检查

Gradle：

./gradlew build                      # 构建
./gradlew test                       # 运行测试

命名约定

  • 包名：全小写，域名反转，如 com.example.project
  • 类名：大驼峰，名词/名词短语，如 UserService、HttpClient
  • 方法名：小驼峰，动词开头，如 findById、isValid
  • 常量：全大写下划线分隔，如 MAX_RETRY_COUNT
  • 布尔返回值：is/has/can 前缀，如 isActive()、hasPermission()

类成员顺序为：静态常量、静态变量、实例变量、构造函数、静态方法、实例方法（公共 → 私有）、getter/setter（或使用 Lombok）。

DTO/VO 类规范

  • DTO、VO、Request、Response 类一律使用 Lombok，禁止手写 getter/setter
  • 普通 DTO 使用 @Data，不可变 DTO 使用 @Value，字段较多时配合 @Builder
  • JPA Entity 慎用 @Data，因为 equals/hashCode 会影响 Hibernate 代理

批量查询规范

  • 禁止 IN 子句超过 500 个参数，超过时分批查询（每批 500，合并结果）
  • 建议封装通用分批工具方法，避免每处手写分批逻辑

N+1 查询防范

  • 禁止在循环内调用 Repository/Mapper
  • 应在循环外批量查询，结果转 Map，将查询次数从 N 降为 1
  • 常见场景修复模式：count 用 countByXxxIn → Map；findById 用 findByIdIn → Map；exists 用 findXxxIn → Set + contains

并发安全规范

  • 禁止 read-modify-write（先读余额再写回，并发下丢失更新）
  • 禁止无兜底的 check-then-act
  • 使用原子更新 SQL（UPDATE SET balance = balance + :delta WHERE id = :id）或乐观锁（@Version + 重试）
  • 唯一索引作为防重复插入的最后防线

异常处理与空值处理

  • 捕获具体异常并添加上下文，避免捕获过宽
  • 使用 try-with-resources 自动关闭资源
  • 使用 Optional、Objects.requireNonNull 进行空值处理

并发编程

  • 使用 ExecutorService 或 CompletableFuture，避免直接 new Thread

测试规范（JUnit 5）

采用 given/when/then 结构，使用 @DisplayName 描述测试意图。

Spring Boot 规范

  • 使用构造函数注入（@RequiredArgsConstructor）
  • REST Controller 使用 @RestController + @RequestMapping
  • Auth Filter 降级原则：optional-auth 路径遇到无效/过期/不完整 token 时降级为匿名访问，不应返回 401/403
  • 循环依赖防范（Spring Boot 3.x 默认禁止构造器循环依赖）：首选提取公共方法到独立工具类，@Lazy 字段注入为应急，Function<> 回调为备选

分页参数规范（Spring Data JPA）

  • 全栈统一 0-based 索引
  • Controller 默认值必须是 0
  • Service 直接使用 PageRequest.of(page, size)，不要 page - 1
  • 重构检查清单：前端传 page: 0、Controller 默认值 0、Service 不减 1、测试 page=0 和 page=1

输入校验规范

  • 禁止 @RequestBody 不加 @Valid
  • DTO 字段加约束注解（@NotBlank、@Size、@Pattern 等）
  • 数值字段加范围约束（@Min、@Max、@Positive 等）
  • 分页 size 必须 @Max(100)
  • 枚举/状态字段白名单校验
  • 常见字段：quantity 用 @NotNull @Min(1)；金额用 @NotNull @Positive；分页 size 用 @Min(1) @Max(100)

性能优化

  • N+1 查询、循环拼接字符串（用 StringBuilder）、频繁装箱拆箱（用原始类型流）、未指定集合初始容量（new ArrayList<>(size)）

第三方 API HTTP 客户端选型

  • 避免 RestTemplate 默认客户端调用国内平台 API（默认 HttpURLConnection 的 POST 与微信/支付宝等 CDN 存在兼容性问题，已知触发 412/403）
  • 优先用 java.net.http.HttpClient（JDK 11+）或配置 HttpComponentsClientHttpRequestFactory
  • 诊断特征：HTTP 错误 + body 为空 + response headers 极简 = CDN 层拦截

Native SQL 规范

  • 别名避免 MySQL 保留字（year_month、order、status、key、value、name、type、date、time、rank、range、rows、column、user、role、group）
  • 使用短别名或缩写，或用反引号转义

日志规范

  • 使用参数化日志（log.debug("Finding user by id: {}", userId)），避免字符串拼接

使用方式

本技能以规范文档形式提供，包含代码示例与检查清单，可在开发与代码审查时对照执行。详细参考文件包括：references/java-style.md（命名约定、异常处理、Spring Boot、测试规范）、references/collections.md（不可变集合、字符串分割）、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 后端项目开发、代码审查、重构与团队规范落地，尤其是使用 Spring Boot、Spring Data JPA、Maven 或 Gradle 的项目。

限制

本技能为开发规范文档，不包含自动化执行工具。具体版本兼容性、依赖配置与运行环境要求暂未提供。