oRPC 仓库贡献指南：从环境搭建、提交流程到 JSDoc 文档校验规范

后端RPC框架API设计【免费下载链接】orpcTypesafe APIs Made Simple 项目地址https://gitcode.com/gh_mirrors/or/orpc点击查看免费下载本文面向希望为 oRPC 开源仓库gh_mirrors/or/orpc提交代码、文档或缺陷修复的开发者完整梳理仓库的贡献工作流、测试组织方式与文档链接校验机制。读完本文你将掌握从 Fork 到合入 PR 的完整路径理解仓库基于 pnpm workspaces Vitest ESLint 的开发环境并能够写出符合 CI 强制校验规范的 JSDoc 注释。仓库与贡献范围概览oRPC 是一个端到端类型安全 APITypesafe APIs Made Simple框架仓库采用pnpm workspaces 单仓多包monorepo结构。根目录的 pnpm-workspace.yaml 声明了三个工作区目录apps/*文档站点apps/content基于 Blume 构建等应用packages/*orpc/server、orpc/client、orpc/contract、orpc/openapi、orpc/zod、orpc/tanstack-query等 20 余个 npm 包playgrounds/*next、bun、cloudflare、nest等可运行的演示项目用于手工验证改动。根据 CONTRIBUTING.md 的说明仓库欢迎所有类型的贡献缺陷报告bug reports、功能请求feature requests、文档改进documentation improvements和代码增强code enhancements。遇到问题或需要帮助时可以加入项目维护的 Discord 社区交流。[!TIP] 原贡献文档特别提示如果只想理解 oRPC 的核心概念而非参与完整开发可以参考 Mini-oRPC——它是 oRPC 的一个精简实现保留了核心特性设计上简单直接是学习 oRPC 内部原理的理想起点。开发环境与工具链仓库的开发环境要求如下见 CONTRIBUTING.md 的 Setup 一节工具用途说明Node.js v22运行时可用pnpm env快速安装指定版本pnpm pnpm workspaces依赖管理与工作区根目录声明了 workspace 包范围Vitest测试运行器单元测试、E2E 测试与基准测试统一由 Vitest 驱动ESLintantfu/eslint-config代码检查与格式化采用社区流行的 antfu 配置预设这些工具在仓库中有对应的落地配置。根目录 package.json 通过devEngines.packageManager声明了pnpm 12.4.2并提供了常用脚本{ scripts: { type:check: pnpm run -r type:check tsc, bench: vitest bench --run, test: pnpm run -r test vitest run, test:coverage: pnpm run -r test:coverage vitest run --coverage, lint: eslint ., lint:fix: eslint --fix ., repo:fix: sherif --fix, docs:validate: node scripts/verify-docs-jsdoc.ts pnpm run -r docs:validate } }几个值得注意的工程细节简单 Git 钩子simple-git-hooksprepare脚本会安装 Git 钩子pre-commit钩子执行pnpm lint-staged而lint-staged对所有暂存文件运行eslint --no-warn-ignored --fix确保每次提交前自动修正可修复的 lint 问题。monorepo 依赖解析策略pnpm-workspace.yaml 设置了linkWorkspacePackages: true与preferWorkspacePackages: true让playgrounds/*在开发期间无需workspace:协议即可解析本地包当 playground 被单独克隆时同样的依赖会自动回退到 registry 版本。类型声明的隔离处理工作区默认提升hoist全部依赖但显式排除了types/bun。原因是当types/node与types/bun同时被提升到同一环境时会产生冲突破坏同时处理 Node.js 类型与bun导入的包的类型检查。版本门禁白名单minimumReleaseAgeExclude列出了仍处于最低发布年龄限制内的依赖如standard-server/*、blume、effect、rou3这些条目在版本成熟后会失效届时应在下次版本升级时清理而非累积。标准贡献工作流按 CONTRIBUTING.md 的 Workflow 一节一次完整的贡献包含以下 9 步Fork在托管平台 Fork 本仓库。Clone克隆你的 Fork 到本地。Install安装依赖pnpm installBranch创建新分支git checkout -b feature/your-featureCode开始编写改动。Test手工验证在 playground 中手动验证功能例如cd playgrounds/next pnpm dev该命令对应 playgrounds/next/package.json 中的next dev --port 3000。仓库同时提供bun、cloudflare、nest等 playground可依据你的改动类型选择最贴近的环境。Tests自动化测试新增或更新测试具体约定见下一节。Commit Push提交并推送。提交信息应遵循 Conventional Commits 规范不过由于仓库通常使用 Squash and Merge 合入提交信息不是硬性要求。Pull Request向main分支或对应的版本分支发起 PR并在描述中总结改动、关联相关 issue例如Fixes #123。Conventional Commits 的 Scope 规则提交信息以及 PR 标题需要遵循 Conventional Commits 规范其中scope范围的选择有明确约定使用包名改动聚焦于某个包时用包名作 scope例如feat(server): ...使用rpc/openapi当改动涉及协议本身serializers、handlers、links 或专属插件而非单一包时使用rpc或openapi作为 scopecontent仅限文档站点自身只有文档站本身的改动样式、Blume 配置等才使用contentscope并且只能搭配chore类型——绝不能用feat/fix/perf/docs因为这些改动不影响库的使用者。关于某个包或协议的文档改动应使用对应的包/协议 scope例如docs(openapi): ...省略 scope当改动范围太宽、无法归入单一 scope 时可以省略 scope。这套规则的意图很清晰让提交历史中的每个条目都能准确反映它对库使用者的影响面文档站自身的样式调整属于纯内部改动不应伪装成面向用户的变更。测试组织方式仓库的测试体系由 Vitest 驱动根目录 vitest.config.ts 通过projects定义了三个并行测试项目基准测试项目加载codspeed/vitest-plugin匹配**/*.bench.ts如 benches 目录下的各类 benchmarkNode 环境项目globals: true匹配**/*.test.ts并加载 vitest.javascript.ts 作为 setup 文件该文件会初始化ORPCInstrumentationjsdom 环境项目匹配packages/next、packages/tanstack-query、packages/pinia-colada、packages/swr下的*.test.tsx组件测试需要 DOM 环境。按 CONTRIBUTING.md 的约定新增测试时单元测试在与被测代码同目录下添加.test.ts、.test.tsx或.test-d.ts文件。前两者是运行时的单元测试后者是类型级测试利用 Vitest 的expectTypeOf等机制断言类型行为如packages/server/src/builder.test-d.ts。由于globals: true测试文件中可以直接使用describe、it、vi等全局 API无需显式导入见 packages/server/src/builder.test.ts。E2E 测试放在仓库根级tests目录下、按包或协议组织的子目录中。例如 tests/rpc 下既有共享夹具__shared__/也有端到端用例如cancel-and-abort.test.ts、data-transfer.test.tspackages/lock/tests/e2e.test.ts、packages/ratelimit/tests/e2e.test.ts则是锁与限流包各自的 E2E 测试。运行全量测试可以使用pnpm test先跑各包的test脚本再在根目录执行vitest run需要覆盖率报告时使用pnpm test:coverage。注意 coverage 配置会排除packages/bun与packages/cloudflare两个包它们需要各自的运行时环境见 vitest.config.ts。JSDoc 与文档链接规范这是 oRPC 仓库最独特的贡献要求之一文档站点apps/content/docs中提到的每一个公共 API其声明处都必须带有 JSDoc 注释且注释内必须包含指向官方文档站的反向链接backlink。该规则由 CI 强制校验。JSDoc 模板CONTRIBUTING.md 给出了标准模板/** * Summary: 1-3 short sentences. Verb-first for functions, noun phrase for types/classes. * * remarks * **Warning**: footguns, breaking behavior * **Note**: non-obvious behavior, limits * * param name - only extra info beyond the type * returns only extra info beyond the type * * see {link https://orpc.dev/docs/... | Page Title} */模板的每条规则都对应仓库的实际实现。以 packages/server/src/adapters/fetch/rpc-handler.ts 中RPCHandler类的 JSDoc 为例/** * Serves an oRPC router over the RPC protocol using the Fetch API * (Request/Response), supported by modern runtimes like Deno, Bun, * Cloudflare Workers, and browsers. * * see {link https://orpc.dev/docs/adapters/fetch-api | Fetch API Adapter} */ export class RPCHandlerT extends Context extends FetchHandlerT {具体规范要点如下Summary13 句简短描述。函数以动词开头类型/类用名词短语。上述示例以 Serves... 动词开头概括函数行为。remarks可选最多 13 行加粗说明用于标注陷阱与非常规行为。必须使用**Warning**:或**Note**:前缀禁止使用warning/info这类非标准标签。param/returns可选只有当参数/返回值提供了超出类型签名本身的信息时才需要写纯类型冗余信息一律省略。禁止example示例代码统一放在链接指向的文档页面中JSDoc 中不写示例块。see恒为最后一个标签URL 必须映射到 apps/content/docs 下真实存在的.mdx页面可附加对应真实标题的#anchor。|之后的标题必须是该页面的 frontmattertitle若链接目标是锚点则标题格式为Page Title - Heading。全仓库链接扫描packages与playgrounds源码中出现的每一个https://orpc.dev/...链接包括行内 Markdown 链接都会被校验必须指向apps/content中真实存在的内容页面。CI 校验pnpm docs:validate仓库根目录的docs:validate脚本执行两层校验见根 package.jsonpnpm docs:validate # runs scripts/verify-docs-jsdoc.ts (accepts [--filter server,client] [--strict] [--list] via node) and blume validate --strict第一层由 scripts/verify-docs-jsdoc.ts 完成。该脚本会扫描apps/content/docs下所有.md/.mdx页面代码块中从orpc/*导入的每个符号通过正则提取 import 语句读取各包package.json的exports映射定位每个orpc/name[/sub]对应的入口源文件用 TypeScript Compiler API 建立程序与类型检查器解析每个符号的声明及其 JSDoc 文本逐项校验并输出带错误码的诊断信息。错误码含义如下错误码严重级别含义E1error文档从未知入口点导入或该名称未从对应入口导出E2error声明没有 JSDoc 注释E3errorJSDoc 缺少see {link https://orpc.dev/docs/...}反向链接E4error反向链接不指向 docs 前缀下或指向的内容页面不存在E5error反向链接的#anchor在目标页面中找不到对应标题E6error链接标题|后的文字与页面标题不符W1warning链接的目标页面从未提到该符号--strict时升级为 errorW2warning使用了非标准/遗留标签如info、warning、{see ...}、return、{link url Title}空格形式脚本还支持通过node直接运行并传入参数--filter server,client只校验指定包目录、--strict把警告升级为错误、--list仅列出文档中被提及的符号清单输出格式为specifier#nameTABpages方便快速了解校验范围。所有错误信息都会附带声明位置包路径:行号与在哪些文档页被提及的提示便于定位修复。任何 error 都会导致脚本以非零退出码结束从而让 CI 失败。第二层由blume validate --strict完成对应 apps/content/package.json 中的docs:validate脚本校验文档站点自身的构建一致性。两层校验串行执行全部通过才能通过 CI。其他质量门禁除文档校验外仓库还有几道常规质量门禁贡献者在提交前应尽量本地通过Lintpnpm lint运行eslint .基于antfu/eslint-config根 eslint.config.jspnpm lint:fix自动修复可修复问题pre-commit钩子也会自动对暂存文件执行eslint --fix。类型检查pnpm type:check会先递归运行所有包的type:check各包通常为tsc -b再在根目录执行tsc。基准测试pnpm bench运行vitest bench --run覆盖 RPC 序列化、OpenAPI 生成、静态文件服务等热点路径见 benches。仓库结构检查pnpm repo:fix使用sherif --fix检查并修复 monorepo 依赖/结构问题。小结oRPC 仓库的贡献体系可以概括为标准 Git 工作流 强约束的文档-代码联动校验普通贡献遵循 Fork → Branch → Code → Test → PR 的常规流程提交信息与 PR 标题需遵守带 package/protocol scope 的 Conventional Commits 规则而最具特色的部分是 JSDoc 反向链接机制——文档中出现的每个公共 API 都必须在声明处带see {link https://orpc.dev/docs/...}注释并由pnpm docs:validate在 CI 中严格校验。理解这套规范不仅能让你顺利合入 PR也能帮助你从文档驱动 API 设计的角度更深入理解 oRPC 的工程哲学。赞分享后端RPC框架API设计【免费下载链接】orpcTypesafe APIs Made Simple 项目地址https://gitcode.com/gh_mirrors/or/orpc点击查看免费下载相关推荐A2A 协议仓库贡献指南从开发环境搭建、文档构建到代码规范与 PR 提交流程A2A 协议仓库贡献指南从开发环境搭建、文档构建到代码规范与 PR 提交流程 Agent2AgentA2A是面向“黑盒”式智能体应用之间通信与互操作的开放人工智能AI AgentAPI设计Manim 贡献指南从开发环境搭建、PR 提交流程到文档与测试规范Manim 贡献指南从开发环境搭建、PR 提交流程到文档与测试规范 ManimManim Community Edition是一个社区维护的数学动画 Py图形学教育chi 路由贡献指南从环境搭建、测试规范到 Pull Request 提交流程chi 路由贡献指南从环境搭建、测试规范到 Pull Request 提交流程 本文是 chi github.com/go chi/chi/v5 一个 l后端Web框架上一篇探索智能交互新境界 —— 使用Maid实现跨平台的人工智能对话体验下一篇OpenTelemetry Python部署和生产环境配置确保系统稳定运行的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考