前言¶
在编写或审查 Java / Spring Boot 代码时，经常遇到以下问题：空指针、集合操作不当、日期格式混乱、线程池配置错误、日志拼接、包装类型比较、金额计算精度丢失、常量与配置分散、代码职责不清等。这些问题往往不是单一工具能覆盖的，而是散落在多个编码习惯和项目结构中。
Java 编码指南是一个基于 SKILL.md 格式的 Skill，旨在把这些分散的规范与避坑点集中到一个可检索、可复现的上下文中。无论用户是否明确提到“编码规范”或具体工具库，只要在 Java / Spring Boot 代码中遇到相关模式，它都能给出针对性的检查与建议。
是什么¶
Java 编码指南是 SkillHub 社区维护的通用编码规范与避坑助手，面向 Java / Spring Boot 代码的编写、修改、重构或审查场景。它不依赖特定业务逻辑，而是覆盖从基础语法到架构组织的常见问题，并与项目既有技术栈（如 Spring、Hutool、commons-lang3 等）保持一致，不强行引入新依赖。
核心功能¶
1. 规范覆盖¶
- 判空与字符串：对空值与字符串常用操作的规范说明
- 集合与 Stream：集合创建、操作、转换的最佳实践
- 日期时间：日期格式化、时区、时间计算与跨库兼容
- 文件 IO / HTTP 调用 / JSON 序列化：资源管理、超时控制、序列化方式选择
- 线程池与并发：线程池创建方式、线程数量、任务提交策略
- Bean 拷贝：不同拷贝方式（如 BeanUtils / BeanUtil / MapStruct）的选择与注意点
- 加密哈希：密码存储、摘要算法的正确用法
- 异常处理与日志：异常捕获、日志输出、结构化日志建议
- 金额与浮点精确运算：BigDecimal 使用、精度控制、避免浮点比较
- 现代 Java 语法（JDK 8~25）：按特性最低版本门控的语法规范
2. 静默失效排查¶
- 注解自调用问题
- 包装类型比较陷阱
- 不可变集合被修改
3. 分层职责与代码组织¶
- 封装与复用原则
- 常量与配置归属（是否应提取到配置中心）
- 资源托管与生命周期管理
4. 触发信号识别¶
代码中出现以下模式时，会触发相关规范或避坑建议：
- 日期与线程：SimpleDateFormat、Executors.newFixedThreadPool / newCachedThreadPool / newSingleThreadExecutor、new Thread(…)
- 精度问题：new BigDecimal(0.1) 等小数构造
- Bean 拷贝：BeanUtils.copyProperties、BeanUtil.copyProperties、BeanUtil.toBean、BeanUtil.beanToMap
- 异常处理：catch (Throwable) / catch (InterruptedException) 空块
- 加密与哈希：MessageDigest（手写 MD5/SHA）
- 日志拼接：log.error(“x=” + x) 等字符串拼接
- Optional：Optional.get()
- 集合操作：subList(…)、List.of/Map.of 结果被 add
- 控制流：finally 块内 return / throw
- 随机数：Math.random()、new Random()
- 注解使用：@Transactional / @Async / @Cacheable 自调用或打在 private 方法上、@Autowired 字段注入、@Value 注 static 字段
- 类型比较：包装类型（Integer/Long）== 比较
- 集合返回：getXxx() 直接返回内部集合
- 常量与硬编码：业务类内堆 static final 常量 / 硬编码 URL 与超时
5. 任务词识别¶
当用户任务词出现以下内容时，会给出相关规范建议：
- 生成订单号 / 流水号 / 唯一 ID
- 生成验证码 / token / 盐
- 密码加密 / 哈希存储
- 金额 / 价格计算
- 线程池 / 异步任务
- 日期格式化 / 时区
- 分层 / 职责划分
- 常量放哪 / 配置外置
- 代码结构组织 / 复用抽取
6. 技术栈兼容¶
- 跟随项目既有技术栈（Spring / Hutool / commons-lang3 等）
- 不强行引入任何新库或框架
7. 不适用范围¶
- 业务架构设计（微服务拆分 / 领域建模）
- 框架选型
- DDL
- 纯算法
- 前端代码
安装与启用¶
在支持的编辑器或命令行工具中，通过以下方式启用：
# SkillHub 命令行安装（示例，具体路径以官方为准）
skill install @user_a36dc51e/java-coding-guide-pro
安装后，在编辑器中打开 Java / Spring Boot 项目，当遇到上述触发信号或任务词时，即可在上下文或命令面板中调用该 Skill 进行规范检查与避坑建议。
典型用法¶
示例 1：日期与线程池¶
代码片段（触发点）：
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
Executors.newFixedThreadPool(10).execute(() -> {
String date = sdf.format(new Date());
});
规范建议：
- 使用 Java 8+ 的 DateTimeFormatter 代替 SimpleDateFormat
- 线程池应使用自定义 ThreadPoolExecutor，避免使用 Executors 工厂方法
- 考虑使用 ScheduledExecutorService 定时任务，而非手动 new Thread
示例 2：金额计算¶
代码片段（触发点）：
BigDecimal price = new BigDecimal(0.1).multiply(new BigDecimal("99.99"));
规范建议：
- 避免使用小数字面量构造 BigDecimal（如 new BigDecimal(0.1)），应使用字符串或指定精度的构造方法
- 明确精度与舍入模式，避免隐式四舍五入
示例 3：日志输出¶
代码片段（触发点）：
log.error("x=" + x);
规范建议：
- 使用占位符方式输出日志，避免字符串拼接
- 对敏感信息做脱敏处理
适用场景与注意¶
- 适合：Java / Spring Boot 项目的日常编码、重构审查、Code Review 辅助
- 注意：Skill 不会覆盖所有业务逻辑，仅针对编码规范与常见避坑点；对于架构选型、业务建模等宏观问题，应结合具体业务文档与团队规范。
总结¶
Java 编码指南将分散的编码规范与避坑点集中到可检索的上下文中，帮助开发者快速识别常见问题并给出规范建议。它覆盖从基础语法到代码组织的多个维度，并与项目既有技术栈保持一致，适合作为日常编码、重构与审查时的辅助工具。
官方地址：https://www.skillhub.cn/skills/user_a36dc51e/java-coding-guide-pro
