SuperAPI AI 工具集

software-architecture-design

编程与开发

查看项目

更新于 10-16 07:30

技能介绍

用途与定位

本技能用于在已经确定的解决方案中设计运行时拓扑。它适用于选择单体架构还是服务化架构、单元化(cell)划分、一致性模型选择以及编写架构决策记录(ADR)等任务。如果问题起点是业务工作流、系统全景、目标状态或跨系统的分阶段迁移,应当先使用软件解决方案架构(software-solution-architecture)技能,再回到本技能进行运行时、服务拆分和可运维性方面的深入设计。

主要能力

技能提供快速参考,覆盖以下任务:

  • 选择架构风格:默认模块化单体,在明确需要独立部署和所有权之后再考虑分层、微服务、事件驱动或无服务器架构。
  • 决定 API 边界姿态:关注契约姿态和版本策略,而非端点设计。
  • 为规模而设计:负载均衡、缓存、分片、读副本。
  • 确保韧性:断路器、重试、隔板、优雅降级。
  • 记录决策:架构决策记录(ADR)。
  • 定义服务边界:领域驱动设计(DDD)、限界上下文。
  • 建模数据一致性:ACID 与 BASE、事件溯源、CQRS、Saga 模式。
  • 规划可观测性:SLI/SLO/SLA、分布式追踪、指标、日志。
  • 单体迁移:绞杀者模式、数据库拆分、影子流量。
  • 设计服务间通信:API 网关、服务网格、BFF 模式。
  • 设计交付平台:IDP、黄金路径、适应度函数。
  • 梳理服务蔓延:限界上下文平台、仓库与运行时矩阵、平台计分卡。
  • 规划资产现代化:平台优先的迁移波次、整合、兼容性边界。
  • 设计 AI 原生系统:RAG 边界、工具网关、智能体互操作、MCP、A2A。

使用方式

技能内部包含决策树,帮助根据问题类型选择架构模式。例如,大型资产且仓库/服务众多时,区分运行时数量问题和交付一致性问题;确定性工作流与自适应工作流的处理方式不同;强一致性需求下应优先保持数据与写入在一起;平台级一致性需求则考虑 IDP 与黄金路径。

决策因素包括:默认倾向模块化单体而非微服务,除非独立部署、所有权和可运维性收益明确;资产姿态上先优化运行时单元数量而非仓库数量;智能体姿态上优先确定性工作流或单智能体,再考虑多智能体协调;连接姿态上优先网关加应用库模式,直到 mTLS、流量策略或共享遥测需求证明网格的复杂度合理。此外还需考虑团队结构(康威定律)、部署独立性需求、一致性与故障域边界、运维成熟度以及互操作性需求。

拆分平面概念来自《Team Topologies》第二版(2025),指软件系统中允许将系统轻松拆分为两个或多个部分的自然接缝。候选平面包括业务领域限界上下文(默认,大多数拆分应映射到此)、法规合规、变更节奏、团队位置、风险、性能隔离、技术和用户画像。试金石是:拆分后的架构是否支持更多自主团队(更少依赖)并降低认知负荷(更少分散职责)。实际边界通常组合多个平面。分布式单体警告指出,如果拆分软件但不对齐团队及其发布路径,只会付出分布式成本而得不到自主性。

输出指南

技能要求每项架构建议覆盖:最简充分拓扑、具体技术选型、推荐选项与落选备选、明确不应构建的内容、团队与流程对齐、仓库与运行时模型、可运维模型、迁移路径、关键风险与失效模式、成功度量(服务 SLO 及 DORA 五项交付指标,各自与自身基线比较)。

工作流

系统级工作流包括:澄清问题陈述、非目标、约束和成功度量;捕获质量属性(可用性、延迟、吞吐量、持久性、一致性、安全、合规、成本);决定负载形态(确定性工作流、单智能体或多智能体,同步或异步);提出 2–3 个候选架构并比较权衡;默认采用最简可行拓扑;对 20+ 仓库资产进行仓库分类;定义边界;决定数据策略;设计运维;设计治理与安全;明确范围限制;记录决策(当选择改变可部署边界、一致性或故障模型、平台契约或难以逆转的约束时编写 ADR)。

适用场景

适用于绿地项目、重大重构、高流量系统、分布式系统、微服务拆分、多服务事务、生产就绪规划、遗留系统现代化、微服务网络设计、多团队平台与治理、多仓库资产整合、受监管迁移、LLM 产品架构等。

限制

不适用于:跨系统解决方案设计、单服务实现、API 端点设计、安全实现、前端组件架构、数据库查询优化、智能体工作流实现或 MCP 服务器实现。技能强调从满足约束的最简架构出发,不默认使用微服务、事件溯源、服务网格或多智能体拆分。迁移边界上,本技能负责单个系统内部的提取或拆分机制,不负责跨系统的波次计划。

已知陷阱与反模式

陷阱包括:因资产已有许多仓库而选择微服务,但实际问题是运行时蔓延和所有权薄弱;绘制目标状态图却没有迁移序列、回滚边界或新旧路径兼容计划;在所有权、值班和部署权限尚未准备好支持额外表面积之前就拆分领域;在决定哪些路径真正需要解耦之前就在每个边界引入异步和事件驱动工作流;黄金路径仍然可选、不一致或所有权不足时却称之为平台工程。反模式包括:将可部署服务作为默认拆分单元而非限界上下文、团队所有权和运维成本;将超大规模厂商参考架构复制到不具备同等规模、工具或平台人员的团队;为峰值可选的未来设计而非当前吞吐量、故障、合规和变更管理约束;因为每个仓库和运行时都有“某种价值”而保留全部,尽管协调和治理成本明显;将“现代”与“更分布式”混为一谈,将“AI 原生”与“默认多智能体”混为一谈。

参考与模板

技能包含内部参考文档,如 modern-patterns.md、scalability-reliability-guide.md、data-architecture-patterns.md、migration-modernization-guide.md、api-gateway-service-mesh.md、fitness-functions-governance.md、architecture-trends.md、estate-modernization.md、operational-playbook.md。每个问题最多阅读 2–3 个最相关的参考。模板包括规划与文档(architecture-blueprint.md、estate-modernization-blueprint.md、adr-template.md)、架构模式(microservices-template.md、event-driven-template.md)和运维(scalability-checklist.md)。技能还包含评估文件 evals/evals.json。