skills/java-spec/references/coding.md

代码编写规范

Java的新特性

目前主流的JDK选型有4个版本：8、17、21、25。通过pom.xml中的<java.version>标签可以定位当前项目的JDK版本是多少。积极的使用新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、虚拟线程。虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。

必须恪守的基本原则

• 一个Java源文件的行数不得超过300行，否则拆成多个文件。
• 一个方法的行数不得超过20行，否则拆成多个方法。
• 积极使用Optional处理NULL值，避免大量的if (obj != null)。
• 优先使用Stream，若map或flatMap代码块超过5行就单独写一个方法。如果map代码块需要中间对象且JDK版本高于17，则优先使用记录类，否则退化到普通java类，记录类和DTO存放在一个目录。
• 构建JavaBean对象，优先使用构造函数而不是单独写方法，只有3个以内的属性，应提供一个全部参数的构造函数。
• 只在关键地方插入简洁的注释，不啰嗦、不废话、不长篇大论。尽量用清晰明确的命名，避免添加注释。

三方库的使用原则

• 如果项目引入了Lombok，请积极使用，无需担心编译速度被拖慢。
• 如果项目引入了hutool，请尽量少写工具类，最大程度复用hutool-core、hutool-json、hutool-system模块中的工具，其他模块的包慎用！当JDK版本高于11，不得引入hutool-http工具包，使用JDK内置的HttpClient替代，可以新建一个HttpUtils减少代码冗余。
• 如果项目引入了jackson，ObjectMapper或JsonMapper应该单例使用，且基于jackson新建1个JsonUtils去替代hutool-json是更好的选择。但不能创建多个JsonUtils，能复用则复用。

集合与队列

集合工具	何时使用
ArrayList	在非多线程场景使用。 方法返回空集合使用Collections.emptyList()。 如果是Dubbo接口的返回值，空集合要使用new ArrayList<>()。
HashSet	在非多线程且没有排序要求的场景使用。 方法返回空集合使用Collections.emptySet()。 如果是Dubbo接口的返回值，空集合要使用new HashSet<>()。
HashMap	在非多线程且没有排序要求的场景使用。 方法返回空集合使用Collections.emptyMap()。 如果是Dubbo接口的返回值，空集合要使用new HashMap<>()。
LinkedHashSet、LinkedHashMap	在非多线程且需要按照插入顺序遍历的场景使用。
TreeSet、TreeMap	在非多线程场景且有排序要求的场景使用。
ConcurrentSkipListSet	在需要排序的场景且多线程安全的场景使用。
CopyOnWriteArraySet	读多写少、无需排序、集合的规模较少，比如：监听器、回调注册表。
ConcurrentHashMap	在多线程场景且无排序要求的场景下使用。
ConcurrentSkipListMap	在多线程场景且有排序要求的场景下使用。
ArrayBlockingQueue	在多线程需限制内存、容量固定、延迟可预测的场景下使用
LinkedBlockingQueue	在多线程需高吞吐、长度波动大、生产消费并发高的场景下使用，必须显式指定容量，防止OOM。

Lock的使用规范

• 单机环境下，使用ReentrantLock或者StampedLock。
• 分布式环境下，如果pom.xml中引入了Redisson，则应该优先使用RedissonClient。