wfrest 01_basic 实战：用 TaoToken 统一 Key 跑通第一个 C++ HTTP 服务器

1. 从 01_basic 说起为什么第一个 wfrest 服务器值得认真跑一遍wfrest 是一个基于 C 的 Web 框架定位是 REST API 服务器底层复用了 workflow 的异步网络能力。如果你之前用过 mongoose 或者 cpp-http会发现 wfrest 的接口设计思路很接近注册路由、绑定回调、启动监听几行代码就能把 HTTP 服务器跑起来。它适合谁适合已经会写 C、想快速给自己的工具或服务加一个 HTTP 接口的开发者也适合想读源码学习异步网络编程的人。01_basic这个示例是 wfrest 仓库里最基础的入口做的事情不复杂启动一个监听 8888 端口的 HTTP 服务器注册/hello、/data、/multi、/post几个路由然后用wait_group阻塞主线程收到SIGINT信号后优雅退出。看起来简单但真正在本地编译运行时很多人会卡在依赖找不到、CMake 链接顺序、头文件路径这些问题上。这篇内容聚焦的就是「本地编译 运行 验证」这条链路。我会给出 CMakeLists 和 settings.json 的骨架把 TaoToken 作为统一的 Key/API 通道接进示例请求里再用 curl 一步步验证。目标很明确让你一次把基础 HTTP 服务器跑通而不是在环境问题上反复折腾。2. 前置准备TaoToken 统一 Key 与 wfrest 依赖在动手编译之前先把两件事准备好一个是 wfrest 的编译依赖另一个是 TaoToken 的 API Key。前者决定你能不能编译成功后者决定你后面发请求时有没有统一的鉴权通道。wfrest 依赖 workflow而 workflow 又依赖 OpenSSL。在 Ubuntu/Debian 上你可以先装基础库sudo apt update sudo apt install -y build-essential cmake git libssl-devworkflow 和 wfrest 都需要从源码编译安装。先编 workflowgit clone https://github.com/sogou/workflow.git cd workflow mkdir build cd build cmake .. -DCMAKE_INSTALL_PREFIX/usr/local make -j$(nproc) sudo make install再编 wfrestgit clone https://github.com/wfrest/wfrest.git cd wfrest mkdir build cd build cmake .. -DCMAKE_INSTALL_PREFIX/usr/local make -j$(nproc) sudo make install装完之后/usr/local/include下会有wfrest/和workflow/目录/usr/local/lib下会有对应的.so或.a。如果ldconfig没自动刷新手动执行一次sudo ldconfig接下来是 TaoToken。它的作用是把模型调用、编码计划、API Key 管理这些能力收敛到一个入口你不需要在多个平台之间来回切换 Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后建议不要硬编码在源码里而是写进一个settings.json由程序读取。这样后面换 Key 或者换环境时不用重新编译。一个最小骨架长这样{ taotoken: { api_base: https://taotoken.net/api, api_key: sk-你的实际Key, model: claude-sonnet }, server: { host: 0.0.0.0, port: 8888 } }注意api_base用https://taotoken.net/api不要带 UTM 参数避免请求签名或路径匹配出问题。Key 只放在本地配置文件不要提交到 Git。如果你后面要做长期编码或者 Agent 类任务可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。单纯验证模型对话的话模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。3. 可复制配置CMakeLists 与 01_basic 源码改造这一节给你可以直接复制的 CMakeLists 和改造后的01_basic源码。目录结构建议这样组织wfrest_demo/ ├── CMakeLists.txt ├── settings.json └── src/ └── main.cppCMakeLists 的关键是找到 wfrest 和 workflow并把它们链接进去。注意链接顺序wfrest 依赖 workflowworkflow 依赖 OpenSSL所以target_link_libraries里 wfrest 要放在 workflow 前面。cmake_minimum_required(VERSION 3.14) project(wfrest_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(OpenSSL REQUIRED) find_package(Threads REQUIRED) # wfrest 和 workflow 默认安装到 /usr/local find_path(WFREST_INCLUDE_DIR wfrest/HttpServer.h PATHS /usr/local/include /usr/include) find_library(WFREST_LIB wfrest PATHS /usr/local/lib /usr/lib) find_library(WORKFLOW_LIB workflow PATHS /usr/local/lib /usr/lib) if(NOT WFREST_INCLUDE_DIR OR NOT WFREST_LIB OR NOT WORKFLOW_LIB) message(FATAL_ERROR wfrest/workflow not found, check install prefix) endif() add_executable(wfrest_demo src/main.cpp) target_include_directories(wfrest_demo PRIVATE ${WFREST_INCLUDE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src) target_link_libraries(wfrest_demo PRIVATE ${WFREST_LIB} ${WORKFLOW_LIB} OpenSSL::SSL OpenSSL::Crypto Threads::Threads)然后是src/main.cpp。我在原始01_basic的基础上做了两处改造一是读取settings.json拿到端口和 TaoToken 配置二是加了一个/api/echo路由用来演示如何把请求转发到 TaoToken 的 API 通道。这里不引入额外 JSON 库用一个极简的字符串解析函数读取 Key 和端口避免依赖膨胀。#include workflow/WFFacilities.h #include csignal #include cstdio #include cstdlib #include fstream #include sstream #include string #include wfrest/HttpServer.h using namespace wfrest; static WFFacilities::WaitGroup wait_group(1); void sig_handler(int signo) { wait_group.done(); } // 极简配置读取从 settings.json 中提取 key: value static std::string read_json_value(const std::string content, const std::string key) { std::string pattern \ key \; size_t pos content.find(pattern); if (pos std::string::npos) return ; pos content.find(:, pos); if (pos std::string::npos) return ; size_t start content.find(, pos); if (start std::string::npos) return ; size_t end content.find(, start 1); if (end std::string::npos) return ; return content.substr(start 1, end - start - 1); } int main() { signal(SIGINT, sig_handler); std::ifstream ifs(settings.json); if (!ifs.is_open()) { fprintf(stderr, cannot open settings.json\n); return 1; } std::stringstream ss; ss ifs.rdbuf(); std::string cfg ss.str(); std::string api_base read_json_value(cfg, api_base); std::string api_key read_json_value(cfg, api_key); std::string port_str read_json_value(cfg, port); int port port_str.empty() ? 8888 : std::atoi(port_str.c_str()); fprintf(stderr, api_base%s, port%d\n, api_base.c_str(), port); HttpServer svr; // curl -v http://127.0.0.1:8888/hello svr.GET(/hello, [](const HttpReq *req, HttpResp *resp) { resp-String(world\n); }); // curl -v http://127.0.0.1:8888/data svr.GET(/data, [](const HttpReq *req, HttpResp *resp) { std::string str Hello world; resp-String(std::move(str)); }); // curl -v http://127.0.0.1:8888/multi svr.ROUTE(/multi, [](const HttpReq *req, HttpResp *resp) { std::string method(req-get_method()); resp-String(std::move(method)); }, {GET, POST}); // curl -v http://127.0.0.1:8888/post -d post hello world svr.POST(/post, [](const HttpReq *req, HttpResp *resp) { std::string body req-body(); fprintf(stderr, post data : %s\n, body.c_str()); resp-String(received\n); }); // 演示统一 Key 通道返回当前配置的 api_base 与 Key 前缀 svr.GET(/api/echo, [api_base, api_key](const HttpReq *req, HttpResp *resp) { std::string prefix api_key.substr(0, 6); std::string out api_base api_base , key_prefix prefix \n; resp-String(std::move(out)); }); if (svr.track().start(port) 0) { svr.list_routes(); wait_group.wait(); svr.stop(); } else { fprintf(stderr, Cannot start server\n); exit(1); } return 0; }编译命令mkdir -p build cd build cmake .. make -j$(nproc)编译成功后把settings.json放到可执行文件同级目录或者用绝对路径读取。运行./wfrest_demo如果一切正常终端会打印出路由列表和监听端口。4. 验证请求curl 跑通基础路由与统一 Key 通道服务器起来之后用 curl 逐个验证。先测最基础的/hellocurl -v http://127.0.0.1:8888/hello预期返回worldHTTP 状态码 200。-v会打印请求头和响应头方便确认 Content-Length 和 Content-Type。接着测/datacurl -s http://127.0.0.1:8888/data返回Hello world。这个路由演示的是把std::string移动进响应体避免拷贝。测/multi它同时接受 GET 和 POSTcurl -s http://127.0.0.1:8888/multi curl -s -X POST http://127.0.0.1:8888/multi两次分别返回GET和POST说明ROUTE的多方法注册生效了。测/post带 bodycurl -v http://127.0.0.1:8888/post -d post hello world服务器端会打印post data : post hello world客户端收到received。最后测统一 Key 通道/api/echocurl -s http://127.0.0.1:8888/api/echo返回类似api_basehttps://taotoken.net/api, key_prefixsk-xxx这一步验证的是你的settings.json被正确读取TaoToken 的api_base和 Key 已经进入程序运行时。后面你要在这个基础上发真实的模型请求只需要在回调里用 workflow 的 HTTP 客户端去请求api_base对应的接口把Authorization: Bearer key带上即可。如果你更想先验证模型对话本身可以直接用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入细节和鉴权格式参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5. 本篇常见错排查编译、链接、端口与 Key 读取这一节把我在本地跑01_basic时踩过的坑列出来按出现频率排序。找不到 wfrest/HttpServer.h。说明find_path没命中。先确认/usr/local/include/wfrest/HttpServer.h是否存在。如果装在别的 prefix比如$HOME/.local就在 CMakeLists 里把该路径加进PATHS或者编译时传-DCMAKE_PREFIX_PATH$HOME/.local。链接时报 undefined reference towfrest::HttpServer::...。多半是链接顺序问题。target_link_libraries里 wfrest 必须在 workflow 前面因为静态链接时符号解析是从左到右的。如果用的是静态库还要确保 OpenSSL 和 pthread 也在列表里。运行时报error while loading shared libraries: libwfrest.so。这是动态库路径没进ldconfig。执行sudo ldconfig或者运行时临时指定LD_LIBRARY_PATH/usr/local/lib ./wfrest_demo。端口 8888 被占用。start(port)返回非 0程序打印Cannot start server后退出。用ss -lntp | grep 8888查占用进程或者把settings.json里的port改成 8899 再试。settings.json 读取失败或 Key 为空。先确认运行目录下有settings.json因为代码用的是相对路径。如果你在build/里运行而settings.json在项目根目录就会读不到。要么把文件复制过去要么改成绝对路径。另外极简解析函数对 JSON 格式比较敏感api_key: sk-xxx这种标准写法没问题但如果值里本身带引号就会截断生产环境建议换用 nlohmann/json。curl 返回 404。检查路由注册的路径是否和请求路径完全一致wfrest 默认区分大小写。/hello和/Hello是两个不同的路由。收到 SIGINT 后进程不退出。确认wait_group的计数是 1且sig_handler里调用了done()。如果多次注册信号或者计数不对wait()会一直阻塞。6. 把 Key 通道固定下来继续往下走01_basic跑通之后你手里其实已经有了一个最小可用的 HTTP 服务器骨架路由注册、请求体读取、多方法支持、信号处理、配置外置。接下来不管是加数据库、加异步任务还是接模型 API都是在这个骨架上叠。TaoToken 在这里的角色是统一 Key 和 API 通道。你不需要在每个示例里重新配一遍鉴权只要settings.json里的api_base和api_key不变所有请求都走同一个入口。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你打算把 wfrest 用在长期编码或 Agent 场景Coding Plan 会更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。我自己的习惯是每跑通一个示例就把settings.json和 CMakeLists 单独存一份模板下一个示例直接复制只改源码。这样环境问题只解决一次后面精力都花在业务逻辑上。