diff --git a/java-bean.md b/java-bean.md deleted file mode 100644 index 45759d8..0000000 --- a/java-bean.md +++ /dev/null @@ -1,161 +0,0 @@ -# JavaBean生成规范 - -请根据代码示例生成：数据库实体类、枚举类、DTO、VO。 - -## 数据库实体类示例 - -```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; - } - -} -``` - -## 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; - -} -``` - -## 枚举类代码示例 - -[enums.md](./enums.md) \ No newline at end of file diff --git a/java-coding-rules.md b/java-coding-rules.md index 1473e8f..53b7d8f 100644 --- a/java-coding-rules.md +++ b/java-coding-rules.md @@ -1,18 +1,243 @@ -请严格遵守以下原则书写干净整洁的Java源码： +# 代码编写规范 + +请严格遵守以下原则书写干净整洁的Java源码。 + +## 书写规范 - 积极采用JDK11~21的新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程。 - 虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。 - 为了降低代码耦合度，提高可维护性，请积极的采用工厂、模板、策略、发布订阅等常用的设计模式。 -- 对于发布订阅模式，请根据以下情况判断： - - 跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。 - - 单进程通信使用ApplicationEventPublisher和@EventListener即可。 +- 对于发布订阅模式，请根据以下情况判断：跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。进程通信使用ApplicationEventPublisher和@EventListener即可。 - 一个方法体内的行数不得超过20行，若超过20行，请拆成多个方法。 - 一个Java源文件的代码行数不得超过300行，若超过300行，说明拆的不够细，请拆成多个文件。 - 请积极优先使用Lombok注解，无需担心编译速度被拖慢。 - 对于工具类的使用，请优先采纳hutool，除非hutool没有提供才新建一个工具类。 - 对于null处理优先使用Optional而不是if，优先使用Stream而不是循环。 - 如果Stream的map代码块超过5行就单独写一个函数，如果map中代码块需要中间对象，优先使用记录类，记录类和DTO存放在一起。 - - 构建JavaBean对象，优先使用构造函数而不是单独写工具类或方法，只有3个以内的属性，应提供一个全部参数的构造函数。 -- 对于Set集合，除非对排序有要求，否则优先使用HashSet而不是LinkedHashSet或TreeSet，如果存在并发场景，应优先使用`cn.hutool.core.collection.ConcurrentHashSet`。 -- 对于Map集合，除非对排序要要求，否则优先使用HashMap而不是LinkedHashMap或TreeMap，如果存在并发场景，应优先使用ConcurrentHashMap或ConcurrentSkipListMap。 \ No newline at end of file +- 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; + +} +``` \ No newline at end of file diff --git a/java-enums.md b/java-enums.md deleted file mode 100644 index 51ab21b..0000000 --- a/java-enums.md +++ /dev/null @@ -1,29 +0,0 @@ -```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); - } -} -``` \ No newline at end of file diff --git a/java-orm.md b/java-orm.md deleted file mode 100644 index 76a0c8e..0000000 --- a/java-orm.md +++ /dev/null @@ -1,44 +0,0 @@ -# 实体类与数据库表书写规范 - -- 数据库表结构字段名称、实体类字段名称，采用驼峰与下划线映射的方式。 -- 实体类字段包含`@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) - -请根据以上规范，结合下文代码示例，生成建表语句和Java实体类代码。 - -## 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实体类示例 - -[java-bean.md](./java-bean.md#数据库实体类示例) - -## 枚举类代码示例 - -[java-enums.md](./java-enums.md) \ No newline at end of file diff --git a/mis-agent.md b/mis-agent.md index 1d0567d..80b4b24 100644 --- a/mis-agent.md +++ b/mis-agent.md @@ -9,8 +9,6 @@ ## 代码规范 - [Java代码书写规范](./java-coding-rules.md) -- [数据库实体类与建表规范](./java-orm.md) -- [JavaBean书写规范](./java-bean.md) - [书写HTTP接口文档示例](./mis-api-doc.md) ## 目录结构