add

2026-09-07 16:21:48 +08:00
parent 4aac97e3d8
commit a59e0b8ade
14 changed files with 395 additions and 985 deletions
@@ -0,0 +1,37 @@
+# 代码编写规范
+
+| 类目 | 使用原则 | 描述 |
+|:--- | :--- | :--- |
+| 工单 | 适当应用 | 阅读文档[worksheet.md](../references/worksheet.md) |
+| JDK11~21的新特性 | 积极使用 | 局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程，虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。|
+| 设计模式 | 非常看重 | 为了降低代码耦合度，提高可维护性，请积极的采用工厂、模板、策略、发布订阅等常用的设计模式。一个Java源文件的代码行数不得超过300行，超出则拆成多个文件，一个方法体内的行数不得超过20行，超出则拆成多个方法。对于发布订阅模式，请根据以下情况判断：跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。进程内通信则使用ApplicationEventPublisher和@EventListener即可。|
+| Lombok注解 | 积极使用 | 无需担心编译速度被拖慢。|
+| Null值处理 | 适当应用 | 优先考虑`Optional.ofNullable(obj)`而不是`if (obj == null)` |
+| Stream | 积极使用 | 优先使用Stream而不是循环，若map代码块超过5行就单独写一个方法，如果需要中间对象则优先使用记录类，记录类和DTO存放在一个目录。|
+| 工具类 | 积极使用 | 优先采纳hutool，除非hutool没有提供才新建一个工具类。|
+| 构建对象 | 非常看重 | 构建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即可。|
+
+## 实体类与MySQL字段类型映射规则
+
+|实体类字段类型|MySQL字段类型|
+| --- | --- |
+| String | VARCHAT(255) |
+| Long | BIGINT |
+| Integer | INT |
+| LocalDate | DATE |
+| LocalDateTime | DATETIME |
+| BigDecimal | DECIMAL(14, 2) |
+
+- 数据库表结构字段名称、实体类字段名称，采用驼峰与下划线映射的方式。
+- `@TableField`注解中`typeHandler`等于`JacksonTypeHandler.class`时，表结构字段默认JSON类型。
+- 实体类字段包含`@NotNull`注解，需要结合`@Schema`注解中的`defaultValue`属性判断是否需要设置默认值。
+- 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。
+- 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型：
+  - 数值小于或等于2000，使用VARCHAR
+  - 数值大于2000且小于10000，使用TEXT
+  - 数值大于10000，使用LONGTEXT
@@ -0,0 +1,42 @@
+- Java：OpenJDK21
+- spring-boot：
+  - 版本：3.2.9
+  - 文档：https://docs.spring.io/spring-boot/docs/3.2.9/reference/html
+  - 源码：https://github.com/spring-projects/spring-boot/tree/v3.2.9
+- spring-framework：
+  - 版本：6.1.12
+  - 文档：https://docs.spring.io/spring-framework/reference/6.2/index.html
+  - 源码：https://github.com/spring-projects/spring-framework/tree/v6.1.12
+- mybatis-plus：
+  - 版本：3.5.7
+  - 文档：https://github.com/baomidou/mybatis-plus-doc
+  - 源码：https://github.com/baomidou/mybatis-plus/tree/v3.5.7
+- MySQL：
+  - 版本：8.0.25
+  - 文档：https://dev.mysql.com/doc/refman/8.0/en/
+  - 源码：https://github.com/mysql/mysql-server/tree/mysql-8.0.25
+- Redis：8.0+
+- hutool-core：
+  - 版本：5.8.42
+  - 文档：https://github.com/chinabugotech/hutool-site/tree/master/docs/core
+  - 源码：https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-core
+- hutool-json：
+  - 版本：5.8.42
+  - 文档：https://github.com/chinabugotech/hutool-site/tree/master/docs/json
+  - 源码：https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-json
+- spring-cloud-alibaba：
+  - 版本：2023.0.1.2
+  - 文档：https://sca.aliyun.com/docs/2023/overview/version-explain
+  - 源码：https://github.com/alibaba/spring-cloud-alibaba/tree/2023.0.1.2
+- RocketMQ：
+  - 文档：https://rocketmq.apache.org/zh/docs/4.x
+  - rocketmq-client：
+    - 版本：4.9.8
+    - 源码：https://github.com/apache/rocketmq/tree/rocketmq-all-4.9.8
+  - rocketmq-spring-boot-starter：
+    - 版本：2.2.3
+    - 源码：https://github.com/apache/rocketmq-spring/tree/rocketmq-spring-all-2.2.3
+- elasticsearch：
+  - 版本：9.2.0
+  - 文档：https://github.com/elastic/elasticsearch/tree/v9.2.0/docs
+  - 源码：https://github.com/elastic/elasticsearch/tree/v9.2.0    
@@ -0,0 +1,46 @@
+按步骤一步步执行：
+
+1. 从**项目根目录**的`pom.xml`获取以下几个属性：
+
+- `profiles.active`
+- `nacos.server`
+- `nacos.config.group`
+- `nacos.username`
+- `nacos.password`
+
+2. 获取accessToken。
+
+请求示例：
+```bash
+curl -X POST 'http://{nacos.server}/nacos/v1/auth/login' -d 'username={nacos.username}&password={nacos.password}'
+```
+
+输出示例：
+```json
+{"accessToken":"xxx"}
+```
+
+如果输出不包含accessToken字段视为失败，**最多重试2次，仍然失败则直接中断整个流程。**
+
+3. 获取配置文件信息。
+
+- `dataId`：如果要请求MySQL执行SQL使用`datasource.yml`，否则使用`mis-agent.yml`。
+- `accessToken`：上一步得到的`accessToken`。
+
+请求示例：
+
+```bash
+curl -X GET "http://{nacos.server}/nacos/v3/console/cs/config?dataId={dataId}&groupName={groupName}&namespaceId={profiles.active}" -H "Authorization: Bearer {accessToken}"
+```
+
+输出示例：
+
+```json
+{
+    "code": 0,
+    "message": "success",
+    "data": {"content": "..."}
+}
+```
+
+`data.content`就是配置内容，通常是yaml格式。
@@ -0,0 +1,24 @@
+从**项目根目录**`pom.xml`文件中获取查看`profiles`标签内容，类似如下片段：
+
+```xml
+<profile>
+  <id>dev</id>
+  <properties>
+    <profiles.active>lab</profiles.active>
+    <!-- 当前环境的Nacos服务地址 -->
+    <nacos.server>127.0.0.1:8868</nacos.server>
+    <!-- 当前环境的Nacos注册中心分组名称 -->
+    <nacos.discovery.group>DEFAULT_GROUP</nacos.discovery.group>
+    <!-- 当前环境的Nacos配置中心分组名称 -->
+    <nacos.config.group>DEFAULT_GROUP</nacos.config.group>
+    <!-- 当前环境的Nacos登录账号 -->
+    <nacos.username>nacos</nacos.username>
+    <!-- 当前环境的Nacos登录密码 -->
+    <nacos.password>1234567890</nacos.password>
+    <!-- 当前环境的NewAPI服务地址 -->
+    <newAPI.url>http://127.0.0.1:3000</newAPI.url>
+    <!-- 当前环境的NewAPI模型ApiKey -->
+    <newAPI.key>sk-xxx</newAPI.key>
+  </properties>
+</profile>
+```
@@ -0,0 +1,38 @@
+# 使用场景
+
+异步任务捕捉到异常需要发起重试。
+
+## 源码
+
+目录："mis-modules/mis-paw/src/main/java/com/lcfc/mispaw/worksheet"，所有"SimpleWorkSheet.java"的子类都是一个工单处理器，"WorkSheetTaskExecutor.java"将定时轮询查数据库并异步执行。
+
+## 编写代码的模块没有工单怎么办？
+
+把"worksheet"目录拷贝一份到编写代码的模块，放在与springboot启动类同级目录，代码生成完毕以后，把工单的表结构原文输出给用户，让其手动执行。
+
+## 案例
+
+项目中"mis-modules/mis-paw/src/main/java/com/lcfc/mispaw/mq/base/IMessageQueueConsumer.java"在"onMessage"方法捕获异常，调用"mis-modules/mis-paw/src/main/java/com/lcfc/mispaw/worksheet/WorkSheetHandler.java"的"putObjectParam"方法把异步任务保存到数据库。
+
+## 工单的表结构
+
+```sql
+CREATE TABLE `work_sheet` (
+    `id`                  BIGINT        NOT NULL AUTO_INCREMENT COMMENT 'ID',
+    `system_code`         VARCHAR(64)   NOT NULL COMMENT '系统编码',
+    `work_code`           VARCHAR(512)   NOT NULL COMMENT '工单编码',
+    `current_try_times`   INT           NOT NULL COMMENT '当前是第几次重试',
+    `max_try_times`       INT           NOT NULL COMMENT '最多重试多少次',
+    `task_id`             VARCHAR(512)   NOT NULL COMMENT '追踪标识（traceId、业务标识、时间戳等）',
+    `state`               VARCHAR(32)   NOT NULL COMMENT '状态：wait-待执行，error-失败，success-成功',
+    `json_param`          JSON          NULL     COMMENT '请求参数（JSON格式）',
+    `str_param`           VARCHAR(512)  NULL     COMMENT '请求参数（简单字符串）',
+    `response_param`      LONGTEXT      NULL     COMMENT '响应参数',
+    `error`               LONGTEXT NULL     COMMENT '错误信息',
+    `create_time`         DATETIME      NOT NULL COMMENT '创建时间',
+    `start_time`          DATETIME      NULL     COMMENT '执行开始时间',
+    `finish_time`         DATETIME      NULL     COMMENT '执行结束时间',
+    PRIMARY KEY (`id`),
+    KEY idx_task_id(`task_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='工单表';
+```