做完一套企业级框架,我发现"讲明白"比"做明白"还难

大模型是大脑,skill 是小脑。但大脑再强,也得有人先把问题拆开。

最近花两个多月、烧了 7.4B token,做完一套企业级开发平台。代码能跑、架构能扛,我以为最难的部分已经过去了。

直到要把这套东西给团队讲出来。

那一刻才发现:做明白是一回事,讲明白是另一回事。 这篇就讲这两件事——上篇讲架构是怎么"做明白"的,下篇讲我是怎么把它"讲明白"的。两件事背后,其实是同一个道理。

上篇·做明白:这个架构到底在想什么

先说"做明白"。我不是说我做得有多好,是踩的坑够多,才慢慢摸到点门道。

▪ 为什么要有它:企业级开发的五类复杂度

做企业级平台,真正难的从来不是"实现某个功能",而是复杂度本身。我把它归结成五类:

1. 技术栈漂移每个项目自选技术栈、自选版本,维护成本爆炸。
2. 重复造轮子日志、缓存、配置、数据库连接……每个项目重写一遍。
3. 部署形态分裂业务从单体长成微服务,代码要重写一遍,没有平滑路径。
4. 边界腐化没有约束,模块间依赖越绕越乱,最后谁也不敢动。
5. 实现绑死业务代码和 Redis、MyBatis 这些中间件焊死,想换换不动。

这五类的共同点是:它们都是"变化",而且变化会传染。 所以这套架构要解决的不是某个具体问题,而是"怎么把变化关进笼子"。

▪ 我的解法:两层结构,依赖向内

整体分两层。

底层是 Core Runtime——最抽象的一层。它只干一件事:定义"应用到底是怎么跑起来的"这个抽象,以及应用层面的契约(我们定义了 8 个核心契约)。它纯 JDK、零依赖、一旦定下来就冻结不动,是整个架构的地基。

依赖向内的洋葱结构

稳定的 Core Runtime 在中心

业务组件和可替换适配器在外圈

这张图就是用 skill fireworks-tech-graph 生成的,正好呼应下篇要讲的事:一图胜千言,但图得自己先想清楚结构,再让工具去画。

Core Runtime 之上,是组件层,面向业务,由三个角色组成:

• Capability(业务契约 + SPI)定义"做什么"。每个能力是一组契约接口,业务代码面向它编程,不碰具体实现。
• Adapter(技术桥接)把上面的抽象契约,绑到具体技术上(Redis、MySQL、MinIO……)。换实现只换 Adapter,业务代码零改动。
• Starter(装配入口)把一切聚合起来、自动配置,是开发者唯一接触的入口。换不同的 Starter,就换了部署形态——单体或微服务。

这三层和 Core Runtime 之间有一条铁律:依赖只向内。 组件层依赖 Core Runtime,而 Core Runtime 永远不知道上层长什么样。

Starter → Adapter → Capability → Core Runtime

这种"洋葱 / 整洁架构"的画法,核心就一句话:外面怎么变都行,内核不动。

▪ 为什么能扩展:SOLID、高内聚低耦合

这套分层不是随便分的,底子是面向对象的 SOLID 原则、高内聚低耦合。好处很直接——水平和垂直两个方向都能扩展:

• 水平扩展加同类组件。想加一个新能力,就加一个 Capability;想换缓存实现,就换一个 Adapter。业务代码不用动。
• 垂直扩展Core Runtime 冻结不动,上面的组件层可以独立演进,甚至叠加新的层。底层稳,上层活。

(这里有个我自己挺得意的设计:同一套业务代码,换个 Starter,就能在单体和微服务之间零代码切换——调用是走本地还是走远程,框架自动决定,业务无感。)

▪ 光分层不够,还得能治理、能演进

架构设计得再漂亮,没有治理,半年就腐化成一团乱麻。我们不靠口头约定,而是上了三道硬防线:

• ArchUnit(编译期)把"依赖只能向内"这类规则写成测试,违背了 CI 直接挂。
• Maven Enforcer(构建期)在构建阶段强制检查模块依赖关系,不让不该有的依赖混进来。
• 可观测契约(运行期)Core Runtime 定义标准化的观测事件,Adapter 把它输出成监控指标和日志,运行时看得见。

把架构腐化挡在 CI 里,而不是等线上出事才发现。

演进上走"契约先行":Core Runtime 的契约一旦冻结就不变,组件层各自独立迭代;通过 BOM 统一管理版本,业务方升一个版本号,就拿到新能力和安全补丁,基本零成本。

上篇就到这。这不是一篇教你怎么当架构师的教程——只是我当时面对这些复杂度时,真实在想什么。

下篇·讲明白:做分享,比做框架还难

架构做完了,第二步是把它讲出来。这一步,我原以为最简单,结果最折磨。

▪ 第一关:到底讲什么

我是架构师,另一位同事是后端,他讲实战。

我一开始的想法很"架构师":既然是推广,那就讲这套架构有多强、多优雅,讲完大家自然就来用。可我看了下别的同事做分享,发现大家都只讲自己具体做了什么。

那就退一步:做个 demo,展示组件能力?但展示组件怎么用,又好像不是我这个架构师该讲的重点。

后来听了团队一句意见,我才转过弯:"你就讲讲开发这个框架的过程中,你具体做了啥。这个分享不是来教大家怎么当架构师的。"

照这个思路调整后,又冒出一个问题:我准备讲的实战部分,和后端同事要讲的重合了。最后的妥协是——把实战砍掉一大部分,只留一个整体介绍。

你看,光"讲什么"这一关,就来回改了好几轮。

▪ 第二关:PPT 怎么做

内容定了,接下来是 PPT。这一关,我翻了一连串车。

第一翻:让 AI 直接写讲稿。 把需求扔给大模型,出来的东西结构工整、辞藻华丽,但读完就是觉得"这不是我会说的话",念起来别扭。

第二翻:让 AI 按大纲直接生成 HTML slide。 大纲是我给的,但生成出来的 slide,布局、节奏、重点都不对味。

第三翻:去取经。 我找了团队里 PPT 做得很漂亮的一位同事,问他怎么搞的。他给了一套"正规流程":

先写大纲 → 再细化 → 给每个配图写好描述 → 用生图模型把图生成出来 → 把图片用相对路径引进 md 文件 → 最后再让 AI 生成完整的 HTML slide。

我老老实实照着做了。结果呢?仍然差强人意。 我一度怀疑,是不是因为他用的是海外模型,而我这边条件没他那么好。

▪ 关键一悟:全交给 AI,东西就不像你了

折腾到这,我才意识到真正的问题:

全部用 AI 生成 slide 和讲稿,会和你自己的表达习惯脱节,让别人觉得"这不是你自己的"。

AI 给的东西"看起来没问题",但没有你的节奏、你的取舍、你踩过坑之后才冒出来的那句重点。听众是很敏感的,他们一眼就能感觉到"这好像不是他写的"。

解法其实很朴素:自己先想一下——当时到底是怎么做这件事的?有哪些关键点?把这些捋成一个大纲。然后,再让 AI 在这个大纲上辅助你。

做明白,也要讲明白。讲不明白,往往不是因为表达能力差,而是因为你跳过了"自己先想清楚"这一步,直接把活整个外包给了 AI。

▪ 转折:换上 skill,才真正打通

想清楚之后,工具也跟上了。我发现有几款 skill 特别好用,最后是这么打通的:

• 用 fireworks-tech-graph(配合第三方代理接入的海外模型 GPT 太阳模型)生成技术架构图和 HTML slide;
• 再用 guizang-ppt-skill 把 HTML slide 转成 office 格式的 PPT。

这两个 skill 一上,之前"差强人意"的那段,才真正顺过来。

合·大模型是大脑,skill 是小脑

回头看这两段经历,你会发现它们其实是同一件事。

造框架(做明白):我作为架构师,先把要应对的复杂度想清楚、把角色和依赖关系定下来、把治理规则立住——这是"规划";然后才落到代码里。

讲框架(讲明白):我先回忆当时怎么做的、把关键点和大纲理出来——这也是"规划";然后才让 AI 和 skill 帮我出图、出 slide、转 PPT。

人负责拆解和规划,大模型负责理解和生成,skill 负责把规划精准地落地成具体产物。

套个比喻:大模型是大脑,skill 是小脑。 大脑规划完事情,小脑负责把动作精准地做出来。

但这里有个关键的限定,也是我最想说的:今天的大模型已经很强了,但还没有强到——你可以完全不关注过程、不把大问题拆成小问题,就直接拿到期望结果的程度。

你得自己当那个"先拆解、先出大纲"的人。这一步,AI 替不了你。

(再多说一句,我自己都觉得有意思:这套架构的哲学——Core Runtime 只定机制不定策略、对变化做分类——和我用 AI 的方式——自己定大纲、让 skill 去执行——其实是同一个哲学在两个层面的投影。稳定的核心管方向,可替换的零件管落地。)

写在最后

做完这套平台,最让我头大的真不是写代码,是把它说清楚。

代码是诚实的,跑一遍就知道对不对。但人不是代码。要让别人理解,你得一步一步拆开、揉碎,再重新拼起来。

所以无论你做的是框架、系统还是一个功能,都可以问问自己:你现在卡住的,到底是"做明白",还是"讲明白"?

一句话带走:别把大问题整个丢给大模型。自己当大脑先拆解,让 skill 当小脑去落地。

▪ 用到的开源工具,share 给大家

• fireworks-tech-graph —— 生成技术架构图(SVG,内置多种风格)
• guizang-ppt-skill —— 把 HTML slide 转成 office PPT

https://github.com/yizhiyanhua-ai/fireworks-tech-graph

https://github.com/op7418/guizang-ppt-skill

两个工具都是开源的。

小彩蛋：