# Architect Pro：高级软件架构（2026 版）掌握使用经过验证的架构模式构建可维护、可扩展和可测试系统的艺术。该技能针对 **Next.js 16.2 / React 19.3 / Node.js 24** 生态系统进行了优化，专注于将业务逻辑与基础设施解耦，并使 **自主 AI 代理**能够在您的代码库中有效工作。 ## 🎓 先决条件和技能水平 * **级别**：高级/首席工程师/软件架构师 * **先决条件**： * 深入了解 TypeScript 5.5+（泛型、可区分联合、模板文字类型）。 * 熟悉 Next.js 应用程序路由器和服务器组件。 * SQL (PostgreSQL) 和 NoSQL (Redis/MongoDB) 数据库的基本知识。 * 具有自动化测试经验（Jest、Vitest、Playwright）。 * 对领域驱动设计（DDD）感兴趣。 ** ** ## 📌 目录一、核心理念 2. 为什么要在 2026 年推行清洁建筑？ 3. AI 代理的架构 4. 快速入门：2026 堆栈 5. 现代数据流：React 19 + Next.js 16 6. 标准模式：干净的架构+服务器操作 7. 战术 DDD：实体、值对象和聚合 8. 领域服务与应用程序服务 9. 高级模式：事件驱动的 DDD 10.事件风暴和领域建模 11.架构决策记录（ADR） 12. 上下文映射和战略 DDD 13. 架构师的测试策略 14. 建筑执法和护栏 15. 架构层面的性能和可扩展性 16. 建筑术语表 17. 禁止列表（反模式） 18. 深入参考 19. 使用 Repomix 进行存储库分析 ** ** ## 🏛️核心理念 2026 年，软件将越来越多地由 **AI 编码代理** 构建和重构。为了使代理有效，代码库必须具有**可预测的边界**和**明确的契约**。 * **解耦** ：业务逻辑（Domain）不能依赖于数据库、UI或框架。 * **可测试性** ：您应该能够测试您的核心逻辑，而无需启动数据库或模拟复杂的框架内部结构。 * **独立性**：系统应该不知道其交付机制（Web、CLI、移动、AI 代理）。 * **可预测性**：文件和文件夹应遵循严格的约定，以便人类和人工智能都能立即定位逻辑。 ** ** ## 🧠 为什么要在 2026 年进行清洁架构？ “快速行动，打破常规”时代已经演变为“利用人工智能快速行动，保持理智”时代。如果没有坚实的架构： 1. **AI 代理产生幻觉**：当业务逻辑与 Prisma 查询和 React hook 混合时，AI 经常会丢失上下文并引入微妙的错误。 2. **框架流失**：Next.js 和 React 版本快速发展。干净的域层可以保护您免受“app”路由器或服务器操作中下一个重大更改的影响。 3. **复杂性债务**：最初是一个简单的“CRUD”应用程序，通常会发展成为一个复杂的领域。干净的架构允许“逐渐复杂化”，您可以仅在需要时添加层。 ** ** ## 🤖 AI 代理架构 2026 年，我们为两种受众进行设计：人类和特工。 * **确定性文件路径**：使用严格的干净架构文件夹结构可以帮助人工智能立即找到“真相来源”（域）。 * **强类型 (TS 5.5+)** ：用例中的显式返回类型充当 AI 代理的“API 文档”。 * **小上下文窗口**：解耦层允许 AI 处理单个文件（如用例），而无需了解整个数据库模式。 * **Repomix 上下文打包** ：我们使用工具为 AI 代理打包高密度上下文，干净的架构使这种打包效率提高了 10 倍。 ** ** ## ⚡ 快速入门：2026 年堆栈 2026 年最常见的生产堆栈使用 **Next.js 16.2** 和 **Server Functions** 、 **TypeScript 5.x** 和 **Bun/pnpm** monorepos。 ### 推荐的文件夹结构源代码/ ├── domain/ # 核心逻辑（“真相”） │ ├──Entitys/ # 具有身份和生命周期的可识别对象 │ ├── value-objects/# 带验证的数据包装器（电子邮件、金钱） │ ├── services/ # 涉及多个实体的纯逻辑 │ ├── events/ # 领域事件（OrderPlaced、UserDeactivated） │ └── 异常/ # 自定义域异常 ├── application/ # 编排（“用户意图”） │ ├── use-cases/ # 具体业务操作（命令） │ ├── ports/ # 接口（基础设施合约） │ ├── dtos/ # 数据传输对象 │ └──queries/ # 只读操作（如果使用CQRS） ├── 基础设施/ # 工具（“实施”） │ ├── 适配器/ # 端口的实现（Prisma、Stripe、AWS） │ ├── 持久化/ # 数据库模式、迁移、播种器 │ └── external/ # 第三方API客户端 ├── 演示/ # UI（“视图”） │ ├── Components/ # React 19 服务器/客户端组件 │ ├── actions/ # Next.js 服务器操作（主适配器） │ └── pages/ # 路由处理程序和页面定义 └── shared/ # 横切关注点（常量、实用工具） ** ** ## 🌊 现代数据流：React 19 + Next.js 16 交互模型发生了变化。我们不再只是“从 API 获取”。我们“调用服务”。 ### 1\.视图（反应 19）使用新的“useActionState”和“useOptimistic”实现无缝的用户体验。 // 演示文稿/组件/ProjectForm.tsx “使用客户端” 从'react'导入{useActionState}；从 '../actions/project-actions' 导入 { createProjectAction }；导出函数 ProjectForm() { const [state, formAction, isPending] = useActionState(createProjectAction, null); 返回（ <表单操作={formAction}>

项目名称 <输入 id=“项目名称” 名称=“项目名称” className="边框 p-2 圆角" 必填 /> <按钮 className="bg-blue-600 文本白色 p-2 圆形" 已禁用={正在等待} > {正在等待？ '创建...' : '创建项目'} {状态？.error &&

{state.error}

}

）； } ### 2\.操作（Next.js 16.2）充当**主适配器**。它处理从 HTTP (FormData) 到应用程序逻辑的转换。 // 演示文稿/动作/project-actions.ts '使用服务器' 从'@/application/use-cases/CreateProject'导入{CreateProjectUseCase}；从 '@/infrastruct/adapters/PrismaProjectRepository' 导入 { PrismaProjectRepository }；导出异步函数 createProjectAction(prevState: any, formData: FormData) { const name = formData.get('projectName') as string; // 依赖注入：在 2026 年，我们更喜欢显式组合而不是复杂的 DI 容器 const repo = new PrismaProjectRepository(); const useCase = new CreateProjectUseCase(repo); 尝试{ const 项目 = 等待 useCase.execute({ name }); 返回 { 成功：true，数据：项目 }； } 捕获 (e) { // 审核日志或错误跟踪集成 console.error("[操作错误]", e); 返回 { 成功: false, 错误: e.message }; } } ** ** ## 🛠️ 标准模式：干净的架构 + 服务器操作 ### 1\.域实体实体代表具有身份的业务概念。 // src/domain/entities/User.ts 从“../value-objects/Email”导入{电子邮件}；导出类用户{ 构造函数（公共只读 ID：字符串，公共只读电子邮件：电子邮件，私有_isActive：布尔值= true ）{} 公共停用（）{ this._isActive = false; } 获取 isActive() { 返回 this._isActive; } } ### 2\.用例（应用层）用例编排域对象来执行特定任务。 // src/application/use-cases/DeactivateUser.ts 从 '../ports/IUserRepository' 导入 { IUserRepository }；导出类 DeactivateUserUseCase { 构造函数（私有 userRepo：IUserRepository）{} 异步执行（userId：字符串）：Promise { // 1. 从存储库（端口）获取 const user = wait this.userRepo.findById(userId); if (!user) throw new Error("未找到用户"); // 2. 执行领域逻辑（实体） user.deactivate(); // 3. 保存更改（端口）等待 this.userRepo.save(user); } } ### 3\.存储库实施（基础设施）与数据库对话的“适配器”。 // src/infrastruct/adapters/PrismaUserRepository.ts 从 '@/application/ports/IUserRepository' 导入 { IUserRepository }；从 '@/domain/entities/User' 导入 { User }；从 '@/domain/value-objects/Email' 导入 { Email }；从 '../prisma' 导入 { prisma } ；导出类 PrismaUserRepository 实现 IUserRepository { async findById(id: string): Promise<用户|空> { const data =等待 prisma.user.findUnique({ 其中：{ id } }); if (!data) 返回 null；返回新用户（数据.id, 电子邮件.create(数据.电子邮件), 数据处于活动状态）； } 异步保存（用户：用户）：Promise { 等待 prisma.user.upsert({ 其中：{ id: user.id }, 更新：{ isActive：user.isActive }，创建：{ id: 用户.id, 电子邮件：用户.电子邮件.值， isActive: 用户.isActive } }); } } ** ** ## 🧩 战术 DDD：实体、值对象和聚合 ### 值对象（类型的力量）不要将“string”用于所有内容。使用值对象进行验证和业务逻辑。 // 域/值对象/Money.ts 出口类货币{ 私有构造函数（公共只读金额：数字，公共只读货币：字符串）{} 静态创建（金额：数字，货币：字符串='USD'）：金钱{ if (amount < 0) throw new Error("金额不能为负数"); 返回新资金（金额，货币）； } 添加（其他：金钱）：金钱{ if (this.currency !== other.currency) throw new Error("货币不匹配"); return new Money(this.amount + other.amount, this.currency); } } ### 聚合（一致性边界）聚合确保多个相关对象始终满足业务规则。 // 域/实体/Order.ts 导出类订单{ 私人物品：OrderItem[] = []； addItem(产品：产品，数量：数量) { const TotalItems = this.items.reduce((sum, item) => sum + item.quantity, 0); if (总商品数 + 数量 > 50) { throw new Error("一个订单不能超过 50 件商品"); } this.items.push(new OrderItem(product.id, 数量)); } } ** ** ## ⚙️ 领域服务与应用程序服务 DDD 中最常见的混淆点之一。 * **域服务**：包含属于域但不适合单个实体的业务逻辑（例如，两个银行帐户之间的“TransferService”）。它适用于实体和值对象。 * **应用程序服务（用例）**：不包含业务逻辑。它只是编排。它调用存储库、触发域服务并发送电子邮件。 ** ** ## 🚀 高级模式：事件驱动的 DDD 捕获意图并解耦副作用。 ### 域服务示例 // 域/服务/TransferService.ts 导出类 TransferService { 异步执行（来自：帐户，至：帐户，金额：金钱）{ from.withdraw(金额); to.deposit(金额); // 此处捕获领域事件返回新的 FundsTransferredEvent(from.id, to.id, amount); } } ** ** ## 🌪️ 事件风暴和领域建模 2026年，我们不再从“桌子”开始。我们从“事件”开始。 1. **领域事件**：业务中发生了什么？（例如，“已下订单”、“减少库存”）。 2. **命令**：什么触发这些事件？（例如，“下订单”）。 3. **聚合**：确保遵循规则涉及哪些对象？ 4. **读取模型**：我们希望如何向用户显示这些信息？ ** ** ## 📝 架构决策记录 (ADR) 2026 年，我们记录_为什么_我们做出选择，而不仅仅是_我们选择_。 # ADR 005：为 AI 核心使用干净的架构 ## 状态已接受 ## 上下文我们需要一种让人工智能代理在不违反业务规则的情况下安全地重构代码的方法。之前的“Spaghetti Monolith”导致 AI 在 React 组件中产生数据库查询的幻觉。 ## 决定我们将使用干净的架构，严格分离域和基础设施。 ## 后果 - 优点：可预测的文件结构、高可测试性、域中零框架泄漏。 - 缺点：简单 CRUD 操作的样板较多，初级开发人员的学习曲线较高。 ** ** ## 🗺️ 上下文映射和战略 DDD 系统的不同部分如何相互通信。 * **客户/供应商**：一个团队依赖于另一个团队。 * **共享内核**：两个团队共享一个通用模型（很少推荐）。 * **反腐败层 (ACL)**：在遗留系统和干净的新系统之间进行转换的层。 * **单独的方式**：上下文之间没有关系。 ** ** ## 🧪 建筑师的测试策略在清洁架构中，您有不同的“测试槽”： 1. **领域单元测试**：测试实体和值对象。需要零模拟。这里期望 100% 的代码覆盖率。 2. **用例测试**：测试编排。对数据库使用 **内存适配器** (Mocks/Fakes)。 3. **集成测试**：测试真实的适配器（例如，针对真实测试容器的 Prisma 存储库）。 4. **E2E 测试**：使用 Playwright 测试完整的 Next.js 流程。 ### 示例：用例测试（无数据库） // 测试/用例/DeactivateUser.test.ts 从 '@/application/use-cases/DeactivateUser' 导入 { DeactivateUserUseCase }；从 '../mocks/InMemoryUserRepository' 导入 { InMemoryUserRepository } ； test('应该停用用户', async () => { const repo = new InMemoryUserRepository(); 等待 repo.save({ id: '1', email: 'test@test.com', isActive: true }); const useCase = new DeactivateUserUseCase(repo); 等待 useCase.execute('1'); const user = wait repo.findById('1'); 期望（用户。isActive）。toBe（假）; }); ** ** ## 🛡️ 建筑执法和护栏使用工具来确保“依赖规则”永远不会被破坏。 ### `dependency-cruiser` 配置（2026 年最佳实践） { “禁止”：[ { “名称”：“域不导入基础设施”， "from": { "path": "src/domain" }, “到”：{“路径”：“src /基础设施”} }, { "name": "usecase-not-import-infra", “来自”：{“路径”：“src /应用程序”}， “到”：{“路径”：“src /基础设施”} }, { “名称”：“演示文稿-非导入基础设施”， “来自”：{“路径”：“src /演示文稿”}， “到”：{“路径”：“src /基础设施”} } ] } ** ** ## 📈 架构级别的性能和可扩展性 * **读写分离 (CQRS)** ：使用快速的 NoSQL 数据库进行读取，使用强大的 SQL 数据库进行写入。 * **作为一等公民进行缓存**：不要将缓存逻辑放入您的用例中。在表示层中使用 **缓存适配器** 或 Next.js `use cache` 指令。 * **作业队列** ：通过领域事件将繁重的工作（电子邮件、人工智能处理）卸载到后台作业。 ** ** ## 📖 建筑术语表 * **有界上下文**：领域模型一致的特定边界（通常是模块或服务）。 * **端口** ：基础设施必须实现的应用层定义的接口。 * **Adapter** ：端口的实现（例如，“IUserRepository”的 SQL 数据库实现）。 * **控制反转 (IoC)** ：域定义其需求（端口），高层提供实现（适配器）的原则。 * **聚合根**：聚合中控制所有访问并强制执行业务规则的主要实体。 * **通用语言**：所有团队成员用来描述领域的通用语言。 ** ** ## 🚫 禁止列表（反模式） ### 1\. **框架泄漏** **BAD** ：使用 `@prisma/client` 类型作为域或应用程序层中的返回类型。 **好**：将数据库行映射到基础设施层中的域实体。 ### 2\. **贫血域模型** **不好**：将所有逻辑放入“UserService”中，并将“User”仅作为“类型”。 **好**：将业务规则（例如，`user.canJoinProject()`）移动到`User`类中。 ### 3\. **“共享”垃圾箱** **BAD** ：将所有内容都放在“shared/”中，因为你懒得决定它所属的位置。 **好**：保持“共享/”最少。如果与业务相关，则为“domain/”。如果它与工具相关，那就是“基础设施/”。 ### 4\. **不成熟的微服务** **BAD** ：在了解域边界之前就分成 10 个存储库。 **好**：首先使用清洁架构构建**模块化整体**。如果边界是干净的，以后就很容易切割。 ### 5\. **惰性命名** **坏**：`数据`、`信息`、`经理`、`进程`。 **好**：`PaymentRecord`、`UserAuthenticationDetails`、`OrderOrchestrator`。 ** ** ## 📚 深入参考探索我们的专业文档以获得更深入的技术见解： * [清洁架构指南]() * [六边形架构（端口和适配器）]() * [DDD 模式与战术设计]() * [性能和可扩展性 2026]() * [迁移与重构策略]() * [存储库分析指南]() ** ** ## 🔍 使用 Repomix 进行存储库分析在重构之前，始终分析现有的代码库结构。 # 优化架构发现命令 npx repomix@latest --include "src/**/*.ts" --compress --output /tmp/arch-discovery.xml 使用 Repomix 可以让您将架构“打包”到一个文件中，该文件可以输入 AI 进行全面审核。 ** ** ## 💎 最佳实践清单 * 我的域层没有外部依赖吗？ * 我的用例仅进行编排吗？ * 我是否有用于所有外部服务（DB、Auth、Mail、Stripe）的接口（端口）？ * 我是否将值对象用于电子邮件、金钱和地址等内容？ * 我的代码可以在没有真实数据库的情况下进行测试吗？ * 我是否已将基础架构错误映射到域异常？ * 我是否使用 ADR 来记录主要的架构决策？ * 我的通用语言是否反映在代码中？ ** ** _更新时间：2026 年 1 月 22 日 - 15:18_

建筑师专业版

包含技能