1. 从控制台贪吃蛇到在线排行榜：一个练手项目的完整落地路径
C语言贪吃蛇小游戏几乎是每个学C的人都会碰的项目，它把数组、链表、键盘响应、控制台坐标控制这些知识点串成了一条线。但很多人写完本地版本就停了，蛇能跑、能吃食物、能计分，然后代码往硬盘里一扔，再也没打开过。我这次想做的，是在这个经典项目上再往前推一步：让游戏结束后能把分数上传到一个在线排行榜，看看自己到底排第几。这个扩展听起来简单，但它逼着你把C语言从"单机玩具"变成"能跟外部服务对话的程序"，涉及HTTP请求、JSON解析、API Key管理这些真实开发里绕不开的东西。
你可能会问，一个控制台小游戏接排行榜，有必要吗？我的答案是：非常有必要。因为排行榜这个需求，恰好覆盖了从本地程序到网络服务的完整链路。你需要一个稳定的API通道来发请求，需要管理Key避免硬编码泄露，需要处理网络失败的情况，还需要解析返回的JSON。这些技能在你后面写任何联网程序时都会用到。而TaoToken提供的统一Key通道，正好可以把"接入在线服务"这件事的门槛降到最低——你不需要自己搭服务器，不需要处理复杂的鉴权流程，拿到Key就能调。
这篇文章会分成两条线走。第一条线是贪吃蛇本体的完整实现，我会把蛇身链表、方向控制、食物生成、碰撞检测这些核心逻辑讲清楚，代码可以直接编译运行。第二条线是在这个基础上扩展排行榜功能，演示怎么通过TaoToken的API通道把分数传上去、把排名拉下来。两条线合在一起，你得到的不只是一个能玩的游戏，而是一个能跑通"本地程序+在线服务"的最小闭环。适合有C语言基础、想找个项目练手、同时对API调用感兴趣的人。下面先从游戏本身开始。
2. 贪吃蛇核心逻辑拆解：蛇身链表、方向控制与碰撞检测
贪吃蛇的本质是一个状态机在循环里不断更新。每一帧你要做几件事：读键盘、算新蛇头位置、判断有没有吃到食物、判断有没有撞墙或撞自己、重绘画面、休眠一小段时间。听起来简单，但每个环节都有坑。我先把数据结构定下来，再逐个讲实现。
蛇身我用链表存，每个节点是一个坐标加一个next指针。为什么不用数组？因为蛇的移动是"头插尾删"，链表在这两个操作上都是O(1)，数组做尾删虽然也快，但头插要挪整个数组，蛇越长越慢。链表还有个好处是蛇身长度理论上无上限，不用预先分配固定大小。节点结构体长这样：
typedef struct SnakeNode { int x; int y; struct SnakeNode* next; } SnakeNode, *pSnakeNode;游戏的整体状态我封装在一个结构体里，包括蛇头指针、食物指针、当前方向、游戏状态、分数、速度这些。这样传参的时候只传一个指针就够了，不用到处传一堆变量：
typedef struct Snake { pSnakeNode _pSnake; pSnakeNode _pFood; enum DIRECTION _dir; enum GAME_STATUS _status; int _food_weight; int _score; int _sleep_time; } Snake, *pSnake;方向控制这块，很多人第一次写会犯一个错：允许蛇直接反向。比如蛇正在向右走，你按左键，蛇头直接撞到第二节身体上，游戏瞬间结束。所以方向切换必须加一个判断，当前方向是RIGHT时不能切到LEFT，是UP时不能切到DOWN。这个判断放在GameRun的键盘检测里：
if (KEY_PRESS(VK_UP) && ps->_dir != DOWN) { ps->_dir = UP; } else if (KEY_PRESS(VK_DOWN) && ps->_dir != UP) { ps->_dir = DOWN; } else if (KEY_PRESS(VK_LEFT) && ps->_dir != RIGHT) { ps->_dir = LEFT; } else if (KEY_PRESS(VK_RIGHT) && ps->_dir != LEFT) { ps->_dir = RIGHT; }键盘检测用的是Windows的GetAsyncKeyState，它返回一个short，最低位为1表示"自上次调用后这个键被按过"。我封装成一个宏，用起来清爽：
#define KEY_PRESS(vKey) (GetAsyncKeyState(vKey) & 0x0001)食物生成有个细节要注意：坐标不能跟蛇身重叠。我的做法是随机生成一个坐标，然后遍历蛇身链表检查，如果撞上了就重新生成。这里用goto做重试循环最直观：
again: x = 2 * (rand() % 27 + 1); y = rand() % 25 + 1; pSnakeNode cur = ps->_pSnake; while (cur) { if (x == cur->x && y == cur->y) { goto again; } cur = cur->next; }x坐标为什么是偶数？因为宽字符（比如●、★）在控制台里占两列，如果x是奇数，蛇身和食物会错位，看起来就是斜的。这个坑我踩过，当时蛇身画出来是锯齿状的，调了半天才发现是坐标没对齐。
碰撞检测分两种：撞墙和撞自己。撞墙就是看蛇头坐标有没有碰到边界，撞自己就是遍历蛇身（从第二节开始）看有没有跟蛇头坐标重合。这两个检测在每次移动后都要跑一遍，一旦触发就把游戏状态改成对应的结束状态，主循环自然退出。
移动逻辑是核心中的核心。蛇移动时，先根据当前方向算出新蛇头的坐标，然后判断这个位置是不是食物。如果是食物，就把食物节点接到蛇头前面，不删尾，蛇身长度加一，分数加上当前食物的分值，然后重新生成食物。如果不是食物，就新建一个节点插到蛇头前面，然后把蛇尾删掉，保持长度不变。这里有个容易忽略的点：删尾之前要先把蛇尾那个位置的符号用空格覆盖掉，否则屏幕上会残留一个●。宽字符占两列，所以要输出两个空格：
SetPos(cur->next->x, cur->next->y); printf(" "); free(cur->next); cur->next = NULL;速度控制我用_sleep_time这个变量，值越小蛇跑得越快。按F3加速就是减30毫秒，同时食物分值加2；按F4减速就是加30毫秒，食物分值减2。加速有下限（我设的80毫秒），减速有下限（食物分值不能低于2），不然游戏会失控。这个设计让玩家在"跑得快但风险高"和"跑得慢但稳"之间做取舍，比固定速度有意思。
3. 接入TaoToken统一Key通道：配置文件与请求封装
游戏本体跑通之后，接下来做排行榜。排行榜的本质是：游戏结束时，把玩家分数发到一个服务端，服务端存下来，下次打开游戏时拉取前几名显示出来。传统做法是自己搭个后端，但那样你就得处理服务器、数据库、鉴权一大堆事。用TaoToken的统一Key通道，你只需要一个API Key，就能调用它提供的接口，省掉后端搭建的环节。
先说Key怎么拿。访问TaoToken官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=），注册登录后进控制台，在API Keys页面创建一个新的Key。这个Key就是你调用接口的凭证，格式类似sk-开头的一串字符。创建完之后复制下来，存到一个本地文件里，不要直接写死在代码里。为什么？因为如果你把Key硬编码进源码，万一代码传到GitHub上，Key就泄露了，别人可以拿你的Key去刷接口。正确做法是放在一个配置文件里，代码运行时读取。
我在项目根目录建一个config.json，内容长这样：
{ "api_base": "https://taotoken.net/api", "api_key": "sk-你的实际Key填这里", "model_id": "gpt-4o-mini", "leaderboard_endpoint": "/v1/chat/completions" }注意api_base用的是https://taotoken.net/api，不带任何UTM参数，这是接口调用的基础地址。model_id填你实际要用的模型ID，这个在TaoToken的文档里能查到。leaderboard_endpoint这里我先用chat/completions做演示，实际排行榜你可以让模型帮你格式化数据，或者用TaoToken的其他接口。
C语言读JSON没有标准库，我选了一个轻量级的单头文件库cJSON，把它下载下来放到项目里，编译时一起编进去。读配置的代码大概是这样：
#include "cJSON.h" typedef struct { char api_base[256]; char api_key[256]; char model_id[128]; } Config; int load_config(const char* path, Config* cfg) { FILE* fp = fopen(path, "rb"); if (!fp) { perror("open config.json failed"); return -1; } fseek(fp, 0, SEEK_END); long len = ftell(fp); fseek(fp, 0, SEEK_SET); char* buf = (char*)malloc(len + 1); fread(buf, 1, len, fp); buf[len] = '\0'; fclose(fp); cJSON* root = cJSON_Parse(buf); free(buf); if (!root) { printf("parse config.json failed\n"); return -1; } cJSON* base = cJSON_GetObjectItem(root, "api_base"); cJSON* key = cJSON_GetObjectItem(root, "api_key"); cJSON* model = cJSON_GetObjectItem(root, "model_id"); if (base && key && model) { strncpy(cfg->api_base, base->valuestring, sizeof(cfg->api_base) - 1); strncpy(cfg->api_key, key->valuestring, sizeof(cfg->api_key) - 1); strncpy(cfg->model_id, model->valuestring, sizeof(cfg->model_id) - 1); } cJSON_Delete(root); return 0; }发HTTP请求这块，Windows下可以用WinHTTP，Linux下用libcurl。为了跨平台，我选libcurl，它接口统一，文档也全。发一个POST请求的核心代码：
#include <curl/curl.h> struct Memory { char* data; size_t size; }; static size_t write_cb(void* contents, size_t size, size_t nmemb, void* userp) { size_t realsize = size * nmemb; struct Memory* mem = (struct Memory*)userp; char* ptr = realloc(mem->data, mem->size + realsize + 1); if (!ptr) return 0; mem->data = ptr; memcpy(&(mem->data[mem->size]), contents, realsize); mem->size += realsize; mem->data[mem->size] = '\0'; return realsize; } int post_score(Config* cfg, int score) { CURL* curl = curl_easy_init(); if (!curl) return -1; struct Memory chunk = {0}; char url[512]; snprintf(url, sizeof(url), "%s/v1/chat/completions", cfg->api_base); char body[1024]; snprintf(body, sizeof(body), "{\"model\":\"%s\",\"messages\":[{\"role\":\"user\",\"content\":\"记录分数:%d\"}]}", cfg->model_id, score); struct curl_slist* headers = NULL; headers = curl_slist_append(headers, "Content-Type: application/json"); char auth[512]; snprintf(auth, sizeof(auth), "Authorization: Bearer %s", cfg->api_key); headers = curl_slist_append(headers, auth); curl_easy_setopt(curl, CURLOPT_URL, url); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb); curl_easy_setopt(curl, CURLOPT_WRITEDATA, &chunk); CURLcode res = curl_easy_perform(curl); if (res != CURLE_OK) { printf("curl failed: %s\n", curl_easy_strerror(res)); curl_slist_free_all(headers); curl_easy_cleanup(curl); free(chunk.data); return -1; } printf("response: %s\n", chunk.data ? chunk.data : "(empty)"); curl_slist_free_all(headers); curl_easy_cleanup(curl); free(chunk.data); return 0; }这段代码里，Authorization头用的是Bearer加你的Key，这是TaoToken接口的标准鉴权方式。请求体是JSON格式，model字段填配置里的model_id，messages里放你要发的内容。返回的数据会写到chunk.data里，你可以用cJSON解析出来看。
编译的时候要链接libcurl和cJSON。Makefile大概长这样：
CC = gcc CFLAGS = -Wall -O2 -I./include LDFLAGS = -lcurl -lwinhttp SRCS = main.c snake.c config.c api.c cJSON.c OBJS = $(SRCS:.c=.o) TARGET = snake.exe $(TARGET): $(OBJS) $(CC) -o $@ $^ $(LDFLAGS) %.o: %.c $(CC) $(CFLAGS) -c $< -o $@ clean: del /Q *.o $(TARGET)Windows下编译需要先装libcurl的开发包，或者用vcpkg装。Linux下直接apt install libcurl4-openssl-dev就行。cJSON.c直接放进项目里编译，不用额外装库。
4. 编译运行与接口验证：从本地游戏到在线排行榜
代码写完之后，先验证游戏本体能不能跑。编译命令：
make如果一切正常，会生成snake.exe。双击运行，应该能看到欢迎界面，按任意键进入游戏，方向键控制蛇移动，F3加速，F4减速，空格暂停，ESC退出。蛇吃到食物会变长，分数会增加，撞墙或撞自己会结束游戏，然后问你要不要再来一局。
游戏跑通之后，验证排行榜接口。我写了一个独立的测试函数，不依赖游戏流程，直接调post_score发一个分数上去：
int main() { setlocale(LC_ALL, ""); srand((unsigned int)time(NULL)); Config cfg; if (load_config("config.json", &cfg) != 0) { printf("load config failed\n"); return 1; } printf("api_base: %s\n", cfg.api_base); printf("model_id: %s\n", cfg.model_id); post_score(&cfg, 120); test(); return 0; }运行之后，如果Key和配置都对，你会看到类似这样的返回：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1700000000, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "已记录分数:120" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 10, "completion_tokens": 8, "total_tokens": 18 } }看到choices数组里有内容，说明请求成功了。如果返回的是401，说明Key不对或者没带上Authorization头。如果返回404，说明URL拼错了，检查api_base和endpoint有没有多余或缺失的斜杠。
把排行榜功能接进游戏流程，就是在GameEnd里加一段：游戏结束时，如果分数大于0，就调post_score把分数发上去。然后下次游戏启动时，可以再发一个请求拉取排行榜，把前几名显示在欢迎界面旁边。拉取排行榜的请求跟发分数类似，只是body里的content换成"查询排行榜前10名"，然后解析返回的content字段显示出来。
这里有个实际的问题：网络请求会阻塞游戏主线程。如果网络慢，游戏结束到显示排行榜之间会卡几秒。解决办法是把网络请求放到一个单独的线程里，或者用异步IO。但为了简单，我建议先同步做，等跑通了再优化。毕竟排行榜不是核心玩法，卡一下可以接受。
验证的时候还要注意一点：TaoToken的接口有速率限制，别在循环里疯狂发请求。我一般是在游戏结束时发一次，启动时拉一次，频率很低，不会触发限制。如果你要压测，记得看文档里的限流说明。
5. 常见报错排查：401、local proxy failed与JSON解析失败
接入API的过程中，报错是难免的。我把几个高频错误和排查方法列出来，你遇到了可以对照着看。
401 Unauthorized：这是最常见的错误，意思是鉴权失败。原因通常有三个：Key没填对、Authorization头格式不对、Key过期了。排查步骤：先打印cfg.api_key看看是不是空字符串或者还是占位符；再检查Authorization头的格式，必须是"Bearer "加Key，中间有个空格，很多人漏掉空格；最后去TaoToken控制台确认Key还有效。如果Key泄露过，建议删掉重新创建一个。
local proxy failed / Could not resolve host：这个错误说明curl连不上服务器。原因可能是网络不通、DNS解析失败、或者系统代理配置有问题。排查步骤：先用ping命令试试能不能通taotoken.net；如果ping不通，检查网络连接；如果能ping通但curl还是失败，检查环境变量里有没有http_proxy或https_proxy，有的话临时unset掉再试。注意，这里说的是正常的网络代理配置问题，不是让你去搞什么特殊网络工具，就是排查本机环境变量。
reading choices failed / JSON解析失败：这个错误说明请求发出去了，返回也拿到了，但解析返回的JSON时出错了。原因可能是返回的不是JSON格式（比如返回了一个HTML错误页），或者JSON结构跟预期不一样。排查步骤：先把chunk.data原样打印出来，看看返回的到底是什么。如果是一段HTML，说明请求打到了错误的地址，检查URL；如果是JSON但解析失败，用在线JSON校验工具看看格式对不对。cJSON解析失败时可以用cJSON_GetErrorPtr()看具体错在哪。
curl_easy_perform返回CURLE_WRITE_ERROR：这个错误说明写回调函数返回了0，导致curl中断传输。原因通常是realloc失败，内存不够了。排查步骤：检查write_cb里realloc的返回值，如果为NULL要处理；另外确认mem->data初始化为NULL，不然realloc会出问题。
编译时报undefined reference to curl_easy_init：这是链接错误，说明没链接libcurl。检查Makefile里的LDFLAGS有没有-lcurl，Windows下还要确认libcurl的库文件路径对不对。如果用vcpkg装的，编译时要加-I和-L指向vcpkg的include和lib目录。
游戏画面闪烁严重：这不是API的问题，是控制台重绘的问题。每次移动都全屏重绘会导致闪烁。解决办法是用双缓冲，或者只重绘变化的部分。我的做法是移动时只画新蛇头和擦掉蛇尾，不重绘整个蛇身，这样闪烁会少很多。
蛇身坐标错位：如果蛇身看起来是斜的或者有重叠，检查x坐标是不是偶数。宽字符占两列，x必须是偶数才能对齐。另外检查SetPos的坐标有没有算错，特别是左右移动时x的增减是2不是1。
食物生成在墙里或者蛇身上：检查CreateFood的坐标范围。x的范围是2到54的偶数，y的范围是1到25。如果范围写错了，食物可能生成在墙里。另外检查遍历蛇身的循环有没有正确跳过，确保食物不会跟蛇身重叠。
6. 继续扩展：把排行榜做成真正的在线服务
游戏能跑、接口能通之后，你可以在这个基础上继续加东西。比如把排行榜做成真正的在线服务，每次游戏结束自动上传分数，启动时拉取前10名显示。这需要你在TaoToken的接口基础上再包一层，或者用它的其他能力来存储数据。具体怎么做，可以看接入文档里的说明。
如果你想把游戏分享给别人玩，可以把Key放在服务端，客户端只调你自己的接口，这样Key不会暴露。但这又回到了搭后端的老路。折中方案是用TaoToken的Coding Plan，它提供了一些现成的能力，可以省掉一部分后端工作。具体适不适合你的场景，去Coding Plan页面看看就知道了。
模型选择上，排行榜这种场景不需要太强的模型，用gpt-4o-mini这种便宜的就够了。如果你要做的排行榜需要更复杂的逻辑，比如按分数段分组、计算排名变化，可以换更强的模型。Model ID在文档里都能查到，换的时候只改config.json里的model_id就行，代码不用动。
最后说一个实际经验：网络请求一定要加超时。我一开始没加，结果网络卡的时候游戏直接卡死，体验很差。curl_easy_setopt里加CURLOPT_TIMEOUT，设个5秒，超时就放弃，不要让玩家等太久。另外请求失败要有降级方案，比如显示"排行榜暂时不可用"，而不是直接崩溃。这些细节决定了你的程序是"能跑"还是"好用"。
代码写到这里，贪吃蛇已经不只是一个练手项目了。它有了本地游戏循环、有了网络通信、有了配置管理、有了错误处理，这些都是一般C语言教程里不会教但实际工作中天天用的东西。你可以继续往上加功能，比如多人在线对战、分数曲线图、成就系统，每加一个都是在练不同的技能。关键是先把这条最小闭环跑通，后面加什么都是在这个基础上长出来的。
