从请求去重、数据库唯一索引到事务控制,解决企业系统集成中的订单重复创建问题
在企业软件系统集成过程中,订单接口重复提交是一个常见问题。
例如,外部商城向 ERP 系统发送一笔销售订单,服务端已经成功写入数据库,但由于网络超时,客户端没有收到成功响应。客户端认为请求失败,再次发送相同请求,最终可能在系统中生成两笔相同的订单。
这种问题不能单纯依靠前端按钮防抖解决。
真正可靠的处理方式,是在服务端建立幂等机制,通过请求唯一标识、数据库唯一索引和事务控制,确保同一次业务请求重复执行时不会重复创建订单。
本文使用 Python、Flask 和 MySQL 8.0,从数据库设计到接口实现,完成一个可独立部署和验证的订单接口幂等示例。
假设一个外部商城需要向企业 ERP 系统同步销售订单。
正常情况下,业务流程如下:
问题通常发生在数据库提交和响应返回之间。
例如:
最终,同一笔业务请求可能产生两笔销售订单。
这里需要明确一个概念:
客户端请求超时,并不意味着服务端执行失败。
在分布式系统中,网络请求可能出现超时、断开连接、响应丢失等情况。服务端不能简单地把每一次收到的请求都理解为一次新的业务操作。
因此,需要建立请求幂等机制。
接口幂等性是指:在约定的业务范围和有效期内,同一个逻辑请求执行一次或多次,最终产生的业务结果保持一致。
例如:
第一次请求:
服务端成功创建订单,返回订单编号10001。
第二次请求:
服务端识别到这是之前处理过的请求,不再创建新订单,而是返回第一次成功保存的响应。
如果请求键相同,但是订单金额变成126.00,服务端就不能直接返回原结果,也不能重新创建订单,而应该返回请求冲突。
因此,接口幂等机制至少需要解决三个问题:
本文使用幂等键、SHA-256请求指纹和MySQL唯一索引解决这些问题。
实际开发中,很多人会把幂等键和订单编号混为一谈。
实际上,两者解决的是不同的问题。
对比项目 | 幂等键 | 外部订单编号 |
|---|---|---|
主要作用 | 识别同一次请求 | 识别同一笔业务订单 |
使用场景 | 网络超时、客户端重试 | 订单重复创建 |
唯一范围 | 同一租户内 | 同一租户内 |
数据库约束 | 租户ID+请求键唯一 | 租户ID+外部订单号唯一 |
举一个实际例子。
第一次请求:
服务端成功创建订单。
情况一:客户端使用req-A再次发送相同内容。
服务端应该返回第一次创建的订单结果。
情况二:客户端仍然使用req-A,但把金额改成126.00。
服务端应该返回409冲突,因为同一个请求键不能对应不同的业务内容。
情况三:客户端改用req-B,但仍然提交SHOP-1001。
服务端应该通过订单表的业务唯一约束,阻止第二次创建同一笔业务订单。
因此,幂等键负责请求防重,业务唯一编号负责业务防重。两者需要同时设计。
本次使用以下技术:
技术 | 作用 |
|---|---|
Python 3 | 业务逻辑处理 |
Flask | 提供HTTP API接口 |
MySQL 8.0 | 保存订单和幂等记录 |
InnoDB | 提供事务与行级锁机制 |
SHA-256 | 生成请求内容指纹 |
mysql-connector-python | Python连接MySQL |
整体处理流程如下:
第一步:接收请求。 客户端提交订单,服务端校验租户身份、请求键和订单数据。
第二步:生成请求指纹。 对标准化后的订单内容计算SHA-256摘要。
第三步:开启数据库事务。 尝试写入幂等记录,利用唯一索引识别重复请求。
第四步:判断请求状态。 如果请求键已存在,则比较请求指纹。内容相同,返回原始响应;内容不同,返回409冲突。
第五步:创建销售订单。 如果是首次请求,则写入订单表。
第六步:保存响应并提交。 将订单编号和原始响应写入幂等记录,统一提交事务。
这里最重要的一点是:
幂等记录、订单数据和响应结果必须在同一个MySQL事务中完成。
如果订单创建成功,但响应记录保存失败,整个事务应该回滚,避免数据库出现不完整的请求状态。
本次设计两张核心数据表:
CREATE DATABASE IF NOT EXISTS order_demo
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
USE order_demo;CREATE TABLE IF NOT EXISTS sales_orders (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
tenant_id VARCHAR(64)
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin NOT NULL,
external_order_no VARCHAR(64)
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin NOT NULL,
customer_id VARCHAR(64) NOT NULL,
total_amount DECIMAL(18,2) NOT NULL,
created_at DATETIME(6)
NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
PRIMARY KEY (id),
UNIQUE KEY uq_sales_tenant_external_no
(tenant_id, external_order_no)
) ENGINE=InnoDB
DEFAULT CHARSET=utf8mb4
COLLATE=utf8mb4_unicode_ci;这里有一个关键设计:
UNIQUE KEY uq_sales_tenant_external_no
(tenant_id, external_order_no)它保证同一个租户下,外部订单编号不能重复。
即使客户端更换幂等键,也无法通过接口创建同一笔外部业务订单。
CREATE TABLE IF NOT EXISTS api_idempotency (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
tenant_id VARCHAR(64)
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin NOT NULL,
idempotency_key VARCHAR(128)
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin NOT NULL,
request_hash CHAR(64)
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin NOT NULL,
order_id BIGINT UNSIGNED NULL,
response_status SMALLINT UNSIGNED NULL,
response_json JSON NULL,
created_at DATETIME(6)
NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
completed_at DATETIME(6) NULL,
PRIMARY KEY (id),
UNIQUE KEY uq_idem_tenant_key
(tenant_id, idempotency_key),
KEY idx_idem_created_at (created_at),
CONSTRAINT fk_idem_order
FOREIGN KEY (order_id)
REFERENCES sales_orders (id)
) ENGINE=InnoDB
DEFAULT CHARSET=utf8mb4
COLLATE=utf8mb4_unicode_ci;其中:
联合唯一索引保证不同租户之间可以使用相同的请求键,但同一个租户不能重复占用同一个请求键。
本项目使用以下Python依赖:
创建虚拟环境后,使用 pip install Flask mysql-connector-python requests 安装依赖。
通过环境变量配置数据库:
export DB_HOST="127.0.0.1"
export DB_PORT="3306"
export DB_USER="order_app"
export DB_PASSWORD="替换为数据库密码"
export DB_NAME="order_demo"生产环境不要将数据库密码直接写入代码仓库,应使用安全的配置管理方式,并限制数据库账号权限。
创建app.py。
下面是完整的核心实现:
import hashlib
import json
import logging
import os
from decimal import Decimal, InvalidOperation
from flask import Flask, jsonify, request
import mysql.connector
from mysql.connector import errorcode
app = Flask(__name__)
logging.basicConfig(level=logging.INFO)
def get_db_connection():
"""创建数据库连接。"""
return mysql.connector.connect(
host=os.getenv("DB_HOST", "127.0.0.1"),
port=int(os.getenv("DB_PORT", "3306")),
user=os.getenv("DB_USER", "order_app"),
password=os.getenv("DB_PASSWORD", "change_me"),
database=os.getenv("DB_NAME", "order_demo"),
autocommit=False,
connection_timeout=5,
charset="utf8mb4",
)
def normalize_order(data, tenant_id):
"""校验和标准化订单数据。"""
if not isinstance(data, dict):
raise ValueError("请求体必须是JSON对象")
required = {
"external_order_no",
"customer_id",
"total_amount"
}
if set(data.keys()) != required:
raise ValueError("请求字段不完整或包含未支持字段")
external_order_no = data["external_order_no"]
customer_id = data["customer_id"]
amount_text = data["total_amount"]
if not isinstance(external_order_no, str):
raise ValueError("订单编号格式错误")
if not isinstance(customer_id, str):
raise ValueError("客户编号格式错误")
if not isinstance(amount_text, str):
raise ValueError("金额必须使用字符串传入")
external_order_no = external_order_no.strip()
customer_id = customer_id.strip()
if not external_order_no or not customer_id:
raise ValueError("订单编号和客户编号不能为空")
if len(external_order_no) > 64:
raise ValueError("外部订单编号过长")
if len(customer_id) > 64:
raise ValueError("客户编号过长")
try:
amount = Decimal(amount_text)
except InvalidOperation as exc:
raise ValueError("订单金额格式错误") from exc
if not amount.is_finite() or amount <= 0:
raise ValueError("订单金额必须大于0")
try:
normalized_amount = amount.quantize(
Decimal("0.01")
)
except InvalidOperation as exc:
raise ValueError("订单金额超出处理范围") from exc
if amount != normalized_amount:
raise ValueError("订单金额最多保留两位小数")
if normalized_amount > Decimal("9999999999999999.99"):
raise ValueError("订单金额超出数据库字段范围")
normalized = {
"tenant_id": tenant_id,
"external_order_no": external_order_no,
"customer_id": customer_id,
"total_amount": format(normalized_amount, ".2f"),
}
canonical_json = json.dumps(
normalized,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
)
request_hash = hashlib.sha256(
canonical_json.encode("utf-8")
).hexdigest()
return normalized, request_hash
def replay_existing(
tenant_id,
idempotency_key,
request_hash
):
"""读取已经成功处理的原始请求结果。"""
conn = get_db_connection()
cursor = conn.cursor(dictionary=True)
try:
cursor.execute(
"""
SELECT
request_hash,
response_status,
response_json
FROM api_idempotency
WHERE tenant_id = %s
AND idempotency_key = %s
""",
(tenant_id, idempotency_key),
)
row = cursor.fetchone()
if row is None:
return {
"error": "idempotency_record_not_found",
"retryable": True
}, 503
if row["request_hash"] != request_hash:
return {
"error": "idempotency_key_reused_with_different_request"
}, 409
if (
row["response_status"] is None
or row["response_json"] is None
):
return {
"error": "idempotency_response_not_ready",
"retryable": True
}, 503
response_body = row["response_json"]
if isinstance(response_body, str):
response_body = json.loads(response_body)
return response_body, int(row["response_status"])
finally:
cursor.close()
conn.close()
def create_order(
tenant_id,
idempotency_key,
order_data,
request_hash
):
"""创建订单并处理重复请求。"""
conn = get_db_connection()
cursor = conn.cursor()
try:
conn.start_transaction()
# 第一步:尝试占用幂等键。
try:
cursor.execute(
"""
INSERT INTO api_idempotency
(
tenant_id,
idempotency_key,
request_hash
)
VALUES (%s, %s, %s)
""",
(
tenant_id,
idempotency_key,
request_hash
),
)
except mysql.connector.IntegrityError as exc:
if exc.errno != errorcode.ER_DUP_ENTRY:
raise
conn.rollback()
return replay_existing(
tenant_id,
idempotency_key,
request_hash
)
# 第二步:创建销售订单。
try:
cursor.execute(
"""
INSERT INTO sales_orders
(
tenant_id,
external_order_no,
customer_id,
total_amount
)
VALUES (%s, %s, %s, %s)
""",
(
tenant_id,
order_data["external_order_no"],
order_data["customer_id"],
Decimal(order_data["total_amount"]),
),
)
except mysql.connector.IntegrityError as exc:
if exc.errno != errorcode.ER_DUP_ENTRY:
raise
conn.rollback()
return {
"error": "external_order_no_already_exists"
}, 409
order_id = cursor.lastrowid
# 第三步:生成原始响应。
response_body = {
"order_id": order_id,
"external_order_no":
order_data["external_order_no"],
"status": "created",
"total_amount":
order_data["total_amount"],
}
response_json = json.dumps(
response_body,
ensure_ascii=False,
separators=(",", ":"),
)
# 第四步:保存幂等响应。
cursor.execute(
"""
UPDATE api_idempotency
SET
order_id = %s,
response_status = %s,
response_json = %s,
completed_at = CURRENT_TIMESTAMP(6)
WHERE tenant_id = %s
AND idempotency_key = %s
""",
(
order_id,
201,
response_json,
tenant_id,
idempotency_key,
),
)
if cursor.rowcount != 1:
raise RuntimeError("幂等记录更新数量异常")
# 第五步:统一提交。
conn.commit()
return response_body, 201
except Exception:
try:
conn.rollback()
except mysql.connector.Error:
app.logger.exception(
"Transaction rollback failed"
)
raise
finally:
cursor.close()
conn.close()
@app.post("/orders")
def post_order():
# 仅用于演示。
# 生产环境必须从服务端鉴权上下文取得租户身份。
tenant_id = request.headers.get(
"X-Tenant-ID", ""
).strip()
idempotency_key = request.headers.get(
"Idempotency-Key", ""
).strip()
if not tenant_id or len(tenant_id) > 64:
return jsonify({
"error": "missing_or_invalid_tenant_id"
}), 400
if not idempotency_key or len(idempotency_key) > 128:
return jsonify({
"error": "missing_or_invalid_idempotency_key"
}), 400
data = request.get_json(silent=True)
try:
order_data, request_hash = normalize_order(
data,
tenant_id
)
except ValueError as exc:
return jsonify({
"error": str(exc)
}), 400
try:
response_body, status_code = create_order(
tenant_id,
idempotency_key,
order_data,
request_hash
)
return jsonify(response_body), status_code
except mysql.connector.Error:
app.logger.exception(
"Database operation failed"
)
return jsonify({
"error": "database_error"
}), 500
except Exception:
app.logger.exception(
"Unexpected order API failure"
)
return jsonify({
"error": "internal_server_error"
}), 500
@app.get("/health")
def health():
return jsonify({
"status": "ok"
}), 200
if __name__ == "__main__":
app.run(
host="127.0.0.1",
port=5000,
debug=False
)这段代码有几个需要重点理解的地方:
1. 使用Decimal处理金额。
财务和订单金额不应该直接使用Python浮点数进行金额计算。这里使用Decimal,并将金额标准化为两位小数。
2. 使用SHA-256生成请求指纹。
请求内容经过标准化后再生成指纹,可以避免同一金额因格式不同而被错误识别为不同请求。
3. 由数据库唯一索引处理并发。
不能只依赖Python的先查询再插入。唯一索引才是并发情况下最终的约束机制。
4. 使用事务保证数据一致性。
订单记录、请求键和原始响应一起提交。如果中间发生异常,统一回滚。
5. 保存原始响应。
重复请求不再重新创建订单,而是返回之前保存的响应。
启动服务:
使用命令 python app.py 启动接口。
第一次创建订单:
curl -X POST "http://127.0.0.1:5000/orders" \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: tenant-demo" \
-H "Idempotency-Key: req-20261116-001" \
-d '{
"external_order_no": "SHOP-1001",
"customer_id": "CUST-1001",
"total_amount": "125.50"
}'第一次请求成功时,返回结构如下:
{
"order_id": 1,
"external_order_no": "SHOP-1001",
"status": "created",
"total_amount": "125.50"
}这里的订单编号仅用于展示响应格式,实际编号由数据库自动生成。
保持请求键和订单内容不变,再发送一次。
预期结果:
如果把金额改为126.00,但仍使用原请求键,则应返回409。
这说明服务端不仅识别请求键,还会验证请求内容。
单次重复提交只能验证基础逻辑,不能充分验证并发情况。
因此,需要通过多个线程同时发送相同请求,检查数据库是否只创建一笔订单。
创建test_api.py:
import concurrent.futures
import uuid
import requests
BASE_URL = "http://127.0.0.1:5000"
TENANT_ID = "tenant-demo"
def send_order(key, payload):
response = requests.post(
f"{BASE_URL}/orders",
headers={
"X-Tenant-ID": TENANT_ID,
"Idempotency-Key": key,
},
json=payload,
timeout=10,
)
return response.status_code, response.json()
def new_payload():
suffix = uuid.uuid4().hex[:12]
return {
"external_order_no": f"EXT-{suffix}",
"customer_id": "CUST-1001",
"total_amount": "125.50",
}
def test_same_request():
key = f"idem-{uuid.uuid4().hex}"
payload = new_payload()
first = send_order(key, payload)
second = send_order(key, payload)
assert first[0] == 201
assert second[0] == 201
assert (
first[1]["order_id"]
== second[1]["order_id"]
)
print("同键同内容重复请求:通过")
def test_different_payload():
key = f"idem-{uuid.uuid4().hex}"
payload = new_payload()
assert send_order(key, payload)[0] == 201
changed = dict(
payload,
total_amount="126.00"
)
status, body = send_order(key, changed)
assert status == 409
assert (
body["error"]
== "idempotency_key_reused_with_different_request"
)
print("同键不同内容:通过")
def test_duplicate_business_order():
payload = new_payload()
first_key = f"idem-{uuid.uuid4().hex}"
second_key = f"idem-{uuid.uuid4().hex}"
assert send_order(first_key, payload)[0] == 201
status, body = send_order(second_key, payload)
assert status == 409
assert (
body["error"]
== "external_order_no_already_exists"
)
print("不同请求键重复创建同一订单:通过")
def test_concurrent_requests():
key = f"idem-{uuid.uuid4().hex}"
payload = new_payload()
with concurrent.futures.ThreadPoolExecutor(
max_workers=10
) as executor:
futures = [
executor.submit(
send_order,
key,
payload
)
for _ in range(10)
]
results = [
future.result()
for future in futures
]
statuses = [
status
for status, body in results
]
order_ids = {
body.get("order_id")
for status, body in results
}
assert all(
status == 201
for status in statuses
)
assert len(order_ids) == 1
print("10个并发请求:通过")
if __name__ == "__main__":
test_same_request()
test_different_payload()
test_duplicate_business_order()
test_concurrent_requests()
print("全部集成测试通过")执行命令 python test_api.py。
这组测试重点验证四种情况:
测试场景 | 预期结果 |
|---|---|
相同请求键、相同内容 | 返回同一个订单 |
相同请求键、不同内容 | 返回409 |
不同请求键、相同外部订单号 | 返回409 |
10个并发相同请求 | 只产生一笔订单 |
需要说明:上面的代码是可执行的测试程序,实际测试结果必须以连接MySQL 8.0测试实例后的运行输出为准,不能把预期结果当作已经完成的实测结果。
接口返回成功,不代表数据库设计一定正确。
还需要直接查询数据库。
检查重复外部订单号:
SELECT
tenant_id,
external_order_no,
COUNT(*) AS row_count
FROM sales_orders
GROUP BY
tenant_id,
external_order_no
HAVING COUNT(*) > 1;检查重复幂等键:
SELECT
tenant_id,
idempotency_key,
COUNT(*) AS row_count
FROM api_idempotency
GROUP BY
tenant_id,
idempotency_key
HAVING COUNT(*) > 1;两条查询在正常约束下都应该返回空结果。
这也说明为什么不能只在Python程序中做重复判断。数据库必须拥有最终的数据一致性约束。
假设订单已经执行INSERT,但在保存响应之前发生程序异常。
如果订单表和幂等表没有使用同一个事务,就可能产生不一致的数据。
正确的方式是:
如果第3步或第4步发生异常,执行ROLLBACK。
可以在本地测试环境中,在订单创建成功后、更新幂等记录之前临时加入以下故障注入代码:
raise RuntimeError(
"simulate failure before commit"
)重新发送一笔新的测试订单。
预期结果是:
测试结束后,应删除故障注入代码。
前面的实现解决了单个MySQL数据库事务内的请求幂等问题,但生产环境还需要进一步考虑以下情况。
如果请求记录被提前清理,客户端在较长时间后再次重试,服务端可能把它当成新请求。
因此,需要根据客户端最大重试周期和业务补偿周期设置保留时间。
即使幂等记录过期,外部订单号等业务唯一约束仍应保留。
例如:
这些操作不属于当前MySQL事务。
即使本地数据库回滚,也无法自动撤销已经成功执行的外部调用。
这种情况需要结合Outbox消息表、消息消费幂等、重试及补偿机制处理。
多个事务同时操作数据库时,InnoDB可能发生死锁或者锁等待超时。
生产环境应该:
本文为了突出事务和幂等处理,采用了每次请求创建数据库连接的演示方式。
生产环境应该根据并发量使用数据库连接池,并做好连接生命周期管理。
示例中的X-Tenant-ID请求头只用于本地演示。
正式系统必须从登录身份、API凭证或者服务端鉴权上下文取得租户身份,不能允许客户端通过随意修改请求头访问其他租户的数据。
订单接口幂等并不是简单地给数据库增加一个唯一字段。
它需要同时解决请求识别、业务唯一性、并发竞争、事务边界和响应重放等问题。
本文采用的方案可以概括为四个步骤:
第一:使用幂等键识别同一次逻辑请求。
第二:通过SHA-256请求指纹判断重复请求的业务内容是否一致。
第三:使用MySQL唯一索引控制并发,使用业务唯一编号防止订单重复创建。
第四:通过InnoDB事务保证订单、幂等记录和原始响应的一致性。
这套方案适用于需要处理网络重试和重复提交的订单创建接口,也可以作为企业系统集成中设计业务接口幂等机制的基础参考。
但需要明确:它保证的是当前数据库事务边界内的幂等处理,不代表跨支付、消息、库存等多个独立系统都能实现绝对只执行一次。跨系统场景仍然需要配套的消息幂等和补偿机制。
技术场景说明:
本文由广东俊逸软件技术有限公司围绕企业软件应用场景整理,代码为独立演示项目,不代表任何特定ERP产品的内部数据库结构、官方API或产品功能承诺。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。