1. 从一条 API 调用日志说起为什么数据库课要讲游标如果你正在学数据库大概率遇到过这种困惑SELECT * FROM 某张表明明能一次把结果全捞出来为什么教材还要专门花一节讲游标Cursor我当初也这么想直到把课堂练习换成真实场景——用 TaoToken 统一 Key 调用大模型时产生的 API 调用记录才真正理解游标的用武之地。TaoToken 是一个统一 API 通道你用同一个 Key 就能调用不同厂商的模型每次请求都会留下一条调用记录谁调的、用的哪个模型、消耗多少 token、耗时多久、状态码是多少。这些记录天然适合当教学数据因为字段清晰、行数可控、业务含义直观。而游标的核心价值在于它让你能一行一行地处理结果集而不是一次性把整张表读进内存。这在 API 日志场景里特别真实。假设你要给每条调用记录做逐条加工——比如按模型分组统计、给异常状态打标签、把超长 prompt 截断后归档——用一条 UPDATE 很难表达这种逐行判断、逐行处理的逻辑。游标就是为这种场景设计的声明、打开、逐行抓取、处理、关闭五步走完。这篇笔记我会带你从零建一张api_call_log表插入模拟的 TaoToken 调用记录然后用标准游标流程把每一行读出来打印。全程可复制你跟着敲一遍游标这个概念就落地了。适合刚学完 SELECT 和存储过程、想找个真实例子练手的同学。2. 前置准备TaoToken 通道与调用记录表设计在写游标之前得先把数据从哪来讲清楚。TaoToken 的 API 入口是https://taotoken.net/api你可以在控制台创建 Key然后用这个 Key 调用模型对话接口。每次调用成功后平台侧会记录这次请求的元数据。我们要做的是把这些元数据抽象成一张教学用的日志表。为什么用 TaoToken 的记录当示例因为它的字段设计很典型一次调用涉及模型标识、token 消耗、时间戳、状态正好覆盖游标练习需要的多种数据类型字符串、整数、时间、枚举。而且这些字段的业务含义你一看就懂不用额外解释这个字段是干嘛的。先看表结构设计。我把它拆成两类字段一类是调用身份信息谁、用什么模型一类是调用结果信息消耗、耗时、状态。字段名类型含义示例值log_idINT日志主键自增1api_key_aliasVARCHAR(32)Key 别名区分不同项目proj_alphamodel_idVARCHAR(64)调用的模型标识claude-sonnetprompt_tokensINT输入 token 数820completion_tokensINT输出 token 数340latency_msINT端到端耗时毫秒1450status_codeINTHTTP 状态码200created_atDATETIME调用时间2025-01-15 10:23:01这里有个设计细节值得说status_code我特意用整数存而不是字符串。因为游标处理时经常要做数值判断比如状态码不是 200 的就标记为异常整数比较比字符串匹配更直接。model_id用 VARCHAR 而不是枚举是因为模型会不断新增枚举类型维护成本高。建表语句如下你可以直接在 MySQL 8.0 里执行CREATE TABLE api_call_log ( log_id INT PRIMARY KEY AUTO_INCREMENT, api_key_alias VARCHAR(32) NOT NULL, model_id VARCHAR(64) NOT NULL, prompt_tokens INT DEFAULT 0, completion_tokens INT DEFAULT 0, latency_ms INT DEFAULT 0, status_code INT DEFAULT 200, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意ENGINEInnoDB因为游标操作涉及事务语义InnoDB 支持更完整。字符集用utf8mb4避免模型标识里出现特殊字符时乱码。关于 Key 的获取你可以在 TaoToken 控制台的 API Keys 页面创建具体入口是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。创建后记得保存Key 只在创建时完整显示一次。不过这篇的重点是游标Key 只是数据来源的背景你完全可以用我下面给的模拟数据先跑通流程。3. 可复制配置建表、插数据、写游标脚本数据准备分两步先插入模拟的调用记录再写游标脚本。我准备了 8 条记录覆盖不同模型、不同状态码、不同 token 量这样游标逐行处理时你能看到明显的分支差异。插入语句INSERT INTO api_call_log (api_key_alias, model_id, prompt_tokens, completion_tokens, latency_ms, status_code, created_at) VALUES (proj_alpha, claude-sonnet, 820, 340, 1450, 200, 2025-01-15 10:23:01), (proj_alpha, gpt-4o, 1200, 560, 2100, 200, 2025-01-15 10:24:15), (proj_beta, claude-sonnet, 300, 120, 890, 200, 2025-01-15 10:25:30), (proj_beta, deepseek-v3, 2400, 980, 3200, 200, 2025-01-15 10:26:45), (proj_alpha, gpt-4o, 150, 0, 500, 429, 2025-01-15 10:27:10), (proj_gamma, claude-sonnet, 5600, 2100, 5600, 200, 2025-01-15 10:28:22), (proj_gamma, deepseek-v3, 90, 0, 320, 401, 2025-01-15 10:29:05), (proj_alpha, claude-sonnet, 780, 410, 1680, 200, 2025-01-15 10:30:40);插完后先确认行数SELECT COUNT(*) AS total_rows FROM api_call_log;预期结果是 8。这个执行前后行数对比是游标教学里很重要的一步——游标只读不写所以处理前后行数必须一致如果变了说明你的脚本里混进了写操作。接下来是核心游标脚本。我用 MySQL 的存储过程来承载因为游标必须在存储过程或函数里声明。完整脚本如下DELIMITER // CREATE PROCEDURE read_api_logs() BEGIN -- 声明变量用于接收游标抓取的每一列 DECLARE v_log_id INT; DECLARE v_alias VARCHAR(32); DECLARE v_model VARCHAR(64); DECLARE v_prompt INT; DECLARE v_completion INT; DECLARE v_latency INT; DECLARE v_status INT; DECLARE v_created DATETIME; -- 声明是否读完的标志位 DECLARE done INT DEFAULT 0; -- 声明游标按 log_id 升序读取全部记录 DECLARE log_cursor CURSOR FOR SELECT log_id, api_key_alias, model_id, prompt_tokens, completion_tokens, latency_ms, status_code, created_at FROM api_call_log ORDER BY log_id; -- 声明句柄当游标无数据可读时把 done 置为 1 DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1; -- 打开游标 OPEN log_cursor; -- 循环逐行抓取 read_loop: LOOP FETCH log_cursor INTO v_log_id, v_alias, v_model, v_prompt, v_completion, v_latency, v_status, v_created; IF done 1 THEN LEAVE read_loop; END IF; -- 逐行处理逻辑按状态码分支打印 IF v_status 200 THEN SELECT CONCAT([OK] log#, v_log_id, model, v_model, tokens, v_prompt v_completion, latency, v_latency, ms) AS process_result; ELSE SELECT CONCAT([FAIL] log#, v_log_id, model, v_model, status, v_status, alias, v_alias) AS process_result; END IF; END LOOP; -- 关闭游标 CLOSE log_cursor; END // DELIMITER ;这段脚本里有几个关键点我逐个拆解。DECLARE ... CURSOR FOR SELECT ...是游标声明它定义了一个待读取的结果集。注意这里只是声明还没执行查询。真正执行是在OPEN的时候。DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1是游标的刹车机制。当FETCH抓不到数据时MySQL 会触发NOT FOUND条件这个句柄把done置 1循环里检测到就LEAVE退出。没有这个句柄循环会无限执行下去。FETCH ... INTO ...是逐行抓取把当前行的每一列塞进对应变量。变量顺序必须和游标 SELECT 的列顺序严格一致错一个位置数据就串了。OPEN和CLOSE成对出现CLOSE释放游标占用的资源。虽然存储过程结束时游标会自动关闭但显式写CLOSE是好习惯尤其在长过程里。调用这个存储过程CALL read_api_logs();4. 验证请求执行结果与逐行处理输出执行CALL read_api_logs();后你会看到 8 行输出每行对应一条调用记录。前几条长这样[OK] log#1 modelclaude-sonnet tokens1160 latency1450ms [OK] log#2 modelgpt-4o tokens1760 latency2100ms [OK] log#3 modelclaude-sonnet tokens420 latency890ms [OK] log#4 modeldeepseek-v3 tokens3380 latency3200ms [FAIL] log#5 modelgpt-4o status429 aliasproj_alpha [OK] log#6 modelclaude-sonnet tokens7700 latency5600ms [FAIL] log#7 modeldeepseek-v3 status401 aliasproj_gamma [OK] log#8 modelclaude-sonnet tokens1190 latency1680ms看到没第 5 条和第 7 条走了[FAIL]分支因为它们的status_code分别是 429限流和 401鉴权失败。这就是游标逐行处理的价值——每一行都能独立判断、独立走不同逻辑而不是被一条 SQL 一刀切。再验证一下行数没变SELECT COUNT(*) AS total_rows FROM api_call_log;结果还是 8。游标只读处理前后行数一致说明脚本干净。如果你想更直观地看到逐行的效果可以在循环里加一个计数器变量每处理一行就加一最后打印总数DECLARE row_count INT DEFAULT 0; -- 循环内 SET row_count row_count 1; -- 循环后 SELECT CONCAT(processed rows: , row_count) AS summary;输出会是processed rows: 8和表里的行数对上进一步确认每一行都被抓取处理了。这里插一句关于 TaoToken 调用记录的实际意义。真实场景里status_code429意味着你的请求被限流了可能是并发太高401意味着 Key 无效或过期。用游标把这些异常行单独拎出来处理——比如写入告警表、发通知——就是日志分析里很常见的模式。课堂练习用模拟数据但逻辑和真实运维是一致的。如果你想把游标读出的结果和实际 API 调用对照可以去模型对话页面手动发一次请求看看返回的 token 消耗和耗时再和表里的字段比一比理解会更立体https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。5. 常见报错排查游标写不对会踩哪些坑游标脚本看着简单但初学者很容易在几个地方翻车。我把真实遇到过的报错和原因列出来你对照着排查。报错一ERROR 1324 (42000): Undefined CURSOR: log_cursor这个通常是因为OPEN之前游标没声明或者声明的位置不对。游标声明必须在所有变量声明之后、句柄声明之前。MySQL 对声明顺序有严格要求变量 → 游标 → 句柄。顺序错了就会报未定义。报错二ERROR 1337 (42000): Variable or condition declaration after cursor or handler declaration和上面相反这是你把变量声明写在了游标后面。记住口诀先变量再游标最后句柄。三个DECLARE块的顺序不能乱。报错三循环停不下来一直打印同一行这是最经典的坑——忘了写CONTINUE HANDLER或者句柄里没正确设置done。没有NOT FOUND句柄FETCH抓完最后一行后不会报错而是继续返回最后一行循环就死在里面了。检查你的句柄声明DECLARE CONTINUE HANDLER FOR NOT FOUND SET done 1;报错四ERROR 1424 (HY000): Recursive stored functions and triggers are not allowed这个和游标本身无关但常一起出现。如果你在存储过程里又调用了自己就会报这个。游标脚本里不要递归调用。报错五local proxy failed或reading choices之类的网络报错这类报错不是数据库层面的而是你在用客户端工具比如某些 GUI连接数据库时工具自身的网络代理配置有问题。解决办法是检查工具的连接设置直连数据库地址不要走额外代理。如果你在用 TaoToken 的 API 做对照实验时遇到401那要检查 Key 是否正确、是否过期可以在控制台重新生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。报错六OAuth相关鉴权失败如果你用的是需要 OAuth 的数据库云服务token 过期会报这个。重新走一遍授权流程即可。本地 MySQL 一般不会遇到。排查完这些你的游标脚本基本就能稳定跑了。我建议你故意把句柄那行注释掉跑一次看看死循环的样子再恢复这样印象最深。6. 把游标用到真实日志分析下一步怎么练课堂练习跑通只是起点。真实场景里游标常和临时表、批量更新配合使用。比如你想给每条调用记录算一个单位 token 耗时然后写回表里可以这样改-- 先加一列 ALTER TABLE api_call_log ADD COLUMN ms_per_token DECIMAL(10,4); -- 游标里逐行计算并更新 UPDATE api_call_log SET ms_per_token latency_ms / (prompt_tokens completion_tokens) WHERE log_id v_log_id;注意这里在游标循环里做了写操作所以处理前后行数虽然不变但字段值变了。这是游标逐行处理的典型用法——先读出来算再写回去。另一个进阶方向是把游标和异常处理结合。真实日志里总有脏数据比如prompt_tokens为 0 导致除零错误。你可以在循环里加IF v_prompt v_completion 0 THEN ... ELSE ... END IF来跳过而不是让整个存储过程崩掉。如果你想把这条链路走完整——从 TaoToken 产生真实调用记录到落库再到游标分析——可以看看 Coding Plan 的接入方式它适合长期做编码和 Agent 场景调用记录更丰富https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有完整的 Base URL、Key 和 Model ID 配置说明。最后留个练习把游标脚本改成只处理 status_code 非 200 的记录也就是在FETCH之后加一个IF v_status 200 THEN ITERATE read_loop; END IF;跳过正常记录。这个ITERATE语句是游标循环里的continue很实用你可以试试。跑通之后你对游标的理解就不只是会写而是会用了。