把工程约束写进结构的微服务骨架Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0一篇基于真实源码的技术全景 · DDD 四层 CQRS · 27 个即插即用 Starter搭过微服务的人大概率都栽过同样几个坑。公共包越滚越大改一行牵一发动全身能力无法复用每个新服务都重配一遍说好的分层写着写着 Controller 里就开始写 SQL配置散落各处换个数据库地址要翻好几个文件。MateCloud 想给的是另一种答案。01一句话理念五层架构MateCloud 的设计理念可以浓缩成一句话——极简公共层、各司其职、Starter 即插即用能力。它不追求“大而全”把你用不上的东西塞满也不甘于“散而乱”让每个新服务重踩一遍坑。技术底座足够新Java 21、Spring Boot 4.0.7、Spring Cloud 2025.1.2、Dubbo 3.3.6、Spring AI 2.0。开源版含 网关 / 认证 / 系统管理 / 通知 四个核心服务外加 27 个 Starter并支持单体与微服务双形态一键切换。整体是清晰的五层结构。关键设计是mate-common 是纯类型、零自动装配——它只提供 BaseEntity、Result、雪花 ID 这类基础类型绝不夹带任何 Spring 配置。所有“能力”都下沉到 Starter谁需要谁引入。02DDD 四层把架构约束写进代码结构MateCloud 不只是“能跑的微服务”它是一套 DDD 落地范本。每个业务模块严格遵循四层结构包名即架构依赖方向一律指向领域层领域层不知道 Spring、MyBatis、数据库的存在。这套结构背后有五条铁律领域层零框架依赖——不允许出现 Spring / MyBatis 注解纯业务逻辑仓储接口在 domain实现在 infrastructure——依赖倒置聚合根强制不变量——状态变更只能走聚合方法CQRS 读写分离——CommandService 与 QueryService 泾渭分明MapStruct 全量转换——绝不手写 get/set 拷贝字段。“聚合根强制不变量”不是口号。以用户实体为例冻结 / 已删账号禁止自助改密这条业务规则被守卫在实体方法里任何路径都绕不过去mate-system · domain/model/entity/User.javapublic void changePassword(String encodedPassword) { checkActive(); // 冻结/删除账号禁止自助改密this.password encodedPassword; }private void checkActive() { if (isFrozen()) throw UserException.of(USER_IS_FROZEN); if (isDomainDeleted()) throw UserException.of(USER_IS_DELETED); }好处显而易见新人接手看包名就懂分层重构业务改动被牢牢限制在该在的层里业务规则写在聚合里谁都无法绕过。0327 个 Starter能力像积木一样拼装MateCloud 把每一项能力都封装成独立 Starter引入即生效不引入零负担。核心 7 个几乎必用业务和进阶按需添加。分类代表能力核心 7web · ds(MyBatisDruidFlyway) · cache(双级缓存分布式锁雪花ID) · nacos · rpc(Dubbo) · sa-token · monitor业务mq(领域事件) · job(XXL-Job) · security(限流/审计/幂等/数据权限/验签) · file(MinIO) · excel · tenant(多租户)高级 contribai · gray(灰度) · seata(分布式事务) · sentinel(熔断限流) · sharding(分库分表) · flow · rule · test背后是 Spring Boot 3 的自动装配机制Starter 在AutoConfiguration.imports里声明配置类配置类用条件注解按依赖存在性决定装哪些切面——引入即生效、缺依赖则静默降级。mate-security-starter · SecurityAutoConfiguration.javaBeanConditionalOnBean(RedissonClient.class) // 有 Redisson 才装限流切面public RateLimitAspect rateLimitAspect(RedissonClient redisson) { return new RateLimitAspect(redisson); }于是一个典型业务服务的依赖往往就是“核心 7 三两个业务 Starter”application.yml只有十来行——能力靠拼装不靠复制粘贴。04一个 Tool 注解业务方法变 AI 工具很多团队给系统接 AI最后都停在了“一个会聊天的机器人”它能答通用问题却碰不到你的业务数据。MateCloud 的mate-ai-starter基于 Spring AI 2.0把这层胶水全包了——给任意 Spring Bean 的方法加一个 Tool 注解它就自动成为 AI 可调用的工具。mate-system · trigger/ai/DictAiTools.javaTool(description List all dict entries for a given dictType.)public ListDictData listDictByType( ToolParam(description Dict type code, e.g. user_status) String dictType) { return dictQueryService.findByType(dictType); }没有手写 JSON Schema没有工具注册表没有胶水代码。背后是一个BeanPostProcessor容器启动时扫描每个 Bean 的方法凡带 Tool 的就构建成MethodToolCallback注册进中央注册表。而这个注册表本身就是ToolCallbackProvider可以直接喂给 ChatClient。最妙的是——同一批工具会同时暴露给四个入口REST、SSE 流式对话、CLImate ai chat、以及 MCPmate --mcp。写一次业务方法AI 从任何入口都能调用。模型侧支持 6 家 LLMAnthropic、OpenAI、智谱、Minimax、DeepSeek、Ollama。05网关 HMAC 签名堵住身份头伪造微服务里有个经典的越权漏洞网关鉴权后把用户身份以明文头X-User-Id透传给下游。可一旦攻击者绕过网关、直连服务端口随手发一个X-User-Id: 1就能冒充超管。MateCloud 的解法网关持有一把共享密钥对整套身份头 时间戳做 HMAC-SHA256 签名下游用同一把密钥重算比对。攻击者没有密钥就无法为任何伪造的身份头组合算出合法签名。mate-base · GatewaySignature.java纯 JDK网关与下游共用一份// 规范化载荷每个身份头值换行拼接再接时间戳for (String header : AuthHeaders.ALL) sb.append(lookup.apply(header)).append(\n);return hmac(secret, sb.append(ts).toString()); // HmacSHA256对整套身份头签名而不只是 user id意味着篡改任意一个头都会让签名失效时间戳则限定了重放窗口。网关若没配置密钥直接 fail-fast 拒绝启动——安全默认是“打开”的。06单体 / 微服务一个属性切换微服务的运维成本早期团队未必扛得住。MateCloud 让同一套业务模块既能拆成微服务Dubbo Nacos又能打成单体 JAR 进程内直调。切换靠一个属性而非改代码。秘密在于依赖倒置留下的“接缝”跨服务调用都走一个端口接口如UserQueryPort由条件注解决定注入哪个适配器mate-monolith · LocalUserQueryAdapter.javaComponentConditionalOnProperty(name mate.rpc.mode, havingValue local)public class LocalUserQueryAdapter implements UserQueryPort { // 单体进程内直调 mate-system 的 query service// 微服务换成 DubboUserQueryAdapter 走 Dubbo接口不变}本地开发用单体、单进程起得快生产部署拆微服务、按需扩缩。业务代码一行不用改。07技术栈全景与三分钟启动以下版本均取自项目根pom.xml的真实依赖声明核心框架Java 21 · Spring Boot 4.0.7 · Spring Cloud 2025.1.2 · Spring AI 2.0微服务生态Nacos 3.2 · Dubbo 3.3.6 · Sa-Token 1.45 · Spring Cloud Gateway · Sentinel / Seata数据与缓存MySQL 8.3 · MyBatis-Plus 3.5.16 · Druid · Flyway · Redisson 4.5 · Caffeine Redis 双级缓存中间件 / 存储RabbitMQ(领域事件延迟队列) · XXL-Job · MinIO 8.5 / AWS S3工具库MapStruct 1.6 · Lombok · Hutool · fastjson2 · EasyExcel · Smart-Doc(非 Swagger)跑起来只要四步# 1. 编译mvn clean install -DskipTests# 2. 启动基础设施MySQL Redis RabbitMQ Nacos MinIOmake infra-up# 3. 初始化 Nacos 配置java -jar mate-cli/target/mate-cli.jar config init# 4. 启动全部服务Flyway 首启自动建表 内置 admin/admin123make up数据库无需手动建表——mate-system 首启时 Flyway 自动执行迁移完成建表、内置账号、角色、菜单与字典的初始化。08写在最后好架构是“约束”出来的MateCloud 的价值不在于堆了多少组件而在于用清晰的分层、即插即用的能力包、严格的 DDD 约束、AI 原生的工具编排、内建的安全加固把“好的工程实践”固化进了项目结构本身。想加能力引一个 Starter。想接 AI给方法加个 Tool。想从微服务变单体改一个属性。它不是“能跑的 Demo”而是一套把工程约束前置到脚手架里的开源底座。全部代码 Apache-2.0 协议开放欢迎 star、fork、提 PR。TO BE CONTINUED 但这只是一副骨架还记得第 04 节那个Tool吗如果说 MateCloud 是一副长好了的骨架那接下来的两件事是让它“长出手脚”、再“学会繁殖”。 MateClaw · 一个你 IT 部门敢签字的 AI Agent 平台Spring Boot inside一个 JAR 就能交付。它不做“聊天机器人”做的是有角色、有目标、能审批的数字员工ReAct Plan-and-Execute14 模型多厂商容灾自动切换、带来源引用的 LLM Wiki 知识库、RBAC 审批门 全链路审计、Web / 桌面 / 嵌入组件 / 8 个 IM 多端接入。self-hosted$0数据和密钥都在你自己手里。而它和 MateCloud 的接缝正是那个 Tool——把 mate-cli 与业务工具接成 MCP数字员工就能直接操作你的微服务集群查服务、调 RPC、生成模块、迁移数据库。不是 AI 帮你写代码是 AI 直接开你的系统。 从“骨架”到“平台 应用”生态MateCloud 的下一步是从一套单体骨架进化成一个PlatformCRM、商城、短视频、教学、OA…… 一个个子系统长在同一副底座上通过 mate-api 的 RPC、领域事件、网关统一路由共享同一个平台。而生成一个新子系统只需要——你大概已经猜到了——一条 mate-cli 命令。当一副骨架学会了自己生长微服务开发会变成什么样子—— 下一篇我们聊聊 MateClaw 与 MateCloud 的产品生态。官网mate.vipMateCloud开源骨架github.com/matevip/matecloudMateClawAI Agent 平台github.com/mateaix/mateclaw技术栈 · 协议Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 · Apache-2.0