🧑‍💻 简介

在日常开发中，写业务不难，难的是「工程一上来就乱」、「依赖一多就扯皮」、「构建一复杂就抓狂」。Zeka Stack 希望通过系统化的工程体系来解决上述问题.

它不是啥“重框架”，也不是为了造新轮子，而是一个工程提质提速的脚手架体系，用清晰的模块划分、统一的构建规范和灵活的生态扩展，让你在开写业务代码之前，项目骨架就已经整整齐齐、顺手好用。

一句话：让你团队少踩坑、构建不抓狂、协作有章法。

🧱 用 Zeka Stack 打造可维护的工程骨架

大家肯定遇到过这样的问题: 某次新项目启动，一开始小组成员各自拉模块、加依赖、写配置，几天后就发现：

• 依赖重复、冲突，启动报错；
• 构建流程不一致，有人能打包，有人不能；
• 模块命名五花八门，新人根本无从下手;

尤其是多个团队协同开发微服务系统时，经常遇到的问题包括：

🤔 为什么要谈架构哲学？

在企业开发中，我们开发的不是代码，而是系统。一个系统的演化速度、团队协作效率、未来的可维护性，全都深受其架构设计影响。

Zeka Stack 并不是随便拼凑起来的一堆模块，而是围绕以下几个核心哲学构建的：

• 关注分层，职责清晰，最小依赖原则；
• 自动化驱动开发体验统一化；
• 兼顾可维护性与可扩展性；
• 对工具链友好，对新成员友好，对变化友好。

这背后，是一套完整的 Clean Architecture 变体实践，下面我们来逐步解析。

📦 项目结构设计：层次就是边界

现实问题：

多个团队各建各的项目结构，没人关心“这段代码属于哪一层”，组件和业务混在一起，模块之间依赖混乱，导致代码可读性差，难以复用。

Zeka Stack 的解决方式：

“结构就是边界”——我们用目录层次划定职责边界，谁管依赖、谁是基础设施、谁是核心组件、谁是业务系统，一目了然。

Zeka Stack 将项目划分为如下主要目录:

1
2
3
4
5
6
7
8

zeka.stack/
├── arco-meta/             # 构建体系与依赖管理（最上层的规则制定者）
├── blen-toolkit/          # 通用工具集（跨层复用工具）
├── cubo-starter/          # 通用组件封装（核心逻辑）
├── cubo-starter-examples/ # 示例工程（面向开发者）
├── domi-suite/            # 微服务基础能力层（业务通用服务）
├── eiko-orch/             # 二开中间件/基础设施（强化基础能力）
└── felo-space/            # 实际业务系统模块（最终应用）

🎯 每一层在做什么？

💡 哲学核心：每一层只管自己该做的事，其他一律不越界！

这不仅让模块清晰可见，也让新成员一眼就知道“我要从哪里开始看”。每一个层级聚焦某一个领域，模块间低耦合、高内聚，组合使用则功能强大。

你可以把它想象成一个现代城市的建设蓝图：规划、道路、电力、水务、住宅、商业……各司其职，层级清晰。

🛠️ 一致的构建方式：让“构建方式不同步”成为过去式

💥 现实中的常见问题

在传统团队协作中，构建项目简直像“走迷宫”一样：

• 有人用命令行跑 mvn install，有人直接在 IDEA 点点点；
• 部署时得手动打包、上传、配置环境变量，每次都要翻阅历史命令；
• 有人跳过测试，有人没跳，测试结果不一致，线上出问题没人敢认锅；
• 换个开发机就报错，别人能跑你跑不了，构建行为没有统一标准。

久而久之，构建流程变成了“靠经验靠运气”的手工活儿，既浪费时间，又容易出错。

✅ Zeka Stack 的系统性解决方案

为了彻底摆脱这些低效操作，Zeka Stack 引入了一套统一构建机制，让构建行为变得像写代码一样“规范化”。

具体怎么做的？

• 每个聚合模块都包含标准化 pom.xml 与 .mvn 配置，不用手动拷贝，脚本自动生成；
• 内置 mvnw 包装器，确保构建环境一致，不依赖本地 Maven 安装；
• 全面支持并行构建、跳过测试、快速发布等常见构建参数，内置优化；
• 集成自研 publish-maven-plugin 插件，实现一键打包 + 部署，彻底抛弃手动操作。

🚀 最终成果：构建即契约，部署不求人

这一整套方案带来的变化是什么？

• 🧑‍💻 新人再也不用问“怎么打包”、“怎么部署”，一行命令搞定；
• 🤖 CI/CD 脚本统一，自动构建、测试、部署，一气呵成；
• 🧱 每个模块构建行为一致，避免“我这可以你那不行”的尴尬；
• 🚀 多服务发布效率倍增，原本需要手动部署半小时的流程，现在 1 分钟完成。

Zeka Stack 让构建行为变得“确定且可靠”，不再依赖个体经验，而是变成每个人都能依赖的系统能力。

⚙️ 自动化脚本：不是花哨，是生产力

在一个包含多个 Maven Git 仓库的项目体系中，最大的挑战之一就是 初始化和组织这些模块的繁琐流程。

假设你只是业务开发人员，直接关注 felo-space 模块也许够用，依赖都能从 Maven 中央仓库或私服获取，没啥问题。

但一旦你想 深入理解 Zeka.Stack 的完整体系、研究架构演进、修改某个底层组件或者调试 Starter，你就会碰到大问题：

💥 常见痛点

• 要查找十几个 Git 仓库，地址分散、名称类似，容易搞错；
• 每次都得手动 clone，对应到目录结构，全靠自己“比葫芦画瓢”；
• 有些模块缺 .mvn 配置，IDE 配置一团乱，版本冲突频繁。

🧠 Zeka.Stack 是怎么解决的？

我们在 zeka-stack/supports 仓库中专门提供了 init-stack.sh 脚本，一键解决所有繁琐操作：

1

bash <(curl -fsSL https://raw.githubusercontent.com/zeka-stack/supports/main/scripts/init-stack.sh)

你只需要执行这个命令，它会：

• ✅ 按照统一规范创建 zeka.stack/ 项目根目录；
• ✅ 克隆所有子模块到指定层级，结构完全一致；
• ✅ 自动生成每层目录下的 pom.xml 聚合文件；
• ✅ 下载统一的 .mvn 配置，确保构建行为一致；
• ✅ 附带 Maven Wrapper（mvnw）一键构建，避免“版本地狱”。

🎯 背后的设计初衷

Zeka.Stack 的分层架构本质是为了提升协作效率与认知一致性。如果每位开发者对模块的理解、目录的组织都不一样，那就很难做到长期可维护。

所以我们不仅构建了分层结构，还将这套结构“写进脚本”里，让结构标准变成工具行为，不再依赖文档、口头传达或者“老员工带新”。

🧩 为什么自动生成 pom.xml 是必须的？

这可不是为了形式感：

• 提供统一构建入口：只需一次 mvn install，即可构建全部模块；
• 支持IDE 一次性导入所有模块，IntelliJ 识别聚合结构，不再项目乱飞；
• .mvn 目录中的本地配置（线程数、跳测试、私服地址等）确保构建行为一致；
• 多模块构建体验一致，团队间不再为“你那怎么能编译过”而争吵。

🧠 一句话总结：

Zeka.Stack 的脚本不是在替你干活，而是在帮你省心、省时、省麻烦，让“规范”成为默认，而不是靠记忆维持。

📐 分层架构的价值：不是“干净”，而是“高维度可控性”

Zeka Stack 的分层架构并不是为了“好看”或者“对齐视觉强迫症”，而是一种系统性的架构哲学实践，背后藏着三个关键动机：

✅ 1. 降低认知负担：让新成员少走弯路

痛点：

传统大型项目，新人一上来就被无数模块、混乱依赖、奇怪目录劝退。看了一圈后只剩下一个疑问：“我到底要从哪里开始？”

Zeka Stack 的做法：

• 每一层模块语义清晰、职责单一；
• 新成员只需聚焦业务模块（比如 felo-space），其他能力按需引入；
• 所有公共依赖从哪来、技术组件在哪，结构明晰，几乎无需口头解释。

📌 开发者不再“从 0 猜起”，而是“从结构入手”，快速聚焦业务。

✅ 2. 模块独立部署：让测试更轻、上线更快

痛点：

过去一个功能依赖多个模块，一动就得全量构建、全量部署，严重拖慢上线节奏。CI/CD 也跟着“拖家带口”，构建时间越来越久。

Zeka Stack 的做法：

• 每个模块独立 Git 仓库，独立生命周期；
• 聚合模块按目录分组构建，避免无关构建干扰；
• 提供丰富的组件示例，快速验证核心功能或新组件特性。

📌 开发者可以只构建自己关心的部分，部署成本低，验证更迅速。

✅ 3. 解耦可演进：重构成本降到最低

痛点：

传统项目中，换个缓存组件、替个网关逻辑，改起来牵一发动全身，甚至连启动都失败。架构“固化”，成了进化的绊脚石。

Zeka Stack 的做法：

• 技术能力组件（如缓存、中间件、认证）集中在 eiko-orch 层；
• 技术通用逻辑统一封装为 starter，随时可替换、调试、版本回退；
• 新增能力或重构模块，只需在当前层内扩展，对上不干扰，对下可复用。

📌 业务依赖“能力”，而不是耦合“具体实现”。

🧠 核心结论

Zeka Stack 的分层架构真正做到：可读、可测、可替换、可演进。

你不必一次掌握所有，也不用一次构建全部，更不怕一次改动牵连全局。每个模块都像是积木，有边界、有接口、有规范，想组合就组合，想替换就替换。

🎉 Maven 依赖管理：扼杀版本冲突于萌芽状态

💥 现实痛点：版本地狱，令人抓狂

在多模块、多团队的项目中，Maven 依赖管理几乎是最容易引发血案的环节：

• 某个业务模块手动升级了一个依赖，另一个模块没动，结果构建失败；
• 有些依赖 transitively 引入了多个版本，启动时报错，难以排查；
• 开发人员想升级一个库，得反复试错 + 查文档，担心牵一发动全身。

最终结果？代码能写，项目跑不了。

✅ Zeka Stack 的系统级解决方案

Zeka Stack 彻底从 Maven 的根基开始治理依赖问题，采用了企业级 BOM 管理体系：

• 🧩 arco-meta 顶层 BOM 项目：集中定义所有常用依赖版本，做到“一处定义，全局引用”；
• 🧱 父模块分层治理：
  • starter-parent：技术组件开发专用；
  • company-parent：业务模块继承用；
  • distribution-parent：支持一键部署需求；
• 🛠️ 构建工具集成依赖检查插件，在构建阶段就能识别版本冲突，提前预警。

🚀 使用体验：一行配置，全项目同步

Zeka Stack 让依赖管理变得前所未有的简单：

• 所有模块只需继承相应父模块，无需单独声明依赖版本；
• 升级依赖只需改 BOM 中一处配置，其他模块自动同步；
• 无论是构建、运行、打包，都不会再遇到神秘冲突或版本漂移的问题。

🎯 本质价值

Zeka Stack 并不只是“统一依赖”，而是把 Maven 这匹“野马”变成了一套可控的依赖规范机制。

开发者不再为“版本怎么写”、“能不能升级”焦虑，而是可以专注在业务与功能实现本身。

🧠 架构哲学关键词总结

💥 Zeka Stack 带来了哪些价值？

🙋‍♂️ 常见 FAQ

❓ 为什么每个子目录都要一个聚合 pom.xml？

统一构建、IDE 支持、便于 CI/CD 分模块执行，也能避免各自为政。

❓ 子模块太多，如何组织依赖不混乱？

Zeka Stack 通过 arco-meta 层管理 BOM + starter 抽象组件，大大减少手动依赖编写和冲突风险。

❓ 如果我不想用脚本，能手动做吗？

可以。手动创建 pom.xml 和 .mvn，或直接复制自 supports 仓库。

❓ 我已经有一套自己的项目模板了，Zeka Stack 有什么不一样？

很多人也写过脚手架，但 Zeka Stack 不只是“模板”或“代码生成器”，它更像是一套演进体系：

• 结构不是拍脑袋，而是经过多项目演化提炼而来；
• 更关注构建规范、组织方式与团队协作效率。

💬 写在最后

Zeka Stack 不是一个框架，而是一种理念：

结构清晰，协作顺畅，自动高效，持久可维护。

如果你对企业级多模块项目感到痛苦、开发效率缓慢、维护负担繁重，或许是时候尝试 Zeka Stack 式的架构哲学。