媒介
系统设计文档是软件开辟过程中至关重要的交付物，它清楚地描述了系统的架构、组件和交互方式。以下是怎样创建一份高质量系统设计文档的指南：
一、文档布局
一份完整的系统设计文档通常包罗以下部门：
- 标题页：项目名称、版本、日期、作者。例如：
- 修订历史：记录文档的变更。例如：
-
- 目次：便于导航。例如：
- 弁言：目的、范围、读者对象。例如：
- 系统概述：高层次描述
- 设计考虑：假设、约束、依赖
- 架构设计：系统架构图、组件描述
- 数据设计：数据模子、存储方案
- 接口设计：API、用户界面
- 非功能性需求：性能、安全、可扩展性等
- 部署方案：情况需求、部署架构
- 测试策略：测试方法概述
- 附录：术语表、参考资料
二、关键内容要点
2.1 系统概述
2.1.1 系统要办理的问题
本系统旨在办理 [扼要描述核心问题]，当前行业或业务面对的挑衅包罗：
- 问题1（如：数据孤岛、低效的人工流程、高延迟相应、安全漏洞等）
- 问题2（如：缺乏可扩展性、用户体验差、维护本钱高等）
- 问题3（如：多系统集成困难、数据分析能力不足等）
例如，假如设计的是一个电商订单处理系统，问题可能是：
“当前订单处理依赖人工审核，导致高峰期延迟严重，错误率高，且无法及时跟踪库存变化，影响客户体验和运营效率。”
2.1.2 核心功能与代价主张
本系统的重要功能包罗：
(1) 核心功能
- 功能1（如：自动化订单处理）
- 描述：系统自动吸收、验证并处理订单，淘汰人工干预。
- 代价：提高处理速度，降低错误率。
- 功能2（如：及时库存管理）
- 描述：与仓储系统集成，及时更新库存状态。
- 代价：制止超卖，优化供应链管理。
- 功能3（如：智能风控与付出审核）
- 描述：基于规则引擎和机器学习检测欺诈生意业务。
- 代价：降低欺诈风险，提高生意业务安全性。
(2) 代价主张
- 业务代价（如：提高订单处理效率30%，淘汰人工本钱20%）
- 技能代价（如：接纳微服务架构，支持高并发和灵活扩展）
- 用户体验（如：提供及时订单状态跟踪，提升客户满意度）
2.1.3 系统界限（In-Scope & Out-of-Scope）
明确系统的范围有助于制止需求伸张，并聚焦核心功能。
(1) 包罗的内容（In-Scope）
✅ 核心业务流程（如：订单创建、付出处理、库存扣减）
✅ 关键集成点（如：与付出网关、物流系统的API对接）
✅ 数据管理（如：订单数据存储、用户举动日志）
✅ 安全与合规（如：数据加密、GDPR合规性）
(2) 不包罗的内容（Out-of-Scope）
❌ 非核心功能（如：用户交际互动、广告推荐系统）
❌ 第三方系统内部逻辑（如：付出网关的具体风控策略）
❌ 超出当前阶段的需求（如：AI驱动的动态定价，可能在将来迭代中实现）
2.1.4 系统关键指标（可选）
- 性能：支持每秒 X 个并发请求，均匀相应时间 < Y ms
- 可用性：99.9% SLA（全年宕机时间 < 8.76小时）
- 数据规模：预计日均订单量 10万+，存储 TB级 数据
2.1.5 预期用户与长处相关者
- 终极用户（如：斲丧者、商家、客服人员）
- 管理员（如：运营团队、风控审核员）
- 技能团队（如：开辟、运维、测试）
总结：系统概述部门应清楚界说 问题、功能、代价、界限，确保所有长处相关者对系统的目标和范围告竣一致。
2.2 架构设计
2.2.1 架构图（基于C4模子）
本系统接纳 分层架构 和 微服务设计模式，确保高内聚、低耦合。架构图按 C4模子 分解如下：
(1) 上下文图（L1 - System Context）
- 核心系统 与外部依赖的关系：
- 用户（Web/App） → 本系统（订单处理）
- 付出网关（如付出宝、Stripe） ←→ 付出服务
- 库存系统 ←→ 库存管理服务
- 物流系统（如顺丰、FedEx） ←→ 物流调度服务
- (2) 容器图（L2 - Containers）
- 前端：Web（React/Vue）、Mobile（iOS/Android）
- API网关（Kong/Spring Cloud Gateway）：路由、认证、限流
- 微服务集群：
- 订单服务（Order Service）：处理订单生命周期
- 付出服务（Payment Service）：对接第三方付出
- 库存服务（Inventory Service）：及时库存管理
- 物流服务（Shipping Service）：生成运单、跟踪物流
- 数据存储：
- 关系型数据库（MySQL/PostgreSQL）：订单核心数据
- 缓存（Redis）：热门数据加快
- 消息队列（Kafka/RabbitMQ）：异步解耦
(3) 组件图（L3 - Components）
以 订单服务 为例：
- Order Controller：吸收HTTP请求
- Order Processor：业务逻辑（创建/取消订单）
- Payment Client：调用付出服务
- Inventory Client：扣减库存
- Event Publisher：发送订单事件至消息队列
(4) 类图（L4 - Code）
- UML类图 展示关键类关系（如 Order、Payment、Inventory 的关联）
2.2.2 重要组件及职责
组件职责技能栈API网关路由、认证、日志、限流Spring Cloud Gateway订单服务创建/查询/取消订单，状态机管理Spring Boot付出服务付出处理、退款、对账对接Stripe/Alipay SDK库存服务及时库存扣减、库存预警Redis + MySQL物流服务运单生成、物流状态同步第三方物流API消息队列异步处理订单事件（如付出超时检查）Kafka监控告警指标网络（Prometheus）、日志（ELK）Grafana + Alertmanager 2.2.3 组件交互方式
(1) 同步交互（HTTP/gRPC）
- 前端 → API网关 → 订单服务（创建订单）
- 订单服务 → 付出服务（预付出）
- 付出服务 → 第三方网关（实际扣款）
- 付出服务 → 订单服务（更新付出状态）
(2) 异步交互（消息队列）
- 订单服务发布 OrderCreated 事件至Kafka
- 库存服务斲丧事件 → 扣减库存
- 物流服务斲丧事件 → 生成运单
(3) 数据流
- 读写分离：
- 写操纵 → MySQL（强一致性）
- 读操纵 → Redis缓存（高性能）
2.2.4 设计决策与衡量
- 选择微服务而非单体：
- ✅ 优点：独立扩展、技能异构性
- ❌ 缺点：分布式事务（通过Saga模式补偿）
- 数据库选型：
- MySQL（订单强一致性） + Redis（库存高频读写）
- 消息队列选型：
- Kafka（高吞吐） vs RabbitMQ（低延迟）
2.2.5 架构图示例（笔墨描述）
- [用户] → [Web/Mobile] → [API Gateway]
- ↓
- [Order Service] ←→ [Payment Service]
- ↓
- [Kafka] ← OrderCreated → [Inventory Service]
- ↓
- [Shipping Service]
- 绘图工具：Draw.io（C4模板）、PlantUML（代码生成UML）
- 架构决策记录（ADR）：记录技能选型原因
总结：架构设计需明确 分层、组件职责、交互方式，并通过可视化工具（如C4/UML）传达设计意图，确保团队理解一致。
2.3 数据设计
2.3.1 数据模子（ER图与类图）
ER图（实体关系图）核心实体
类图（核心范畴模子）
- // 领域模型示例代码
- public class Order {
- private Long id;
- private Customer customer;
- private List<OrderItem> items;
- private Payment payment;
- private OrderStatus status;
- private LocalDateTime orderDate;
- // getters/setters
- }
- public class OrderItem {
- private Long id;
- private Product product;
- private int quantity;
- private BigDecimal price;
- // getters/setters
- }
- public enum OrderStatus {
- CREATED, PAID, SHIPPED, COMPLETED, CANCELLED
- }
类型方案版本推荐关键特性关系型PostgreSQL14+分区表、并行查询、JIT编译缓存Redis6.2+多线程IO、RedisJSON模块支持搜索Elasticsearch7.x向量搜索、SQL查询接口分析ClickHouse22.3+物化视图、及时数据摄入- -- PostgreSQL示例表结构
- CREATE TABLE orders (
- id BIGSERIAL PRIMARY KEY,
- customer_id BIGINT REFERENCES customers(id),
- total DECIMAL(10,2),
- status VARCHAR(20),
- created_at TIMESTAMPTZ DEFAULT NOW()
- );
- -- Redis库存操作示例
- Jedis jedis = new Jedis("redis-host");
- jedis.set("inventory:1001", "50");
- Long remaining = jedis.decr("inventory:1001");
关键数据流
- # 伪代码示例
- def create_order(order_data):
- # 1. 写入订单主表
- db.execute("INSERT INTO orders VALUES(...)")
-
- # 2. 扣减库存（Redis原子操作）
- redis.decr(f"inventory:{product_id}")
-
- # 3. 发送支付事件
- kafka.produce("payment_events", json.dumps({
- "order_id": order.id,
- "amount": order.total
- }))
容量规划
- // 数据量预估模型
- const DAILY_ORDERS = 100000; // 日订单量
- const ORDER_SIZE_KB = 10; // 单订单大小
- // 年数据量计算
- const yearlyDataGB = (DAILY_ORDERS * 365 * ORDER_SIZE_KB) / (1024 * 1024);
- console.log(`年数据量: ${yearlyDataGB.toFixed(2)} GB`);
- // 输出: 年数据量: 347.85 GB
- // 订单表按用户ID分片
- ShardingKey shardingKey = new ShardingKey(userId % 16);
- orderRepository.save(order, shardingKey);
- -- 将3个月前的订单归档
- CREATE TABLE orders_archive (LIKE orders);
- INSERT INTO orders_archive
- SELECT * FROM orders WHERE created_at < NOW() - INTERVAL '3 months';
- 数据生命周期：
┌─────────────┬──────────────────────┐
│ 数据类型 │ 保存策略 │
├─────────────┼──────────────────────┤
│ 热订单数据 │ PostgreSQL (6个月) │
│ 温订单数据 │ S3 + Athena (2年) │
│ 冷订单数据 │ Glacier (5年) │
└─────────────┴──────────────────────┘
- 索引优化：
- -- 常用查询索引
- CREATE INDEX idx_orders_user_status ON orders(customer_id, status);
- CREATE INDEX idx_orders_date ON orders(created_at);
- 终极一致性：库存扣减接纳Redis+异步MySQL更新
- 读写分离：报表查询走只读副本
- 数据加密：PCI数据使用Vault加密存储
- 备份策略：每日全量备份+WAL日志
通过以上设计，系统可支持：
- 1000+ TPS的订单创建
- 毫秒级库存查询
- 线性扩展的存储能力
2.4 接口设计
2.4.1 API规范
RESTful API 设计
- ### 创建订单
- POST /api/v1/orders HTTP/1.1
- Content-Type: application/json
- Authorization: Bearer {token}
- {
- "items": [
- {
- "product_id": "1001",
- "quantity": 2
- }
- ],
- "shipping_address": "123 Main St"
- }
- ### 查询订单
- GET /api/v1/orders/{order_id} HTTP/1.1
- Accept: application/json
- query GetOrder($id: ID!) {
- order(id: $id) {
- id
- status
- items {
- product {
- name
- price
- }
- quantity
- }
- }
- }
- mutation CreateOrder($input: OrderInput!) {
- createOrder(input: $input) {
- id
- status
- }
- }
协议类型内容格式编码使用场景HTTPSJSONUTF-8重要业务接口WebSocketProtocol BuffersBinary及时通知gRPCProtobufBinary服务间通讯 JSON Schema 示例:
- {
- "$schema": "http://json-schema.org/draft-07/schema#",
- "type": "object",
- "properties": {
- "order_id": {
- "type": "string",
- "format": "uuid"
- },
- "status": {
- "type": "string",
- "enum": ["CREATED", "PAID", "SHIPPED"]
- }
- },
- "required": ["order_id", "status"]
- }
尺度错误相应
- {
- "error": {
- "code": "INVALID_PAYMENT",
- "message": "支付金额不匹配",
- "details": {
- "expected": 100.00,
- "actual": 95.50
- },
- "trace_id": "abc123-xzy456"
- }
- }
错误类型状态码错误码示例客户端错误400VALIDATION_ERROR未授权401AUTH_REQUIRED克制访问403PERMISSION_DENIED资源不存在404ORDER_NOT_FOUND服务端错误500INTERNAL_ERROR 2.4.4 版本控制策略
版本管理方式
- /api/v1/orders
- /api/v2/orders
- GET /api/orders HTTP/1.1
- Accept: application/vnd.company.api+json;version=2
- MAJOR: 不兼容的API修改
- MINOR: 向后兼容的功能新增
- PATCH: 向后兼容的问题修正
版本过渡方案
接口变更日志示例
[2.1.0] - 2023-05-15
Added
- 订单新增estimated_delivery_time字段
Deprecated
最佳实践
- 使用Swagger/OpenAPI进行接口文档化
- 为所有接口编写自动化测试用例
- 重大变更提供至少6个月的过渡期
- 监控接口弃用情况，及时通知调用方
三、最佳实践
- 明确受众：技能团队、产品经理、运维人员可能有不同需求
- 保持简洁：制止过度具体，聚焦关键决策
- 使用可视化：一图胜千言，合理使用图表
- 记录决策：阐明为什么选择特定方案
- 版本控制：与代码一样管理文档版本
- 保持更新：设计变更时同步更新文档
- 评审流程：让相关方评审设计文档
四、工具推荐
- 绘图工具：Draw.io、Lucidchart、PlantUML
- 文档工具：Confluence、Markdown、Google Docs
- 架构工具：C4 Model、ArchiMate
- 版本控制：Git、GitHub/GitLab
五、常见错误制止
- 过于技能性或过于抽象
- 忽略非功能性需求
- 不考虑可扩展性和维护性
- 不记录设计决策的原因
- 缺乏实际约束考虑（如预算、时间）
献给读者
|
