详细设计实战：数据库 + 接口 + 概要设计的层次化文档

Mon, 15 Sep 2025 00:00:00 +0800

详细设计（Detailed Design）是项目从"概要"走向"可编码"的关键文档——它是程序员写代码的"施工图"。本文基于多年项目实践，给出一套层次化、可落地的详细设计实战模板。

本文写于 2025 年 9 月——敏捷开发的时代，详设不会过时，只是形式更轻量。

一、详细设计 vs 概要设计

维度	概要设计	详细设计
粒度	模块 / 子系统	函数 / 类 / 表
读者	架构师 / PM	程序员
目的	划定边界	指导编码
重点	架构图 / 模块划分	数据结构 / 算法 / 接口
产物	架构图 / 接口契约	类图 / 时序图 / 表结构
更新频率	季度	周 / 迭代

二、详细设计 7 大章节

2.1 章节结构总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


1. 引言
 1.1 编写目的
 1.2 背景
 1.3 参考资料
 1.4 术语定义及说明

2. 设计概述
 2.1 任务和目标
 2.2 需求概述
 2.3 运行环境概述
 2.4 条件与限制
 2.5 详细设计方法和工具

3. 系统详细需求分析
 3.1 详细需求分析
 3.2 详细系统运行环境及限制条件分析
 3.3 接口需求分析

4. 总体方案确认
 4.1 系统总体结构确认
 4.2 系统详细界面划分

5. 系统详细设计
 5.1 系统结构设计及子系统划分
 5.2 系统功能模块详细设计
 （采用 HIPO 图进行功能分解与模块描述）
 5.3 用 IPO 或结构图描述各模块的组成结构、算法、模块间的接口关系，
 以及需求、功能和模块三者之间的交叉参照关系
 5.4 系统界面详细设计

6. 数据库系统设计
 6.1 数据库概念设计（E-R 图）
 6.2 数据库逻辑设计（表结构）
 6.3 数据库物理设计（索引 / 分区）
 6.4 数据字典

7. 接口设计
 7.1 内部接口（模块间）
 7.2 外部接口（系统间）
 7.3 用户接口（UI）

三、章节 1：引言

3.1 编写目的

模板：

本文是某项目的详细设计文档，目的是：

明确系统的功能模块划分和接口关系

为程序员编码提供"施工图"

作为测试用例设计的依据

作为项目验收的标准

预期读者：项目开发工程师、测试工程师、架构师、产品经理

3.2 背景

模板：

项目名称：某业务系统委托单位：某部门开发单位：某研发部主管部门：某信息中心

3.3 参考资料

模板：

序号	文档名称	作者	日期	版本
1	需求规格说明书	张三	2025-09-01	V1.0
2	概要设计文档	李四	2025-09-10	V1.0
3	数据库设计规范	王五	2025-08-15	V2.0

3.4 术语定义

术语	解释
CRM	客户关系管理
ERP	企业资源计划
MES	制造执行系统
…	…

四、章节 2：设计概述

4.1 任务和目标

任务：完成某业务系统的详细设计，确保系统可实现性。

目标：

100% 覆盖需求规格说明书的功能点
性能指标：响应时间 < 2s，并发 1000+
可用性：99.9%
安全性：通过等保三级

4.2 需求概述

简要说明系统要实现的核心功能（不超过 5 页）：

用户管理（登录、权限、角色）
订单管理（创建、查询、修改、删除）
报表管理（日报、月报、季报）
系统管理（参数配置、日志审计）

4.3 运行环境

维度	描述
操作系统	Linux 7+ / Windows Server 2016+
Web 服务器	Nginx 1.20+
应用服务器	Tomcat 9 / Spring Boot 内嵌
数据库	MySQL 8.0+
缓存	Redis 6+
消息队列	RabbitMQ / Kafka
监控	Prometheus + Grafana
日志	ELK（Elasticsearch + Logstash + Kibana）

4.4 条件与限制

必须兼容 IE 11 浏览器（仅老系统迁移）
数据库必须使用 MySQL（甲方要求）
单台服务器资源：16 核 32G
项目周期：6 个月

4.5 详细设计方法和工具

设计方法：面向对象（OOAD）+ 结构化（SA/SD）
设计模式：MVC、Factory、Strategy、Observer
设计工具：PlantUML、draw.io、Visio
文档工具：Confluence + Markdown

五、章节 3：详细需求分析

5.1 功能需求矩阵

需求 ID	需求名称	优先级	详细说明
FR-001	用户登录	高	支持账密、SSO、扫码登录
FR-002	权限管理	高	RBAC 模型
FR-003	订单创建	高	包含订单明细
…	…	…	…

5.2 非功能需求

类别	指标
性能	响应时间 < 2s，并发 1000+
可用性	99.9%（年宕机 < 8.76 小时）
安全性	等保三级
兼容性	Chrome / Edge / Firefox 最新版
可维护性	模块独立部署

5.3 接口需求

内部接口：模块 A 调用模块 B 的接口
外部接口：与 CRM、ERP、支付的接口
数据接口：数据库、缓存、文件

六、章节 4：总体方案确认

4.1 系统总体结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


┌────────────────────────────────────┐
│ 表现层（Web/App） │
├────────────────────────────────────┤
│ API 网关（Gateway） │
├────────────────────────────────────┤
│ 业务服务层（订单 / 用户 / 报表） │
├────────────────────────────────────┤
│ 数据访问层（MyBatis / JPA） │
├────────────────────────────────────┤
│ 数据层（MySQL / Redis / MQ） │
└────────────────────────────────────┘

4.2 模块划分

模块编号	模块名称	职责
M-001	用户中心	登录、权限、SSO
M-002	订单中心	订单生命周期
M-003	报表中心	数据聚合、可视化
M-004	系统中心	字典、参数、日志

七、章节 5：系统详细设计（核心）

7.1 模块 HIPO 图

HIPO（Hierarchy plus Input-Process-Output） 是经典的结构化设计方法。

示例：订单中心 HIPO 图

1
2
3
4
5
6
7
8
9


 订单中心
 │
 ┌─────────────────┼─────────────────┐
 │ │ │
 订单创建 订单查询 订单修改
 │ │ │
 ┌────┴────┐ ┌───┴───┐ ┌────┴────┐
 │ │ │ │ │ │
 输入参数 业务规则 输入条件 返回结果 输入参数 业务规则

7.2 模块详细设计

每个模块都需要包含：

字段	描述
1. 模块编号	M-002
2. 模块名称	订单中心
3. 输入	订单数据 / 用户 ID / 操作类型
4. 处理	业务逻辑描述
5. 算法描述	伪代码 / 流程图
6. 输出	订单结果 / 错误码

7.3 模块 1：订单创建（M-002-001）

1. 模块编号：M-002-001

2. 模块名称：订单创建

3. 输入：

1
2
3
4
5
6
7
8
9


{
 "userId": "12345",
 "items": [
 {"productCode": "P001", "qty": 2, "price": 99.00},
 {"productCode": "P002", "qty": 1, "price": 199.00}
 ],
 "addressId": "A001",
 "remark": "请尽快发货"
}

4. 处理：

校验用户登录态
校验商品库存（每件商品）
校验地址有效性
计算订单总金额（含运费、优惠）
创建订单记录
冻结库存
返回订单号

5. 算法描述（伪代码）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


def create_order(user_id, items, address_id, remark):
 # 1. 校验登录
 user = check_login(user_id)
 if not user:
 return error(401, "未登录")

 # 2. 校验库存
 for item in items:
 stock = get_stock(item.product_code)
 if stock < item.qty:
 return error(400, f"商品 {item.product_code} 库存不足")

 # 3. 校验地址
 address = get_address(address_id)
 if not address or address.user_id != user_id:
 return error(400, "地址无效")

 # 4. 计算金额
 total = 0
 for item in items:
 total += item.qty * item.price
 shipping_fee = calc_shipping(address, total)
 discount = calc_discount(user, total)
 final_total = total + shipping_fee - discount

 # 5. 创建订单
 with transaction():
 order_no = generate_order_no()
 order = Order(
 order_no=order_no,
 user_id=user_id,
 status="待付款",
 total=final_total,
 remark=remark
 )
 order.save()

 for item in items:
 order_item = OrderItem(
 order_no=order_no,
 **item
 )
 order_item.save()

 # 6. 冻结库存
 for item in items:
 freeze_stock(item.product_code, item.qty, order_no)

 return success({"order_no": order_no, "total": final_total})

6. 输出：

1
2
3
4
5
6
7
8


{
 "code": 200,
 "data": {
 "orderNo": "SO20250915001",
 "total": 397.00,
 "payUrl": "https://pay.example.com/..."
 }
}

7.4 模块 2：订单查询（M-002-002）

输入：

1
2
3
4
5
6


{
 "userId": "12345",
 "page": 1,
 "size": 20,
 "status": "待发货"
}

处理：

分页查询订单主表
关联查询订单明细
返回结果

输出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "code": 200,
 "data": {
 "total": 50,
 "list": [
 {
 "orderNo": "SO20250915001",
 "status": "待发货",
 "total": 397.00,
 "items": [...]
 }
 ]
 }
}

八、章节 6：数据库系统设计

8.1 E-R 图

1
2
3


用户 ──< 订单 >── 订单明细 >── 商品
 │
 └──< 支付

8.2 核心表设计

订单主表（t_order）：

字段	类型	必填	说明
order_no	VARCHAR(32)	Y	主键
user_id	BIGINT	Y	用户 ID
status	VARCHAR(20)	Y	订单状态
total_amount	DECIMAL(18,2)	Y	总金额
shipping_fee	DECIMAL(18,2)	Y	运费
discount	DECIMAL(18,2)	Y	优惠
final_amount	DECIMAL(18,2)	Y	实付金额
address_id	BIGINT	Y	收货地址 ID
remark	VARCHAR(500)		备注
created_at	DATETIME	Y	创建时间
updated_at	DATETIME	Y	更新时间
version	INT	Y	乐观锁版本

订单明细表（t_order_item）：

字段	类型	必填	说明
id	BIGINT	Y	主键
order_no	VARCHAR(32)	Y	订单号
product_code	VARCHAR(50)	Y	商品编码
product_name	VARCHAR(200)	Y	商品名称（冗余）
qty	INT	Y	数量
price	DECIMAL(18,2)	Y	单价
amount	DECIMAL(18,2)	Y	金额

支付表（t_payment）：

字段	类型	必填	说明
id	BIGINT	Y	主键
order_no	VARCHAR(32)	Y	订单号
pay_type	VARCHAR(20)	Y	支付方式
pay_amount	DECIMAL(18,2)	Y	支付金额
pay_status	VARCHAR(20)	Y	支付状态
pay_time	DATETIME		支付时间

8.3 索引设计

表	索引	字段	类型
t_order	PK	order_no	主键索引
t_order	IDX_user_status	user_id, status	联合索引
t_order	IDX_created	created_at	普通索引
t_order_item	PK	id	主键索引
t_order_item	IDX_order	order_no	普通索引
t_order_item	IDX_product	product_code	普通索引
t_payment	PK	id	主键索引
t_payment	IDX_order	order_no	唯一索引

8.4 数据字典

订单状态字典：

状态码	状态名称	描述
10	待付款	订单创建未支付
20	已付款	已支付待发货
30	已发货	已发货待收货
40	已完成	已确认收货
50	已取消	用户主动取消
60	已退款	退款完成

九、章节 7：接口设计

7.1 RESTful API 规范

统一格式：

1
2
3
4
5
6
7


{
 "code": 200,
 "message": "success",
 "data": { ... },
 "timestamp": "2025-09-15T10:00:00Z",
 "traceId": "abc123"
}

错误码：

错误码	含义
200	成功
400	参数错误
401	未登录
403	无权限
404	资源不存在
500	系统错误

7.2 订单 API 列表

方法	路径	描述
POST	`/api/orders`	创建订单
GET	`/api/orders/{orderNo}`	查询订单详情
GET	`/api/orders`	分页查询
PUT	`/api/orders/{orderNo}`	修改订单
DELETE	`/api/orders/{orderNo}`	删除订单（仅草稿）
POST	`/api/orders/{orderNo}/pay`	发起支付
POST	`/api/orders/{orderNo}/cancel`	取消订单

7.3 API 详细设计

POST /api/orders 创建订单

请求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


POST /api/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGc...

{
 "items": [
 {"productCode": "P001", "qty": 2, "price": 99.00}
 ],
 "addressId": "A001",
 "remark": "请尽快发货"
}

响应：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


HTTP/1.1 200 OK
Content-Type: application/json

{
 "code": 200,
 "message": "success",
 "data": {
 "orderNo": "SO20250915001",
 "total": 198.00,
 "payUrl": "https://pay.example.com/..."
 }
}