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/scylladbScyllaDB 从首个版本起就内置了 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 到 V2RESTful API 的定位与演进ScyllaDB 的 RESTful API 主要面向运维、监控与故障诊断场景暴露集群内部各子系统存储、压缩、修复、流式传输、Raft 等的状态并允许部分运行时参数被动态修改。V1 接口自项目初版即存在但正如文档所述其设计令人困惑confusing正逐步被 V2 取代。从源码结构看V1 与 V2 的差异体现在注册器上。api/api.cc 的set_server_init中同时创建了两个 registry builderauto rb std::make_sharedapi_registry_builder(ctx.api_doc); // V1 auto rb02 std::make_sharedapi_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 并非静态文件而是由多个部件拼装而成头部元信息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为/。各分节的 path/definitionsrb02-register_api_file(r, ...)与rb-register_function(r, 分节名, 描述)逐节追加。构建期生成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浏览器访问http://localhost:10000/ui确认页面 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例如分节定义文件说明源自 api-doc 或注册代码systemapi/api-doc/system.jsonThe system related APIapi/api.ccerror_injectionapi/api-doc/error_injection.jsonThe error injection APIstorage_proxyapi/api-doc/storage_proxy.jsonThe storage proxy APIstorage_serviceapi/api-doc/storage_service.jsonThe storage service APIconfigapi/api-doc/config.json配置查询见下一节metrics / client_routesapi/api-doc/metrics.json、api/api-doc/client_routes.json在set_server_init中显式register_api_file注册的 V2 定义其余gossiper、hinted_handoff、compaction_manager、commitlog、stream_manager、task_manager、raft、failure_detector、column_family、lsa、collectd、messaging_service、service_levels、streaming 等各自模块注册这些分节并非一次性全部就绪。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配置项默认值说明api_port10000Http Rest API portapi_address空回退rpc_addressHttp Rest API addressapi_ui_dirswagger-ui/dist/swagger-ui 静态资源目录即/ui端点的文件来源api_doc_dirapi/api-doc/Swagger 定义文件目录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.ccfor (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.cccs::find_config_id.set(r, [cfg] (std::unique_ptrhttp::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_sec3. 部分 V2 端点还支持运行时修改。同一文件中的set_compaction_throughput_mb_per_sec、set_stream_throughput_mb_per_sec通过req_param解析查询参数value并以config_source::API标记来源写回db::configapi/config.cc。而各set_*_timeout端点目前仍带有//TBD注释并调用unimplemented()说明写接口尚在完善中使用前应以实际 Swagger 定义为准。Config 分节的路径模板见 api/api-doc/config.json/v2/config/{id}operationId为find_config_id200 响应描述为 Config value错误则引用ErrorModel定义。实践小结从启动节点到浏览 API启动 ScyllaDB 后API 服务器默认监听127.0.0.1:10000api_address未设置时回退rpc_address见 main.cc 的解析逻辑浏览器或 curl 访问http://host:10000/v2获取 Swagger 2.0 完整定义访问http://host:10000/ui确保 URL 框指向.../v2用 swagger-ui 按分节浏览、在线调用用/v2/config/{id}查询任意配置项当前生效值注意这是查询当前值而非配置文件内容二者在发生运行时修改后会不一致修改静态资源目录例如自定义部署 swagger-ui时配置api_ui_dir/api_doc_dir无需带结尾斜杠。V1/V2 并存期的注意事项从源码结构看当前版本中 V1 与 V2 同时在线api_registry_builderV1与api_registry_builder20V2在 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.mdAPI 注册与/ui路由api/api.ccConfig 动态 Swagger 生成与取值实现api/config.cc头部定义与配置项定义api/api-doc/swagger20_header.json、api/api-doc/config.jsonSwagger 构建期代码生成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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
