Repository navigation
docs(api): builder 家族进入 spec/API 参考 + 拆掉 server.h 里的 request 声明 - #476
Merged
Merged
Conversation
v2.10 roadmap d8（API 参考与示例同步）。对账发现两份文档对 uvhttp_server.h 的 45 个公共函数都有实质缺口，且 server.h 里还挂着声明在 别处的 request 函数。 ## 1. builder 家族原本两份文档都没有条目 `uvhttp_server_create` / `uvhttp_get..uvhttp_any` / `uvhttp_set_max_connections` / `uvhttp_server_run` / `stop_simple` / `simple_free` / `uvhttp_serve` / `uvhttp_server_new_with_loop` —— 一个条目 都没有，而 `uvhttp_serve` 与 builder 链是 README 快速开始之外最常被抄的入口。 d5 刚改了这条路径的契约，文档还是空白。 补齐内容（spec 给完整契约、API 参考给精简版）： - **builder 是视图不是所有者** —— server/router/config 由 server_free 释放， 拆卸只有 simple_free 一条路，没有 per-field teardown 的选项 - **错误码透传**（d5 新增）：NULL host 是 INVALID_PARAM，端口占用是 SERVER_LISTEN，不再一律塌缩成 SERVER_LISTEN - **out-param 契约**：任何失败下 *server 为 NULL，调用方无回滚可写 - uvhttp_get..uvhttp_any 的失败**只记日志不返回** —— 链式调用无法从返回值 发现注册失败，此前无任何文档说明 - uvhttp_set_max_connections 是**唯一有效**的 builder 配置旋钮（另两个假 旋钮已在 v2.10 删除，指向 config-api.md 的归属表） - uvhttp_serve 的 host=NULL 是错误而非默认（发警告后继续走 listen，然后失败） ## 2. uvhttp_request 的"内部函数"块从 server.h 拆出 server.h 尾部挂着 `/* internalFunction */` 的 uvhttp_request_init / uvhttp_request_cleanup —— request API 出现在 server.h 里，正是本轮审计 O1「归属错误」的同款（#470 已删三个纯别名，这两个是漏网的）。cleanup 在 request.h 本就有一份声明（两份并存），init 则只在 server.h。 处理：init 移到 request.h（紧邻其余 request API），两块都从 server.h 移除。 uvhttp.h 同时包含两个头文件，标准入口不受影响；只 include server.h 的调用方 需自行补上 request.h —— 破坏性，但与 v2.10 "一次改干净"的口径一致。 ## 3. 记录的文档债（本 PR 不补） - WebSocket 13 个 ws_* 函数、限流 7 个 rate_limit_* 函数在两份文档仍无条目 —— 分别属 docs/guide/websocket.md 与 RATE_LIMIT_API.md 的领域，建议各自 单独 PR 补齐，不塞进本次 - port 范围校验在 listen / listen_routes / create 三条路径都缺（#470 评审 已记），待 d6 一并处理 ## 验证 ctest 120/120；test-validity 门禁 PASS；check-doc-sync（31 文件 0 过时 0 缺 中译）；check-brain OK；核心 API 对账双向零缺口；门禁口径内文件 clang-format 合规。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v2.10 roadmap d8（API 参考与示例同步）。用脚本对账
uvhttp_server.h的 45 个公共函数 vs 两份文档，发现 builder 家族一个条目都没有——而 d5 刚改了这条路径的契约。1. builder 家族原本两份文档都没有条目
uvhttp_server_create/uvhttp_get..uvhttp_any/uvhttp_set_max_connections/uvhttp_server_run/stop_simple/simple_free/uvhttp_serve/uvhttp_server_new_with_loop全部缺席，而uvhttp_serve与 builder 链是 README 之外最常被抄的入口。补齐（spec 给完整契约、API 参考给精简版）：
server_free释放，拆卸只有simple_free一条路INVALID_PARAM，端口占用是SERVER_LISTEN，不再一律塌缩*server为 NULL，调用方无回滚可写uvhttp_get..uvhttp_any失败只记日志不返回 —— 此前无任何文档说明（链式调用无法从返回值发现注册失败）uvhttp_set_max_connections是唯一有效的 builder 配置旋钮，另两个假旋钮已在 v2.10 删除uvhttp_serve的 host=NULL 是错误而非默认2. server.h 拆出 request 的「内部函数」块
uvhttp_request_init/uvhttp_request_cleanup声明挂在uvhttp_server.h尾部、标着/* internalFunction */—— request API 出现在 server.h 里，正是本轮 O1「归属错误」的同款（#470 删了三个纯别名，这两个漏网）。cleanup在request.h本就有一份（两份并存），init只在 server.h。处理：
init移到request.h紧邻其余 request API，两块都从 server.h 移除。uvhttp.h同时含两个头文件，标准入口不受影响；只 includeserver.h的调用方需自行补request.h（破坏性，与 v2.10 口径一致）。记录的文档债（不在本 PR）
ws_*、限流 7 个rate_limit_*仍无条目 —— 属websocket.md/RATE_LIMIT_API.md领域，建议各自单独 PRport范围校验在listen/listen_routes/create三条路径都缺（refactor(api): 原子构造 + 所有权进名字（v2.10 第一刀） #470 评审已记），待 d6验证
ctest 120/120；test-validity PASS；check-doc-sync（31 文件 0 过时 0 缺中译）；check-brain OK；核心 API 对账双向零缺口；门禁口径内格式合规。