架构筑基：驾驭 AI 编程的底层方法论

内容提要

当 GPT、Claude、Gemini 等大模型让"几分钟写出可用代码"成为现实，一个新的困境却悄然蔓延——代码越写越多，项目却崩溃得越来越快。

问题不在 AI 的能力，而在缺少架构约束。AI 是世界上最快的施工队，但如果没有施工图纸，它大概率只会把砖越堆越高。好架构会被 AI 复制，坏架构同样会被放大——几十次迭代之后，原本清晰的工程就可能沦为成千上万行难以维护的"大泥球"代码。

本书正是一部为 AI 编程时代量身定制的架构实战指南。作者从真实企业级项目（开源框架 miniagent）的工程实践中提炼经验，不堆砌空洞理论，而是将软件架构的经典理念——前后端分离、领域驱动设计、分层整洁架构、依赖注入、面向切面编程、统一鉴权、多级缓存、异步并发、流式推送、插件化扩展——逐一转化为 AI 能读懂、可执行的项目规则与提示词模板。每章遵循统一节奏：通俗比喻引入概念 → 架构规范拆解 → 收益分析 → AI 失控现场还原 → 提示词落地 → 正面代码产出，让读者不仅知其然，更能直接照着做。

不同于传统架构书籍面向资深工程师的厚重论述，本书刻意面向更广泛的读者：中新手开发者、技术管理者、正在尝试用 AI 编程的跨界开发者。全程以生活化的比喻替代晦涩术语，用"反面教材 + 正面产出"的对照讲透每一个知识点。读完本书，您将完成一次身份跃迁——从亲手砌砖的"码农"，升级为给 AI 立规矩、搭骨架、做审查的"系统指挥官"。

AI 提升开发速度，架构决定软件能走多远。

1.1　一个令人困惑的现象：代码越多，项目越脆弱
1.2　AI 的三大天然缺陷：近视眼、坏结构复制、安全盲区
1.3　从"砌砖工"到"施工总指挥"：人类工程师的新角色
1.4　实战对比：无约束自由发挥 vs 架构约束下的代码质量
1.5　人类与 AI 的新分工：谁负责宏观决策，谁负责微观实现

第二章　架构图纸 Prompt 化：如何用 Context / Rule 约束 AI 的编码边界

2.1　从设计文档到项目级规则：架构规范的载体变迁
2.2　主流 AI IDE 的规则机制（Cursor / Copilot / Claude Code / AGENTS.md）
2.3　规则编写三原则：明确边界、制定标准、搭好骨架
2.4　企业级架构规则模板实战
2.5　规则生效的关键：让 AI 每次都先读"施工守则"

板块一：顶层架构拆分

第三章　前后端分离：约束 AI 分工，避免接口耦合与职责错乱

3.1　技术名片与通俗比喻：前端是门面，后端是后厨
3.2　架构规范：接口契约先行，前后端各司其职
3.3　AI 失控现场：把数据库操作写进前端页面逻辑
3.4　提示词落地：前后端分离的项目规则模板
3.5　正面产出：前后端清晰分离的工程结构

第四章　领域驱动设计：给 AI 划定上下文边界，告别"大泥球"代码

4.1　技术名片与通俗比喻：大型医院的部门划分
4.2　限界上下文——DDD 对 AI 编程最实用的概念
4.3　四条架构规则：按业务划分、不越界操作、接口协作、统一语言
4.4　AI 失控现场：一个接口里混入六种职责
4.5　提示词落地：把领域边界写成可执行规则
4.6　正面产出：miniagent 的领域边界设计

第五章　分层整洁架构：标准化工程目录结构，防范 AI 越界调用

5.1　技术名片与通俗比喻：大楼的楼层功能规划
5.2　整洁架构的核心：依赖方向只能由外向内
5.3　分层规范：API 层 / Service 层 / Repository 层 / 基础设施层
5.4　AI 失控现场：Router 直接操作数据库，Service 感知 HTTP 协议
5.5　提示词落地：分层架构的禁止与强制规则
5.6　正面产出：miniagent 的六层目录结构解析

第六章　异常与统一封装架构：规范统一返回值、全局异常与入参校验

6.1　技术名片与通俗比喻：快递包裹的统一包装标准
6.2　统一返回值规范：所有接口遵循一致的数据结构
6.3　全局异常处理：集中捕获、分类处理、统一格式化
6.4　入参校验前置：用类型安全替代手写 if 判断
6.5　AI 失控现场：每个接口自己 try-catch、返回结构各不相同
6.6　提示词落地与正面产出：统一响应模型与全局异常中间件

板块二：代码解耦与接口规范

第七章　依赖注入：禁止 AI 硬编码实例化，提升可测试性与扩展性

7.1　技术名片与通俗比喻：餐厅厨师与提前备好的食材
7.2　反面教材：AI 的"自由发挥"与四大隐患
7.3　五条架构规则：不主动 new、集中创建、构造注入、API 用 Depends、禁止绕过容器
7.4　这样做有什么好处：可替换、可测试、资源统一、配置切换
7.5　AI 失控现场：每个 Service 自己创建数据库和 LLM 客户端
7.6　提示词落地：DI 规则模板
7.7　正面产出：miniagent 的 ServiceContainer 依赖注入实现

第八章　面向切面编程：指导 AI 抽离横切逻辑，日志、鉴权、埋点不再重复编写

8.1　技术名片与通俗比喻：高速公路的统一收费站
8.2　横切关注点识别：哪些逻辑在到处重复
8.3　架构规范：用装饰器 / 中间件 / 拦截器统一处理横切逻辑
8.4　AI 失控现场：每个接口手写日志和权限判断
8.5　提示词落地：横切逻辑抽离规则
8.6　正面产出：装饰器鉴权与日志中间件的工程实现

第九章　日志体系架构：规范 AI 日志打印格式、分级、链路埋点，杜绝散乱无效日志

9.1　技术名片与通俗比喻：医院的病历记录制度
9.2　日志规范：分级体系、结构化格式、上下文字段
9.3　链路追踪：请求 ID 贯穿全调用栈
9.4　AI 失控现场：到处 print 散乱信息、日志无级别无结构
9.5　提示词落地：日志规范模板
6.6　正面产出：统一日志中间件与链路 ID 传递

第十章　RESTful 与契约优先：规范接口定义，统一接口设计范式

10.1　技术名片与通俗比喻：交通规则与道路标识
10.2　RESTful 设计规范：资源命名、HTTP 方法语义、状态码约定
10.3　契约优先：先定义 Schema，再生成代码
10.4　AI 失控现场：接口风格混乱、命名随意、状态码滥用
10.5　提示词落地：接口设计规范模板
10.6　正面产出：统一的 API 契约定义实例

板块三：安全、存储与工程基建

第十一章　统一鉴权（JWT）与 RBAC：标准化 AI 令牌签发、校验逻辑

11.1　技术名片与通俗比喻：小区门禁卡与楼层权限
11.2　JWT 架构规范：签发、校验、刷新、失效的标准流程
11.3　RBAC 权限模型：角色与权限的映射设计
11.4　AI 失控现场：业务代码里散落零散 if 权限判断
11.5　提示词落地：鉴权统一规则模板
11.6　正面产出：统一鉴权中间件与权限装饰器

第十二章　缓存与多级存储：纠正 AI 无脑直查数据库，规范缓存击穿/穿透处理

12.1　技术名片与通俗比喻：图书馆的阅览区与书库
12.2　多级缓存架构：本地缓存 / 分布式缓存 / 数据库
12.3　三大经典问题防御：缓存穿透、缓存击穿、缓存雪崩
12.4　AI 失控现场：每次请求都直查数据库、缓存无失效策略
12.5　提示词落地：缓存使用规范模板
12.6　正面产出：缓存封装层与失效通知机制

第十三章　跨多数据源架构：规避兼容不同的数据库

13.1　技术名片与通俗比喻：跨国公司的多地区仓库协同
13.2　多数据源场景识别与常见陷阱
13.3　架构规范：统一抽象层、Repository 模式、事务边界管理
13.4　AI 失控现场：业务代码直接绑定具体数据库方言
13.5　提示词落地：多数据源隔离规则
13.6　正面产出：跨数据源 Repository 抽象实现

第十四章　中心化配置与 I18n：严格禁止 AI 魔法值与硬编码参数

14.1　技术名片与通俗比喻：中央空调温控与多语言广播
14.2　中心化配置规范：环境隔离、动态加载、敏感信息保护
14.3　国际化（I18n）规范：文案与代码分离、多语言资源管理
14.4　AI 失控现场：密钥硬编码、提示词散落、文案写死在逻辑中
14.5　提示词落地：禁止魔法值与硬编码规则模板
14.6　正面产出：统一配置中心与 I18n 资源结构

板块四：高性能通信与拓展架构

第十五章　异步与并发架构：纠正 AI 同步阻塞写法，提升系统吞吐能力

15.1　技术名片与通俗比喻：单窗口银行与多窗口政务大厅
15.2　异步架构规范：async/await 纪律、线程池/协程选型
15.3　并发控制：连接池管理、信号量限流、超时熔断
15.4　AI 失控现场：同步阻塞调用拖垮整个接口性能
15.5　提示词落地：异步编程规范模板
15.6　正面产出：异步 Service 与并发安全的数据访问

第十六章　长连接与流式推送：规范 SSE/WebSocket 实现，替换无效轮询

16.1　技术名片与通俗比喻：对讲机 vs 反复打电话确认
16.2　通信范式选型：轮询 / 长轮询 / SSE / WebSocket
16.3　架构规范：连接生命周期管理、消息协议设计、断线重连
16.4　AI 失控现场：前端每秒轮询、后端无连接管理
16.5　提示词落地：长连接通信规范模板
16.6　正面产出：SSE 流式推送与会话管理的工程实现

第十七章　插件化与扩展点：引导 AI 模块化插拔开发，功能解耦便于迭代

17.1　技术名片与通俗比喻：积木式插座与可更换零件
17.2　插件架构核心：接口抽象、注册机制、生命周期管理
17.3　扩展点设计规范：开闭原则在 AI 编程中的落地
17.4　AI 失控现场：新功能直接修改核心代码、到处打补丁
17.5　提示词落地：插件化开发规则模板
17.6　正面产出：Tool 注册机制与可插拔扩展点实现

收尾篇

第十八章　架构师 + AI：从"码农"到"系统指挥官"的职业跃迁

18.1　回顾：十七个架构理念如何串联成完整的 AI 工程体系
18.2　AI 编程时代的人类核心价值：理解业务、设计架构、制定约束、审查决策
18.3　架构不是 AI 的束缚，而是 AI 高质量发挥的边界与导航系统
18.4　从工具使用者到系统指挥官：写给每一位 AI 时代的开发者

架构筑基：驾驭 AI 编程的底层方法论#

内容提要#

目录#

导论篇：为什么 AI 时代更需要架构#

板块一：顶层架构拆分#

板块二：代码解耦与接口规范#

板块三：安全、存储与工程基建#

板块四：高性能通信与拓展架构#

收尾篇#