后端网络【免费下载链接】pumaA Ruby/Rack web server built for parallelism项目地址https://gitcode.com/gh_mirrors/pu/puma点击查看免费下载Puma 是一个面向 Ruby/Rack 应用、专为并行场景设计的多线程 HTTP/1.1 服务器它在 MRICRuby、JRuby、TruffleRuby 上均有对应的原生扩展实现。本文以仓库根目录的 CONTRIBUTING.md 为主线完整梳理贡献者从搭建本地开发环境、编译原生扩展、运行测试到提交 PR、复现 Bug 的完整工作流并穿插 Rakefile、测试辅助脚本、测试用例与 Dockerfile 等仓库源码证据帮助第一次接触系统级 Ruby 项目的开发者快速建立可落地的贡献路径。一、参与 Puma 的方式不止写代码贡献不限于提交代码。Puma 项目欢迎以下几类参与方式提交 [bug 报告]或[功能请求]把问题描述清楚本身就是贡献为已有的 bug 报告补充可复现步骤见下文复现 Bug 的标准流程一节审阅 [pull request]并在本地实际测试改动编写或修订[文档]仓库的 docs 目录下还有大量待完善的主题提升测试覆盖率修复可复现的 bug 或实现新功能。对于初次接触开源项目的人Puma 也明确表示欢迎Newbies welcome!。特别地Puma 明确不实行 issue 认领机制——不存在被占用的 issue只要 issue 列表里存在未关闭的 issue就可以直接开始动手写出几行代码后就可以提交 draft PR维护者会在草稿 PR 基础上提供帮助。对于首次贡献者可以优先关注带有contrib-wanted标签的 issueneeds-repro标签表示该 issue 缺少复现步骤是最容易切入的起点之一。从源码结构看Puma 的核心代码分布在 lib/puma纯 Ruby 部分、ext/puma_http11C 与 Java 原生扩展和 test测试套件三个主要区域贡献者可以根据自身技能选择切入深度——即使只写 Ruby 测试也能覆盖大量改动。二、搭建本地开发环境2.1 克隆仓库git clone gitgithub.com:puma/puma.git cd puma2.2 安装 Ragel生成解析器代码的前提Puma 的 HTTP/1.1 解析器是用 Ragel 状态机编译器编写的Ragel 7.0.0.9必须先安装它才能生成扩展代码。仓库中的 Rakefile 定义了对应的ragel任务会从.rl源文件生成 C 与 Java 两份产物ext/puma_http11/http11_parser.c←ext/puma_http11/http11_parser.rlext/puma_http11/org/jruby/puma/Http11Parser.java←ext/puma_http11/http11_parser.java.rl公共规则放在 ext/puma_http11/http11_parser_common.rl供两个平台共享。各平台安装方式macOSbrew install ragelLinuxDebian/Ubuntu 系apt-get install ragelWindowsRuby 2.5使用 RubyInstaller 的 devkitridk exec pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-ragel2.3 安装 Ruby 依赖bundle installGemfile 通过gemspec引入 puma.gemspec 声明的依赖运行期核心依赖为nio4r ~ 2.0并额外引入开发依赖rake-compiler编译扩展、minitest系列测试框架、rubocop静态检查、m单测运行器、rack ~ 3.2与rackup ~ 2.3等。若设置环境变量PUMA_CI_RACKrack2则会改用 Rack 2.2 与 rackup 1.0 来测试旧版兼容路径。2.4 编译原生扩展运行本地 Puma 必须先编译原生扩展。执行testrake 任务时会自动完成编译但如果还没跑过测试、想直接启动 Puma则需要手动执行Ubuntu、macOS 等bundle exec rake compileWindowsbundle exec rake -rdevkit compile编译行为在 Rakefile 中按平台分派非 JRuby 环境使用Rake::ExtensionTask编译 C 扩展puma_http11JRuby 环境则使用Rake::JavaExtensionTask编译 Java 版本并可通过PUMA_DISABLE_SSL环境变量决定是否排除MiniSSL.java。平台检测逻辑位于 lib/puma/detect.rb其中Puma.jruby?、Puma.windows?、Puma.mri?、Puma.forkable?等判定会贯穿整个构建与测试流程。2.5 启动本地 Puma 验证环境编译完成后即可直接运行仓库自带的示例 Rack 应用bundle exec bin/puma test/rackup/hello.ru # -or- bundle exec ruby -Ilib bin/puma test/rackup/hello.rutest/rackup/hello.ru 是一个极简 Rack 应用返回text/plain的Hello World可用于快速确认扩展与服务器能正常工作。仓库 bin 目录下提供puma、pumactl与puma-wild三个可执行脚本。如果希望在现有项目里引用本地副本可以在项目的Gemfile中写gem puma, path: /path/to/local/pumaBundler 的path选项支持直接指向本地 gem 目录改完 Puma 源码即可在宿主项目中即时生效。三、运行测试从全量到单测3.1 全量检查与仅跑测试# rubocop 测试 bundle exec rake # 仅测试套件 bundle exec rake testbundle exec rake的默认任务是[:rubocop, :test]。需要注意test任务本身不是独立可跑的在 MRI 上它会先触发compile_for_test静默编译原生扩展在 JRuby 上则先执行:java任务因此首次运行前无需手动编译。3.2 运行单个测试文件bundle exec ruby test/test_binder.rb也可以用m这个测试运行器获得更精细的控制# 单个文件 bundle exec m test/test_binder.rb # 单条用例按行号定位 bundle exec m test/test_binder.rb:37 # 单条用例 指定 5 秒用例超时 TEST_CASE_TIMEOUT5 bundle exec m test/test_binder.rb:37m已列入 Gemfile 的开发依赖开箱即用。3.3 调试信息与辅助运行器如果希望了解更多构建细节扩展编译过程、SSL 版本、本地 Ruby 版本等可以开启调试环境变量PUMA_TEST_DEBUG1 bundle exec rake test在 Rakefile 中PUMA_TEST_DEBUG会把Rake::FileUtilsExt.verbose_flag置为 true让编译等文件操作输出详细日志。仓库还附带一个独立的测试辅助运行器test/runner见 test/runner 文件头注释它默认运行全部test_*.rb支持 glob 与多文件参数并提供了额外选项test/runner -v test_puma_server.rb test/runner -v test_puma_server* # glob 需视 shell 决定是否加引号 test/runner -v test_integration_*.rb # macOS 上建议加引号 test/runner -v test_integration_cluster:test_integration_single其中-v显示测试详情、-w在加载测试前开启$VERBOSE警告收集模式、-z开启警告但取消实际执行。多文件之间用系统路径分隔符:或;连接。3.4 文件数限制too many open filesPuma 的测试套件会打开大量 socket可能超出操作系统默认的文件描述符上限导致too many open files报错。建议先检查当前会话限制必要时提高# 查看当前 soft limit ulimit -S -n # 为当前会话临时调高 ulimit -S -n value实践中 4000 及以上的值通常够用。这是本地跑 Puma 测试最常见的前置问题值得在写测试前先确认。四、复现 Bug 的标准流程复现是定位根因的第一步。标准做法是准备一个 rackup 应用 一个配置文件然后用本地编译好的 Puma 启动bundle exec puma -C path/to/config.rb path/to/rackup.ru文档给出了可直接运行的仓库内示例——用测试 rack 应用和测试配置各跑一遍bundle exec puma -C test/config/settings.rb test/rackup/hello.ru其中test/rackup/hello.ru返回Hello World的最小 Rack 应用test/config/settings.rb内容为port 3000与threads 3, 5即监听 3000 端口、线程池最小 3 最大 5。-C参数加载的配置文件是完整的 Puma 配置 DSL见 lib/puma/dsl.rb可以按需追加workers、environment、ssl_bind等指令来逼近线上形态。4.1 使用 Docker 复现 Linux 专属问题对于只能在特定 Linux 环境下出现的问题仓库提供了 tools/Dockerfiledocker build -f tools/Dockerfile -t puma . docker run -p 9292:9292 -it puma该 Dockerfile 以ruby:latest为基础镜像默认BUNDLE_FROZENtrue会安装 ragel、procps、git 后执行bundle install并在 MRI 上执行bundle exec rake compile容器内EXPOSE 9292启动命令为bundle exec bin/puma test/rackup/hello.ru。若需在 JRuby 下复现可以用--build-arg RUBY_IMAGEjruby:9.4覆盖基础镜像需要在构建中更新锁文件时可设--build-arg BUNDLE_FROZENfalse。五、提交 Pull Request 的规范尽早开 draft PR写完少量代码就提交草稿 PR方便社区尽早给出反馈代码改动应包含测试覆盖不确定如何为改动写测试时可以在 PR 中留言求助不需要手动更新 History.md变更日志在发版时统一处理流程见 Release.md采纳评审意见时使用独立 commit方便维护者合并时 squashCI 对齐项目使用 GitHub Actions 做 CI建议在 fork 中预先运行工作流CI 针对每个受支持 Ruby 小版本的最新 patch 版本运行因此复现问题或报告 bug 时也请使用对应小版本的最新 patch release使本地环境与 CI 覆盖一致当前 puma.gemspec 要求 Ruby 3.0。5.1 Bug 修复的两段式提交如果 PR 是 bug 修复建议至少拆成两个 commit第一个或几个commit 只包含测试这些测试在main上应当失败第二个可能只有一个commit 才是修复代码。这样维护者可以单独 checkout 测试 commit 运行先验证 bug 确实存在再合并修复形成清晰的可审计闭环。5.2 Backport向旧版本回移植Puma 没有固定的 backport 策略——维护者不会无条件把 bugfix 移植回旧的小版本或大版本但安全问题例外安全相关处理见 SECURITY.md。对于 Ruby 本身的 patch 级问题Puma 可能添加针对性 workaround并在受影响的 Ruby 小版本生命周期内保留它即使后续 patch release 已修复底层问题。贡献者可以自行向-stable分支发起 backport PR合并后由维护者发版。例如要为 4.3.x 移植修复就向4-3-stable分支提交 PR如果目标版本没有对应分支可以开一个 issue维护者会补建。六、深入了解 Puma 内部机制对于第一次接触 Puma 的贡献者可能会遇到 Rack、socket、fork、线程等此前较少接触的概念。仓库内可直接阅读的入门材料包括官方架构文档 docs/architecture.md配合 docs 目录下的 signals.md、deployment.md、fork_worker.md 等可以快速建立整体认知Rack 规范理解env、请求/响应三元组约定的基础Ruby 标准库中IO.pipe、TCPServer/Socket的文档Puma 的网络层基于 socket 抽象构建见 lib/puma/binder.rb 与 lib/puma/reactor.rbnio4r 的入门文档——Puma 的非阻塞 I/O 依赖nio4rpuma.gemspec 声明nio4r ~ 2.0Working With 系列一套免费 Ruby 电子书深入讲解线程、TCP 与 Unix Socket 实战。此外docs/testing_test_rackup_ci_files.md 和 docs/testing_benchmarks_local_files.md 分别说明了测试/rackup/CI 文件与本地基准测试脚本的用途跑通测试后如果想评估改动对性能的影响可参考 benchmarks 目录下的 wrk 脚本。七、社区协作与治理贡献过程中有任何问题都可以在项目的 Discussions 讨论区提问。项目按 GOVERNANCE.md 描述的流程治理参与即表示同意遵守 CODE_OF_CONDUCT.md 中的行为准则。小结从这条贡献链路可以看到 Puma 工程化的几个特点解析器由 Ragel 生成、扩展按 MRI/JRuby 平台分别编译、测试套件以 socket 密集型场景为主、Bug 复现被工具化配置 DSL 测试 rackup Docker。对新手来说最快的上手路径是搭好环境跑通bundle exec rake挑一个contrib-wanted或needs-repro的 issue 入手先补测试再改代码尽早开 draft PR 获取反馈。这套流程不仅适用于 Puma 本身也适用于任何带原生扩展的 Ruby 项目。赞分享后端网络【免费下载链接】pumaA Ruby/Rack web server built for parallelism项目地址https://gitcode.com/gh_mirrors/pu/puma点击查看免费下载相关推荐Kitematic 开发者贡献指南环境搭建、Flux 架构与测试发布全流程Kitematic 开发者贡献指南环境搭建、Flux 架构与测试发布全流程 导读 本文面向希望为 Kitematic 贡献代码、修复缺陷或扩展新功能的开发者桌面应用SvelteKit 贡献开发指南monorepo 环境搭建、测试运行与 PR 提交流程实战SvelteKit 贡献开发指南monorepo 环境搭建、测试运行与 PR 提交流程实战 导读 本文以 SvelteKit 官方仓库根目录的 CONTRIBWeb框架后端前端Chainlit 本地开发环境搭建与贡献指南从源码运行、lint 到 E2E 测试全流程Chainlit 本地开发环境搭建与贡献指南从源码运行、lint 到 E2E 测试全流程 Chainlit 是一个用于快速构建对话式 AI 应用Conver人工智能大模型AI 应用后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考