被一个 shared 目录卡住后，我重新思考了 AI 时代的代码封装

从权限卡点到工程范式反思

roseey

672人浏览 · 2026-01-30 08:47:22

roseey · 2026-01-30 08:47:22 发布

上周，我启动一个新项目，准备用 AI 工具快速生成前后端代码。
一切都很顺利——直到我发现：项目依赖一个内部 shared/prisma/ 模块，而我没有访问权限。

申请权限要走流程，等审批可能要一天。
可讽刺的是——我用 Vibe Coding 这类 AI 工具，10 分钟就能写出一模一样的数据库访问层。

那一刻我意识到：在 AI 编程普及的今天，有些“封装”正在从助力变成阻力。

一、传统封装的逻辑：统一、复用、防错

在纯手工开发时代，封装是工程最佳实践的核心。
我们把数据库操作抽象成 ORM 层，把工具函数放进 shared/utils/，把认证逻辑抽成中间件——目的很明确：

✅ 减少重复代码
✅ 统一团队规范
✅ 降低人为错误

这些做法建立在一个前提上：开发者是人，而人会累、会忘、会写错。

所以，“封装 = 提效”几乎成了共识。

二、AI 编程时代，这个前提变了

如今，我用 AI 辅助开发，体验完全不同：

AI 不怕“重复”：它能秒级生成标准化的 CRUD、Service、Controller。
AI 怕“黑盒”：如果封装没有清晰类型、文档或调用示例，AI 无法理解，只能瞎猜甚至绕过。
AI 追求“敏捷”：项目启动越快越好，强依赖外部模块反而拖慢节奏。

回到我的卡点：
那个 shared/prisma/ 模块，初衷可能是好的——统一 ORM 初始化、连接池配置等。
但它带来的问题也很现实：

❌ 新项目无法独立启动（权限壁垒）
❌ AI 无法理解其内部逻辑（缺乏类型/文档）
❌ 修改成本高（需协调维护者）

结果是：为了“复用几行初始化代码”，整个项目被卡住。

这还是“提效”吗？

三、AI 时代的封装，应该长什么样？

不是不要封装，而是要为 AI 友好而设计的封装。结合近期实践，我总结了几条原则：

✅ 1. 显式优于隐式

让逻辑“看得见”。例如，直接在项目中定义 prisma/schema.prisma，AI 能直接读取模型并生成对应代码。
避免再包一层“统一 DAO”，除非它导出完整 TypeScript 类型。

✅ 2. 自包含优于强耦合

每个项目应能独立运行。共享能力可通过以下方式提供：

私有 npm 包（如 @company/db-client）
脚手架模板（如 create-company-app）
Git Submodule（谨慎使用）

关键：非强制依赖，按需引入。

✅ 3. 类型驱动，而非约定驱动

AI 依赖结构化元数据。确保任何共享模块：

导出完整的 .d.ts 类型
提供调用示例（最好带 JSDoc）
避免动态 require 或魔法字符串

✅ 4. 可生成 > 可复用

过去追求“一次编写，处处复用”；现在更应追求“按需生成，处处一致”。
AI 能保证不同项目中的相似逻辑高度一致，无需靠共享库“强制统一”。

四、我的新项目实践

基于以上思考，我现在的新项目结构如下：

my-new-project/
├── prisma/
│   ├── schema.prisma      ← 显式定义模型
│   └── client.ts          ← 导出 PrismaClient（带类型）
├── src/
│   ├── services/
│   └── controllers/
├── package.json
└── README.md              ← 包含 AI 友好说明