数据库图数据库分布式数据库后端【免费下载链接】dgraphhigh-performance graph database for real-time use cases项目地址https://gitcode.com/gh_mirrors/dg/dgraph点击查看免费下载本篇指南以 Dgraph 仓库的 CONTRIBUTING.md 为骨架完整讲解如何从源码搭建 Dgraph 开发环境、编译 dgraph 二进制与本地 Docker 镜像、理解其分层测试体系unit / integration / integration2 / upgrade / fuzz并落实提交 PR 时必须遵守的编码规范与许可证要求。读完本文你将能够独立完成一次从git clone到make test、再到提交合格 PR 的完整开发流程并对 Dgraph 背后的构建与测试机制有源码级的理解。快速开始先认识项目Dgraph 是一个面向实时场景的高性能图数据库。开始贡献之前官方建议先完成两件事阅读官方入门指南理解 Dgraph 的核心概念图模型、DQL 查询、GraphQL 集成完成一次 Dgraph 交互式教程tour实际操作一遍查询与变更。这两步是理解仓库代码dql/、query/、edgraph/ 等核心包的认知基础。而本篇接下来聚焦的是仓库内可以直接验证的开发链路环境搭建 → proto 代码生成 → 编译 → 镜像 → 测试 → 提交规范。开发环境搭建前置依赖根据 CONTRIBUTING.md 的 Prerequisites 章节参与 Dgraph 开发需要以下工具依赖用途安装说明Git获取与管理源码可能已随系统安装或通过包管理器安装Make驱动构建与测试流程可能已随系统安装或通过包管理器安装Docker Docker Compose集成测试的集群运行环境独立安装需保证内存资源充足Go 1.27.0 及以上编译与运行测试从 Go 官方安装包安装trunk代码风格检查CI 复用Dgraph 的 CI 用 trunk 做 lint本地安装可节省提交返工时间关于 Go 版本仓库的 go.mod 中声明了go 1.27.0而依赖检查脚本 t/scripts/check-deps-go.sh 会直接从go.mod解析所需版本并与本机go version比对版本过低会直接报错。这意味着版本要求以仓库 go.mod 为准安装后无需手工记忆版本号。从源码克隆并初始化git clone Dgraph 仓库地址 cd ./dgraph make setup # 自动安装工具依赖gotestsum、ack 等 make install # 构建并安装 dgraph 二进制执行后源码位于$GOPATH/src/...对应的 Git 仓库中编译出的二进制则被安装到$GOPATH/bin若GOBIN已设置则为$GOBIN见 dgraph/Makefile。make setup的实际行为是调用make check-deps AUTO_INSTALLtrue见 Makefile它会依次运行 t/Makefile 中声明的依赖检查目标check-deps-go解析 go.mod 中的 Go 版本并校验check-deps-docker校验 Docker 与 Docker Composecheck-deps-gotestsum安装/校验测试输出汇总工具 gotestsumcheck-deps-ack安装/校验ackt/ 测试框架用于按名称定位测试函数check-deps-cross-compiler在非 Linux 主机上校验交叉编译工具链check-deps-protocLinux 上校验 protoc 编译器check-docker-available-memory检查 Docker 可用内存低于 8GB 会告警macOS 上可自动修复。这套脚本体系让首次环境搭建基本做到一条命令完成。可选从源码搭建 BadgerDgraph 的存储层依赖 BadgerKV 引擎在仓库中通过github.com/dgraph-io/badger/v4 v4.9.4引入见 go.mod。Dgraph 仓库自带 vendor 版本的 Badger如果只开发 Dgraph无需单独检出 Badger 仓库但如果你想同时为 Badger 贡献代码则需要单独检出go get -t -v github.com/dgraph-io/badger执行后 Badger 源码会位于$GOPATH/src/...对应的 Git 仓库中。Protocol Buffers 与 gRPC 代码生成Dgraph 使用 Protocol Buffers。如果你修改了.proto文件就必须重新编译生成对应的 Go 代码。安装 protoc 编译器编译 proto 文件需要protoc版本 3.0.0 及以上。在 Linux 上也可以通过包管理器快速安装sudo apt update sudo apt install -y protobuf-compiler安装 gogo protobuf 插件Dgraph 使用 gogo protobuf 体系。要获取 gogo 的 protoc 编译器插件go get -u github.com/gogo/protobuf/protoc-gen-gofast注意从 protos/Makefile 的check目标可以看到当前仓库实际还会安装protoc-gen-gov1.31.0与protoc-gen-go-grpcv1.3.0并依赖depcheck.sh校验依赖版本保证生成代码与 go.mod 中的依赖保持一致。重新生成 .pb.go在包含.proto文件的目录下执行cd protos make regenerate该目标protos/Makefile的完整流程值得展开tidy-deps执行go mod tidy -v整理依赖copy-protos从dgo客户端 API与badger模块的 go.mod 路径中拷贝api.proto与badgerpb.proto到临时目录供protoc的--proto_path引用check运行depcheck.sh并安装所需插件protoc 编译按--proto_path组合含 dgo、badger 的 proto 路径生成--go_outpb与--go-grpc_outpbpatch-pb执行 patch_pb.sh 对生成的代码做补丁处理。在非 Linux 平台上regenerate会自动封装进 Docker 容器golang:1.27.0镜像内执行避免本机缺少 protoc 的环境差异见 protos/Makefile。编译完成后会生成所需的.pb.go文件仓库中对应的产物为 protos/pb/pb.pb.go 与 protos/pb/pb_grpc.pb.go。此外 protos/pb/sensitive.go 中定义了涉及加密等敏感字段的处理逻辑属于生成代码之上的定制层。构建 Dgraph 二进制构建 Dgraph 有两条命令区别在于产物位置与是否携带版本信息make dgraph在./dgraph/dgraph生成二进制对应 Makefile 的dgraph目标实际委托dgraph/Makefile执行make install将二进制安装到$GOPATH/bin/dgraph若未在 PATH 中需手动添加$GOPATH/bin。两条命令都会通过-ldflags把版本信息注入二进制dgraph/Makefile注入的构建期变量包括x.dgraphVersion版本号默认取自git describe --always --tags发布流水线可通过DGRAPH_VERSION覆盖x.dgraphCodename代号默认dgraphx.gitBranch当前分支x.lastCommitSHA最近提交的短 SHAx.lastCommitTime最近提交时间。这些变量的宿主定义位于 buildvars/buildvars.go命令行工具为 buildvars/cmd/buildvars/buildvars.godgraph version命令输出的正是这些注入值。一个典型的构建与验证过程如下$ make install Installing Dgraph... Commit SHA256: 15839b156e9920ca2c4ab718e1e73b6637b8ecec Old SHA256: 596e362ede7466a2569d19ded91241e457e665ada785d05a902af2c6f2cea508 Installed dgraph to /Users/homedir/go/bin/dgraph $ dgraph version Dgraph version : v24.0.2-103-g15839b156 Dgraph codename : dgraph Dgraph SHA-256 : 9ce738cd055dfebdef5d68b2a49ea4e062e597799498607dbd1bb618d48861a6 Commit SHA-1 : 15839b156 Commit timestamp : 2025-01-10 17:56:49 -0500 Branch : username/some-branch-that-im-on Go version : go1.22.12 jemalloc enabled : true构建的底层细节jemalloc 集成在 Linux/macOS 上默认启用jemalloc构建标签dgraph/Makefile用于优化内存分配性能。若系统未安装 jemallocmake会从官方发布页下载 5.3.1 源码并本地编译安装dgraph/Makefile。调试构建设置BUILD_DEBUG1会追加-gcflagsall-N -l禁用优化便于 dlv 调试设置BUILD_RACE1会追加-race开启竞态检测。fork 友好make install特意用go build -o $(INSTALL_TARGET)而非go install以便BIN变量被重命名如 fork 出别的二进制名时仍能正确输出文件名dgraph/Makefile。在非 Linux 机器上构建非 Linux 平台主要是 macOS的构建说明见 t/README.md 与 Makefile由于 Docker 容器内运行的是 Linux 二进制make install在 macOS 上会自动额外交叉编译一份Linux 二进制到$GOPATH/linux_$(GOHOSTARCH)/dgraph并依赖对应架构的交叉编译器aarch64-unknown-linux-gnu-gcc/x86_64-unknown-linux-gnu-gcc。Docker Compose 文件通过${LINUX_GOBIN}环境变量自动定位这份二进制因此 macOS 用户改完代码只需重新make install无需手动搬运二进制。构建本地 Docker 镜像make image-local该命令Makefile等价于local-image目标其流程为构建 Linux 版 dgraph 二进制非 Linux 主机走交叉编译将二进制移入linux/目录用 contrib/Dockerfile 构建镜像标签为dgraph/dgraph:local清理临时目录。构建完成后你就可以在本地 Docker 环境中直接使用该镜像测试改动例如配合 dgraph/docker-compose.yml 拉起集群。如果你需要发布带版本号的镜像可使用make docker-image标签为dgraph/dgraph:$(DGRAPH_VERSION)默认local或make docker-image-standalone一并构建 standalone 变体依赖 contrib/standalone 的 Makefile用于无外置依赖的单机部署镜像。测试Dgraph 的分层测试体系Dgraph 拥有复杂精细原文措辞的测试框架与广泛的覆盖率仓库内包含超过 200 个测试文件、2000 个测试/基准函数TESTING.md。完整测试跑一遍可能需要数小时因此仓库在标准 Go 测试之上自研了一个 Go 编写的测试运行器 t/t.go提供比标准框架更强的控制力与灵活性。常用测试命令# 首次使用安装工具依赖 make setup # 默认测试约 30 分钟integration 套件 integration2 make test # 跑完仓库内所有测试 make test-all # 按类型运行 make test-unit # 纯单元测试——无需 Docker、无构建标签 make test-integration # 通过 t/ 运行器 Docker 的集成测试 make test-integration-heavy # 所有重型测试systest-heavy ldbc load make test-integration2 # 基于 dgraphtest 的 Integration2 测试 make test-upgrade # 升级测试 # 通过变量精细控制 make test TAGSintegration2 PKGsystest/vector make test SUITEall # 运行 t/ 运行器的全部套件 make test TIMEOUT90m # 覆盖单包超时默认 30m运行make help可查看全部可用目标与变量。完整的测试指南见仓库根目录的 TESTING.md。make test 的控制变量结合 Makefile 与make help输出的说明make test支持以下变量优先级TAGS FUZZ SUITE 默认值变量作用示例SUITE选择 t/ 运行器的测试套件make test SUITEintegrationTAGSGo 构建标签绕过 t/ 运行器make test TAGSintegration2PKG限定具体包make test PKGsystest/exportTEST运行指定测试函数make test TESTTestGQLSchemaTIMEOUT单包测试超时默认 30mmake test TIMEOUT90mFUZZ启用 fuzz 测试make test FUZZ1FUZZTIME每个包的 fuzz 时长默认 300smake test FUZZ1 FUZZTIME60s不传任何变量时make test默认先跑 t/ 运行器的integration套件再跑带integration2标签的 Go 测试。测试类型与构建标签Dgraph 用 Go 构建标签把成本较高、依赖集群的测试从默认的go test ./...中隔离出去TESTING.md类型构建标签说明示例文件单元测试无单函数/组件隔离测试无需集群速度快dql/dql_test.go、types/value_test.go、schema/parse_test.go集成测试//go:build integration组件交互与全系统工作流需要 Docker 集群acl/acl_test.go、worker/worker_test.go、query/query0_test.goUpgrade 测试//go:build upgrade跨版本升级与迁移场景acl/upgrade_test.go、worker/upgrade_test.go基准测试函数名Benchmark前缀性能测试与优化query/benchmark_test.go、dql/bench_test.goFuzz 测试-fuzzFuzz随机输入探测解析器崩溃dql/parser_fuzz_test.go其中集成、升级、基准测试需要运行中的 Dgraph 集群Docker分为两类驱动方式t/ 运行器驱动以及dgraphtest包通过 Docker Go client 对本地集群做编程式控制。新测试优先使用dgraphtest集群管理与dgraphapi客户端操作testutil仅保留向后兼容TESTING.md。t/ 运行器详解测试框架的入口是 t/t.go构建后得到t可执行文件。它的关键设计参数包括默认拉起 3 个 Zero 节点与 6 个 Alpha 节点NumZeroNodes/NumAlphaNodest/t.go并通过 Docker Compose 管理集群生命周期。常用参数如下参数作用--suiteX选择套件all、ldbc、load、unit、integration、systest、systest-baseline、systest-heavy、vector、core可逗号组合--pkgX只运行指定包可逗号多选--testX只运行指定测试函数借助 ack 定位--timeoutX单包超时如 60m、2h默认 30m--race下为 180m-jN并发创建多少个集群默认 1资源有限时勿调高--keep测试结束后保留集群容器便于故障分析-r清理所有测试容器--prefixX复用已存在的集群前缀不再新起集群--dry仅列出将要执行的包不真正运行--skip-slow跳过已知的慢包各套件的内容划分详见 TESTING.mdunit是纯单元测试integration是默认套件除重型外的全部集成测试core聚焦查询、变更、schema、GraphQL e2e、ACL、TLS、workersystest为系统级集成测试含 baseline 与 heavyvector面向向量索引与 HNSW 相似度检索ldbc是 LDBC 基准查询套件load覆盖 21million、1million、bulk_live、bgindex 等重型数据加载场景all则是 t/ 运行器内的全部包。Docker Compose 发现机制运行器先在测试包目录内寻找docker-compose.yml例如 systest/export/docker-compose.yml找不到则逐级向上最终回退到仓库根级默认配置 dgraph/docker-compose.yml。因此需要特殊集群拓扑的测试应在自己的测试目录内自带 compose 文件。测试写作规范摘要如果为改动补充测试仓库约定如下详见 TESTING.md命名函数以Test开头、camelCase 且描述性如TestVectorIndexRebuilding文件名以_test.go结尾并匹配源文件schema.go→schema_test.go表驱动测试一个测试函数内用结构体切片覆盖多个用例并用t.Run建立子测试失败信息清晰断言默认使用require.*失败立即终止仅在极少数场景用assert.*资源清理用defert.Cleanup保证失败时也释放集群与客户端连接辅助函数标记t.Helper()让失败定位到真实调用行禁止反模式不用time.Sleep做同步改用轮询/显式等待不共享可变全局状态不依赖测试执行顺序不忽略错误返回值并行化t.Parallel()仅用于不共享资源的测试集成测试与改全局状态的测试禁用共享集群用testify/suiteSetupSuite/SetupTest/TearDownTest等钩子同一套测试方法可同时跑integration与upgrade两种模式典型示例见 acl/integration_test.go 与 systest/plugin 的集成升级双套件。提交贡献的规范基本原则在多年构建大规模可扩展系统的经验中Dgraph 团队将尽可能追求简单视为构建健壮系统的唯一途径——无论是设计、编码还是重写一个昨天才辛苦完成、今天看来可以更简洁的模块。据此贡献 PR 时需要遵循欢迎 Pull Request前提是愿意付出努力满足指南。Fork 仓库后请针对main分支创建 PR并仔细遵循 PR 模板中的说明做好准备在官方公开文档中记录你的新增/变更如适用追求清晰、易读、可维护的代码功能采用简单、最小化的实现方式与 Go 的哲学一致新功能必须附带通过的单元测试适当时还要有集成测试重构现有代码提升性能、可读性或可测试性优先于新增功能不要向当前用不到的模块添加函数除非它明确服务于已规划的功能不要交付半成品功能——那种需要大幅改动才能完整工作的功能像躲避癌症一样避免技术债务离开时让代码比你进入时更干净。代码风格遵循 Go Code Review 注释规范提交前至少用go fmt格式化代码理想情况下使用trunk因为 CI 会对代码运行trunk检查看到任何明显违反风格指南的代码可直接修复并提交 PR无需请求许可避免不必要的垂直留白用判断力或参考 code review 意见代码与注释换行宽度不超过 120 字符除非这样做会降低可读性。许可证头每个新源文件必须以许可证头开头。Dgraph、Badger 以及 Dgraph 客户端dgo、dgraph-js、pydgraph、dgraph4j大部分采用 Apache 2.0 许可证/* * SPDX-FileCopyrightText: © 2017-2026 Istari Digital, Inc. * SPDX-License-Identifier: Apache-2.0 */仓库内几乎所有 Go 源文件如 Makefile、t/t.go都携带了同样的 SPDX 头新增文件照此办理即可。值得注意的是Dgraph 的许可证是混合的dgraph version输出明确写着 Licensed variously under the Apache Public License 2.0 and Dgraph Community License见 LICENSE.txt社区版二进制与商业版Enterprise在核心模块许可上存在差异贡献前应留意该条款。签名提交Signed Commits签名提交有助于验证贡献者的真实性。Dgraph 使用签名提交并优先推荐但不强制——对于打算长期、规律性贡献的开发者这是推荐的一步。可按 GPG 签名提交的标准流程生成并配置 GPG 密钥然后在git commit -S时启用签名。结语从git clone、make setup、make install构建出带版本信息的二进制到make image-local产出本地 Docker 镜像再到用 t/ 运行器与 Go 构建标签驱动分层测试最后以规范的代码风格、SPDX 许可证头与签名提交交付 PR——这条完整的开发链路既是 Dgraph 仓库 CONTRIBUTING.md 的文档骨架也被 Makefile、dgraph/Makefile、protos/Makefile、t/t.go 与 TESTING.md 等源码与配置文件逐一印证。对于希望深入参与 Dgraph 开发的工程师而言掌握这条链路不仅是贡献的门槛也是理解一个大型 Go 图数据库如何构建、测试与演进的绝佳入口。赞分享数据库图数据库分布式数据库后端【免费下载链接】dgraphhigh-performance graph database for real-time use cases项目地址https://gitcode.com/gh_mirrors/dg/dgraph点击查看免费下载相关推荐Thumbor 源码开发与贡献指南环境搭建、测试运行与代码规范全解析Thumbor 源码开发与贡献指南环境搭建、测试运行与代码规范全解析 Thumbor 是 globo.com 开源的智能图片缩略图服务项目核心代码见 thu后端图像处理计算机视觉date-fns 贡献指南全解析从环境搭建、测试体系到代码风格与文档规范date fns 贡献指南全解析从环境搭建、测试体系到代码风格与文档规范 date fns 是一套面向浏览器与 Node.js 的现代 JavaScript前端后端Instructor 贡献指南环境搭建、代码规范、测试与发布流程全解析Instructor 贡献指南环境搭建、代码规范、测试与发布流程全解析 本指南是 Instructor面向 LLM 的 Pydantic 结构化输出库的完网页爬虫后端AI 应用上一篇Home Assistant 配置完全指南YAML 文件编写与 UI 界面设置下一篇3个技巧让电脑风扇安静又高效FanControl完全掌控指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考