代码架构 on 有趣的AI

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

Sat, 01 Aug 2026 00:00:00 +0000

AI 负责“手速”，人类负责“图纸”。
本专栏概述了常见的软件架构设计技巧，旨在教你如何通过“架构设计”与“规则约束（Prompt / Rules）”，驯服 AI 编写出工业级、高维护性的高质量代码，避免陷入“代码越写越多、系统崩溃越快”的泥潭。

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

Mon, 17 Aug 2026 00:00:00 +0000

AI 写代码很快，但也很容易出现一种典型问题：

每增加一个功能，就继续往核心代码里加 if/elif。

例如：

if domain == "legal":
    ...
elif domain == "finance":
    ...
elif domain == "medical":
    ...

功能少时没有问题，但随着类型不断增加，核心模块会越来越臃肿，每次新增功能都可能影响已有逻辑。

更合理的做法是提前定义：

Plugin：插件 Extension Point：扩展点

让 AI 遵循一个原则：

新增能力优先增加模块，而不是修改核心流程。

架构师 + AI：从“码农”到“系统指挥官”的职业跃迁

Mon, 17 Aug 2026 00:00:00 +0000

这一系列文章，我们讨论了前后端分离、DDD（Domain-Driven Design，领域驱动设计）、分层架构、DI（Dependency Injection，依赖注入）、RESTful（Representational State Transfer，表现层状态转移）、异步并发、SSE（Server-Sent Events，服务器发送事件）、插件化以及 Project Rules（项目规则）等一系列工程方法。

看起来讲了很多技术，但它们最终都指向同一个问题：

当 AI 已经能够大量生成代码，程序员最重要的能力还是什么？

答案正在从：

“如何把代码写出来”

转向：

“如何设计一个让 AI 能够正确写代码的系统”。

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

Sun, 16 Aug 2026 00:00:00 +0000

在 Web 系统里，有一类需求特别容易被 AI 写成“能跑，但很笨”的实现：

前端：
每 1 秒问一次服务器
“任务完成了吗？”

服务器：
“没有。”

1 秒后再问：
“完成了吗？”

这种方式叫：

Polling：轮询

偶尔查询一次状态没有问题，但如果是 AI 流式回答、OCR 进度、文档解析、知识库构建、后台任务状态等实时场景，高频轮询会产生大量无效请求。

更合适的方案通常是：

SSE（Server-Sent Events，服务器发送事件）

或者：

WebSocket：Web 套接字，全双工长连接通信协议

核心思想只有一句：

不要让客户端不停问“有消息了吗”，而是让服务器有消息时主动推送。

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

Sat, 15 Aug 2026 00:00:00 +0000

AI 写代码有一个很常见的问题：

代码能跑，但一到多人访问就变慢。

尤其在 Python Web 项目中，即使使用 FastAPI，函数也写成了 async def，数据库查询、HTTP 请求、大模型调用等操作仍然可能同步阻塞。

问题的关键在于：

async def 只是异步函数的入口，并不会自动把里面的同步代码变成异步代码。

对于 Web 服务、知识库和智能体平台这类大量依赖外部 I/O 的系统，建立统一的异步与并发架构，是提升系统吞吐能力的重要基础。

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

Fri, 14 Aug 2026 00:00:00 +0000

AI（Artificial Intelligence，人工智能）写代码有一个很常见的问题：

它特别喜欢“顺手写死”。

timeout = 30
max_retries = 3
model = "qwen3:14b"
raise ValueError("用户不存在")

单独看，每一行都没什么大问题。

但当几十个模块都有自己的 30、3、模型名称和提示文案时，维护者就会开始头疼：

这些值是什么意思？在哪里修改？换环境怎么办？支持英文怎么办？

因此，AI 编程项目最好提前建立一条明确的架构规则：

具有业务含义、环境差异或用户可见含义的值，不允许散落在业务代码中。

解决这个问题，主要依靠两套机制：

中心化配置 + I18n 国际化。

跨多数据源架构：让 AI 不再绑死数据库

Thu, 13 Aug 2026 00:00:00 +0000

很多项目一开始只有一个数据库。于是 AI 很自然地写出：

async def get_user(user_id: int):
    async with sqlite_session() as session:
        ...

或者更直接：

conn = sqlite3.connect("app.db")

功能当然能跑,但问题会在以后出现。

今天是 SQLite ，明天可能要换成 PostgreSQL …

随着代码规模的增加，项目很快就会变成：

业务代码和具体存储技术绑死。

这正是 Multi-Data-Source Architecture（多数据源架构） 要解决的问题。

缓存与多级存储：别让 AI 无脑直查数据库

Wed, 12 Aug 2026 00:00:00 +0000

AI 写业务代码时，有一种非常典型的倾向：

async def get_user(user_id: int):
    return await user_db.get_by_id(user_id)

功能没错。但如果项目里所有读取都变成：

查用户 → 数据库
查权限 → 数据库
查模型 → 数据库
查 Agent → 数据库
查知识库 → 数据库
查配置 → 数据库

系统很快就会进入一种状态：

每个函数都很正确，整体架构却越来越低效。

问题不只是“有没有缓存”，而是：

AI 没有先判断：我要复用的是一个“值”，还是一个“已经构建好的运行对象”？

这正是 miniagent 当前缓存架构最值得借鉴的地方。

它不是简单地做一套缓存，而是明确分成两类：

Object Cache
对象缓存

Value Cache
值缓存

两者解决的根本不是同一个问题。

统一鉴权：标准化 AI 令牌签发、校验逻辑

Tue, 11 Aug 2026 00:00:00 +0000

在 AI 编程里，有一类代码特别容易“越写越多、越写越乱”：

if user.role != "admin":
    raise HTTPException(status_code=403)

换一个接口，AI 又写：

if "user:delete" not in user.permissions:
    raise ForbiddenError()

再换一个接口：

if current_user.id != owner_id and not current_user.is_admin:
    raise HTTPException(status_code=403)

每一段单独看都说得过去。但当项目里出现几十种这样的 if，权限系统实际上已经失控了。

真正成熟的做法不是“让 AI 更认真地写 if”，而是建立一套统一的：

身份认证 + 权限模型 + 权限执行机制

其中最常见的一种权限模型，就是 RBAC（Role-Based Access Control，基于角色的访问控制）。

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

Mon, 10 Aug 2026 00:00:00 +0000

在 AI 编程时代，有一种代码特别容易疯狂复制：

logger.info("开始处理请求")

if not token:
    raise UnauthorizedError()

start = time.time()
result = await service.do_something()
logger.info(f"执行耗时: {time.time() - start}")
return result

一开始只有一个接口，看起来没什么问题。

但当项目发展到几十个甚至几百个接口以后，情况很快变成：

用户接口
  ├─ 鉴权
  ├─ 日志
  ├─ 参数检查
  ├─ 业务逻辑
  └─ 埋点

智能体接口
  ├─ 鉴权
  ├─ 日志
  ├─ 参数检查
  ├─ 业务逻辑
  └─ 埋点

知识库接口
  ├─ 鉴权
  ├─ 日志
  ├─ 参数检查
  ├─ 业务逻辑
  └─ 埋点

  ...

真正不同的可能只有中间那几行业务代码，其余代码，AI 每写一个接口，就顺手再复制一遍。

这正是 AOP（Aspect-Oriented Programming，面向切面编程） 要解决的问题。

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

Sun, 09 Aug 2026 00:00:00 +0000

先把接口规则定清楚，再让 AI 写代码。

在 AI 辅助开发中，接口设计是一个非常容易“看起来能用，最后越来越乱”的地方。

让 AI 帮你写几个接口，它可能很快就生成：

/getUser
/createUser
/update_user
/delete-user
/userList

功能都能跑。但项目继续发展，就很容易出现：

同一个资源，不同命名
同一个动作，不同 HTTP 方法
同一种错误，不同返回结构
同一个分页，不同字段名称

最后前端、后端、测试人员，甚至 AI 自己都开始猜：

“这个接口到底应该怎么调用？”

这时候真正缺少的，并不是代码能力，而是：

统一的接口契约。

日志体系架构：让 AI 写出的每一条日志都有价值

Sat, 08 Aug 2026 00:00:00 +0000

在 AI 辅助编程越来越普遍之后，一个很容易被忽略的问题正在出现：

AI 很会写日志，但不一定会写“有用的日志”。

让 AI 实现一个功能，它很可能顺手生成：

logger.info("start")
logger.info("processing...")
logger.info("data loaded")
logger.error("failed")

单独看似乎没有问题，但项目越来越大之后，你会发现日志开始变成这样：

start
processing...
loading data...
done
request failed
retry...
success

真正出了故障，却很难回答几个最基本的问题：

哪个请求出的错？
哪个模块出的错？
哪一步出的错？
…

问题并不是“日志太少”，而往往是：

日志很多，但没有体系。

因此，和异常处理、依赖注入、接口规范一样，日志也应该成为项目架构的一部分，而不是让开发者或者 AI 自由发挥。

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

Fri, 07 Aug 2026 00:00:00 +0000

AI 写代码时，非常喜欢一种“最快能跑”的方式,，例如：

db = Database()
cache = RedisCache()
mailer = EmailService()
service = UserService()

哪里需要，就在哪里创建。

短期看很方便，但当项目越来越大以后，就会出现：

数据库实例到处创建
缓存客户端到处创建
配置散落
Service 互相 new
测试时无法替换依赖

这类代码最明显的问题是：

对象把自己的依赖写死了。

而 DI（Dependency Injection，依赖注入） 要解决的，就是这件事。

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

Thu, 06 Aug 2026 00:00:00 +0000

AI 很擅长快速写接口，比如你告诉它：

“增加一个创建用户接口。”

它很可能几分钟就能给出一段能运行的代码，但如果项目里没有统一规范，不同接口很快就会变成这样：

{
  "success": true
}

另一个接口返回：

{
  "code": 0,
  "msg": "ok",
  "result": {}
}

再一个接口出错时直接返回：

{
  "error": "user not found"
}

甚至有些地方直接把数据库异常抛给前端。单个接口都“能跑”，整个系统却越来越难维护。

所以，AI 编程里有一类非常重要、却经常被忽略的基础架构：

统一返回值 + 全局异常处理 + 统一参数校验。

它们的作用，就是提前规定：

成功怎么返回，失败怎么返回，非法输入在哪里拦截。

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

Wed, 05 Aug 2026 00:00:00 +0000

AI 写代码有一个很常见的问题：

它知道功能应该怎么实现，却不一定知道代码应该放在哪里。

比如你告诉 AI：

“增加一个删除 Agent 的功能。”

如果没有清晰的工程结构，它可能直接在 API 接口里：查数据库、判断业务规则、清理缓存 …

功能可能很快就跑起来了。但随着 AI 一次次这样写，项目最终会变成：

API 里有业务逻辑
Service 里也有数据库操作
Repository 里又夹着业务判断
工具类到处被引用

这时候，我们就需要另一种非常基础、却极其重要的架构思想：

分层。

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

Tue, 04 Aug 2026 00:00:00 +0000

AI 写一个功能，通常并不难，真正难的是：

当 AI 连续写几十个、几百个功能以后，代码还能不能保持清晰？

很多项目一开始结构还不错，用户功能放一点，权限功能放一点，订单功能放一点，日志功能放一点。

随着需求越来越多，不同模块开始互相调用、互相引用、互相修改，最后可能变成这样：

user.py
  ↓
permission.py
  ↓
agent.py
  ↓
tool.py
  ↓
knowledge_base.py
  ↓
conversation.py
  ↘
   又调用 user.py

文件很多，代码也不少，但谁负责什么，已经越来越说不清。

软件架构里有一个非常形象的名字：

大泥球（Big Ball of Mud）

而领域驱动设计，也就是我们经常听到的 DDD，其中一个非常重要的作用，就是在系统开始变乱之前，先把边界划清楚。

对于 AI 编程来说，这个作用尤其重要。

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

Mon, 03 Aug 2026 00:00:00 +0000

AI 很会写代码。但如果没有明确的架构边界，它也很容易出现一个问题：

哪里写起来方便，就把代码写到哪里。

本应由后端负责的业务规则，可能被塞进 Vue 页面；本应统一封装的接口调用，可能散落在各个组件里；前端甚至可能根据页面需求，自己“发明”一套与后端不一致的数据结构。

代码可能能运行，但项目会逐渐失去边界。

而前后端分离，就是给 AI 划下的第一条重要边界。

如何用项目规则给 AI 划定编码边界

Sun, 02 Aug 2026 00:00:00 +0000

上一篇我们讨论了一个核心原则：

先定义边界和规则，再让 AI 在边界内发挥能力。

那么问题来了：

这些架构规则，怎样才能真正交给 AI？

答案就是本文的主题——Project Rules（项目规则）。

为什么越依赖 AI 写代码，越不能丢掉架构设计？

Sat, 01 Aug 2026 00:00:00 +0000

随着 GPT、Claude、Gemini、Qwen 等大模型的发展，软件开发正在进入一个新的时代。
过去需要数小时甚至数天完成的编码工作，如今 AI 几分钟便可以完成。然而，很多团队却发现了一个令人困惑的现象：

代码越写越多，项目却崩溃得越来越快。

原因并不是 AI 不够聪明，而是：

缺少架构约束。

现代 AI Agent 能够相对稳定地运行，一个重要原因就是：不会让大模型毫无约束地自由发挥。

成熟的 Agent 系统通常会通过系统提示词、权限控制、工作流、状态管理和结果校验等机制，为大模型划定明确的行为边界。

从本质上说，这与软件架构的思想高度一致：

先定义边界和规则，再让 AI 在边界内发挥能力。
即使能力很强的大模型，在缺乏明确约束、上下文持续膨胀或工具权限过大的情况下，也可能逐渐出现格式漂移、职责越界、错误调用工具或代码风格不一致等问题。