返回博客列表

一个API接口，支持插入与更新

2025年06月03日
APISQL 团队
一个API接口，支持插入与更新
APIUpsert开发技巧

一、背景介绍

在日常开发过程中，我们经常遇到这样的需求：设计API向数据库插入数据、更新数据，一般情况下，需要设计两个API来分别处理插入、更新操作。

本文将详细介绍如何在 apiSQL 平台，使用MySQL数据库 Upsert 功能，来设计一个融合API，并通过实际案例演示其应用场景。

二、什么是 Upsert？

Upsert 是一种数据库操作模式，它会根据数据是否已存在来自动选择执行插入或更新操作：

  • 当数据不存在时，执行 INSERT 操作
  • 当数据已存在时，执行 UPDATE 操作
  • 这种需求被称为 Upsert（Insert + Update 的组合词）

三、upsert核心机制：唯一性约束

MySQL 通过表的主键（PRIMARY KEY）、唯一索引（UNIQUE INDEX） 或 唯一约束（UNIQUE CONSTRAINT） 来判断数据是否重复：

  1. 唯一性检查：当插入新记录时，MySQL 会检查待插入数据在唯一键上的值
  2. 冲突处理：
    • 若唯一键的值与现有记录无冲突 → 执行 INSERT 操作
    • 若唯一键的值与现有记录有冲突 → 触发 UPDATE 操作

四、实战演示

1. 创建MySQL测试表

首先，我们创建一个用于测试的用户表：

CREATE TABLE `user_upsert` (
  `id` int NOT NULL COMMENT '用户唯一标识（主键，不可重复）',
  `name` varchar(50) NOT NULL COMMENT '用户姓名',
  `age` int DEFAULT NULL COMMENT '年龄',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='用户表upsert测试用';

关键点：PRIMARY KEY (id) 确保了 ID 字段的唯一性，这是 Upsert 功能的基础。

2、设计 Upsert 功能 API

使用 MySQL 的 INSERT INTO …… ON DUPLICATE KEY UPDATE 语法实现 Upsert 功能：

INSERT INTO `user_upsert` (id, name, age) 
VALUES (:id, :姓名, :年龄)
ON DUPLICATE KEY UPDATE 
  id   = VALUES(id),
  name = VALUES(name),
  age  = VALUES(age);

Insert插入操作示例 这里配置了默认参数，以方便后面调式：

  • :id = 1
  • :姓名 = 张三
  • :年龄 = 30

五、【Insert插入】操作

当数据库中不存在 ID 为 1 的记录时，执行插入操作，执行结果显示影响行数为 1，表示成功插入了一条新记录。

通过数据管理界面查看，可以确认数据已成功插入：

数据查看

数据表中显示：ID=1, 姓名=张三, 年龄=30

六、【Update更新】操作

修改参数，保持 ID 不变，更新姓名和年龄，点击运行

Update更新操作示例

由于 ID=1 的记录已存在，系统自动执行更新操作。

💡 温馨提示： 这是一个演示项目，其 Authorization 配置为 公开。因此，您无需配置 API Key，直接点击运行即可。

查看更新后的数据

更新结果

数据已成功更新为：ID=1, 姓名=张三丰, 年龄=33

七、跨数据库支持

Upsert 功能在多种数据库系统中都有相应的实现：

PostgreSQL & SQLite

INSERT ... ON CONFLICT (column) DO UPDATE

Oracle & SQL Server & 达梦 & 人大金仓

MERGE INTO 语句

虽然语法略有差异，但核心原理完全一致，都是基于唯一性约束来实现插入或更新的自动选择。

八、应用优势

  1. 简化接口设计：一个接口处理两种操作，减少API数量
  2. 降低维护成本：无需维护单独的插入和更新接口
  3. 提高开发效率：业务逻辑更加简洁清晰
  4. 增强数据一致性：避免了手动判断数据是否存在的复杂逻辑

九、总结

通过本文的实战演示，我们可以看到 Upsert 功能在简化API设计方面的显著优势。apiSQL 平台完美支持这一特性，让开发者能够轻松实现高效的数据操作接口。

返回博客列表