SurrealDB 源码贡献指南从环境搭建、代码规范到提交 PR 的完整工作流【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb本篇指南面向希望向 SurrealDB 开源仓库贡献代码的开发者系统讲解如何搭建 Rust 开发环境、编译并启动数据库、编写与运行 SurrealQL 语言测试、遵守代码规范与 crate 组织约定以及从分支命名到合并的全套 Pull Request 工作流。读完本文你将能够在 SurrealDB 仓库中独立完成一次从代码修改、测试验证到提交合并的完整贡献闭环。参与开发的整体预期SurrealDB 是一个开源的、可扩展的分布式文档-图数据库document-graph database面向实时 Web 场景。仓库本身欢迎一切类型的贡献包括新功能、缺陷修复、文档改进、博客思路与工作坊内容。不过需要理解它的实际协作节奏绝大多数开发由内部工程团队规划并完成社区提交的 PR 通常需要等待一段时间才会被审查很多被合并的 PR 在收到审查前往往要经历数周。在提交之前可以先从两个维度评估自己的 PR 前景关键性cruciality这个改动有多重要规模size这个改动有多大由此形成两个典型极端关键且小巧例如一行代码的缺陷修复审查和合并都快不关键且庞大例如某个新功能的大规模实现依然有可能被合并但最好在动手前与团队进行充分讨论。一些较大的功能特性可能需要先走 RFC 流程。仓库根目录的 CONTRIBUTING.md 正是官方维护的贡献入口文档本文的所有内容均以它为主线展开。PR 长时间无人处理怎么办如果 PR 提交后迟迟没有动静可以参考以下建议观察当前活跃度查看最近更新的 PR 与活跃分支。如果这些 PR 普遍很大说明团队正在进行大规模开发工程师可能暂时没有精力审查新 PR主动讨论在 Discord 社区中适时提及你的 PR工程团队成员大多会关注与自己负责代码块相关的频道补充图片或视频视觉化的变更演示常常是吸引注意、说明 PR 价值的最有效方式。同时需要保持心理预期你的 PR 可能与一个尚未公开的新功能冲突。如果工程团队已经在开发类似功能出于保密原因甚至无法对 PR 发表评论这并非针对个人。代码规范格式化与 LintSurrealDB 使用 cargo 生态的标准命令来保证代码格式和静态检查的一致// 使用 nightly rustfmt 进行格式化仓库内 rust-toolchain.nightly 指定了具体版本 make fmt或 cargo make fmt cargo clippy需要说明的是根目录的 Makefile 本身是一个透传封装它会检查cargo-make是否可用然后把所有目标透传给cargo make任务定义在 Makefile.toml并进一步扩展 Makefile.ci.toml 与 Makefile.local.toml。因此实际执行make fmt前需要先安装cargo-makecargo install --no-default-features --force --locked cargo-make在仓库根目录的 Cargo.toml 中[workspace.lints.clippy]定义了一系列全局 Clippy 规则例如assigning_clones warn、redundant_clone warn、unwrap_used warn等所有 workspace 成员共享这些 lint 配置。值得注意的是unused_async allowSurrealDB 在 AST 解析器与执行器中依赖 async 函数来避免栈溢出所以这条 lint 被显式放行。提交代码前运行cargo clippy并通过这些规则是 CI 通过的第一步。仓库结构与 crate 组织SurrealDB 是一个 Cargo workspace根目录的 Cargo.toml 中通过members数组列出了全部 crate。官方在贡献指南中给出了清晰的 crate 分类主 cratecrate目录职责surrealdbsurrealdb/主 SDK crate提供客户端与嵌入式数据库功能surrealdb-coresurrealdb/core/核心数据库引擎、查询执行与存储层surrealdb-serversurrealdb/server/服务器实现提供 HTTP、WebSocket 与 gRPC 端点surrealdb-typessurrealdb/types/SurrealDB 值的公开类型被 SDK 与服务器共用surrealdb-types-derivesurrealdb/types/derive/用于派生SurrealValuetrait 的过程宏支撑 cratecrate目录职责surrealismsurrealism/用于执行用户自定义函数的 WebAssembly 运行时language-testslanguage-tests/基于.surql文件的 SurrealQL 语言测试框架fuzzfuzz/面向安全与稳定性的模糊测试profilingprofiling/性能剖析工具从源码可以看到workspace 还包含surrealdb/common、surrealdb/ast、surrealdb/token、surrealdb/parser、surrealml/core等 crate共同构成完整的分层架构。新增 crate 的规范贡献指南对新增 workspace crate 提出了明确要求以确保结构一致性1. 命名约定层级 crate对于层级 crate某个父 crate 下的子 cratecrate 名应通过把连字符替换为目录分隔符来匹配目录结构crate 名为surrealdb-types-derive→ 位于surrealdb/types/derive/crate 名为surrealdb-core→ 位于surrealdb/core/对于根级 crate工具、测试等则允许使用连字符crate 名为language-tests→ 位于language-tests/2. 位置根据用途放置 crate核心数据库功能 → 放在surrealdb/下工具与测试 → 放在根级3. 更新 workspace在根 Cargo.toml 的members数组中加入 crate 路径[workspace] members [ # ... existing members ... your-new-crate, ]4. 声明 workspace 依赖如果该 crate 会被其他 workspace 成员引用还需要加入[workspace.dependencies][workspace.dependencies] # 预发布版本例如 -alpha、-beta、-rc your-new-crate { version x.y.z-prerelease, path path/to/your-new-crate } # 或正式发布版本 your-new-crate { version x.y, path path/to/your-new-crate }仓库现有配置正是这一规范的直接体现例如 Cargo.toml 中surrealdb-core { version 3.1.0-alpha, path surrealdb/core, default-features false }与ast { package surrealdb-ast, path surrealdb/ast }都遵循了这套模式。从源码搭建开发环境设置开发环境有两种途径一是使用 Nix 包管理器自动管理 C/C 依赖与工具链二是手动安装依赖并确保已安装rustup。注意以下指令面向的是贡献者代码维护者的开发环境如果只想日常使用 SurrealDB应参考官方安装与集成文档而不是从源码构建。doc/BUILDING.md 详细记录了在 macOS、Ubuntu、Debian、Windows 等多个平台上的编译步骤包括交叉编译到aarch64-unknown-linux-gnu、x86_64-unknown-linux-gnu等目标并明确指出 Windows 编译需要管理员权限、部分交叉编译目标如 Windows GNU、Linux Musl当前尚不能成功构建。如果遇到环境问题请优先查阅该文档。基础环境# 提示选择时使用默认的 stable 发布通道 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh git clone gitgithub.com:[YOUR_FORK_HERE]/surrealdb.git cd surrealdb cargo run -- helpcargo run -- help用于验证编译链路与 CLI 入口是否正常。仓库的src/main.rs是根包surreal见 Cargo.toml 的[package]段的二进制入口。启动 SurrealDB 服务器为了快速启动一个本地数据库实例可以用--no-default-features显式挑选最小特性集只启用内存存储、HTTP 与脚本能力cargo run --no-default-features --features \ storage-mem,http,scripting -- start --log trace \ --user root --pass root memory这条命令同时展示了仓库 Cargo.toml 中特性开关的用法storage-mem内存存储、httpHTTP API与scripting脚本支持都是顶层 crate 定义的 feature它们分别透传到surrealdb-server的同名 feature。默认特性集还包含storage-surrealkv、storage-rocksdb、storage-tikv、graphql、surrealism、cli等。开发时监听代码变更利用cargo watch在文件变化时自动重新编译并重启cargo watch -x run --no-default-features \ --features storage-mem,http,scripting -- start \ --log trace --user root --pass root memory修改监听地址与端口默认情况下 SurrealDB 在本地 8000 端口运行。需要变更监听地址或端口时使用--bindcargo run --no-default-features --features \ storage-mem,http,scripting -- start --log trace \ --user root --pass root --bind 0.0.0.0:9000 memory运行全部测试cargo test使用 language-tests 编写 SurrealQL 语言测试许多测试已经迁移到 language-tests crate它允许仅用 SurrealQL 配合一个 TOML 配置注释来创建测试无需编写任何 Rust 代码。这也是当前仓库最主要的新测试提交方式官方贡献指南给出了完整示例/** # The env map configures the general environment of the test [env] namespace false database false auth { level owner } signin {} signup {} [test] # Sets the reason behind this test; what exactly this test is testing. reason Ensure multi line comments are properly parsed as toml. # Whether to actually run this file, some files might only be used as an import, # setting this to false disables running that test. run true # set the expected result for this test # Can also be a plain array i.e. results [foo,{ error true }] [[test.results]] # the first result should be foo value foo [[test.results]] # the second result should be an error. # You can error to a string for an error test, then the test will ensure that # the error has the same text. Otherwise it will just check for an error without # checking its value. error true */ // The actual queries tested in the test. RETURN foo; 1 1;该 TOML 配置写在/** */或//!特殊注释中运行测试时所有测试注释会被拼接后解析为 TOML。仓库中真实的测试文件例如 language-tests/tests/self_tests/simple_matching_expression.surql/** [test] [[test.results]] match true */ 1;可见[[test.results]]支持value、error、match等多种断言方式。language-tests CLI 的用法language-tests/README.md 详细说明了测试运行工具# 在 language-tests 目录下运行全部测试第二个 run 是子命令 cargo run run # 只运行路径中包含 foo 的测试过滤器 cargo run run foo # 自动为未指定结果的测试填充期望输出 cargo run run --results accept # 覆盖现有结果需谨慎使用仅当确认新结果有效时 cargo run run --results overwrite还支持通过--backend指定存储引擎运行测试memory或mem默认内存存储引擎测试最快rocksdbRocksDB 嵌入式引擎需backend-rocksdbfeaturesurrealkvSurrealKV 文件存储引擎需backend-surrealkvfeaturetikvTiKV 分布式引擎需backend-tikvfeature 与运行中的 TiKV 集群cargo run --features backend-rocksdb run --backend rocksdb在测试配置的[test]与[env]表中还支持wip已知问题或进行中功能失败仅告警不阻断、version语义化版本要求、imports前置导入文件、timeout、backend、versionedMVCC 版本化、auth、signin/signup、capabilities、planner-strategy新/旧执行器策略等丰富的控制键默认值均为安全的保守选择。构建生产级二进制调试阶段完成后构建生产可用的 SurrealDB 二进制cargo build --release根 Cargo.toml 的[profile.release]配置了lto true、codegen-units 1、opt-level 3、panic abort、strip true这意味着 release 构建会经过完整 LTO 并剥离符号体积与性能都面向生产优化。若要为特定平台交叉编译参考 doc/BUILDING.md 中cargo build --release --locked --target target-triple的用法。性能与可扩展性考量SurrealDB 被设计为既要快又要能扩展既支持单节点部署也支持分布式集群分布式模式下基于 TiKV。同时它被设计运行在不同环境、不同配置与不同规模下。因此在贡献代码时需要特别关注以下指标SurrealDB 启动时间查询执行时间查询响应时间查询吞吐量每秒请求数Requests per secondWebSocket 连接数网络使用量内存使用量仓库中与这些指标直接对应的工具包括 profiling/性能剖析与 surrealdb/benchesCriterion 基准测试覆盖 array、hash trie、HNSW 索引、解析器与执行器等。当你的改动涉及存储层、索引或执行器时运行相关基准是很有说服力的佐证。安全与隐私SurrealDB 团队非常重视代码、软件与云平台的安全。如果你认为发现了安全漏洞请立即通过邮件 securitysurrealdb.com 报告而不是在 GitHub 上公开创建 issue。报告时请附上surreal version命令输出的版本标识符漏洞可利用方式的详细说明。在开发过程中也请遵循行业最佳实践与标准。外部依赖管理请避免未经团队讨论就引入新的依赖。新依赖虽然可能带来便利但也会引入新的安全与隐私问题、增加复杂度并影响最终 Docker 镜像的体积。添加依赖应当对产品有至关重要的价值同时把风险降到最低。仓库根目录的 supply-chain/ 目录包含audits.toml、config.toml、imports.lock与 deny.toml 体现了这一治理策略依赖准入是受控流程而不是随手添加。Revisioned structs 与 revision-lockSurrealDB 使用Revision机制来管理内部类型的版本如果这些类型的定义发生变更必须同步更新对应的版本号。为追踪这些版本仓库使用revision-lock生成锁文件。根目录的 revision.lock 就是一个实际的锁文件示例例如AccessDefinition:1(surrealdb/core/src/catalog/schema/access.rs)(3072791384) EventDefinition:3(surrealdb/core/src/catalog/schema/event.rs)(3537595141) Relation:2(surrealdb/core/src/catalog/table.rs)(3166613370)每行记录了类型名、当前修订版本号、定义位置与哈希校验。如果 CI 中的 revision.lock 检查失败安装并运行校验工具即可cargo install revision-lock revision-lock这条命令会根据源码中的#[revision]派生宏重新生成/校验锁文件。修改了任何被 Revision 管理的类型如新增字段、改变序列化格式却不同步更新版本号就是这类 CI 失败的典型原因。善用 issue 的 topic 标签SurrealDB 的 GitHub issue 带有以topic:开头的标签例如topic:typing、topic:record ids。在解决某个 issue 时引用这些标签相关的 issue 往往能带来更深的理解甚至顺带解决其他相关问题。提交 PR 之前先搜索一遍相关标签是提高贡献质量的小技巧。提交 Pull Request 的完整工作流分支命名第一层上下文分支名是给任务提供上下文的第一机会。命名约定为TYPE-ISSUE_ID-DESCRIPTION强烈建议把相关 GitHub issue 编号与简短描述结合。如果没有对应 issue可以省略前缀但通常最好先创建 issue。例如bugfix-548-ensure-queries-execute-sequentially其中TYPE可以是refactor既不修复 bug 也不增加功能的代码改动feature新增功能的代码改动bugfix修复 bug 的代码改动docs仅文档改动ci与 CI 系统相关的改动提交信息规范总结要具描述性提交信息第一行应是对改动的简明总结不超过 50 个字符且易于理解正文提供更多细节解释你解决的问题、所做的改动以及背后的推理善用提交历史小而自包含的提交能让审查者仅通过阅读提交历史就理解整个 PR 的解决思路。创建 PR 的要点标题清晰且具有描述性简洁概括改动内容描述要详细解释改动推理、解决的问题及对代码库的影响。记住审查者并没有参与你的任务你需要解释为什么这样写代码提供背景在描述中关联相关 GitHub issue、PR、项目或第三方文档链接如有潜在缺陷或权衡也要提及请求审查向合适的人维护者、其他贡献者、熟悉该代码库的人发起审查请求。如何获得更好的审查Draft PR将仍在进行中的工作以草稿 PR 形式分享不急于合并或请求即时反馈积极回应反馈根据审查意见做出修改、回答问题或表达感谢使用 re-request review修改完成后提醒审查者重新查看利用 CODEOWNERS仓库的 CODEOWNERS 文件可以指定每个目录的负责人自动把 PR 分配给合适的人。完成变更团队积极使用评论线程进行针对性的详细讨论已解决的线程意味着对话已处理、问题已解决。评论线程由审查者负责 resolve作者只需回复说明已完成或婉拒PR 获批后团队会负责任地合并可能还会运行额外测试或检查以确保代码库仍然可用。标准流程总结Summary一个标准的 issue 解决流程如下克隆surrealdb仓库到本地git clone https://github.com/surrealdb/surrealdb可选安装 pre-commit 以在每次提交前运行检查pre-commit install创建新分支前先从 upstreammain拉取全部变更确保本地main是最新的git pull从main创建新分支例如bugfix-548-ensure-queries-execute-sequentiallygit checkout -b [the name of your branch]修改代码并确保所有代码变更格式正确cargo fmt完成后提交变更git add -A git commit -m [your commit message]推送到 GitHubgit push origin [the name of your branch]到你的 GitHub 仓库点击Compare pull request提交审查确保提交信息详细说明了改动内容与 PR 的目的点击Create pull request提交 PR等待代码审查与批准批准后合并 PR。除了 PR还有更多贡献方式PR 固然重要但还有许多其他参与方式博客与演讲撰写关于 SurrealDB 特性的博客、教程或演讲可以联系社区获得推广支持meetup 分享在 meetup 与会议上分享你的 SurrealDB 项目经验反馈、bug 与想法通过 GitHub Discussions、Discord 反馈使用体验通过 GitHub Issues 提交 bug文档改进提交文档更新、增强、设计或修复拼写/语法错误加入社区参与官方博客、开发者社区、Discord 等渠道的讨论。维护者专用发布流程如果你是有发布权限的维护者请参阅完整的发布流程文档。该文档涵盖如何执行 nightly、预发布pre-release、稳定版stable与补丁patch发布分支策略与版本管理带示例的分步操作说明常见问题的排查工作流架构与幂等性保证发布是仓库协作链条的最后一环理解它有助于贡献者把握版本节奏也有助于维护者标准化操作。【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SurrealDB 源码贡献指南：从环境搭建、代码规范到提交 PR 的完整工作流
SurrealDB 源码贡献指南从环境搭建、代码规范到提交 PR 的完整工作流【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb本篇指南面向希望向 SurrealDB 开源仓库贡献代码的开发者系统讲解如何搭建 Rust 开发环境、编译并启动数据库、编写与运行 SurrealQL 语言测试、遵守代码规范与 crate 组织约定以及从分支命名到合并的全套 Pull Request 工作流。读完本文你将能够在 SurrealDB 仓库中独立完成一次从代码修改、测试验证到提交合并的完整贡献闭环。参与开发的整体预期SurrealDB 是一个开源的、可扩展的分布式文档-图数据库document-graph database面向实时 Web 场景。仓库本身欢迎一切类型的贡献包括新功能、缺陷修复、文档改进、博客思路与工作坊内容。不过需要理解它的实际协作节奏绝大多数开发由内部工程团队规划并完成社区提交的 PR 通常需要等待一段时间才会被审查很多被合并的 PR 在收到审查前往往要经历数周。在提交之前可以先从两个维度评估自己的 PR 前景关键性cruciality这个改动有多重要规模size这个改动有多大由此形成两个典型极端关键且小巧例如一行代码的缺陷修复审查和合并都快不关键且庞大例如某个新功能的大规模实现依然有可能被合并但最好在动手前与团队进行充分讨论。一些较大的功能特性可能需要先走 RFC 流程。仓库根目录的 CONTRIBUTING.md 正是官方维护的贡献入口文档本文的所有内容均以它为主线展开。PR 长时间无人处理怎么办如果 PR 提交后迟迟没有动静可以参考以下建议观察当前活跃度查看最近更新的 PR 与活跃分支。如果这些 PR 普遍很大说明团队正在进行大规模开发工程师可能暂时没有精力审查新 PR主动讨论在 Discord 社区中适时提及你的 PR工程团队成员大多会关注与自己负责代码块相关的频道补充图片或视频视觉化的变更演示常常是吸引注意、说明 PR 价值的最有效方式。同时需要保持心理预期你的 PR 可能与一个尚未公开的新功能冲突。如果工程团队已经在开发类似功能出于保密原因甚至无法对 PR 发表评论这并非针对个人。代码规范格式化与 LintSurrealDB 使用 cargo 生态的标准命令来保证代码格式和静态检查的一致// 使用 nightly rustfmt 进行格式化仓库内 rust-toolchain.nightly 指定了具体版本 make fmt或 cargo make fmt cargo clippy需要说明的是根目录的 Makefile 本身是一个透传封装它会检查cargo-make是否可用然后把所有目标透传给cargo make任务定义在 Makefile.toml并进一步扩展 Makefile.ci.toml 与 Makefile.local.toml。因此实际执行make fmt前需要先安装cargo-makecargo install --no-default-features --force --locked cargo-make在仓库根目录的 Cargo.toml 中[workspace.lints.clippy]定义了一系列全局 Clippy 规则例如assigning_clones warn、redundant_clone warn、unwrap_used warn等所有 workspace 成员共享这些 lint 配置。值得注意的是unused_async allowSurrealDB 在 AST 解析器与执行器中依赖 async 函数来避免栈溢出所以这条 lint 被显式放行。提交代码前运行cargo clippy并通过这些规则是 CI 通过的第一步。仓库结构与 crate 组织SurrealDB 是一个 Cargo workspace根目录的 Cargo.toml 中通过members数组列出了全部 crate。官方在贡献指南中给出了清晰的 crate 分类主 cratecrate目录职责surrealdbsurrealdb/主 SDK crate提供客户端与嵌入式数据库功能surrealdb-coresurrealdb/core/核心数据库引擎、查询执行与存储层surrealdb-serversurrealdb/server/服务器实现提供 HTTP、WebSocket 与 gRPC 端点surrealdb-typessurrealdb/types/SurrealDB 值的公开类型被 SDK 与服务器共用surrealdb-types-derivesurrealdb/types/derive/用于派生SurrealValuetrait 的过程宏支撑 cratecrate目录职责surrealismsurrealism/用于执行用户自定义函数的 WebAssembly 运行时language-testslanguage-tests/基于.surql文件的 SurrealQL 语言测试框架fuzzfuzz/面向安全与稳定性的模糊测试profilingprofiling/性能剖析工具从源码可以看到workspace 还包含surrealdb/common、surrealdb/ast、surrealdb/token、surrealdb/parser、surrealml/core等 crate共同构成完整的分层架构。新增 crate 的规范贡献指南对新增 workspace crate 提出了明确要求以确保结构一致性1. 命名约定层级 crate对于层级 crate某个父 crate 下的子 cratecrate 名应通过把连字符替换为目录分隔符来匹配目录结构crate 名为surrealdb-types-derive→ 位于surrealdb/types/derive/crate 名为surrealdb-core→ 位于surrealdb/core/对于根级 crate工具、测试等则允许使用连字符crate 名为language-tests→ 位于language-tests/2. 位置根据用途放置 crate核心数据库功能 → 放在surrealdb/下工具与测试 → 放在根级3. 更新 workspace在根 Cargo.toml 的members数组中加入 crate 路径[workspace] members [ # ... existing members ... your-new-crate, ]4. 声明 workspace 依赖如果该 crate 会被其他 workspace 成员引用还需要加入[workspace.dependencies][workspace.dependencies] # 预发布版本例如 -alpha、-beta、-rc your-new-crate { version x.y.z-prerelease, path path/to/your-new-crate } # 或正式发布版本 your-new-crate { version x.y, path path/to/your-new-crate }仓库现有配置正是这一规范的直接体现例如 Cargo.toml 中surrealdb-core { version 3.1.0-alpha, path surrealdb/core, default-features false }与ast { package surrealdb-ast, path surrealdb/ast }都遵循了这套模式。从源码搭建开发环境设置开发环境有两种途径一是使用 Nix 包管理器自动管理 C/C 依赖与工具链二是手动安装依赖并确保已安装rustup。注意以下指令面向的是贡献者代码维护者的开发环境如果只想日常使用 SurrealDB应参考官方安装与集成文档而不是从源码构建。doc/BUILDING.md 详细记录了在 macOS、Ubuntu、Debian、Windows 等多个平台上的编译步骤包括交叉编译到aarch64-unknown-linux-gnu、x86_64-unknown-linux-gnu等目标并明确指出 Windows 编译需要管理员权限、部分交叉编译目标如 Windows GNU、Linux Musl当前尚不能成功构建。如果遇到环境问题请优先查阅该文档。基础环境# 提示选择时使用默认的 stable 发布通道 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh git clone gitgithub.com:[YOUR_FORK_HERE]/surrealdb.git cd surrealdb cargo run -- helpcargo run -- help用于验证编译链路与 CLI 入口是否正常。仓库的src/main.rs是根包surreal见 Cargo.toml 的[package]段的二进制入口。启动 SurrealDB 服务器为了快速启动一个本地数据库实例可以用--no-default-features显式挑选最小特性集只启用内存存储、HTTP 与脚本能力cargo run --no-default-features --features \ storage-mem,http,scripting -- start --log trace \ --user root --pass root memory这条命令同时展示了仓库 Cargo.toml 中特性开关的用法storage-mem内存存储、httpHTTP API与scripting脚本支持都是顶层 crate 定义的 feature它们分别透传到surrealdb-server的同名 feature。默认特性集还包含storage-surrealkv、storage-rocksdb、storage-tikv、graphql、surrealism、cli等。开发时监听代码变更利用cargo watch在文件变化时自动重新编译并重启cargo watch -x run --no-default-features \ --features storage-mem,http,scripting -- start \ --log trace --user root --pass root memory修改监听地址与端口默认情况下 SurrealDB 在本地 8000 端口运行。需要变更监听地址或端口时使用--bindcargo run --no-default-features --features \ storage-mem,http,scripting -- start --log trace \ --user root --pass root --bind 0.0.0.0:9000 memory运行全部测试cargo test使用 language-tests 编写 SurrealQL 语言测试许多测试已经迁移到 language-tests crate它允许仅用 SurrealQL 配合一个 TOML 配置注释来创建测试无需编写任何 Rust 代码。这也是当前仓库最主要的新测试提交方式官方贡献指南给出了完整示例/** # The env map configures the general environment of the test [env] namespace false database false auth { level owner } signin {} signup {} [test] # Sets the reason behind this test; what exactly this test is testing. reason Ensure multi line comments are properly parsed as toml. # Whether to actually run this file, some files might only be used as an import, # setting this to false disables running that test. run true # set the expected result for this test # Can also be a plain array i.e. results [foo,{ error true }] [[test.results]] # the first result should be foo value foo [[test.results]] # the second result should be an error. # You can error to a string for an error test, then the test will ensure that # the error has the same text. Otherwise it will just check for an error without # checking its value. error true */ // The actual queries tested in the test. RETURN foo; 1 1;该 TOML 配置写在/** */或//!特殊注释中运行测试时所有测试注释会被拼接后解析为 TOML。仓库中真实的测试文件例如 language-tests/tests/self_tests/simple_matching_expression.surql/** [test] [[test.results]] match true */ 1;可见[[test.results]]支持value、error、match等多种断言方式。language-tests CLI 的用法language-tests/README.md 详细说明了测试运行工具# 在 language-tests 目录下运行全部测试第二个 run 是子命令 cargo run run # 只运行路径中包含 foo 的测试过滤器 cargo run run foo # 自动为未指定结果的测试填充期望输出 cargo run run --results accept # 覆盖现有结果需谨慎使用仅当确认新结果有效时 cargo run run --results overwrite还支持通过--backend指定存储引擎运行测试memory或mem默认内存存储引擎测试最快rocksdbRocksDB 嵌入式引擎需backend-rocksdbfeaturesurrealkvSurrealKV 文件存储引擎需backend-surrealkvfeaturetikvTiKV 分布式引擎需backend-tikvfeature 与运行中的 TiKV 集群cargo run --features backend-rocksdb run --backend rocksdb在测试配置的[test]与[env]表中还支持wip已知问题或进行中功能失败仅告警不阻断、version语义化版本要求、imports前置导入文件、timeout、backend、versionedMVCC 版本化、auth、signin/signup、capabilities、planner-strategy新/旧执行器策略等丰富的控制键默认值均为安全的保守选择。构建生产级二进制调试阶段完成后构建生产可用的 SurrealDB 二进制cargo build --release根 Cargo.toml 的[profile.release]配置了lto true、codegen-units 1、opt-level 3、panic abort、strip true这意味着 release 构建会经过完整 LTO 并剥离符号体积与性能都面向生产优化。若要为特定平台交叉编译参考 doc/BUILDING.md 中cargo build --release --locked --target target-triple的用法。性能与可扩展性考量SurrealDB 被设计为既要快又要能扩展既支持单节点部署也支持分布式集群分布式模式下基于 TiKV。同时它被设计运行在不同环境、不同配置与不同规模下。因此在贡献代码时需要特别关注以下指标SurrealDB 启动时间查询执行时间查询响应时间查询吞吐量每秒请求数Requests per secondWebSocket 连接数网络使用量内存使用量仓库中与这些指标直接对应的工具包括 profiling/性能剖析与 surrealdb/benchesCriterion 基准测试覆盖 array、hash trie、HNSW 索引、解析器与执行器等。当你的改动涉及存储层、索引或执行器时运行相关基准是很有说服力的佐证。安全与隐私SurrealDB 团队非常重视代码、软件与云平台的安全。如果你认为发现了安全漏洞请立即通过邮件 securitysurrealdb.com 报告而不是在 GitHub 上公开创建 issue。报告时请附上surreal version命令输出的版本标识符漏洞可利用方式的详细说明。在开发过程中也请遵循行业最佳实践与标准。外部依赖管理请避免未经团队讨论就引入新的依赖。新依赖虽然可能带来便利但也会引入新的安全与隐私问题、增加复杂度并影响最终 Docker 镜像的体积。添加依赖应当对产品有至关重要的价值同时把风险降到最低。仓库根目录的 supply-chain/ 目录包含audits.toml、config.toml、imports.lock与 deny.toml 体现了这一治理策略依赖准入是受控流程而不是随手添加。Revisioned structs 与 revision-lockSurrealDB 使用Revision机制来管理内部类型的版本如果这些类型的定义发生变更必须同步更新对应的版本号。为追踪这些版本仓库使用revision-lock生成锁文件。根目录的 revision.lock 就是一个实际的锁文件示例例如AccessDefinition:1(surrealdb/core/src/catalog/schema/access.rs)(3072791384) EventDefinition:3(surrealdb/core/src/catalog/schema/event.rs)(3537595141) Relation:2(surrealdb/core/src/catalog/table.rs)(3166613370)每行记录了类型名、当前修订版本号、定义位置与哈希校验。如果 CI 中的 revision.lock 检查失败安装并运行校验工具即可cargo install revision-lock revision-lock这条命令会根据源码中的#[revision]派生宏重新生成/校验锁文件。修改了任何被 Revision 管理的类型如新增字段、改变序列化格式却不同步更新版本号就是这类 CI 失败的典型原因。善用 issue 的 topic 标签SurrealDB 的 GitHub issue 带有以topic:开头的标签例如topic:typing、topic:record ids。在解决某个 issue 时引用这些标签相关的 issue 往往能带来更深的理解甚至顺带解决其他相关问题。提交 PR 之前先搜索一遍相关标签是提高贡献质量的小技巧。提交 Pull Request 的完整工作流分支命名第一层上下文分支名是给任务提供上下文的第一机会。命名约定为TYPE-ISSUE_ID-DESCRIPTION强烈建议把相关 GitHub issue 编号与简短描述结合。如果没有对应 issue可以省略前缀但通常最好先创建 issue。例如bugfix-548-ensure-queries-execute-sequentially其中TYPE可以是refactor既不修复 bug 也不增加功能的代码改动feature新增功能的代码改动bugfix修复 bug 的代码改动docs仅文档改动ci与 CI 系统相关的改动提交信息规范总结要具描述性提交信息第一行应是对改动的简明总结不超过 50 个字符且易于理解正文提供更多细节解释你解决的问题、所做的改动以及背后的推理善用提交历史小而自包含的提交能让审查者仅通过阅读提交历史就理解整个 PR 的解决思路。创建 PR 的要点标题清晰且具有描述性简洁概括改动内容描述要详细解释改动推理、解决的问题及对代码库的影响。记住审查者并没有参与你的任务你需要解释为什么这样写代码提供背景在描述中关联相关 GitHub issue、PR、项目或第三方文档链接如有潜在缺陷或权衡也要提及请求审查向合适的人维护者、其他贡献者、熟悉该代码库的人发起审查请求。如何获得更好的审查Draft PR将仍在进行中的工作以草稿 PR 形式分享不急于合并或请求即时反馈积极回应反馈根据审查意见做出修改、回答问题或表达感谢使用 re-request review修改完成后提醒审查者重新查看利用 CODEOWNERS仓库的 CODEOWNERS 文件可以指定每个目录的负责人自动把 PR 分配给合适的人。完成变更团队积极使用评论线程进行针对性的详细讨论已解决的线程意味着对话已处理、问题已解决。评论线程由审查者负责 resolve作者只需回复说明已完成或婉拒PR 获批后团队会负责任地合并可能还会运行额外测试或检查以确保代码库仍然可用。标准流程总结Summary一个标准的 issue 解决流程如下克隆surrealdb仓库到本地git clone https://github.com/surrealdb/surrealdb可选安装 pre-commit 以在每次提交前运行检查pre-commit install创建新分支前先从 upstreammain拉取全部变更确保本地main是最新的git pull从main创建新分支例如bugfix-548-ensure-queries-execute-sequentiallygit checkout -b [the name of your branch]修改代码并确保所有代码变更格式正确cargo fmt完成后提交变更git add -A git commit -m [your commit message]推送到 GitHubgit push origin [the name of your branch]到你的 GitHub 仓库点击Compare pull request提交审查确保提交信息详细说明了改动内容与 PR 的目的点击Create pull request提交 PR等待代码审查与批准批准后合并 PR。除了 PR还有更多贡献方式PR 固然重要但还有许多其他参与方式博客与演讲撰写关于 SurrealDB 特性的博客、教程或演讲可以联系社区获得推广支持meetup 分享在 meetup 与会议上分享你的 SurrealDB 项目经验反馈、bug 与想法通过 GitHub Discussions、Discord 反馈使用体验通过 GitHub Issues 提交 bug文档改进提交文档更新、增强、设计或修复拼写/语法错误加入社区参与官方博客、开发者社区、Discord 等渠道的讨论。维护者专用发布流程如果你是有发布权限的维护者请参阅完整的发布流程文档。该文档涵盖如何执行 nightly、预发布pre-release、稳定版stable与补丁patch发布分支策略与版本管理带示例的分步操作说明常见问题的排查工作流架构与幂等性保证发布是仓库协作链条的最后一环理解它有助于贡献者把握版本节奏也有助于维护者标准化操作。【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考