架构评审的避坑手册——常见的设计缺陷与评审检查清单
一、背景与动机
架构评审是防止重大设计缺陷进入实施阶段的"安全网"。然而，现实中大量架构评审存在两个典型问题：评审流于形式（只看方案文档是否完整，不检查设计逻辑是否正确）和检查点不系统（评审者凭借经验随机提问，没有覆盖关键设计维度）。
本文梳理了架构评审中最常见的设计缺陷类型，并提供一份系统化的评审检查清单，帮助评审者高效、全面地识别设计风险。
二、架构评审常见的设计缺陷分类
架构级缺陷
缺陷1：职责边界模糊
服务之间的职责划分不清晰，导致功能重叠或职责真空。典型表现：两个服务都包含"用户信息查询"功能，但数据来源和更新逻辑不同，导致数据不一致。
评审检查点：
- 每个服务的核心职责是否用一句话能概括？
- 服务之间的职责是否有重叠区域？
- 是否有"没人负责"的功能空白？
缺陷2：耦合度过高
服务之间通过共享数据库、同步调用链、硬编码配置等方式产生强耦合，导致修改一个服务需要同时修改多个服务。
评审检查点：
- 服务之间是否通过共享数据库直接读写？
- 是否存在超过 3 层的同步调用链？
- 配置是否硬编码而非外部化？
缺陷3：过度设计
为"未来可能的需求"设计了复杂的抽象层、策略模式、扩展点，但当前需求只需要简单实现。过度设计的危害不是"浪费开发时间"，而是"增加理解和维护成本"。
评审检查点：
- 当前是否真的需要这个抽象层？
- 预期的扩展需求是否有明确的时间线？
- 简单实现是否能在 6 个月内满足需求？
接口级缺陷
缺陷4：接口契约不完整
API 定义只有功能描述，缺少输入校验规则、输出格式约定、错误码定义、版本管理策略。
评审检查点：
- 输入参数是否有校验规则（类型、范围、必填）？
- 输出格式是否固定且文档化？
- 错误码是否有统一的定义和分类？
- 接口是否有版本管理策略？
缺陷5：错误处理不统一
不同接口的错误返回格式不一致：有的返回 HTTP 状态码 + JSON body，有的只返回状态码，有的返回自定义错误码但无文档说明。
评审检查点：
- 是否有统一的错误响应格式？
- 业务错误和系统错误是否区分？
- 错误信息是否对调用者有足够的价值（可定位问题）？
缺陷6：缺少幂等设计
写操作接口没有幂等性保障，在网络抖动或调用方重试时可能导致重复创建订单、重复扣款等业务事故。
评审检查点：
- 所有写操作是否支持幂等调用？
- 幂等实现方式是否合理（唯一业务键 vs 状态机 vs 分布式锁）？
数据级缺陷
缺陷7：数据一致性无保障
跨服务的数据修改没有一致性保障机制。典型表现：订单服务创建订单后，库存服务扣减库存失败，但订单已不可回滚。
评审检查点：
- 跨服务的数据修改是否有一致性保障机制（Saga、TCC、事件驱动）？
- 一致性保障机制的失败场景是否有明确的补偿策略？
- 是否有最终一致性的校验与修复机制？
缺陷8：读写比例未分析
数据存储选型没有基于读写比例分析。例如日志型数据（写多读少）选了 MySQL，而配置型数据（写少读多）应该用缓存。
评审检查点：
- 核心数据表的读写比例是否有量化分析？
- 存储选型是否与读写比例匹配？
- 是否有热点数据的缓存策略？
运维级缺陷
缺陷9：可观测性缺失
系统没有结构化日志、指标暴露、链路追踪的完整覆盖。出问题时只能"看日志猜原因"。
评审检查点：
- 是否有结构化日志输出（包含 traceId、业务标识、关键参数）？
- 是否暴露了核心业务指标（QPS、延迟分布、错误率）？
- 是否接入链路追踪（OpenTelemetry）？
缺陷10：回退方案未设计
上线方案没有回退设计，一旦上线出问题，只能"紧急修代码"而非"快速回退到旧版本"。
评审检查点：
- 是否有数据兼容性保障（新旧版本数据格式兼容）？
- 是否有灰度发布方案（先小流量再全量）？
- 回退操作是否能在 10 分钟内完成？
安全级缺陷
缺陷11：权限边界未定义
服务间调用没有权限控制，任何服务都能调用任何接口，导致内部调用链不可管控。
评审检查点：
- 服务间调用是否有认证机制？
- 接口是否有权限分级（内部调用 vs 外部调用）？
- 是否有调用来源的审计日志？
缺陷12：API 无限流防护
对外暴露的 API 没有限流保护，异常流量可能导致服务崩溃。
评审检查点：
- 是否有全局限流策略？
- 是否有基于调用来源的差异化限流？
- 限流后的拒绝响应是否友好？
三、实践案例：架构评审检查清单的自动化检测
以下是一个基于检查清单的架构评审辅助工具：
@Service @Slf4j public class ArchitectureReviewService { private final ReviewChecklistRepository checklistRepository; private final ReviewResultRepository resultRepository; public ArchitectureReviewService(ReviewChecklistRepository checklistRepository, ReviewResultRepository resultRepository) { this.checklistRepository = checklistRepository; this.resultRepository = resultRepository; } /** * 执行架构评审检查——基于预定义的检查清单逐项评估 * * @param proposalId 待评审的技术方案ID * @param reviewerId 评审人ID * @return 评审结果，包含各维度的检查项与问题清单 */ public ReviewResult executeReview(Long proposalId, String reviewerId) { try { // 加载完整检查清单 List<ReviewCheckItem> allCheckItems = checklistRepository.loadAllCheckItems(); ReviewResult result = new ReviewResult(); result.setProposalId(proposalId); result.setReviewerId(reviewerId); result.setReviewedAt(LocalDateTime.now()); int passCount = 0; int failCount = 0; int warningCount = 0; for (ReviewCheckItem item : allCheckItems) { CheckResult checkResult = evaluateCheckItem(proposalId, item); result.addCheckResult(item.getCategory(), item.getDescription(), checkResult); switch (checkResult.getStatus()) { case PASS -> passCount++; case FAIL -> failCount++; case WARNING -> warningCount++; } } // 生成评审结论 if (failCount > 0) { result.setConclusion(ReviewConclusion.REJECT); result.setSummary("存在" + failCount + "个必须修改的设计缺陷，方案需修订后重新评审"); } else if (warningCount >= 3) { result.setConclusion(ReviewConclusion.CONDITIONAL_PASS); result.setSummary("存在" + warningCount + "个需要关注的潜在风险，建议补充设计后通过"); } else { result.setConclusion(ReviewConclusion.PASS); result.setSummary("评审通过，共" + passCount + "项通过，" + warningCount + "项建议关注"); } ReviewResult saved = resultRepository.save(result); log.info("架构评审完成, proposalId={}, conclusion={}, pass={}, fail={}, warning={}", proposalId, result.getConclusion(), passCount, failCount, warningCount); return saved; } catch (DataAccessException e) { log.error("评审结果保存失败, proposalId={}", proposalId); throw new BusinessException("评审保存失败，请重试"); } } /** * 评估单个检查项——检查方案文档中是否覆盖了该设计维度 * * @param proposalId 方案ID * @param item 检查项定义 * @return 检查结果（PASS/FAIL/WARNING） */ private CheckResult evaluateCheckItem(Long proposalId, ReviewCheckItem item) { try { // 检查方案文档中是否有对应的描述 boolean covered = checkProposalCoverage(proposalId, item.getRequiredKeywords()); if (!covered && item.isMandatory()) { // 必须项未覆盖 → FAIL return CheckResult.fail( "方案未覆盖" + item.getCategory() + "维度: " + item.getDescription(), item.getFixSuggestion() ); } else if (!covered && !item.isMandatory()) { // 建议项未覆盖 → WARNING return CheckResult.warning( "方案建议补充" + item.getCategory() + "维度的设计: " + item.getDescription(), item.getFixSuggestion() ); } else { // 已覆盖 → PASS return CheckResult.pass("方案已覆盖" + item.getDescription()); } } catch (ProposalAccessException e) { log.error("方案文档访问异常, proposalId={}, item={}", proposalId, item.getId()); return CheckResult.fail("无法访问方案文档，评审中断", "请确认方案文档已提交"); } } /** * 检查方案文档中是否包含指定关键词（简化实现） * 实际生产中可接入 NLP 分析或规则引擎 */ private boolean checkProposalCoverage(Long proposalId, List<String> requiredKeywords) { String proposalContent = loadProposalContent(proposalId); for (String keyword : requiredKeywords) { if (!proposalContent.contains(keyword)) { return false; } } return true; } }关键设计点：
- 检查清单区分"必须项"和"建议项"——必须项未覆盖直接 FAIL，建议项未覆盖给出 WARNING
- 评审结论三级：PASS（通过）、CONDITIONAL_PASS（有条件通过，需补充设计）、REJECT（存在必须修改的缺陷）
- 每个检查项都有
fixSuggestion（修复建议），帮助方案作者理解"需要补充什么"
四、常见问题与避坑
问题一：评审"只看文档不看逻辑"
架构评审的价值不在于检查"文档是否完整"，而在于检查"设计逻辑是否正确"。完整但逻辑错误的方案，比不完整但逻辑正确的方案风险更大。评审者需要理解方案的设计意图，而非只看表面形式。
问题二：评审变成"挑毛病大会"
评审的目的不是"找尽可能多的问题"，而是"找最关键的几个风险"。建议每次评审聚焦前 5 个最重要的设计维度，深度讨论而非广度扫描。
问题三：评审结果没有后续跟踪
评审发现了问题但没有跟踪修复，等于"白评审"。评审结论必须进入项目管理的跟踪流程——REJECT 的方案需要修订后重新评审，CONDITIONAL_PASS 的方案需要在实施前补充设计。
问题四：检查清单"一成不变"
不同项目类型的检查重点不同——高并发系统的重点在容量规划，数据密集系统的重点在一致性保障，AI 系统的重点在效果评测和成本管控。检查清单需要根据项目类型动态调整权重和覆盖范围。
五、总结与展望
架构评审的避坑手册，核心结论是：评审的价值不在于"找到了多少问题"，而在于"防止了多少重大缺陷进入实施阶段"。五类常见设计缺陷——架构级、接口级、数据级、运维级、安全级——覆盖了架构评审的核心检查维度。系统化的检查清单是评审效率和质量的基础保障。
下半年的评审实践重点：
- 开发检查清单的项目类型适配机制——根据项目类型自动调整检查重点
- 建立评审案例库——记录每次评审发现的典型缺陷和修复方案，为后续评审提供参考
- 将评审检查清单与 ADR 流程结合——确保重大设计决策都有评审记录
架构评审是架构师最重要的"质量守门"职责。系统化的检查清单让评审从"经验驱动"升级为"方法驱动"，从"随机提问"升级为"全面覆盖"。这不是"形式主义"，而是"降低重大设计缺陷进入生产环境概率"的工程化手段。
资料说明
本文中的协议、版本、性能、成本和行业趋势应以可核验的一手资料为准。未标注统计口径的比例、时间表和预测仅作工程讨论，不应视为行业事实。可参考 0730 资料来源索引，并在发布前将具体来源贴到对应断言之后。
