一个 AI 生成的单一代码库，支持 Web、移动 与 API

单一 AI 生成代码库 的含义

“一个代码库”很少意味着一个在任何地方都相同运行的 UI。在实践中，它通常指的是一个仓库和一套共享规则——由不同的交付面（Web 应用、移动应用、API）组成，但都依赖相同的业务决策。

共享逻辑 vs. 共享 UI

一个有用的心智模型是共享那些绝不能出现分歧的部分：

• 领域规则：计算、资格校验、定价、工作流、不变量。
• 用例：“创建订单”、“取消订阅”、“发放退款”等。
• 数据合约：请求/响应形状、验证规则、错误码。

与此同时，通常不会把 UI 层完全共享。Web 和移动有不同的导航模式、无障碍期望、性能约束和平台能力。在某些场景下共享 UI 是有利的，但这并不是“单一代码库”的定义。

AI 改变了什么（以及什么没变）

AI 生成的代码可以显著加速：

• 搭建脚手架（文件夹、构建脚本、基础组件）\n- 生成 CRUD 端点与客户端\n- 根据示例创建测试与夹具

但 AI 并不会自动产出连贯的架构。没有清晰边界时，它倾向于在应用间重复逻辑、混淆关注点（UI 直接调用数据库代码），并在多个地方创建“几乎相同”的验证。杠杆在于先定义结构——然后用 AI 填充重复部分。

期望达成的结果

一个 AI 辅助的单一代码库在能交付以下内容时才算成功：

• 一致性：Web、移动和 API 强制相同的规则。\n- 速度：新功能只需实现一次，然后在各处呈现。\n- 可维护性：更改可局部化、可复审、可测试，并且可预测地发布。

面向 Web、移动和 API 交付的目标与约束

单一代码库只有在明确它必须实现什么——以及不应试图统一什么时才有效。Web、移动和 API 服务不同的受众与使用模式，即便它们共享相同的业务规则。

服务对象是谁（以及如何服务）

大多数产品至少有三个“入口”：

• Web 应用用户（客户、管理员、支持团队），期待快速导航、无障碍和便捷更新。\n- 移动用户，期待原生体验、间歇网络支持以及高效的电量/网络使用。\n- 第三方集成（合作伙伴、内部系统、自动化工具），依赖稳定的 API、清晰的合约和可预测的错误处理。

目标是行为上的一致性（规则、权限、计算）——而非体验相同。

非目标：不要强行统一 UX

常见失败模式是把“单一代码库”当成“单一 UI”。这通常会产生一个像 Web 的移动应用或像移动的 Web 应用——两者都令人沮丧。

相反，应当追求：

• 共享域逻辑与验证
• 共享数据模型与 API 合约\n- 平台特有的展示与交互设计

早期需要为之设计的关键约束

离线模式： 移动端通常需要在无网络时读取（有时还要写入）。这意味着本地存储、同步策略、冲突处理以及明确的“事实来源”规则。\n 性能： Web 关注 bundle 大小与可交互时间；移动关注启动时间与网络效率；API 关注延迟与吞吐。共享代码不应意味着把不必要的模块发给每个客户端。\n 安全与合规： 认证、授权、审计轨迹、加密与数据保留必须在各面一致。如果你处于受监管的领域，从一开始就把日志、用户同意和最小权限访问等要求内置，而不是事后补丁式添加。

参考架构：层次与职责

单一代码库在组织成明确层次并有严格职责划分时效果最佳。这种结构也让 AI 生成的代码更容易审查、测试和替换，而不会破坏不相关的部分。

高层流程

下面是大多数团队最终趋向的基本形态：

Clients (Web / Mobile / Partners)
          ↓
     API Layer
          ↓
    Domain Layer
          ↓
 Data Sources (DB / Cache / External APIs)

关键思想：用户界面和传输细节位于边缘，而业务规则保持在中心。

共享哪些内容

“可共享的核心”是所有在任何地方都应表现一致的部分：

• 域（业务逻辑）：定价规则、资格校验、订单状态转换等。\n- 验证：输入规则与错误信息，映射到一致的错误码。\n- 网络与模式：API 请求/响应类型、序列化与契约测试。

当 AI 生成新功能时，最佳结果是：它只更新一次域规则，所有客户端自动受益。

哪些应保持不同

某些代码强行放入共享抽象代价高且风险大：

• UI 组件：Web 设计系统 vs 原生控件。\n- 导航与用户流：浏览器路由 vs 移动导航栈。\n- 设备能力：推送、指纹/面容识别、相机、离线存储。

实用规则：如果用户能“看到”它或操作系统能“打破”它，就把它保持为应用特有；如果是业务决策，就放在域层。

各层职责

• API 层： 认证、限流、将 HTTP/GraphQL 映射到域命令。\n- 域层： 纯粹的规则与用例，最小依赖。\n- 数据源： 数据库与第三方服务位于接口之后，这样实现可以更换而无需重写业务逻辑。

共享域层（业务逻辑）

共享域层应该让人觉得“无聊”——最好的那种：可预测、可测试、处处可复用。如果 AI 在帮你构建系统，这一层就是你锚定项目意义的地方——因此 Web 屏幕、移动流程与 API 端点都能反映相同规则。

从名词和动词开始

把产品的核心概念定义为实体（随时间有身份的事物，如 Account、Order、Subscription）和值对象（由值定义的事物，如 Money、EmailAddress、DateRange）。然后把行为捕捉为用例（有时称作应用服务）：“创建订单”、“取消订阅”、“更改邮箱”。

这种结构让域对非专业人员更易理解：名词描述存在的东西，动词描述系统能做什么。

保持业务规则与 UI 无关

业务逻辑不应知道它是被按钮点击、网页表单提交还是 API 请求触发的。实际要做到：

• 没有框架导入（域代码中不要有 web 控制器、移动视图或 ORM 注解）\n- 没有 UI 字符串（使用错误码或键代替硬编码文案）\n- 没有网络假设（域不应“调用 API”；它应体现规则）

当 AI 生成代码时，这种分离很容易丢失——模型会把 UI 关切塞进域代码。把这当作重构信号，而不是偏好问题。

全平台一致的验证规则

验证是产品经常出现偏差的地方：Web 允许但 API 拒绝，或移动的验证不同。把一致的验证放到域层（或共享验证模块）以便所有端都强制相同规则。

示例：

• EmailAddress 只在一处验证格式，Web/移动/API 复用\n- Money 阻止负总额，无论值从哪来\n- 用例强制跨字段规则（例如“结束日期必须晚于开始日期”）

做好这些后，API 层就变成翻译器，Web/移动成为呈现者——而域层保持单一事实来源。

API 层：驱动整个系统的合约

API 层是系统的“公共面孔”——在单一 AI 生成代码库中，它应该是锚定其他部分的那一层。如果合约清晰，Web、移动，甚至内部服务都可以从同一事实来源生成并校验。

从 API 优先的合约开始

在生成处理器或 UI 绑定之前先定义合约：

• 端点与资源：一致的名词（例如 /users、/orders/{id}），可预测的过滤与排序。\n- 错误：稳定的错误形状（code、message、details），并记录 HTTP 状态码使用。\n- 分页：选定一种方式（游标分页通常更易演进）并标准化响应字段。\n- 版本控制：尽早决定（路径如 /v1/... 或基于 header）并记录弃用规则。

从一个模式生成类型与客户端

把 OpenAPI（或像 GraphQL SDL 这样的模式优先工具）作为规范产物。从中生成：

• 服务端存根（路由、验证脚手架）\n- Web 与移动的类型化客户端\n- 减少漂移的共享请求/响应模型

这对 AI 生成代码很重要：模型可快速生成大量代码，但模式能让输出保持一致。

防止微妙破坏的一致性规则

设定一些不可谈判的规则：

• 命名：用 snake_case 或 camelCase，不要混用；JSON 与生成类型保持一致。\n- 状态码：成功用 200/201/204，验证错误用 400，认证用 401/403，冲突用 409。\n- 幂等性：对风险操作（支付、创建订单）要求 Idempotency-Key，并定义重试策略。

把 API 合约当作产品来对待。当它稳定时，其他所有东西都更容易生成、测试和发布。

Web 应用：集成共享逻辑但不耦合

Web 应用从共享业务逻辑中获益良多，但当这些逻辑与 UI 关切纠缠时就会受苦。关键是把共享域层当作一个“无头”引擎：它知道规则、验证和工作流，但不了解组件、路由或浏览器 API。

渲染选择：SSR vs CSR（以及为啥重要）

如果你使用 SSR（服务端渲染），共享代码必须安全地在服务器上运行：不能直接使用 window、document 或浏览器存储。这是个很好的强制：把浏览器依赖行为放在薄薄的 Web 适配层中。\n 使用 CSR（客户端渲染） 时，你有更多自由，但相同的纪律依然有用。仅 CSR 的项目常会“意外”把 UI 代码导入到域模块，因为一切都在浏览器运行——直到后来加入 SSR、边缘渲染或在 Node 中运行的测试时问题才暴露。

实用规则：共享模块应确定性且与环境无关；任何触碰 cookies、localStorage 或 URL 的行为都属于 Web 层。

状态边界：域状态 vs UI 状态

共享逻辑可以通过普通对象和纯函数暴露域状态（例如订单总额、资格、派生标志）。Web 应用应拥有UI 状态：加载指示、表单焦点、乐观动画、模态可见性。

这让 React/Vue 的状态管理保持灵活：你可更换库而无需重写业务规则。

应在 Web 层隔离的关注点

Web 层应处理：\n\n- 无障碍（语义化标记、键盘导航、ARIA）\n- 路由（URL 结构、深度链接、服务端重定向）\n- 浏览器存储（cookies/session、localStorage、缓存）

把 Web 应用视为把用户交互翻译为域命令的适配器，并把域结果翻译为可访问的界面。

移动应用：共享逻辑与原生能力并存

移动应用从共享域层获益最大：定价、资格、验证和工作流的规则应与 Web 与 API 行为一致。移动 UI 成为围绕共享逻辑的“外壳”——针对触控、间歇连接与设备特性进行优化。

应为哪些平台模式设计

即便有共享业务逻辑，移动也有难以 1:1 对应 Web 的模式：

• 导航：在应用层建模导航状态（屏幕、标签、模态），而把域决策（例如“用户需验证邮箱后才能结账”）放在共享代码中。\n- 后台任务：把同步、上传与刷新作为明确的任务来处理，考虑时间限制与可恢复性。\n- 推送通知：在应用层解析通知负载，再交给共享逻辑决定下一步。\n- 深度链接：在应用层路由链接，但用共享代码验证权限并获取所需数据。

离线优先：缓存、同步与冲突策略

如果预期真实的移动使用，假定会离线：

• 在本地缓存读取模型（键值或 SQLite），并明确陈旧性策略。\n- 将写入排为意图/事件（如“创建订单草稿”），在线时再同步。\n- 提前定义冲突规则（后写胜、服务器权威合并或用户解决）。\n- 实现带退避的重试与幂等键，使 API 可以安全接收重复请求。

移动特有关注点

• 应用体积：保持共享层模块化，只发布应用所需部分。\n- 电量/流量：批量网络请求，避免频繁轮询。\n- 权限：仅在需要时请求（相机、定位、联系人），并把权限检查放在应用层，以便策略在各平台上可变。

全面面的数据模型、认证与权限

如果 Web、移动和 API 各自发明数据形状与安全规则，“单一代码库”会很快崩溃。解决方法是把模型、认证与授权视为共享的产品决策，然后只做一次编码。

数据模型的单一事实来源

选一个地方让模型“驻留”，其他一切从它派生。常见选项：

• 模式优先：在模式文件中定义实体与验证规则（如 OpenAPI/JSON Schema），然后为 API、Web 与移动生成类型。\n- 共享模块：把模型类型与验证器放在共享包（通常是“domain”包）供各应用导入。\n- 混合：对外合约使用模式文件，内部域规则使用共享模块。

关键不是工具而是一致性。如果一个客户端的 OrderStatus 有五个值，另一个有六个，AI 生成的代码会高高兴兴地编译并仍然发布 bug。

认证：会话、令牌与安全存储

认证对用户来说应有一致感受，但各面实现不同：

• Web 常用 基于 Cookie 的会话（便于 CSRF 防护、浏览器存储简洁）。\n- 移动 与第三方客户端通常需要 基于令牌 的方案（访问令牌 + 刷新令牌）。

设计单一路径：登录 → 短期访问 → 需要时刷新 → 注销并使服务器端状态失效。在移动端把秘密存到安全存储（Keychain/Keystore），不要放在普通偏好中；在 Web 上尽量使用 httpOnly cookie，避免令牌暴露给 JS。

授权：集中规则，并在 API 强制执行

权限应集中定义——最好靠近业务规则——然后在各处应用：

• 在域层集中检查（例如 canApproveInvoice(user, invoice)）。\n- 在 API 层强制以保证安全。\n- 在 UI 层镜像用于隐藏/禁用动作，但不要依赖它来保护数据。

这能防止“在移动上工作但在 Web 上不行”的漂移，并为 AI 代码生成提供清晰、可测试的谁可以做什么的契约。

构建、发布与部署策略

只有在构建与发布可预测时，统一代码库才能保持统一。目标是让团队可以独立发布 API、Web 和移动应用——而不会为逻辑分叉或“针对环境做特殊处理”。

单仓库 vs 多仓库

单仓库（monorepo） 往往更适合单一代码库，因为共享域逻辑、API 合约与 UI 客户端可以同步演进。你得到原子性变更（一个 PR 同时更新合约及其所有消费者）和更简单的重构。\n 多仓库 仍可实现统一，但会付出协调成本：为共享包做版本控制、发布工件和同步破坏性变更。仅当组织边界、安全规则或规模使单仓库不可行时才选多仓库。

构建目标与工件

把每个交付面当作独立构建目标，消费共享包：

• API 服务工件：容器镜像或 serverless 包，从 API 应用包构建。\n- Web bundle：静态资源 + 服务器运行时（若需 SSR）从 Web 应用包构建。\n- 移动构建：Android（AAB/APK）与 iOS（IPA）由本地流水线生成，但把共享逻辑作为依赖引入。

保持构建产物显式且可重现（锁定依赖文件、固定工具链、确定性构建）。

CI/CD 流水线与环境隔离

典型流水线：lint → 类型检查 → 单元测试 → 契约测试 → 构建 → 安全扫描 → 部署。\n 把配置与代码分离：环境变量与秘密保存在 CI/CD 与密钥管理中，而不是仓库里。使用环境特定的覆盖层（dev/stage/prod），使得同一工件可在不重建的情况下在各环境间晋级——尤其适用于 API 与 Web 运行时。

共享代码的测试与质量门禁

当 Web、移动与 API 从同一代码库发布时，测试不再是“多做一项检查”，而是防止小改动破坏三端的机制。目标很简单：在修复成本最低处检测问题，并在到达用户前阻止高风险变更。

适用于共享代码库的实用测试金字塔

从共享域（业务逻辑）开始，因为它被最多复用且最容易在没有慢速基础设施的情况下测试。\n

• 单元测试（域层）：验证定价、资格、权限决策、状态转换与边界情况。它们应运行快捷并占测试套件的大头。\n- 集成测试（API 层）：用真实序列化、验证、认证与数据访问证明 API 的端到端工作情况。把它们聚焦在关键流程上而非每个角落用例。\n- UI 测试（每个客户端）：少量高价值的关键旅程检查（登录、结账、提交表单）以确认真实 UI 中关键路径可行。这类测试较慢，应作为“烟雾报警器”，而非穷尽性的证明。

这种结构把大部分信心放在共享逻辑上，同时还能捕捉层与层之间的“布线”问题。

保持客户端与 API 对齐的契约测试

即便在单仓库里，API 也容易在编译时变更但破坏用户体验。契约测试可以阻止无声漂移。\n

• API 到客户端的契约：锁定请求/响应形状、错误格式与状态码。如果 API 返回新的必需字段或更改枚举值，契约测试会在合并前失败。\n- 把模式当作门禁：如果你发布 OpenAPI/GraphQL 模式，把模式更改视为可审查的产物。破坏性变更应需要显式批准与迁移计划。

保护发布的质量门禁

好测试很重要，但治理规则也很关键。\n

• Pull Request 门禁：要求通过单元+集成测试、lint/格式化，并对域层要求最低覆盖率。\n- 功能开关：通过在环境或用户组级别隐藏未完成行为来安全发布代码。\n- 分阶段发布：先向内部用户发布，然后逐步对一小部分生产流量开放，最后全面推广。\n- 回滚计划：把回滚当作一等公民——版本化发布、可逆数据库迁移（或可安全向前迁移）、以及明确的“停线”标准。

有了这些门禁，AI 辅助的变更可以频繁且不易脆弱。

在不失去架构控制的情况下使用 AI

AI 能加速单一代码库开发，但前提是把它当作速度很快的初级工程师：能生成草稿，但合并前必须审查。目标是用 AI 提高速度，同时由人把控架构、合约与长期一致性。

AI 最有帮助且低风险的场景

用 AI 生成那些你本来会机械性写出的“第一版”：

• 项目脚手架（文件夹、样板模块、功能骨架）\n- 基于现有合约的 API 文档与示例\n- 测试套件（围绕域规则的单元测试、端点的契约测试）\n- 迁移与种子数据脚本\n- 重复性重构（重命名字段、拆分模块），在你先定义好计划之后\n 一个好的规则：让 AI 产出的代码易于通过阅读或运行测试来验证，而不是悄然改变业务含义的代码。

保护架构的护栏

AI 输出应受显式规则约束，而不是凭直觉。把这些规则放在代码中：

• 编码标准：linter/formatter、命名规则，以及“UI 不得直接访问 DB” 的风格约束。\n- 架构规则：依赖边界（如域层不得 import API/web/mobile），通过工具或简单构建检查强制执行。\n- PR 清单：“合约变更？更新 OpenAPI + 客户端类型 + 测试。” “新增域规则？添加域测试。”

如果 AI 建议的捷径违反边界，即便能编译也要否决。

治理：让 AI 工作具备可审计性

风险不仅是糟糕的代码，还有未被追踪的决策。保持审计记录：

• 把关键提示（prompts）与响应保存在工作项旁（工单 ID、PR 链接）。\n- 把合规或架构决策记录为 ADR（架构决策记录），用于合约变更、认证模型变更或新域概念。\n- 要求 API 变更显式化：版本化、文档化并由契约测试保障。

当团队能看到为什么生成某段代码、验证它并在需求演进时安全重生成，AI 的价值就会最大化。

工具提示：尊重边界的 AI

如果在系统层面（Web + API + 移动）采用 AI 辅助开发，最重要的“特性”不是原始的生成速度，而是保持输出与合约和分层一致的能力。

例如，Koder.ai 是一个通过聊天界面帮助团队构建 Web、服务端和移动应用的 vibe-coding 平台——同时仍然产出真实、可导出源码。实际上，这对于本文所述的工作流很有用：你可以先定义 API 合约与域规则，然后在不丢失审查、测试和强制架构边界能力的情况下快速迭代 React Web 界面、Go + PostgreSQL 后端和 Flutter 移动应用。像计划模式、快照与回滚之类的特性也很适合“生成 → 验证 → 晋级”的发布纪律，在统一代码库中尤其有价值。

何时不适合使用单一代码库（以及改用何种方案）

单一代码库能减少重复，但它并非默认的“最佳”选择。当共享代码开始强制妥协 UX、拖慢发布或掩盖平台差异时，你会把更多时间花在架构协商上，而非交付价值。

适合分开代码库的情形

当以下情形存在时，分开代码库（或至少分开 UI 层）通常更划算：

• 高度定制的 UI 是产品本身。 如果 Web 与移动需要根本不同的交互模型（手势、离线优先屏幕、以相机为中心的流程、复杂动画），共享 UI 往往成为折衷。\n- 严格的平台约束。应用商店审查规则、设备硬件权限、后台执行限制与无障碍要求可能要求平台特定实现。\n- 不同的发布节奏重要。移动可能按月发布而 Web 每日发布。紧耦合的单仓库会把每次改动都变成协调事件。

常见失败模式

• 过度共享 UI： “一个 UI 管理一切” 导致最差通用体验。\n- 泄露的抽象： 一个“共享”模块仍然暴露 Web/移动细节（路由、存储、令牌），导致每个消费者变得脆弱。\n- 版本漂移： 团队为加速而复制粘贴共享代码，修复只落到某一个地方。

决策清单（以及替代方案）

在决定采用单一代码库前问自己：

• 域逻辑能否清晰共享，同时保持原生 UX？\n- 平台团队是否需要在工具链、发布节奏与实验上保持自主？\n- API 是否足够稳定以允许客户端独立演进？

如果你看到警告信号，实用的替代方案是 共享域 + API 合约，同时 分开 Web 与移动 应用。把共享代码聚焦在业务规则与验证，把每个客户端留给自己负责 UX 与平台集成。

如果你需要帮助选择路径，可在 /pricing 比较选项，或在 /blog 浏览相关架构模式。