# 代码编写规范 请严格遵守以下原则书写干净整洁的Java源码。 ## 书写规范 - 积极采用JDK11~21的新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程。 - 虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。 - 为了降低代码耦合度，提高可维护性，请积极的采用工厂、模板、策略、发布订阅等常用的设计模式。 - 对于发布订阅模式，请根据以下情况判断：跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。进程通信使用ApplicationEventPublisher和@EventListener即可。 - 一个方法体内的行数不得超过20行，若超过20行，请拆成多个方法。 - 一个Java源文件的代码行数不得超过300行，若超过300行，说明拆的不够细，请拆成多个文件。 - 请积极优先使用Lombok注解，无需担心编译速度被拖慢。 - 对于工具类的使用，请优先采纳hutool，除非hutool没有提供才新建一个工具类。 - 对于null处理优先使用Optional而不是if，优先使用Stream而不是循环。 - 如果Stream的map代码块超过5行就单独写一个函数，如果map中代码块需要中间对象，优先使用记录类，记录类和DTO存放在一起。 - 构建JavaBean对象，优先使用构造函数而不是单独写工具类或方法，只有3个以内的属性，应提供一个全部参数的构造函数。 - List在非多线程场景，默认用ArrayList就够了。只有需要按照插入顺序遍历元素的场景，才考虑使用LinkedList。需考虑线程安全用CopyOnWriteArrayList。 - Set在非多线程场景，默认用HashSet。对排序要求考虑用LinkedHashSet或TreeSet。需考虑线程安全用`cn.hutool.core.collection.ConcurrentHashSet`、ConcurrentSkipListSet、CopyOnWriteArraySet等。 - Map在非线程场景，默认使用HashMap就够了。对排序要求考虑用LinkedHashMap或TreeMap。如果存在并发场景，需考虑线程安全用ConcurrentHashMap或ConcurrentSkipListMap等JUC工具包。 - Queue的使用原则：要控制内存，用ArrayBlockingQueue。经典生产者消费者，用LinkedBlockingQueue。要窃取任务，用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨，用ConcurrentLinkedQueue。必须双端且高吞吐，用ConcurrentLinkedDeque。 - Lock的使用原则：分布式锁使用Redisson相关API，单机使用ReentrantLock、StampedLock、ReentrantReadWriteLock即可。 ## ORM映射规则 - 数据库表结构字段名称、实体类字段名称，采用驼峰与下划线映射的方式。 - 实体类字段包含`@NotNull`注解，需要结合`@Schema`注解中的`defaultValue`属性判断是否需要设置默认值。 - 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。 - 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型： - 数值小于或等于2000，使用VARCHAR - 数值大于2000且小于10000，使用TEXT - 数值大于10000，使用LONGTEXT - 实体类的属性类型与表结构的字段类型映射关系： - String：默认VARCHAT(255) - Long：默认BIGINT - Integer：默认INT - LocalDate：默认DATE - LocalDateTime：默认DATETIME - `@TableField`注解中`typeHandler`等于`JacksonTypeHandler.class`时，表结构字段默认JSON类型 - BigDecimal：默认DECIMAL(14, 2) ## MySQL建表语句示例 ```sql CREATE TABLE `example_table` ( `id` BIGINT NOT NULL COMMENT 'ID', `str_field` VARCHAR(32) NOT NULL COMMENT '字符串`, `int_field` INT DEFAULT NULL COMMENT '整数`, `long_field` BIGINT DEFAULT NULL COMMENT '长整数`, `decimal_field` DECIMAL(14, 2) DEFAULT NULL COMMENT '高精度浮点数`, `date_field` DATE NOT NULL COMMENT '日期类型`, `time_field` DATETIME NOT NULL COMMENT '日期类型`, `state` VARCHAR(32) NOT NULL COMMENT '状态：only_read、read_write', `json_field` JSON DATETIME NULL COMMENT 'JSON类型' PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表'; ``` ## 数据库实体类示例 ```java import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableField; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import com.fasterxml.jackson.annotation.JsonFormat; import io.swagger.v3.oas.annotations.media.Schema; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import lombok.Data; import lombok.Getter; import org.springframework.format.annotation.DateTimeFormat; import com.fasterxml.jackson.databind.annotation.JsonSerialize; import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler; import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; import java.io.Serial; import java.io.Serializable; import java.time.LocalDate; import java.time.LocalDateTime; import java.math.BigDecimal; @Data @TableName(value = "example_table", autoResultMap = true) @Schema(title = "示例表") public class ExampleEntity implements Serializable { @Serial private static final long serialVersionUID = 1L; @Schema(description = "ID") @TableId(value = "id", type = IdType.ASSIGN_ID) @TableField(value = "id") @JsonSerialize(using = ToStringSerializer.class) private Long id; @NotBlank @Schema(description = "字符串") @TableField(value = "str_field") private String strField; @Schema(description = "整数", defaultValue = "0") @TableField(value = "int_field") private Integer intField; @Schema(description = "长整数") @TableField(value = "long_field") @JsonSerialize(using = ToStringSerializer.class) private Long longField; @Schema(description = "高精度浮点数") @TableField(value = "decimal_field") private BigDecimal decimalField; @NotNull @Schema(description = "日期类型", pattern = "yyyy-MM-dd") @TableField(value = "date_field") @DateTimeFormat(pattern = "yyyy-MM-dd") @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") private LocalDate dateField; @NotNull @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") @TableField(value = "time_field") @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") private LocalDateTime timeField; @NotNull @Schema( title = "状态", description = "参考示例值", example = StateEnum.DESC ) @TableField(value = "state") private StateEnum state; @Schema(description = "JSON类型") @TableField(value = "json_field", typeHandler = JacksonTypeHandler.class) private JsonField jsonField; @Data public static class JsonField implements Serializable { @Serial private static final long serialVersionUID = 1L; @Schema(description = "示例字段1") private String field1; @Schema(description = "示例字段2") private Integer field2; } } ``` ## 枚举类示例 ```java import com.baomidou.mybatisplus.annotation.EnumValue; import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonValue; import io.swagger.v3.oas.annotations.media.Schema; import lombok.Getter; import lombok.RequiredArgsConstructor; @Getter @RequiredArgsConstructor @Schema(description = "某某状态") public enum StateEnum { ONLY_READ("only_read"), READ_WRITE("read_write"); public static final String DESC = "only_read=只读、read_write=读写"; @JsonValue @EnumValue private final String value; @JsonCreator public static StateEnum deserialize(String input) { return Arrays.stream(values()).filter(e -> e.getValue().equals(input)).findFirst().orElse(null); } } ``` ## DTO、VO ```java import com.fasterxml.jackson.annotation.JsonFormat; import io.swagger.v3.oas.annotations.media.Schema; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import lombok.Data; import lombok.Getter; import org.springframework.format.annotation.DateTimeFormat; import com.fasterxml.jackson.databind.annotation.JsonSerialize; import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; import java.io.Serial; import java.io.Serializable; import java.time.LocalDate; import java.time.LocalDateTime; import java.math.BigDecimal; @Data @Schema(title = "DTO示例") public class ExampleDTO implements Serializable { @Serial private static final long serialVersionUID = 1L; @NotBlank @Schema(description = "字符串") private String strField; @Schema(description = "长整数") @JsonSerialize(using = ToStringSerializer.class) private Long longField; @NotNull @Schema(description = "日期类型", pattern = "yyyy-MM-dd") @DateTimeFormat(pattern = "yyyy-MM-dd") @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") private LocalDate dateField; @NotNull @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") private LocalDateTime timeField; @NotNull @Schema( title = "状态", description = "参考示例值", example = StateEnum.DESC ) private StateEnum state; } ```