接口设计 on Liangweidong's blog

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

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/..."
 }
}

错误码：

code	message	触发条件
400	INVALID_PARAMS	参数校验失败
401	UNAUTHORIZED	未登录
403	NO_PERMISSION	无下单权限
409	STOCK_NOT_ENOUGH	库存不足
500	SYSTEM_ERROR	系统异常

十、详细设计的常见问题

10.1 写得太"概要"

症状：详细设计文档和概要设计文档内容重复，没有具体到函数 / 表 / 接口。

解决：每个模块都必须有"输入 / 处理 / 输出 / 算法描述"4 个要素。

10.2 写得太"详细"

症状：详细设计文档变成代码注释，文档太长没人看。

解决：只描述"做什么"和"用什么算法"，不写具体代码。伪代码为主，复杂逻辑用流程图。

10.3 不更新

症状：代码已经改了好几版，详细设计文档还是 v1.0。

解决：

每个迭代更新一次
引入变更管理（设计变更需评审）
详细设计与代码不一致时，以代码为准 + 标注 TODO 更新文档

10.4 不评审

症状：详细设计文档直接进入开发，没有同行评审。

解决：

必须经过至少 2 人评审
评审 checklist：覆盖率、正确性、一致性、可读性

十一、写在最后

详细设计的本质是"将概要变成可施工的图纸"——既不能太抽象（程序员看不懂），也不能太具体（变成代码注释）。

个人建议：

新项目起步：用本模板的 7 大章节结构

敏捷项目：用轻量版（只保留 3 / 5 / 6 / 7 章节）

核心模块：必须写（订单、支付、库存）

辅助模块：可以只写接口设计

评审流程：至少 2 人同行评审 + 1 人架构师 review

参考资料

REST API 企业级设计实战：登录鉴权、重大危险源、双预防与园区版双向同步

Sun, 15 Nov 2020 00:00:00 +0800

背景：本文以一份 1931 行的"安全生产类平台"接口规范为蓝本——它包含登录、重大危险源监测设备、双预防（安全风险分析单元/事件/管控措施/隐患排查任务/记录/信息）、特殊作业票、教育培训等 30+ 个端点，全部采用统一响应体 + Bearer Token + add/update/delete 三段式风格。本文重点不是"再写一遍规范"，而是抽丝剥茧出企业级 REST API 设计的 6 大原则，让读者下次写接口时直接对号入座。

Why 2020 年：REST 在 2014-2018 完成主流化（Spring 5 / JAX-RS 2.1 / OpenAPI 3.0 都是这一时期定型的），2020 年是企业从"能跑"转向"规范 + 可观测"的分水岭。本文的方法论至今仍是企业级接口设计的底座。

一、统一响应体：把"成功"和"业务失败"分开

很多团队在写 REST 接口时，第一反应是"成功返回数据、失败抛 4xx/5xx + 异常 message"——但企业级 API 必须把"协议层错误"和"业务层错误"分开，否则前端要写两套解析逻辑，后端监控也要维护两套指标。

1.1 业界三大响应体风格对比

风格	成功	业务失败	网络失败	典型代表
HTTP 优先	`200 + 数据`	`4xx/5xx + 错误体`	`5xx + 异常`	Spring MVC 默认、Express 默认
统一信封	`200 + {code:0, data}`	`200 + {code:1xxx, msg}`	`5xx + 异常`	阿里云 API、字节内部 RPC 协议
混合模式	`200/201 + 数据`	`4xx + 业务 code`	`5xx + 异常`	GitHub API、Stripe API

这份规范采用"统一信封"风格，所有业务成功都返回 200，靠 code 字段区分：

1
2
3
4
5
6


{
 "msg": "成功",
 "code": 0,
 "data": null,
 "success": true
}

设计要点：

code = 0 表示业务成功，非 0 表示业务错误（避免误用 HTTP 200 + 业务失败 + HTTP 4xx 三者交叉）

success 冗余但友好，前端 if (res.success) 比 if (res.code === 0) 可读性高

msg 用中文（业务系统），对外公开的 API 建议英文 + 国际化 key

data 类型根据业务而定，列表/对象/null 都允许

1.2 状态码语义对照表

HTTP 状态码	业务场景	后端处理	前端处理
200	业务成功（包含 `code != 0` 业务失败）	永远返回 200	看 `success` 字段
400	请求参数格式错误（JSON 解析失败）	Spring `@Valid` 触发	弹"参数错误"Toast
401	Token 缺失/过期/无效	拦截器抛 `AuthException`	跳登录页
403	权限不足	RBAC 拦截	弹"无权限"
404	资源不存在	`@ExceptionHandler`	弹"记录不存在"
429	限流	Sentinel/Sentinel 拦截	弹"操作太频繁"
500	系统异常	全局异常处理	弹"系统异常"+ 上报埋点
502/503/504	网关/上游异常	Nginx/OpenResty	弹"服务暂不可用"

二、URL 命名：模块化 + 资源化 + 动词三段式

这份规范的 URL 设计非常典型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


POST /hazard/monitorEquip/add # 重大危险源-监测设备-新增
POST /hazard/monitorEquip/update # 重大危险源-监测设备-修改
POST /hazard/monitorEquip/delete # 重大危险源-监测设备-删除
POST /prevent/riskUnit/add # 双预防-风险分析单元-新增
POST /prevent/riskEvents/add # 双预防-安全风险事件-新增
POST /prevent/riskMeasures/add # 双预防-管控措施-新增
POST /prevent/troubleshootTask/add # 双预防-隐患排查任务-新增
POST /prevent/troubleshootRecord/add # 双预防-隐患排查记录-新增
POST /prevent/troubleshootInfo/add # 双预防-隐患排查信息-新增
POST /prevent/ticketBaseInfo/add # 特殊作业票-票证信息-新增
POST /prevent/trainBaseInfo/add # 教育培训-培训信息-新增

2.1 URL 设计的 4 层语义

层级	含义	这份规范的做法
L1 一级模块	业务域	`hazard`（重大危险源）、`prevent`（双预防 + 特殊作业票 + 教育培训）、`system`（系统）
L2 二级模块	子系统	`monitorEquip`（监测设备）、`riskUnit`（风险单元）
L3 动作	CRUD	`add` / `update` / `delete`（不是 RESTful 的 POST/GET/PUT/DELETE）
L4 路径参数	资源 ID	写在请求体 `id` 字段，不是 URL

2.2 这种"动作式 URL" vs RESTful 风格

RESTful 风格（HTTP 动词 + 资源）：

1
2
3
4


POST /api/v1/hazard/monitor-equip # 新增
GET /api/v1/hazard/monitor-equip/{id} # 查询
PUT /api/v1/hazard/monitor-equip/{id} # 修改
DELETE /api/v1/hazard/monitor-equip/{id} # 删除

这份规范的动作式风格：

1
2
3


POST /hazard/monitorEquip/add
POST /hazard/monitorEquip/update
POST /hazard/monitorEquip/delete

维度	RESTful	动作式（这份规范）
HTTP 动词丰富度	4-5 个	仅 POST（与 CSRF/中间件兼容性好）
网关路由匹配	复杂（要看动词）	简单（只看路径）
审计日志	看 `method + path`	看 `path`（更易聚合）
团队学习成本	中	低（无歧义）
幂等性	需显式声明	`update`/`delete` 天然要求幂等
OpenAPI 自动生成	友好	不友好（同一路径下多个动作）

我的建议：对内系统、CRUD 密集型、强审计 → 动作式（add/update/delete）；对外 API、平台化 → RESTful。这份规范属于前者，理由是它要对接大量前端 + 移动端 + 第三方园区版系统，用 POST /xxx/add 这种风格，后端可以用统一的请求体 + 鉴权 + 日志拦截器，避免 HTTP 动词带来的中间件兼容性问题。

2.3 命名规范：驼峰 vs 短横线

1
2
3
4
5
6
7


# 驼峰（这份规范）
/hazard/monitorEquip
/prevent/riskUnit

# 短横线（RESTful 推荐）
/hazard/monitor-equip
/prevent/risk-unit

风格	优点	缺点
驼峰 `monitorEquip`	与 Java/Go 字段名一致	URL 编码 `%2D` 不需要，但 RFC 3986 不推荐
短横线 `monitor-equip`	RFC 3986 友好、SEO 友好	需与字段名手动映射

最佳实践：对外 API 用短横线（GitHub、Twitter、Stripe 都这样），对内 RPC 用驼峰（与业务代码一致，减少转换）。

三、鉴权：Bearer Token + 30 天有效期

3.1 登录接口

1
2


POST /system/login
Content-Type: application/json

请求体：

1
2
3
4


{
 "userName": "{{USERNAME}}",
 "password": "{{PASSWORD}}"
}

响应体：

1
2
3
4
5
6
7
8


{
 "msg": "",
 "code": 0,
 "data": {
 "token": "{{TOKEN}}"
 },
 "success": true
}

脱敏说明：源文档中 userName 默认填 admin、password 默认填 123456、token 是一个真实的 UUID 格式字符串（b5b6b03f-18f4-4caf-acdf-25c5cc555bd3）。默认账号密码不应在博文中演示，token 也应视为凭据——博文全部用 {{}} 占位。

3.2 业务请求的鉴权头

1
2
3


POST /hazard/monitorEquip/add
Authorization: Bearer {{TOKEN}}
Content-Type: application/json

关键设计：

项	取值	原因
鉴权方案	`Bearer Token`	RFC 6750 标准，与 OAuth 2.0 / OIDC 兼容
有效期	30 天	长效适合企业用户（避免每天重新登录），但配合刷新机制更佳
存储	localStorage / sessionStorage	前端选型决定（localStorage 持久但有 XSS 风险，HttpOnly Cookie 安全但要 CSRF 防护）
传输	HTTPS 强制	防止 token 泄露
撤销	服务端黑名单 + JWT	推荐：Redis 黑名单 + 短 JWT

3.3 进阶：刷新令牌模式

1
2


POST /system/refresh
Authorization: Bearer {{REFRESH_TOKEN}}

返回新的 access_token（短效 2 小时）+ 复用 refresh_token（长效 30 天）。这种"双 token"模式是 OAuth 2.0 推荐的工业实践，避免一个长效 token 泄露就要全员重置。

四、请求/响应体设计：5 个核心要素

4.1 请求体的 5 段式结构

以"重大危险源-监测设备-新增"为例（这份规范最详细的端点）：

要素	字段	类型	必选	备注
基础标识	`id`	string	是	主键
业务字段	`monitorName` `monitorCode` `monitorType` `numericalUnit` `rangeMax` `rangeMin`	string	是	业务核心数据
责任字段	`responsibilityPeopleName` `deptName`	string	是	责任人/部门
位置字段	`longitude` `latitude` `address`	number/string	是	经纬度 + 地址
设备字段	`manufacturer` `checkTime` `checkCycle`	string/datetime	是	厂家/校验
告警字段	`oneLevelHigh` `twoLevelHigh` `oneLevelLow` `twoLevelLow`	string	是	一二级高低报
类型字段	`monitorSpotType` `state` `equipmentType` `equipmentName`	string	是	类型/状态

4.2 字段类型选型决策树

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


字段值是什么？
├── 中文/枚举/编号
│ ├── 固定有限集合 → string（"男"/"女"、"已处理"/"未处理"）
│ ├── 不定文本 → string（地址、姓名、备注）
│ └── 编号/UUID → string（不直接用 number！避免 JS 精度问题）
│
├── 数值
│ ├── 整数计数 → int（年龄、数量）
│ ├── 小数金额 → string 或 long（避免精度问题，"1.23"）
│ ├── 经纬度 → number（前端 leaflet/高德直接用）
│ └── 大 ID → string（雪花 ID 19 位超出 JS Number 安全范围）
│
└── 时间
 ├── 精确到秒 → string ISO 8601（"2026-06-04T10:30:00+08:00"）
 ├── 仅日期 → string（"2026-06-04"）
 └── 时间戳 → long（毫秒，前端 new Date(ms)）

关键提醒：永远不要用 number 表示 ID/编号/金额！JavaScript 的 Number 是双精度浮点，Number.MAX_SAFE_INTEGER 是 9007199254740991（约 9 * 10^15），超出后 12345678901234567 === 12345678901234568 会返回 true。雪花 ID 通常是 18-19 位，必须用 string。

4.3 必选/可选字段的标注规范

1
2
3
4
5


# 推荐：仅标注"必选"（默认是可选）
"id": { "type": "string", "required": true, "desc": "主键" }
"monitorName": { "type": "string", "required": true, "desc": "监测点名称" }

# 不推荐：每个字段都标注 required: false（噪音）

4.4 错误响应体的差异化

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


// 业务错误（4xx + 业务 code）
{
 "msg": "监测点编号已存在",
 "code": 1001,
 "data": null,
 "success": false
}

// 系统错误（5xx + 异常 trace）
{
 "msg": "系统繁忙，请稍后重试",
 "code": -1,
 "data": null,
 "success": false
}

code 设计原则：

0 = 成功

1xxx = 业务错误（参数错误、唯一冲突、状态非法等）

2xxx = 鉴权错误（token 过期、权限不足）

3xxx = 第三方错误（短信/邮件/支付失败）

4xxx-5xxx = 内部错误（数据库异常、Redis 异常等）

-1 = 系统兜底

五、批量与同步：园区版双向同步的 4 种模式

这份规范有一个特殊设计：几乎所有端点的接口功能都写"企业版新增数据时同步到园区版"——这意味着每个写操作都是双写的。这种"企业版 + 园区版"的同步模式在政企/工业互联网场景非常典型。

5.1 4 种同步模式对比

模式	实时性	复杂度	一致性	适用
同步双写	实时	低	强	企业版 ↔ 园区版（这份规范的做法）
异步消息	准实时（秒级）	中	最终一致	跨地域多活、削峰填谷
CDC 监听	准实时	高	最终一致	数据库迁移、异构同步
定时拉取	延迟（分钟/小时）	低	弱	对账、非关键数据

5.2 同步双写的实现细节

 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


@PostMapping("/hazard/monitorEquip/add")
public Result<?> addMonitorEquip(@RequestBody MonitorEquipDTO dto) {
 // 1. 参数校验
 validator.validate(dto);
 
 // 2. 业务校验（编号唯一性、权限等）
 if (monitorEquipRepository.existsByCode(dto.getMonitorCode())) {
 return Result.fail(1001, "监测点编号已存在");
 }
 
 // 3. 企业版落库
 monitorEquipRepository.save(dto);
 
 // 4. 同步园区版（这里是关键！）
 try {
 parkApiClient.pushMonitorEquip(dto);
 } catch (Exception e) {
 // 5. 园区版同步失败的处理（决定了一致性策略）
 log.warn("园区版同步失败，已加入重试队列: id={}", dto.getId(), e);
 retryQueue.push("park_sync", dto); // 异步重试
 // 注意：这里**不要抛异常给前端**，因为企业版已经成功了
 }
 
 return Result.ok();
}

5 个关键决策：

是否同步等待园区版响应？ 答：否，园区版失败不阻断企业版（否则企业用户卡死）

失败后如何重试？ 答：MQ 异步重试 + 死信队列人工介入

如何避免重复同步？ 答：每个端点都带 id（主键），园区版用 upsert 语义

如何追踪同步状态？ 答：每个对象加 sync_status（待同步/已同步/失败）+ sync_time

如何保证最终一致？ 答：定时对账任务（每天凌晨拉取企业版增量 vs 园区版已收，对账差异）

5.3 批量同步的端点设计

1
2


POST /prevent/riskUnit/add-batch
Content-Type: application/json

1
2
3
4
5
6
7


{
 "list": [
 { "id": "1", "riskUnitName": "反应釜 A 单元" },
 { "id": "2", "riskUnitName": "储罐区 B 单元" },
 { "id": "3", "riskUnitName": "装卸区 C 单元" }
 ]
}

批量端点的 3 个原则：

总量限制：单次 ≤ 500 条（超过容易超时/内存溢出）

部分成功语义：返回 data.succeeded / data.failed 两个数组

失败明细可重试：failed[].reason 标明原因，前端可一键重试

六、CRUD 三段式 vs RESTful 的 7 大差异

维度	动作式（这份规范）	RESTful	推荐
新增	`POST /xxx/add`	`POST /xxx`	等价
修改（整对象）	`POST /xxx/update`	`PUT /xxx/{id}`	等价
修改（部分字段）	`POST /xxx/update`	`PATCH /xxx/{id}`	RESTful 更精确
删除	`POST /xxx/delete`	`DELETE /xxx/{id}`	等价
查询单个	`POST /xxx/getById`	`GET /xxx/{id}`	RESTful 天然缓存
查询列表	`POST /xxx/list`	`GET /xxx?page=1&size=20`	RESTful 更标准
查询复杂条件	`POST /xxx/search`	`POST /xxx/search`	等价（因为 GET 装不下复杂 JSON）

实战选型：

CRUD 增删改 → 动作式（少一层 RESTful 心智负担）

查询（特别是 GET）→ RESTful（浏览器/网关/CDN 都能缓存）

复杂搜索（多条件 + JSON body）→ 动作式（POST /search 不可避免）

七、OpenAPI 3.0 自动化生成

这份规范是手写 Markdown 的，但现代化的企业 API 规范应该从代码生成：

7.1 Java + springdoc-openapi

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@RestController
@RequestMapping("/hazard/monitorEquip")
@Tag(name = "重大危险源-监测设备")
public class MonitorEquipController {

 @Operation(summary = "新增监测设备")
 @PostMapping("/add")
 public Result<MonitorEquipVO> add(@Valid @RequestBody MonitorEquipDTO dto) {
 // ...
 }
}

7.2 自动生成 OpenAPI 3.0 + Swagger UI

1
2
3
4
5
6


<!-- pom.xml -->
<dependency>
 <groupId>org.springdoc</groupId>
 <artifactId>springdoc-openapi-ui</artifactId>
 <version>1.7.0</version>
</dependency>

访问 http://{{INTERNAL_HOST}}:8080/swagger-ui.html 即可看到自动生成的接口文档。比手写 Markdown 强 10 倍——前后端联调、自动化测试、Mock 数据都能从 OpenAPI 自动派生。

八、6 大设计原则速记

统一信封：所有响应都是 {code, msg, data, success}，业务成功用 200
Bearer Token：Authorization 头 + 30 天有效期 + HTTPS 强制
模块化 URL：/一级模块/二级模块/动作，动作可选 add/update/delete 或 HTTP 动词
字段类型谨慎：ID/编号/金额 永远用 string，时间用 ISO 8601
批量与同步：单次 ≤ 500 条 + 部分成功 + MQ 异步重试 + 定时对账
OpenAPI 自动化：从代码注解生成文档，不要手写 Markdown

九、典型代码生成（Java + Spring Boot）

 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


// 统一响应体
@Data
public class Result<T> {
 private String msg;
 private int code;
 private T data;
 private boolean success;
 
 public static <T> Result<T> ok() { return ok(null); }
 public static <T> Result<T> ok(T data) {
 Result<T> r = new Result<>();
 r.setCode(0);
 r.setMsg("成功");
 r.setData(data);
 r.setSuccess(true);
 return r;
 }
 public static <T> Result<T> fail(int code, String msg) {
 Result<T> r = new Result<>();
 r.setCode(code);
 r.setMsg(msg);
 r.setSuccess(false);
 return r;
 }
}

// 鉴权拦截器
@Component
public class AuthInterceptor implements HandlerInterceptor {
 @Override
 public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
 String auth = req.getHeader("Authorization");
 if (auth == null || !auth.startsWith("Bearer ")) {
 throw new AuthException("未登录");
 }
 String token = auth.substring(7);
 // 校验 token：从 Redis 取用户信息
 Long userId = tokenService.getUserIdByToken(token);
 if (userId == null) {
 throw new AuthException("Token 已过期");
 }
 // 放入 ThreadLocal
 UserContext.set(userId);
 return true;
 }
}

十、参考与延伸

OpenAPI 3.0 规范：https://swagger.io/specification/
RFC 6750 - OAuth 2.0 Bearer Token：https://datatracker.ietf.org/doc/html/rfc6750
RESTful API 设计指南（GitHub）：https://docs.github.com/en/rest
Stripe API 设计：https://stripe.com/docs/api（业界标杆）
Google API Design Guide：https://cloud.google.com/apis/design
微软 REST API 指南：https://github.com/microsoft/api-guidelines

下一步：建议直接用 springdoc-openapi（Java）或 swaggo（Go）从代码生成 API 文档；用 Postman / Apifox 维护接口测试用例；用 YApi / Apifox 做 Mock 数据；用 Pact 做消费者驱动的契约测试。

2024+ 视角

2020 年的"统一响应体 + Bearer Token + RESTful"骨架在 2024-2026 年依然成立，但生态发生了几个关键演进：

OpenAPI 3.1 落地：3.0 在 2024 年仍是主流，但 3.1 已对齐 JSON Schema 2020-12 规范，并支持 Webhook 和 API 设计优先（spec-first）模式。Stoplight Elements / Redocly 等文档渲染工具成为新标配。
API 网关与契约测试：
- 网关：Kong 3.x、Apigee、Apache APISIX 3.x（云原生 + eBPF 加速）已成主流
- 契约测试：Pact 2.0 + Pactflow 是消费者驱动测试的工业标准，配合 CI 做兼容性回归
鉴权演进：Bearer Token + JWT 仍是基础，但OAuth 2.1（2024 草案）将 PKCE 设为强制；企业级推荐 OIDC（OpenID Connect） + Keycloak / Auth0 / Authing。
API 安全：OWASP API Security Top 10（2023 版） 把"Broken Object Level Authorization（BOLA）“列为 #1——任何列表/详情接口都要做资源所有权校验。42Crunch / APIsec 提供自动化 API 安全扫描。
GraphQL / gRPC 互补：
- 复杂前端聚合场景：GraphQL（Hasura、Apollo、Yoga）正在替代"网关聚合多个 REST”
- 内部服务通信：gRPC + protobuf 已成事实标准（Envoy/Istio 内部走 xDS/gRPC）
可观测性：API 监控从"看 HTTP 状态码"升级到 RED（Rate/Error/Duration）+ 业务维度 trace。OpenTelemetry 1.x + Jaeger / Tempo 把 traceid 注入 HTTP header，跨服务追踪成为标配。
园区版/双写模式进化：2024 年企业级同步更推荐 CDC（Change Data Capture） ——Debezium 监听 MySQL binlog，Kafka 分发，下游订阅。比"应用层 try-catch 同步双写"更可靠、侵入小。

实战建议更新：

单体 → REST + OpenAPI + 统一信封
微服务 → REST（对外）+ gRPC（对内）+ GraphQL（BFF）
鉴权 → OIDC + OAuth 2.1 + RBAC/ABAC
文档 → Spec-First（OpenAPI 3.1 + Stoplight）
测试 → 契约测试（Pact）+ E2E（Playwright）+ 性能（k6）
同步 → 避免应用层双写，改 CDC + 事件驱动

2020 年这篇的"6 大设计原则"骨架完全成立，2024+ 视角主要补全的是 OAuth 2.1、OWASP API Top 10、CDC 同步、OpenTelemetry 四个维度。