# quick-start-boot-framwork **Repository Path**: roggie/quick-start-boot-framwork ## Basic Information - **Project Name**: quick-start-boot-framwork - **Description**: 一个面向 Spring Boot 的基础设施能力框架，提供可靠消息、MQTT 接入、Netty 协议服务端、统一缓存、统一 JSON、可观测性和敏感字段脱敏等通用模块。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-04-25 - **Last Updated**: 2026-04-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # quick-start-boot-framwork ## 项目简介 这是一个基于 Maven 的多模块快速启动框架仓库，当前主要模块包括： - `quick-start-boot-core` - `quick-start-boot-annotation-processor` - `quick-start-boot-sensitive` - `quick-start-boot-json` - `quick-start-boot-ai` - `quick-start-boot-mqtt` - `quick-start-boot-acl` - `quick-start-boot-spring-netty` - `quick-start-boot-cache` - `quick-start-boot-sample-order` ## AI 模块 `quick-start-boot-ai` 当前的定位是：**为 Spring Boot 业务系统提供一套低心智负担、可恢复、可观测的 AI Agent 开发骨架**。 第一版已经落下这些核心能力： - `workflow`：由 LiteFlow 接管控制流编排，统一串行、条件、并行、子流程与循环 - `state`：统一 `AgentState` 承载消息、记忆、工具结果、审批结果和业务扩展属性 - `checkpoint`：每个节点执行前后都可以持久化快照，支持 resume - `tool`：业务侧通过 `@AgentTool` 暴露工具，框架内部负责注册、schema 生成、治理与执行 - `memory`：提供 `AgentMemoryStore` 端口，并支持 PostgreSQL + pgvector 默认实现 - `approval/interrupt`：支持审批节点与中断恢复 - `model provider`：内置 OpenAI-compatible、DashScope、Ollama、智谱接入 starter - `evaluation/web`：补齐运行评测、prompt trace 与标准 HTTP/SSE 接口模板 - `starter`：业务方直接引用 starter，并通过 `@AgentTool`、`@LiteflowComponent` 和 LiteFlow 规则文件完成扩展 默认规则文件入口已经收敛为： - `classpath:liteflow/flow.el.xml` 如果业务侧需要多规则文件，再自行显式配置成： - `classpath*:liteflow/*.el.xml` 当前 AI 模块的子结构为： - `quick-start-boot-ai-api` - `quick-start-boot-ai-core` - `quick-start-boot-ai-autoconfigure` - `quick-start-boot-ai-starter` - `quick-start-boot-ai-model-openai-starter` - `quick-start-boot-ai-model-dashscope-starter` - `quick-start-boot-ai-model-ollama-starter` - `quick-start-boot-ai-model-zhipu-starter` - `quick-start-boot-ai-tool-starter` - `quick-start-boot-ai-memory-pgvector-starter` - `quick-start-boot-ai-observability-starter` - `quick-start-boot-ai-evaluation-starter` - `quick-start-boot-ai-orchestration-liteflow-starter` - `quick-start-boot-ai-web-starter` - `quick-start-boot-ai-approval-notifier-wecom-starter` - `quick-start-boot-ai-approval-notifier-feishu-starter` - `quick-start-boot-ai-approval-notifier-dingtalk-starter` - `quick-start-boot-ai-samples` 如果你第一次接入 AI 模块，推荐先看： - [quick-start-boot-ai/README.md](quick-start-boot-ai/README.md) - [quick-start-boot-ai/samples/README.md](quick-start-boot-ai/samples/README.md) `quick-start-boot-ai/README.md` 里现在已经补了： - 完整分层架构图 - 标准单轮执行时序图 - 审批 / 中断 / 恢复时序图 - Web / SSE 接口时序图 ## MQTT 模块 `quick-start-boot-mqtt` 已统一为单核心、多适配器结构，当前定位是： - `quick-start-boot-mqtt-api` 与 `quick-start-boot-mqtt-core` 作为唯一公共契约与核心能力 - 业务侧统一通过 `BusinessProtocolAdapter`、`ProtocolMessageHandler`、`ProtocolGateway` 扩展 - 底层传输通过适配器模块接入，Spring Integration 不再作为独立框架产品存在 - 框架统一提供配置校验、异常模型、默认拦截器、统一失败链路与生命周期管理 ### 传输适配模块 - `quick-start-boot-mqtt-transport-paho-v3` - `quick-start-boot-mqtt-transport-paho-v5` - `quick-start-boot-mqtt-transport-spring-integration-v3` - `quick-start-boot-mqtt-transport-spring-integration-v5` ### 依赖方式 同一应用在同一协议版本下只能引入一个传输实现，请勿同时引入 Paho 与 Spring Integration 的同版本模块。 使用 Paho MQTT v3： ```xml org.dw quick-start-boot-mqtt-transport-paho-v3 ${project.version} ``` 使用 Paho MQTT v5： ```xml org.dw quick-start-boot-mqtt-transport-paho-v5 ${project.version} ``` 使用 Spring Integration MQTT v3： ```xml org.dw quick-start-boot-mqtt-transport-spring-integration-v3 ${project.version} ``` 使用 Spring Integration MQTT v5： ```xml org.dw quick-start-boot-mqtt-transport-spring-integration-v5 ${project.version} ``` ### 配置结构 统一使用 `spring.mqtt` 前缀： ```yaml spring: mqtt: connection: protocol-version: v3 uris: - tcp://localhost:1883 username: demo password: demo clean-session: true automatic-reconnect: true connection-timeout: 30 keep-alive-interval: 60 max-reconnect-delay: 10000 inbound: client-id: demo-inbound auto-startup: true subscriptions: - topic: device/+/up qos: 1 allowed-topic-patterns: - device/+/up max-payload-size: 1048576 max-messages-per-second: 1000 outbound: client-id: demo-outbound default-topic: device/reply default-qos: 1 retained: false protocol: strict-matcher-validation: true ``` ### 协议接入示例 定义业务协议适配器： ```java package demo.mqtt; import java.nio.charset.StandardCharsets; import java.util.List; import java.util.Map; import org.dw.mqtt.api.model.MqttInboundEnvelope; import org.dw.mqtt.api.model.MqttOutboundEnvelope; import org.dw.mqtt.api.model.ProtocolSendRequest; import org.dw.mqtt.api.spi.BusinessProtocolAdapter; import org.springframework.stereotype.Component; @Component public class DeviceUpProtocolAdapter implements BusinessProtocolAdapter { @Override public String protocolId() { return "device-up"; } @Override public Class payloadType() { return DeviceUpMessage.class; } @Override public List inboundTopicPatterns() { return List.of("device/+/up"); } @Override public boolean supports(MqttInboundEnvelope envelope) { return envelope.topic().startsWith("device/") && envelope.topic().endsWith("/up"); } @Override public DeviceUpMessage decode(MqttInboundEnvelope envelope) { String body = new String(envelope.payload(), StandardCharsets.UTF_8); return new DeviceUpMessage(envelope.topic(), body); } @Override public MqttOutboundEnvelope encode(ProtocolSendRequest request) { return new MqttOutboundEnvelope( "device/reply", request.payload().body().getBytes(StandardCharsets.UTF_8), 1, false, Map.of("protocolId", request.protocolId())); } } ``` 定义业务处理器： ```java package demo.mqtt; import org.dw.mqtt.api.model.MqttInboundEnvelope; import org.dw.mqtt.api.spi.ProtocolMessageHandler; import org.springframework.stereotype.Component; @Component public class DeviceUpMessageHandler implements ProtocolMessageHandler { @Override public Class payloadType() { return DeviceUpMessage.class; } @Override public void handle(DeviceUpMessage payload, MqttInboundEnvelope envelope) { System.out.println("收到设备上报：" + payload.body()); } } ``` 统一发送业务消息： ```java package demo.mqtt; import org.dw.mqtt.api.gateway.ProtocolGateway; import org.dw.mqtt.api.model.ProtocolSendRequest; import org.springframework.stereotype.Service; @Service public class DeviceMessagePublisher { private final ProtocolGateway protocolGateway; public DeviceMessagePublisher(ProtocolGateway protocolGateway) { this.protocolGateway = protocolGateway; } public void publish(String body) { protocolGateway.send(ProtocolSendRequest.of( "device-up", new DeviceUpMessage("device/reply", body))); } } ``` 当业务确实需要直接操作原始 topic/qos/retain 时，可以注入 `MqttTransportClient`。 ### 默认能力与异常模型 默认启用以下全局入站能力： - `LoggingInterceptor`：记录基础接收日志 - `PayloadValidationInterceptor`：校验主题白名单与最大载荷 - `RateLimitInterceptor`：按配置限制入站吞吐 统一异常基类为 `MqttException`，常见子类包括： - `MqttConfigurationException` - `MqttConnectionException` - `MqttPublishException` - `MqttSubscribeException` - `ProtocolDecodeException` - `ProtocolEncodeException` - `ProtocolRouteNotFoundException` - `BusinessHandlerException` 所有异常统一携带 `errorCode`、`category`、`retryable`、`context`，入站未处理异常会发布 `MqttInboundFailureEvent`。 ## Jackson 模块 `quick-start-boot-json` 当前定位不是“可切换实现的通用 JSON 抽象层”，而是**面向 Jackson 的统一封装层**。 这样定义它的目的有两个： - 第一，让仓库内所有 Jackson 配置、序列化入口、异常语义和多态扩展点有统一收口，不再散落在各模块里各写一套。 - 第二，让业务应用接入时只需要关心统一入口，不需要自己拼装 `ObjectMapper`、时间模块、大整数序列化规则和多态注册逻辑。 当前它采用聚合工程结构，形式与 `quick-start-boot-spring-netty`、`quick-start-boot-cache` 保持一致： - 物理目录：`quick-start-boot-json/api` - 对外 `artifactId`：`quick-start-boot-json-api` - 物理目录：`quick-start-boot-json/core` - 对外 `artifactId`：`quick-start-boot-json-core` - 物理目录：`quick-start-boot-json/autoconfigure` - 对外 `artifactId`：`quick-start-boot-json-autoconfigure` - 物理目录：`quick-start-boot-json/starter` - 对外 `artifactId`：`quick-start-boot-json-starter` - 聚合目录 `quick-start-boot-json` 本身只负责组织子模块，不作为业务应用依赖入口 这几个目录名为什么要收短： - 物理目录短，避免出现 `quick-start-boot-json/quick-start-boot-json-core/...` 这种重复路径 - 对外 `artifactId` 仍然保持完整语义，业务接入和文档说明不会变模糊 - 后续如果继续扩子模块，路径层级也更容易维护 ### 推荐使用方式 业务应用依赖方式如下： - 这里依赖的是 `quick-start-boot-json-starter` - 它会把 Jackson 基础依赖和本项目自己的自动装配一起带进来 - 业务项目通常不需要单独再拼 `api/core/autoconfigure` ```xml org.dw quick-start-boot-json-starter ${project.version} ``` - 业务侧统一注入 `JsonOperations` - 不再使用旧的 `JsonUtils` - 不再在业务代码中重复创建全局 `ObjectMapper` 下面这个示例为什么这样写： - `JsonOperations` 是对业务开放的统一 Jackson 入口 - 业务服务只依赖这个接口，不需要知道底层 `ObjectMapper` 是怎么装配的 - `toJson` 调用走的是项目统一配置，因此会自动继承时间格式、大整数安全序列化等规则 ```java package demo.json; import org.springframework.stereotype.Service; import quick.start.boot.json.api.JsonOperations; @Service public class DemoJsonService { // 统一注入 Jackson 封装入口，而不是在服务里自己 new ObjectMapper private final JsonOperations jsonOperations; public DemoJsonService(JsonOperations jsonOperations) { this.jsonOperations = jsonOperations; } // 执行后会按框架统一规则完成序列化 public String toJson(Object value) { return jsonOperations.toJson(value); } } ``` ### 配置前缀 统一使用 `quick.start.boot.json`： 这段配置里最常用的几个参数含义如下： - `date-format` - 影响传统 `Date` / `Calendar` 类型的输出格式 - `local-date-time-format` - 影响 `LocalDateTime` 的统一输出格式 - `write-dates-as-timestamps` - 控制日期是否按时间戳输出；大多数业务场景建议保持 `false` - `safe-number-to-string` - 控制超出 JavaScript 安全整数范围的 Long / BigInteger 是否转字符串；前后端交互场景建议保持 `true` ```yaml quick: start: boot: json: date-format: yyyy-MM-dd HH:mm:ss local-date-time-format: yyyy-MM-dd HH:mm:ss pretty-print: false write-dates-as-timestamps: false fail-on-unknown-properties: false field-visibility: false safe-number-to-string: true ``` ### 扩展点 - 需要注册 JSON 多态子类型时，声明 `JsonSubtypeRegistrar` Bean - 上层模块不应再直接接管全局 `ObjectMapper` - `spring-boot-starter-netty` 已改为通过公开扩展点注册 `Message` 多态类型