Skip to content

WebApiClient 文档站:从群友到文档维护者的四年 ​

2026.11 · 文档仓库:WebApiClientWiki · 文档站:webapiclient.github.io

WebApiClient 是 .NET Core Community 旗下的声明式 HTTP 客户端库:写一个 interface,打上 [HttpGet] 之类的特性,工厂帮你生成实现,BenchmarkDotNet 里多数场景耗时 2 倍以上领先于同类产品 Refit。库本体是老九(xljiulang)的作品,从接口设计到运行时动态代理,都是他的手艺。

我和它的结缘,是开源社区里最常见的那条路:刷到这个库,读了几段源码,越看越觉得"这东西值得被更多人用",顺手进了官方 QQ 群。不常见的是后面那步——在群里看了一阵提问和答疑,我发现一个比代码更扎眼的缺口:这么好的库,没有一份像样的文档站。于是我主动把文档仓库 WebApiClientWiki 建了起来,一维护就是四年;老九也从群名片背后的一个 ID,处成了熟悉的网友。

这篇讲的就是这四年:一个"只写文档、不写库代码"的维护者,把文档当产品做,都做了些什么。库的实现细节一句不聊——那是老九的博客该写的。

先把边界说清楚 ​

开源协作里最容易被忽视的角色,是"项目的文档维护者"。我的情况是:

  • 库代码:在 dotnetcore/WebApiClient,我不碰
  • 文档:在独立的 WebApiClient/WebApiClientWiki 仓库,从 Initial commit(2022-11)到现在,355 个提交里我占 247 个——包括建站、写作、重构、迁移、CI,一条龙

这不是"帮别人打工",而是各守一摊的协作:老九专注库本体,偶尔也来文档仓库留笔——他在这边攒了 28 个提交,多是内容勘误。最直观的注脚在捐赠页:并排放着两个收款码,一个是老九的,一个是我的——库与文档,各有其主,也各有各该感谢的人。仓库也独立于库仓库,生命周期、CI、部署策略全是文档自己的事,责任边界反而干净。

代价也有:文档和代码天然存在同步延迟,库发了 v2.1.6,文档得专门跑一轮"同步"(45d78a6 docs: 同步 v2.1.6 内容并新增 AI 辅助开发指南)。库作者改了一个特性,文档不会自动知道——这事后面还会说,我最近给它找到了一个新解法。

第一课:文档的信息架构比文笔重要 ​

建站头几年,自己写的指南是 guide/ 下从 1_getting-started 排到 13_migration-guide 的编号平铺——编号是写作顺序,不是查阅顺序。新手最常问的问题——"这个特性怎么配"、"为什么我的接口不生效"——在一串编号里要靠运气翻。另有一批主库时代传下来的 basic/senior 旧文档,我在 2023 年 4 月整体归档进 old/,导航栏挂上"旧版本[不再更新]":旧文档不是垃圾,是存量用户的书签——链接不能断,内容不再长,边界写明白。

真正的彻底重组发生在 2026 年 4 月,动机正是那串编号。原则只有一条:按读者的心智分层,而不是按写作顺序:

docs/guide/
├── overview/        # 概览:架构、快速上手——5 分钟决定"用不用"
├── core/            # 核心功能:HTTP/内容/返回/过滤器特性、特殊类型……——日常查阅
├── configuration/   # 配置与诊断:HttpClient、重试、异常处理——出问题才来
├── extensions/      # 扩展包:OAuth、JsonRpc、OpenApi 代码生成——按需选装
└── advanced/        # 高级主题:AOT、Cookie 刷新、自解释参数——小众场景

13 篇编号长文拆开、重写、归位到对应层级,再补上原来没人写的 HttpClient 配置、重试策略、Cookie 自动刷新……最终长成近 30 篇主题文档,从 Uri 拼接规则 到 适配畸形接口,每一篇对应一个真实的用户问题域。

这条路上还攒下一条反复受益的经验:目录即边界。有一回"捐赠、贡献者"这类支持页混住在 reference/ 下,侧栏配置要逐页枚举,新增页面必漏。最后的解法不是加注释提醒,而是把整个 /support/ 目录迁出去——目录结构对了,配置想写错都难。

第二课:文档站是个正经工程,不是"能访问就行" ​

文档站也是软件,该有的工程质量一样不能少。这几年攒下的家底:

跨仓库部署。 文档站部署在 WebApiClient/WebApiClient.github.io 而不是本仓库的 gh-pages 分支,域名独立。CI 用一把 SSH key 从 Wiki 仓库推送到那个仓库,single-commit + clean 保证部署分支永远只有一次干净快照,不会积攒几百个 "Docs Deploy"。

细节兜底。 dev server 的本地 HTTPS 证书不存在时自动降级 HTTP——注释里写死了原则:证书问题只许影响 dev,绝不能影响 build。GitHub 上的"编辑此页"链接直接指向 edit/main/docs/:path,读者发现错字,顺手一个 PR 比开 issue 便宜得多。外加 dependabot 常年盯依赖(四年攒了 77 个升级 PR),以及一个 gitee 镜像同步工作流照顾国内访问。

零依赖链接检查器。 家底里最新的一件,是 VitePress 迁移时顺手写的,但已经是最常用的一件。文档最大的天敌是死链——改一次目录结构,散落各页的内部链接悄无声息地烂掉。于是我写了 check-links.mjs:纯 Node ESM、零依赖,构建完成后扫 dist/ 里全部 HTML 的 <a href>,跳过外链和锚点,按"精确文件 / index.html / xxx.html / 尾斜杠目录"四步判定目标存在性,发现断链退出码非 0,最后一行吐 LINKCHECK_JSON 汇总。有个细节值得一提:VitePress 语言切换菜单会生成指向对侧 locale 的镜像链接,对侧没建对应页面时天然 404,这是框架已知行为而非内容断链——检查器里专门按菜单文案排除,不然每次跑都是狼来了。

第三课:迁移框架,迁的是语义不是配置 ​

目录重组完半年,我又动了框架的念头:2026 年 10 月,整站从 VuePress 2 迁到 VitePress。动机很朴素:VuePress 2 长期 RC、生态停滞,VitePress 是 Vue 团队亲儿子,构建快、主题现成。真正干的活,大概分成三档:

第一档是体力活:改配置结构、调主题配置、双语路由(/en/ 前缀)重排,顺着报错修就是了。

第二档才是迁移的本质:补语义缺口。 站内有几页靠 VuePress 2 的 <Content path="/reference/tags.md" /> 做跨页内容嵌入,VitePress 压根没有这个语义——它的全局 <Content /> 不吃 path prop,硬传会渲染当前页自身组件,SSR 直接无限递归。解法是写了个 markdown-it 插件 md-content-include.mts:渲染期把 <Content path> 内联成目标 markdown 的渲染结果,剥 BOM 和 frontmatter,嵌套渲染共用同一个 env——这样目标文件里的 <script setup>、链接、mermaid 都走完全相同的管线。递归深度限 5 层,防 include 环。

这个插件给我的启示比迁移本身值钱:框架迁移的坑不在配置表,而在旧框架"顺手给你做了"而新框架没说的那些事。配置项报错会喊疼,语义缺口只会沉默——直到某个页面白屏。

第三档是迁移顺手还的债:启用 Mermaid,把旧文档里那些对不齐的 ASCII 框图全部换成正经图表;加版式宽窄开关(宽屏 / 全屏两档,右下角浮动按钮切换);本地搜索把 old/ 旧文档隔离出索引,一搜一个准;pnpm overrides 强制 vite 6.4.5,一次清掉全部 9 条依赖安全告警。导航也重排了一轮:"参考"独立为一级导航,首页徽章去重,失效的 starchart 换成 star-history。

第四课:AI 时代,文档的第二读者是模型 ​

最近一次内容更新,我加了一篇自己也没想到会写的文档:AI 辅助开发。

起因很现实:越来越多用户是让 Claude Code、Cursor 替自己写 WebApiClient 接口的,而模型凭训练记忆"猜" API,生成的特性组合经常不符合官方实践。库本体那边给出了答案——官方维护了一个 Agent Skill(webapiclientcore),放进 .claude/skills/ 或 .cursor/skills/ 就能让 AI 按官方最佳实践写代码。

文档这边要做的,就是把"如何获取和安装这个 Skill"写成正式指南,和快速上手、AOT 发布并列。这件事标志着文档维护者多了一个新职责:文档不再只给人看,还要给模型读。而两种读者的口味完全不同:人类指南从"这是什么、5 分钟能不能跑起来"讲起,目录分层、循序渐进;那份 Skill 文件开篇就是触发词和选型决策树——什么时候用 WebApiClientCore、什么时候直接用 HttpClient——正文全是接口声明模板、特性速查表和异常处理速查,外加约 1000 行按"查"而非"读"组织的参考手册。给 AI 写文档,信息密度就是一切:它不会读到第三章才恍然大悟,它只会在速查表里命中或落空。这是这四年里文档这个行当变化最大的一件事。

数字收尾 ​

指标数值
维护时长4 年(2022-11 至今)
仓库提交247 / 355(其余多为 dependabot 与库作者)
文档页面中文 30+ 篇,英文全镜像
站点框架VuePress 2 → VitePress(2026-10)
工程配套零依赖链接检查 / 跨仓库部署 / gitee 镜像 / dependabot

回头看,当年群里那个潜水看答疑的 ID,如今在文档站留下 247 个提交——没有一行库代码,但每一页、每条 CI、每个插件都有指纹。"不会写库代码就别贡献开源"是个伪命题——把文档当产品做,本身就是一种全职贡献:它需要信息架构的判断、工程化的手段,如今还需要面向 AI 的内容设计。而这一切的起点,不过是四年前主动揽下的一句话:文档站,我来搭。

还欠的账:英文版落后中文版一个身位、old/ 旧文档里仍有少量过时示例没插"内容已过时"横幅、Agent Skill 的文档还可以再厚。这些是下一个四年的事——反正文档这活,永远有下一页。

基于 CC BY 4.0 发布