架构设计总览

本文用于整理系统设计、技术方案、设计原则、设计模式、分布式系统、性能优化、稳定性建设、安全设计、可观测性设计和架构复盘等内容。

架构设计目录不关注某个具体框架的 API 用法，而关注：

• 为什么这样设计
• 什么场景适合这样设计
• 有哪些可选方案
• 不同方案有什么取舍
• 系统如何扩展、稳定、可观测、可维护
• 事故或问题背后的架构原因是什么

如果一篇文档主要讲“怎么使用某个技术”，通常应该放到 Java、Spring、SQL、Git、构建工具、工具库等实现层目录。

如果一篇文档主要讲“为什么这么设计、什么时候这么设计、有什么代价和取舍”，通常应该放到架构设计目录。

目录说明

设计原则

用于记录通用的软件设计原则和工程实践原则。

这类文档通常不绑定某个具体框架，具有长期复用价值。

适合放：

• 简单优先
• 避免过度设计
• 可回滚设计
• 可观测性优先
• 失败可恢复
• 幂等设计
• 防重复提交
• 超时控制
• 重试机制
• 资源隔离
• 配置外置化
• 向后兼容
• 渐进式改造

判断标准：

如果这篇文档是在讲“做系统设计时应该遵守什么原则”，放这里。

设计模式

用于记录代码结构设计、常见设计模式、重构思路和业务代码中的模式实践。

这里不只是记录 GoF 23 种设计模式，也可以记录实际业务开发中总结出来的代码组织方式。

适合放：

• 工厂模式
• 策略模式
• 模板方法模式
• 责任链模式
• 观察者模式
• 适配器模式
• 代理模式
• 建造者模式
• 事件驱动模式
• 支付渠道策略模式实践
• 风控校验责任链实践
• 同步任务模板方法实践
• 多客户端工厂封装
• 复杂 if else 重构

判断标准：

如果这篇文档主要讲“代码结构怎么设计更清晰、更可扩展”，放这里。

方法论

用于记录学习方法、工作方法、问题分析方法、代码优化方法和产品思考。

方法论不直接等于某次具体问题复盘，而是从多个问题中抽象出来的思考方式。

适合放：

• 如何分析一个线上问题
• 如何做技术选型
• 如何做代码优化
• 如何学习一个新技术
• 如何拆解复杂需求
• 如何写技术方案
• 如何做系统复盘
• 如何判断一个方案是否过度设计
• 产品视角下的技术判断

判断标准：

如果这篇文档是在讲“我应该怎么思考、怎么分析、怎么学习、怎么工作”，放这里。

如果文档是某一次具体事故或具体问题的排查过程，优先放到“问题复盘”。

场景分析

用于记录具体业务场景或技术场景下的设计分析。

这类文档通常从一个明确问题出发，分析可选方案、优缺点、实现方式和最终选择。

适合放：

• 接口耗时 500ms，目标 QPS 是 1 万，需要多少机器？
• 订单超时关闭的实现
• 灰度发布
• 定时任务设计
• 支付回调设计
• 文件上传设计
• 通知系统设计
• 审批流设计
• 任务补偿设计
• 批量导入设计
• 数据同步设计

判断标准：

如果这篇文档是在回答“某个具体场景该怎么设计”，放这里。

分布式系统

用于记录分布式系统中的通用问题和设计方案。

适合放：

• 分布式锁
• 分布式事务
• 服务注册与发现
• 配置中心
• 链路追踪
• 消息队列
• 最终一致性
• 服务调用超时
• 服务降级
• 任务调度
• 分布式 ID
• 多节点部署
• 跨服务数据同步

判断标准：

如果这篇文档的核心问题来自“多个服务、多个节点、多个系统之间如何协作”，放这里。

数据一致性

用于记录数据正确性、事务边界、幂等、补偿、对账和最终一致性相关内容。

适合放：

• 幂等设计
• 防重复提交
• 事务边界
• 本地事务与分布式事务
• 最终一致性
• 补偿机制
• 对账机制
• 重试导致的数据重复问题
• 消息重复消费
• 支付回调重复通知
• 订单状态流转一致性
• 数据同步一致性

判断标准：

如果这篇文档主要关注“数据会不会错、会不会重复、会不会丢、状态是否一致”，放这里。

系统稳定性

用于记录系统在异常情况下如何保持可用、可恢复、可降级。

适合放：

• 超时控制
• 重试机制
• 熔断
• 降级
• 限流
• 资源隔离
• 线程池隔离
• 服务保护
• 失败恢复
• 回滚方案
• 兜底方案
• 容灾设计
• 故障演练

判断标准：

如果这篇文档主要关注“系统出问题时如何不崩、如何恢复、如何兜底”，放这里。

高并发 / 高性能 / 高可用

用于记录系统容量、吞吐、性能、可用性相关的架构设计。

这个目录偏“系统怎么扛住”。

适合放：

• 如何发现系统瓶颈
• 系统容量估算
• QPS 估算
• 机器数量估算
• 高并发接口设计
• 缓存设计
• 异步化
• 批处理
• 限流
• 降级
• 数据库压力优化
• 高可用部署
• 多节点扩容
• 读写分离
• 分库分表

判断标准：

如果这篇文档主要关注“流量上来后系统如何扛住”，放这里。

性能优化

用于记录具体性能问题的优化方法。

这个目录偏“某个点怎么变快”。

适合放：

• SQL 优化
• 慢查询优化
• JVM 参数优化
• GC 优化
• 接口响应时间优化
• 批量处理优化
• 序列化优化
• 日志性能优化
• HTTP 调用优化
• 线程池参数优化
• 大文件处理优化
• 内存占用优化
• 启动速度优化

和“高并发 / 高性能 / 高可用”的区别：

• 高并发 / 高性能 / 高可用：偏系统容量和架构设计
• 性能优化：偏具体问题和局部优化手段

判断标准：

如果这篇文档是在解决“某个接口、某段代码、某条 SQL、某个服务为什么慢”，放这里。

可观测性设计

用于记录日志、指标、链路追踪、告警、排查入口等可观测性相关设计。

适合放：

• 日志设计
• TraceId 设计
• 业务日志规范
• 错误日志规范
• 指标设计
• Prometheus 指标设计
• Grafana 面板设计
• 链路追踪
• 告警规则设计
• 健康检查
• 审计日志
• 排查入口设计
• 如何让问题更容易被发现

判断标准：

如果这篇文档主要关注“系统出了问题后，我能不能快速看见、定位、解释”，放这里。

具体工具安装和部署，例如 Prometheus、Grafana、Loki、ELK、CAT 的部署文档，优先放到基础设施与运维。

安全设计

用于记录系统安全、接口安全、权限控制、数据安全和风控相关设计。

适合放：

• 接口签名
• 防重放
• 权限模型
• 数据权限
• 敏感信息脱敏
• 密码存储
• Token 设计
• API 安全
• 内外网隔离
• IP 白名单
• 访问频率限制
• 文件上传安全
• SQL 注入防护
• XSS / CSRF 防护

判断标准：

如果这篇文档主要关注“系统如何避免被误用、滥用、攻击、越权访问”，放这里。

架构复盘

用于记录架构层面的复盘、反思和经验沉淀。

它和“问题复盘”不同：

• 问题复盘：偏具体事故、具体故障、具体排查过程
• 架构复盘：偏从问题中抽象出来的架构缺陷、设计改进和长期经验

适合放：

• 某次系统改造后的架构总结
• 某次故障暴露出的设计问题
• 某个方案为什么后来不适合了
• 某次重构的得失
• 某个技术选型的复盘
• 某个系统长期演进的总结

判断标准：

如果这篇文档不是单纯记录“怎么排查”，而是总结“系统设计哪里有问题、以后怎么设计更好”，放这里。

归类规则

1. 如果文档主要讨论某个具体技术组件的使用，放到对应组件目录，例如 Java、Spring、SQL、Git、构建工具、工具库等。
2. 如果文档主要讨论“一个具体场景该怎么设计”，放入 架构设计 / 场景分析。
3. 如果文档主要讨论设计原则、设计取舍、长期经验，放入 架构设计 / 设计原则。
4. 如果文档主要讨论代码结构、设计模式、重构方式，放入 架构设计 / 设计模式。
5. 如果文档主要讨论思考方法、学习方法、分析方法、工作方法，放入 架构设计 / 方法论。
6. 如果文档主要讨论多个服务、多个节点、多个系统之间的协作，放入 架构设计 / 分布式系统。
7. 如果文档主要关注数据是否正确、一致、不重复、不丢失，放入 架构设计 / 数据一致性。
8. 如果文档主要关注系统异常情况下如何可用、可恢复、可降级，放入 架构设计 / 系统稳定性。
9. 如果文档主要关注容量、并发、吞吐、高可用，放入 架构设计 / 高并发/高性能/高可用。
10. 如果文档主要关注某个具体性能点怎么优化，放入 架构设计 / 性能优化。
11. 如果文档主要关注日志、指标、链路追踪、告警和排查入口设计，放入 架构设计 / 可观测性设计。
12. 如果文档主要关注权限、签名、防重放、脱敏、接口安全等，放入 架构设计 / 安全设计。
13. 如果文档主要是线上事故的具体排查过程，放入 问题复盘。
14. 如果文档主要讨论业务流程本身，放入业务知识库或业务 wiki。
15. 如果一篇文档中既有实现细节又有设计取舍，优先看文档目标：讲怎么写代码放实现层，讲为什么这样设计放架构设计。

常见判断

• 订单超时关闭的实现：架构设计 / 场景分析
• 接口 QPS 估算：架构设计 / 场景分析
• 灰度发布：架构设计 / 场景分析
• 支付回调重复通知怎么处理：架构设计 / 数据一致性
• 接口超时和重试怎么设计：架构设计 / 系统稳定性
• 如何发现系统瓶颈：架构设计 / 高并发/高性能/高可用
• 某条 SQL 很慢怎么优化：架构设计 / 性能优化 或 SQL
• Prometheus 怎么安装：基础设施与运维 / 监控告警
• 系统指标应该怎么设计：架构设计 / 可观测性设计
• 接口签名怎么设计：架构设计 / 安全设计
• Redis 分布式锁代码实现：Spring 集成案例 / 工具库 / Redis 相关实现文档
• 分布式锁适用场景和风险：架构设计 / 分布式系统
• 某次线上故障排查过程：问题复盘
• 某次故障暴露出的架构问题总结：架构设计 / 架构复盘
• 策略模式处理多支付渠道：架构设计 / 设计模式
• 如何分析一个复杂问题：架构设计 / 方法论

与其它目录的边界

与 Java / Spring / Quarkus 的边界

Java、Spring、Quarkus 主要记录具体技术实现。

例如：

• Spring Boot 配置文件怎么写
• Spring Boot Actuator 怎么接入
• Java ThreadPoolExecutor 怎么使用
• Quarkus 怎么配置 Redis

这些放实现层。

如果文档讨论的是：

• 为什么要做线程池隔离
• 怎么设计系统指标
• 怎么设计超时和重试
• 怎么做系统容量估算

这些放架构设计。

与 SQL 的边界

SQL 目录主要记录 SQL 写法、数据库语法、执行计划、数据恢复等开发视角内容。

如果文档主要是：

• MySQL EXPLAIN 怎么看
• PostgreSQL 建表语法
• 根据 MySQL 表生成 PostgreSQL 建表语句

放 SQL。

如果文档主要是：

• 数据库索引设计原则
• 如何降低数据库压力
• 读写分离怎么设计
• 数据一致性如何保证

放架构设计。

与问题复盘的边界

问题复盘记录具体事故和排查过程。

架构复盘记录从问题中抽象出来的架构经验。

例如：

• 某次 No route to host 的排查过程：问题复盘
• 这次问题说明服务依赖和网络隔离应该如何设计：架构设计 / 架构复盘

与基础设施与运维的边界

基础设施与运维记录部署、安装、配置、运行维护。

架构设计记录系统层面的设计原则和方案。

例如：

• Prometheus 安装：基础设施与运维
• 指标体系如何设计：架构设计 / 可观测性设计
• Nginx 配置 Basic Auth：基础设施与运维
• 接口访问安全方案：架构设计 / 安全设计