From a59e0b8adeb5aaeecc5540f11a45ddf189e8cf11 Mon Sep 17 00:00:00 2001 From: V-LiuShuang Date: Mon, 7 Sep 2026 16:21:48 +0800 Subject: [PATCH] add --- mis-agent-spec/SKILL.md | 482 ------------------ mis-paw-spec/SKILL.md | 443 ---------------- mis-paw-spec/examples/api-doc.md | 60 --- mis-spec/SKILL.md | 25 + mis-spec/examples/ExampleDTO.java | 51 ++ mis-spec/examples/ExampleEntity.java | 93 ++++ mis-spec/examples/StateEnum.java | 27 + .../examples/api-doc.md | 0 mis-spec/examples/example_table.sql | 12 + mis-spec/references/coding_rules.md | 37 ++ mis-spec/references/core_arch.md | 42 ++ mis-spec/references/read_nacos_config.md | 46 ++ mis-spec/references/read_profile.md | 24 + mis-spec/references/worksheet.md | 38 ++ 14 files changed, 395 insertions(+), 985 deletions(-) delete mode 100644 mis-agent-spec/SKILL.md delete mode 100644 mis-paw-spec/SKILL.md delete mode 100644 mis-paw-spec/examples/api-doc.md create mode 100644 mis-spec/SKILL.md create mode 100644 mis-spec/examples/ExampleDTO.java create mode 100644 mis-spec/examples/ExampleEntity.java create mode 100644 mis-spec/examples/StateEnum.java rename {mis-agent-spec => mis-spec}/examples/api-doc.md (100%) create mode 100644 mis-spec/examples/example_table.sql create mode 100644 mis-spec/references/coding_rules.md create mode 100644 mis-spec/references/core_arch.md create mode 100644 mis-spec/references/read_nacos_config.md create mode 100644 mis-spec/references/read_profile.md create mode 100644 mis-spec/references/worksheet.md diff --git a/mis-agent-spec/SKILL.md b/mis-agent-spec/SKILL.md deleted file mode 100644 index 35cbdca..0000000 --- a/mis-agent-spec/SKILL.md +++ /dev/null @@ -1,482 +0,0 @@ ---- -name: mis-agent-spec -description: 在mis-agent模块编写代码必备技能。 ---- - -# Intro - -请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)生成代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。 - -## 核心技术栈 - -- 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+ -- redisson-spring-boot-starter： - - 版本：3.34.1 - - 文档：https://redisson.pro/docs/integration-with-spring/#usage - - 源码：https://github.com/redisson/redisson/tree/redisson-3.34.1/redisson-spring-boot-starter/src/main -- 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 -- agentscope-java： - - 版本：1.0.11 - - 文档：https://java.agentscope.io/v1/zh/docs/task/agent-as-tool.html - - 源码：https://github.com/agentscope-ai/agentscope-java/tree/v1.0.11 -- spring-ai： - - 版本：1.1.2 - - 文档：https://docs.spring.io/spring-ai/reference/1.1/index.html - - 源码：https://github.com/spring-projects/spring-ai/tree/v1.1.2 -- spring-ai-alibaba： - - 版本：1.1.2.2 - - 文档：https://java2ai.com/docs/overview - - 源码：https://github.com/alibaba/spring-ai-alibaba/tree/v1.1.2.2 -- 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 - -## 目录结构 - -### 项目根目录 - -```text -\ -├── mis-api\ # 微服务之间暴露的dubbo接口 -├── mis-auth\ # API网关鉴权服务 -├── mis-common\ # 存放多个模块的公共依赖 -├── mis-gateway\ # API网关 -├── mis-modules\ # 业务模块代码根目录 -├── mis-visual\ # 与业务无关的子模块 -└── pom.xml # 在中定义了Nacos地址及账号密码、NewAPI的地址和密钥 -``` - -### 模块根目录 - -```text -mis-modules\mis-agent\src\main\ -├── java -│ └── com\lcfc\agent\ -│ ├── agents\ # 智能体核心 -│ │ ├── a2a\ # A2A Agent -│ │ ├── config\ # Spring配置类 -│ │ ├── constants\ # 常量类 -│ │ ├── context\ # 自定义上下文载体类 -│ │ ├── controller\ # SpringWeb控制器 -│ │ ├── dubbo\ # Dubbo接口实现类 -│ │ ├── enums\ # 枚举类 -│ │ ├── events\ # Spring事件消息 -│ │ ├── mapper\ # Mybatis Mapper接口 -│ │ ├── multiagent\ # 多智能体 -│ │ ├── saa\ # 单智能体 -│ │ ├── service\ # Service接口 -│ │ │ └── impl\ # Service接口实现类 -│ │ ├── util\ # 工具类 -│ │ ├── validator\ # 验证器 -│ │ └── domain\ # 数据库实体类 -│ │ ├── DTO\ # 数据传输对象 -│ │ └── VO\ # 视图对象 -│ ├── eventhub\ # 事件发布订阅（非SpringBean可用） -│ │ ├── MisAgentEventHub.java # 注册监听器，broadcast推送事件 -│ │ └── MisAgentEventListener.java # 所有监听器须实现此接口 -│ ├── memory\ # 长期记忆 -│ │ ├── UserLongTermChannel.java # 记忆通道（如hindsight） -│ │ ├── UserLongTermMemoryClient.java # 用户级长期记忆客户端接口 -│ │ ├── UserLongTermMemoryConfig.java # 用户级长期记忆配置 -│ │ └── UserLongTermMemoryCtl.java # 用户级长期记忆控制类 -│ ├── monitor\ # 智能体监控（收集tool/skill/workflow/知识库调用及token消耗） -│ │ ├── AgentChatMetricsCtx.java # 监控数据上下文 -│ │ ├── AgentChatMetricsFinishEvent.java# 监控数据收集完成事件 -│ │ ├── AgentChatMetricsFinishListener.java # 监控数据完成监听器 -│ │ ├── IAgentChatMetricsConsumer.java # 消费监控数据接口 -│ │ ├── MisAgentChatMetricsCtl.java # 监控上下文控制类 -│ │ └── MisMcpToolMetadataCtl.java # MCP元数据控制类 -│ ├── skills\ # 智能体Skill -│ │ ├── BaseSkillToolsExecutor.java # Skill脚本执行工具父类 -│ │ ├── AgentScopeSkillTools.java # 基于agentscope-java执行Skill脚本 -│ │ ├── SpringAiSkillTools.java # 基于spring-ai执行Skill脚本 -│ │ ├── AgentSkillMetadataHandler.java # Skill元数据（磁盘记录数量） -│ │ ├── AgentSkillResourceHandler.java # Skill静态资源处理（下载/删除） -│ │ ├── AgentSkillRuntimeHandler.java # Skill运行时临时目录管理（创建/删除） -│ │ ├── AgentSkillRuntimeConfigHandler.java # Skill运行时自定义配置（读取/删除） -│ │ ├── AgentSkillSessionCache.java # Skill临时目录缓存（自动续期/删除） -│ │ ├── RemoveSkillConsumer.java # 智能体解绑Skill事件 / 服务端Skill删除事件 -│ │ ├── SkillRemoveConsumer.java # （待确认用途） -│ │ ├── SkillResourceChangeConsumer.java # Skill静态资源更新事件处理 -│ │ └── SkillStateChangeConsumer.java # Skill状态变更事件处理（禁用/启用） -│ ├── utils\ # 公共工具包 -│ │ ├── AsyncTaskTemplate.java # 多线程异步任务模板 -│ │ ├── RLockTemplate.java # 基于Redis的分布式锁 -│ │ └── TransactionTaskTemplate.java # 编程式Spring事务模板 -│ └── stats\ # 项目数据统计 -│ ├── api\ # Controller -│ ├── service\ # Service -│ ├── conf\ # 配置类 -│ ├── domain\ -│ │ ├── dto\ # DTO -│ │ ├── vo\ # VO -│ │ ├── enums\ # Enum -│ │ ├── entity\ # Entity -│ │ └── mapper\ # Mapper Java源文件 -│ └── mq\ -│ ├── event\ # 消息载体 -│ └── consumer\ # 监听器 -└── resources - ├── mapper\ # Mybatis Mapper XML - └── application.yml # 配置文件 -``` - -## 代码编写规范 - -| 类目 | 使用原则 | 描述 | -|:--- | :--- | :--- | -| 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 - -## 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示例 - -```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; - -} -``` - -## FAQ - -### 怎么确认用哪个profile？ - -若当前Git分支出于dev则使用dev，否则使用qas。 - -### 怎么读profile的配置？ - -从[项目根目录](#项目根目录)的`pom.xml`文件中获取不同`profiles.active`的配置，示例： - -```xml - - dev - - - dev - - 127.0.0.1:8868 - - DEFAULT_GROUP - - DEFAULT_GROUP - - nacos - - 1234567890 - - http://127.0.0.1:3000 - - sk-xxx - - -``` - -### 怎么打包？ - -系统已安装`mvnd`用来替换`mvn`命令，先确认该用哪个profile，获取`profiles.active`后在[项目根目录](#项目根目录)执行命令`mvnd clean package -DskipTests -P{profiles.active}`，**耗时约80秒**。 - -### 怎么读取nacos配置文件？ - -按步骤一步步执行： - -1. 先确认该用哪个profile，从**项目根目录**的`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格式。 \ No newline at end of file diff --git a/mis-paw-spec/SKILL.md b/mis-paw-spec/SKILL.md deleted file mode 100644 index a2c0d5b..0000000 --- a/mis-paw-spec/SKILL.md +++ /dev/null @@ -1,443 +0,0 @@ ---- -name: mis-paw-spec -description: 在mis-paw模块编写代码必备技能。 ---- - -# Intro - -请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)生成代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。 - -## 核心技术栈 - -- 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 - -## 目录结构 - -### 项目根目录 - -```text -\ -├── mis-api\ # 微服务之间暴露的dubbo接口 -├── mis-auth\ # API网关鉴权服务 -├── mis-common\ # 存放多个模块的公共依赖 -├── mis-gateway\ # API网关 -├── mis-modules\ # 业务模块代码根目录 -├── mis-visual\ # 与业务无关的子模块 -└── pom.xml # 在中定义了Nacos地址及账号密码、NewAPI的地址和密钥 -``` - -### 模块目录结构 - -```text -mis-modules\mis-paw\ -├── src\main\ -│ ├── java\com\lcfc\mispaw\ -│ │ ├── cluster # 集群相关 -│ │ ├── config # 配置类 -│ │ ├── constant # 常量定义 -│ │ ├── controller\ # 控制器层 -│ │ │ ├── agents # 智能体 -│ │ │ ├── approval # 审批 -│ │ │ ├── chats # 聊天 -│ │ │ ├── client # 客户端 -│ │ │ ├── corn # 定时任务 -│ │ │ ├── export # 导出 -│ │ │ ├── files # 文件预览 -│ │ │ ├── instance # 管理qwenpaw实例 -│ │ │ ├── mcp # 管理qwenpaw实例的MCP -│ │ │ ├── models # 模型相关 -│ │ │ ├── plan # 计划模式配置 -│ │ │ ├── plugins # 管理qwenpaw实例的插件 -│ │ │ ├── settings # 自定义qwenpaw实例设置 -│ │ │ ├── skills # 管理qwenpaw实例的Skill -│ │ │ ├── token # 查看qwenpaw实例的token消耗 -│ │ │ ├── toolguard # 管理qwenpaw实例的工具护栏 -│ │ │ ├── tools # 管理qwenpaw实例的工具 -│ │ │ └── workspace # 管理qwenpaw实例的工作区 -│ │ ├── domain\ # 存放DTO、VO -│ │ ├── dubbo # Dubbo接口实现类 -│ │ ├── enums # 枚举 -│ │ ├── event # Spring的ApplicationEvent子类 -│ │ ├── exception # 自定义异常类 -│ │ ├── filter # 过滤器 -│ │ ├── handler # 处理器 -│ │ ├── mapper\ # MybatisMapper接口 -│ │ ├── mq # 消息队列相关 -│ │ ├── service\ # 业务服务层 -│ │ ├── sessionfact\ # 会话服务 -│ │ ├── task # 定时任务 -│ │ ├── util # 工具类 -│ │ └── workflow # 工作流 -│ └── resources\ -│ ├── mapper\ # MybatisMapperXML -│ ├── application.yml # 配置文件 -│ └── logback-plus.xml # 日志配置 -└── pom.xml # 当前Maven模块的依赖与构建配置 -``` - -## 代码编写规范 - -| 类目 | 使用原则 | 描述 | -|:--- | :--- | :--- | -| 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 - -## 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示例 - -```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; - -} -``` - -## FAQ - -### 怎么确认用哪个profile？ - -固定使用dev的profile。 - -### 怎么读profile的配置？ - -从[项目根目录](#项目根目录)的`pom.xml`文件中获取**id=dev，profiles.active=lab**的profile，例如： - -```xml - - dev - - lab - - 127.0.0.1:8868 - - DEFAULT_GROUP - - DEFAULT_GROUP - - nacos - - 1234567890 - - http://127.0.0.1:3000 - - sk-xxx - - -``` - -### 怎么打包？ - -系统已安装`mvnd`用来替换`mvn`命令，在[项目根目录](#项目根目录)执行命令：`mvnd clean package -DskipTests -Pdev`，**耗时约80秒**。 - -### 怎么读取nacos配置文件？ - -按步骤一步步执行： - -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格式。 \ No newline at end of file diff --git a/mis-paw-spec/examples/api-doc.md b/mis-paw-spec/examples/api-doc.md deleted file mode 100644 index 956e74a..0000000 --- a/mis-paw-spec/examples/api-doc.md +++ /dev/null @@ -1,60 +0,0 @@ -# 智能体使用数据 - -以下是关于智能体使用数据的API文档。 - -## 累计使用数据卡片 - -- 请求地址：/agent/metrics/total -- 请求方式：GET - -### 请求参数 - -| 参数名称 | 是否必传 | 类型 | 描述 | -|:-----|:-----|:-----|:-----| -| agentId | 是 | String | 智能体ID | - -### 请求示例 - -```bash -curl -X GET {gateway}/agent/metrics/total?agentId={agentId} -``` - -### 响应参数 - -| 参数名称 | 类型 | 描述 | -|:-----|:-----|:-----| -| code | Number | 返回码（200=成功） | -| msg | String | 提示信息 | -| data | Object | 返回数据 | -| data.agentId | String | 智能体 ID | -| data.agentName | String | 智能体名称 | -| data.inputToken | Number | 累计输入Token | -| data.outputToken | Number | 累计输出Token | -| data.userNum | Number | 累计用户数 | -| data.chatNum | Number | 累计对话数 | - -### 成功示例 - -```json -{ - "code": 200, - "msg": "操作成功", - "data": { - "agentId": "123456", - "agentName": "智能体名称", - "inputToken": "123243654645", - "outputToken": "345645765765", - "userNum": 5678, - "chatNum": 45678999 - } -} -``` - -### 失败示例 - -```json -{ - "code": 500, - "msg": "错误信息" -} -``` \ No newline at end of file diff --git a/mis-spec/SKILL.md b/mis-spec/SKILL.md new file mode 100644 index 0000000..9461869 --- /dev/null +++ b/mis-spec/SKILL.md @@ -0,0 +1,25 @@ +--- +name: mis-spec +description: 在mis编写代码的必备技能。 +--- + +# mis-spec + +请结合[核心技术栈](./references/core_arch.md)，并严格遵守[代码编写规范](./references/coding_rules.md)生成代码，[示例代码](#示例代码)提供了一些代码示例可供参考，被要求编写HTTP接口文档时，请参考[api-doc.md](./examples//api-doc.md)文档生成。 + +## 示例代码 + +- [MySQL建表语句示例](./examples/example_table.sql) +- [Java实体类示例](./examples/ExampleEntity.java) +- [Java枚举类示例](./examples/StateEnum.java) +- [DTO或者VO示例](./examples/ExampleDTO.java) + +## FAQ + +| 问题 | 答案 | +|:---|:---| +|该用哪个profile执行编译？|向用户询问，可用的数值有：dev、local、qas、prd。| +|怎么读profile的配置？| 阅读文档[read_profile.md](./references/read_profile.md)| +|怎么编译或打包？|系统已安装`mvnd`用来替换`mvn`命令，在**项目根目录**执行命令：`mvnd clean package -DskipTests -Pdev`，**耗时约80秒**。| +|怎么读取nacos配置文件？|阅读文档[read_nacos_config.md](./references/read_nacos_config.md)| +|如何发起重试？比如提高异步任务可靠性！| \ No newline at end of file diff --git a/mis-spec/examples/ExampleDTO.java b/mis-spec/examples/ExampleDTO.java new file mode 100644 index 0000000..2e230b7 --- /dev/null +++ b/mis-spec/examples/ExampleDTO.java @@ -0,0 +1,51 @@ +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/mis-spec/examples/ExampleEntity.java b/mis-spec/examples/ExampleEntity.java new file mode 100644 index 0000000..d3b586c --- /dev/null +++ b/mis-spec/examples/ExampleEntity.java @@ -0,0 +1,93 @@ +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; + } + +} \ No newline at end of file diff --git a/mis-spec/examples/StateEnum.java b/mis-spec/examples/StateEnum.java new file mode 100644 index 0000000..7a12834 --- /dev/null +++ b/mis-spec/examples/StateEnum.java @@ -0,0 +1,27 @@ +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/mis-agent-spec/examples/api-doc.md b/mis-spec/examples/api-doc.md similarity index 100% rename from mis-agent-spec/examples/api-doc.md rename to mis-spec/examples/api-doc.md diff --git a/mis-spec/examples/example_table.sql b/mis-spec/examples/example_table.sql new file mode 100644 index 0000000..b242f12 --- /dev/null +++ b/mis-spec/examples/example_table.sql @@ -0,0 +1,12 @@ +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='示例表'; \ No newline at end of file diff --git a/mis-spec/references/coding_rules.md b/mis-spec/references/coding_rules.md new file mode 100644 index 0000000..cd00305 --- /dev/null +++ b/mis-spec/references/coding_rules.md @@ -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 \ No newline at end of file diff --git a/mis-spec/references/core_arch.md b/mis-spec/references/core_arch.md new file mode 100644 index 0000000..743594e --- /dev/null +++ b/mis-spec/references/core_arch.md @@ -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 \ No newline at end of file diff --git a/mis-spec/references/read_nacos_config.md b/mis-spec/references/read_nacos_config.md new file mode 100644 index 0000000..ca3c7dd --- /dev/null +++ b/mis-spec/references/read_nacos_config.md @@ -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格式。 \ No newline at end of file diff --git a/mis-spec/references/read_profile.md b/mis-spec/references/read_profile.md new file mode 100644 index 0000000..7be558b --- /dev/null +++ b/mis-spec/references/read_profile.md @@ -0,0 +1,24 @@ +从**项目根目录**`pom.xml`文件中获取查看`profiles`标签内容，类似如下片段： + +```xml + + dev + + lab + + 127.0.0.1:8868 + + DEFAULT_GROUP + + DEFAULT_GROUP + + nacos + + 1234567890 + + http://127.0.0.1:3000 + + sk-xxx + + +``` \ No newline at end of file diff --git a/mis-spec/references/worksheet.md b/mis-spec/references/worksheet.md new file mode 100644 index 0000000..abff7bc --- /dev/null +++ b/mis-spec/references/worksheet.md @@ -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='工单表'; +``` \ No newline at end of file