企业官网建设流程全解析

ScyllaDB RESTful API V2 详解：Swagger 2.0 定义、Config 配置查询与源码实现剖析

【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb

ScyllaDB 从首个版本起就内置了 RESTful API，早期的 V1 接口路径组织较为混乱，其继任者 V2 通过统一的/v2前缀与 Swagger 2.0 规范定义了清晰、可自描述的接口体系。本文基于仓库文档 docs/dev/api_v2.md 展开，结合 api/api.cc、api/config.cc 等源码，讲解如何通过/v2获取 API 定义、如何用 swagger-ui 图形化浏览、V2 接口的分节（section）组织方式，以及 Config 配置查询接口背后的实现原理。读完本文，你将能够直接对运行中的 ScyllaDB 节点进行配置查询、接口探索，并理解 V1/V2 双轨并存的注册机制。

从 V1 到 V2：RESTful API 的定位与演进

ScyllaDB 的 RESTful API 主要面向运维、监控与故障诊断场景：暴露集群内部各子系统（存储、压缩、修复、流式传输、Raft 等）的状态，并允许部分运行时参数被动态修改。V1 接口自项目初版即存在，但正如文档所述，其设计"令人困惑（confusing）"，正逐步被 V2 取代。

从源码结构看，V1 与 V2 的差异体现在注册器上。api/api.cc 的set_server_init中同时创建了两个 registry builder：

auto rb = std::make_shared<api_registry_builder>(ctx.api_doc); // V1 auto rb02 = std::make_shared<api_registry_builder20>(ctx.api_doc, "/v2"); // V2 ... rb->set_api_doc(r); rb02->set_api_doc(r); rb02->register_api_file(r, "swagger20_header"); rb02->register_api_file(r, "metrics"); rb02->register_api_file(r, "client_routes");

api_registry_builder20构造时显式传入"/v2"前缀，因此所有 V2 路由都落在/v2之下；而 V1 的api_registry_builder不带该前缀。两者共享同一 HTTP 服务器与文档目录，这正是"V1 将被 V2 逐步替换"期间双轨并存的实现方式。

获取 Swagger 2.0 定义文件：/v2 端点

V2 的 API 定义采用 Swagger 2.0 格式。将浏览器或 curl 指向运行节点即可取到完整定义：

http://localhost:10000/v2

这个 JSON 并非静态文件，而是由多个部件拼装而成：

1. 头部元信息：api/api-doc/swagger20_header.json 提供swagger: "2.0"、info.title: "Scylla API"、description: "The scylla API version 2.0"，并声明consumes/produces均为application/json、schemes为http、basePath为/。
2. 各分节的 path/definitions：rb02->register_api_file(r, ...)与rb->register_function(r, 分节名, 描述)逐节追加。
3. 构建期生成：api/CMakeLists.txt 中的generate_swagger函数把 api/api-doc/ 下的每个.json文件编译成对应的.json.hh头文件（如api/api-doc/config.json.hh），路由绑定在编译期就与 JSON 定义一一对应，保证了定义与实际 handler 的一致性。

使用 swagger-ui 图形化探索 API

除直接查看 JSON 外，文档推荐的更实用方式是 swagger-ui——一个基于 JavaScript 的 GUI：

1. 浏览器访问http://localhost:10000/ui；
2. 确认页面 URL 输入框中的地址为http://localhost:10000/v2，即可加载全部接口并在线试用（Try it out）。

这两个端点在 api/api.cc 中注册：

r.put(GET, "/ui", new httpd::file_handler(ctx.api_dir + "/index.html", new content_replace("html"))); r.add(GET, url("/ui").remainder("path"), new httpd::directory_handler(ctx.api_dir, new content_replace("html")));

即/ui本身返回 swagger-ui 的index.html，/ui/*的其余静态资源（JS/CSS）由directory_handler按目录分发。ctx.api_dir来自节点配置，见下文配置项一节。

API 分节（Sections）：从源码结构看组织方式

文档指出 "The API is split into sections"。在 swagger-ui 中按 Tag 展开即可看到各节。从源码结构看，每个子系统对应 api/ 目录下一个模块文件与 api/api-doc/ 下一个 Swagger JSON，例如：

这些分节并非一次性全部就绪。main.cc 展示了生命周期驱动的注册模式：某个子系统就绪后调用对应的api::set_server_*，停止时调用api::unset_server_*解注册，例如：

api::set_server_config(ctx, *cfg).get(); auto stop_config_api = defer_verbose_shutdown("config API", [&ctx] { api::unset_server_config(ctx).get(); });

main.cc 还体现了 API 监听地址的确定逻辑：优先使用api_address，未设置时回退到rpc_address，最终在api_port（默认 10000）上listen。

相关配置项在 db/config.cc 中定义，可写入 conf/scylla.yaml：

main.cc 中还会自动为api_ui_dir/api_doc_dir补齐结尾斜杠，因此配置时不需要手动带/。

Config 分节：查询运行中的真实配置值

文档对 Config 分节有两条关键说明，这里结合 api/config.cc 的实现逐条印证：

1. "展开 config 分节可以看到系统里所有可用的配置项"。这些条目是动态生成的，而非静态 JSON。api/config.cc 的set_config遍历db::config的全部配置项，为每一项调用get_config_swagger_entry输出一条/v2/config/{name}的 GET 定义，其中 description 取自配置项的描述文本，schema 类型由type_name()映射（int会被规范为 Swagger 的integer，见 api/config.cc）：

for (auto&& cfg_ref : cfg.values()) { auto&& cfg = cfg_ref.get(); f = f.then([&os, &first, &cfg] { return get_config_swagger_entry(cfg.name(), std::string(cfg.desc()), cfg.type_name(), first, os); }); }

这就是为什么/v2里 config 分节能列出全部参数——它是从运行节点当前配置表逐项推导出来的。

2. "API 返回的取值是系统当前的真实值，无论它来自默认值、配置文件还是命令行参数。"对应 handler 在 api/config.cc：

cs::find_config_id.set(r, [&cfg] (std::unique_ptr<http::request> req) { auto id = req->get_path_param("id"); auto value = co_await cfg.value_as_json_string_for_name(id); if (!value) { throw bad_param_exception(sstring("No such config entry: ") + id); } json::json_return_type ret{json::json_void()}; ret._res = std::move(*value); co_return ret; });

value_as_json_string_for_name按名称查询配置项当前生效值并序列化为 JSON 字符串直接返回；参数不存在时抛出bad_param_exception。因此实际用法是：

# 查看某个配置项的当前值，例如请求超时（毫秒级参数返回秒级浮点，见下） curl http://localhost:10000/v2/config/compaction_throughput_mb_per_sec

3. 部分 V2 端点还支持运行时修改。同一文件中的set_compaction_throughput_mb_per_sec、set_stream_throughput_mb_per_sec通过req_param解析查询参数value，并以config_source::API标记来源写回db::config（api/config.cc）。而各set_*_timeout端点目前仍带有//TBD注释并调用unimplemented()，说明写接口尚在完善中，使用前应以实际 Swagger 定义为准。

Config 分节的路径模板见 api/api-doc/config.json：/v2/config/{id}，operationId为find_config_id，200 响应描述为 "Config value"，错误则引用ErrorModel定义。

实践小结：从启动节点到浏览 API

1. 启动 ScyllaDB 后，API 服务器默认监听127.0.0.1:10000（api_address未设置时回退rpc_address，见 main.cc 的解析逻辑）；
2. 浏览器或 curl 访问http://<host>:10000/v2获取 Swagger 2.0 完整定义；
3. 访问http://<host>:10000/ui，确保 URL 框指向.../v2，用 swagger-ui 按分节浏览、在线调用；
4. 用/v2/config/{id}查询任意配置项当前生效值；注意这是查询当前值而非配置文件内容，二者在发生运行时修改后会不一致；
5. 修改静态资源目录（例如自定义部署 swagger-ui）时配置api_ui_dir/api_doc_dir，无需带结尾斜杠。

V1/V2 并存期的注意事项

从源码结构看，当前版本中 V1 与 V2 同时在线：api_registry_builder（V1）与api_registry_builder20（V2）在 api/api.cc 中并存，且各分节的set_server_*注册函数内部仍可能同时使用两套 builder（如 api/api.cc 的register_api只注册到 V1）。因此脚本与监控工具在迁移时应优先使用/v2路径——这也与文档"V1 将逐步被 V2 取代"的表述一致。对于自动化系统，建议以GET /v2返回的定义作为单一事实来源（single source of truth），而非硬编码路径。

相关源码与文档索引

• 文档主体：docs/dev/api_v2.md
• API 注册与/ui路由：api/api.cc
• Config 动态 Swagger 生成与取值实现：api/config.cc
• 头部定义与配置项定义：api/api-doc/swagger20_header.json、api/api-doc/config.json
• Swagger 构建期代码生成：api/CMakeLists.txt
• 配置项声明：db/config.cc
• 服务器生命周期注册：main.cc

【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb