MySQL 游标（Cursor）实战：从声明到关闭的完整流程与常见坑

1. 为什么存储过程里还需要游标逐行处理结果集的真实场景MySQL 游标Cursor是存储过程里用来逐行读取结果集的机制。它解决的是一个很具体的问题当一条 SQL 没法把逻辑表达完必须拿到每一行、对每一行做判断或计算时游标就是那个把结果集拆成一行一行喂给你的工具。适合谁写存储过程做数据迁移、批量状态流转、逐行校验、报表中间计算的开发者。如果你平时只写 SELECT 和 UPDATE可能一年都用不上但一旦进了存储过程做批处理游标几乎是绕不开的。我见过太多人第一次写游标时踩的坑循环停不下来、FETCH 拿到的变量永远是第一行、NOT FOUND 处理器位置放错导致语法报错。这些问题不是逻辑难而是 MySQL 游标的声明顺序和退出条件有硬性规则写错一个位置整个存储过程就建不起来。游标的完整生命周期是四步DECLARE 声明、OPEN 打开、FETCH 取数、CLOSE 关闭。但真正让循环能正常结束的是第五个隐藏角色——NOT FOUND 处理器。没有它FETCH 到结果集末尾时不会自动退出循环会一直跑下去直到你把连接掐掉。这篇文章给一套可以直接复制运行的模板建表、写存储过程、逐行累加、CALL 调用、SELECT 验证结果每一步都有可执行的 SQL。同时把 NOT FOUND 处理器为什么必须加、加在哪里、循环退出条件怎么写讲清楚。你跟着敲一遍就能理解游标的行为边界。需要说明的是游标逐行处理会放大数据库负载。数据量小的时候无所谓几万行以上就要认真考虑能不能用集合操作替代。游标是最后手段不是首选。但在必须逐行判断的场景里它是标准答案。2. TaoToken 前置用 API 方式调试存储过程与模型辅助排查写游标的过程中报错信息往往很简短比如ERROR 1064 (42000)只告诉你语法有问题不告诉你哪一行。这时候除了翻官方文档用模型辅助定位是个提速办法。TaoToken 提供统一的 API 入口可以把报错原文和你的存储过程片段一起发过去让它帮你指出 DECLARE 顺序或 HANDLER 位置的问题。TaoToken 是什么一个聚合多家大模型能力的 API 平台能做什么通过一个 Base URL 和 Key 调用对话模型适合谁需要快速排查 SQL 报错、生成模板代码、解释存储过程行为的开发者。它的接入方式和 OpenAI 兼容接口一致改 Base URL 就能用。先拿 Key。打开 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建后复制 Key注意只显示一次。然后确认接入文档里的 Base URL 和模型 IDhttps://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteBase URL 用这个不要加多余路径https://taotoken.net/api模型 ID 在文档的模型列表里查不同模型 ID 不一样填错会返回 model not found。如果你只是想验证模型能不能正常返回用模型对话页面直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期做编码和 Agent 任务的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台在这里可以看调用量和余额https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你用 Claude Code 这类工具接入配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite把报错贴给模型时建议这样组织先贴完整的 CREATE PROCEDURE 语句再贴 MySQL 返回的原始错误最后说明你的预期行为。模型能快速指出你的 DECLARE CONTINUE HANDLER 放在了 DECLARE CURSOR 后面这类顺序问题。这比你自己逐行比对快得多。3. 可复制配置建表、存储过程与游标模板这一节给一套完整可运行的 SQL。先建一张测试表插入几行数据然后写一个逐行累加的存储过程。所有代码可以直接在 MySQL 客户端里执行。建表和插入数据DROP TABLE IF EXISTS employees; CREATE TABLE employees ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50), salary DECIMAL(10,2) ); INSERT INTO employees (name, salary) VALUES (张三, 8000.00), (李四, 12000.00), (王五, 9500.00), (赵六, 15000.00);现在写存储过程计算平均工资。注意 DECLARE 的顺序变量声明、游标声明、处理器声明三者必须按这个顺序且都在 BEGIN 之后、其他语句之前。DELIMITER // CREATE PROCEDURE calculate_avg_salary() BEGIN DECLARE emp_salary DECIMAL(10,2); DECLARE total DECIMAL(10,2) DEFAULT 0; DECLARE cnt INT DEFAULT 0; DECLARE done INT DEFAULT 0; DECLARE cur CURSOR FOR SELECT salary FROM employees; DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1; OPEN cur; read_loop: LOOP FETCH cur INTO emp_salary; IF done 1 THEN LEAVE read_loop; END IF; SET total total emp_salary; SET cnt cnt 1; END LOOP; CLOSE cur; SELECT total / cnt AS avg_salary; END // DELIMITER ;几个关键点。第一DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1;必须放在游标声明之后。如果放在游标声明之前MySQL 会报ERROR 1338或语法错误因为处理器需要引用游标上下文。第二done变量初始值必须是 0FETCH 到末尾时处理器把它置为 1循环里的 IF 判断才能生效。第三LEAVE read_loop的标签名要和read_loop: LOOP一致写错标签名会报ERROR 1308。如果你用配置文件方式管理连接比如在应用里配置数据库连接池可以这样写 JSON{ mysql: { host: 127.0.0.1, port: 3306, user: root, password: your_password, database: test_db, connectionLimit: 10 } }存储过程本身不依赖这个配置但你在应用里调用 CALL 时需要连接信息。把数据库名、用户、密码换成你自己的。4. 验证请求与成功结果CALL 调用和 SELECT 检查存储过程建好后直接调用CALL calculate_avg_salary();预期返回------------ | avg_salary | ------------ | 11125.00 | ------------四行工资 8000 12000 9500 15000 47500除以 4 等于 11875。等等这里算一下80001200020000加 9500 是 29500加 15000 是 44500除以 4 是 11125。对结果是 11125.00。如果你得到这个数说明游标逐行累加正确。再验证一个场景逐行更新订单状态。先建订单表DROP TABLE IF EXISTS orders; CREATE TABLE orders ( id INT PRIMARY KEY AUTO_INCREMENT, status VARCHAR(20), created_at DATETIME ); INSERT INTO orders (status, created_at) VALUES (PENDING, NOW() - INTERVAL 40 DAY), (PENDING, NOW() - INTERVAL 10 DAY), (PAID, NOW() - INTERVAL 50 DAY), (PENDING, NOW() - INTERVAL 35 DAY);写存储过程把超过 30 天且状态为 PENDING 的订单改成 EXPIREDDELIMITER // CREATE PROCEDURE expire_old_orders() BEGIN DECLARE o_id INT; DECLARE o_status VARCHAR(20); DECLARE done INT DEFAULT 0; DECLARE cur CURSOR FOR SELECT id, status FROM orders WHERE created_at NOW() - INTERVAL 30 DAY; DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1; OPEN cur; order_loop: LOOP FETCH cur INTO o_id, o_status; IF done 1 THEN LEAVE order_loop; END IF; IF o_status PENDING THEN UPDATE orders SET status EXPIRED WHERE id o_id; END IF; END LOOP; CLOSE cur; END // DELIMITER ;调用并检查CALL expire_old_orders(); SELECT id, status, created_at FROM orders;预期结果id 为 1 和 4 的订单40 天前和 35 天前状态 PENDING变成 EXPIREDid 为 2 的订单只有 10 天不在游标结果集里保持 PENDINGid 为 3 的订单状态是 PAID即使超过 30 天也不改。这个验证能同时确认三件事游标的 WHERE 条件生效、逐行 IF 判断生效、UPDATE 只作用于当前行。如果 id 为 2 也被改了说明你的游标查询条件写错了如果 id 为 3 被改了说明 IF 判断没生效。5. 本篇常见错排查401、NOT FOUND 死循环与语法报错游标相关的报错集中在几类逐个对照。ERROR 1064 (42000) 语法错误。最常见的原因是 DECLARE 顺序不对。MySQL 要求所有 DECLARE 语句必须在 BEGIN 之后、其他可执行语句之前且变量声明、游标声明、处理器声明按顺序排列。如果你把DECLARE CONTINUE HANDLER写在OPEN cur后面直接报 1064。检查方法把存储过程里所有 DECLARE 行拎出来确认它们连续且顺序正确。ERROR 1338 (42000): Cursor declaration after handler declaration。这个报错很明确游标声明跑到了处理器声明后面。把DECLARE cur CURSOR FOR ...移到DECLARE CONTINUE HANDLER ...前面即可。循环停不下来一直执行。原因是 NOT FOUND 处理器没写或者done变量没在 FETCH 后判断。没有处理器时FETCH 到末尾不会报错也不会退出循环继续跑emp_salary保持上一行的值total 一直累加。解决办法就是加上DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1;并在 FETCH 后立刻IF done 1 THEN LEAVE ...。FETCH 拿到的永远是第一行。检查你的 FETCH 语句是否在循环体内。如果 FETCH 写在 LOOP 外面只取一次循环里用的永远是同一个值。正确写法是 FETCH 在 LOOP 内部第一行。ERROR 1308 (42000): LEAVE with no matching label。标签名不匹配。read_loop: LOOP和LEAVE read_loop必须完全一致包括大小写MySQL 标签不区分大小写但拼写要一致。ERROR 1324 (42000): Undefined CURSOR。OPEN 了一个没声明的游标名或者游标名拼写错误。检查 DECLARE 和 OPEN 的游标名是否一致。调用 API 时返回 401。如果你在用 TaoToken 辅助排查401 表示 Key 无效或没带。检查请求头里Authorization: Bearer sk-xxx是否完整Key 是否复制时带了空格。Base URL 确认是https://taotoken.net/api不要多加/v1之外的路径。local proxy failed 或连接超时。检查你的网络环境是否能正常访问 API 地址以及本地是否设置了会拦截请求的代理配置。这类问题通常和本地环境有关换一个网络环境测试即可。reading choices 报错。这通常出现在解析模型返回时说明返回结构和你代码里取值的路径不一致。打印完整响应体确认choices字段的实际位置。OAuth 相关报错。如果你用 Claude Code 等工具接入OAuth 流程失败通常是回调地址或 token 过期。重新走一遍授权确认配置里的 Base URL 和 Key 都是最新的。排查顺序建议先看 MySQL 返回的错误码对照上面几类定位如果是 API 调用问题先确认 Base URL、Key、Model ID 三件套是否齐全且正确。6. 语义一致 CTA把游标模板跑通后继续深入游标这套模板跑通后你手里就有了一个可复用的逐行处理骨架。接下来可以做的把累加逻辑换成你真实的业务判断把测试表换成生产表的只读副本先验证行为再上线。需要继续查 API 接入细节的看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite需要新建或管理 Key 的去 API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite想直接验证模型返回、测试报错排查效果的用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期做编码和 Agent 任务的看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后提醒一句游标不是性能工具是逻辑工具。能用一条 UPDATE JOIN 解决的不要用游标。只有当每一行的处理依赖上一行的结果或者需要调用其他存储过程时游标才是合理选择。把模板存下来需要的时候改查询和循环体比每次从零写快得多。