拓冰网站定制 
如何为World of ClaudeCraft添加REST接口server/http RouteDef管道完整开发者指南【免费下载链接】world-of-claudecraft项目地址: https://gitcode.com/gh_mirrors/wo/world-of-claudecraftWorld of ClaudeCraft 是一款自研的多人在线 3D 网页 MMO 游戏其权威游戏服务器为 TypeScript 编写。想给它加一个 REST 接口吗本文带你在10 分钟内理解项目内建的server/http请求管道学会用RouteDef路由表注册端点、编写中间件洋葱、输出稳定错误码并跑通测试。无需任何外部框架——整套管道是项目自研的零依赖实现。先搞清楚REST 请求是怎么走到你的代码的游戏服务器启动后main.ts里的routeHttpRequest是一个前缀阶梯它把请求按前缀分发给四个入口——/api、/admin/api、/oauth、/internal。在默认的API_DISPATCHnew模式下每个入口都会先查询路由注册表注册表匹配server/http/registry.ts 把所有业务域模块导出的routes数组即RouteDef[]拼成一张扁平表按最具体优先排序后构建查表路由器洋葱执行匹配成功后server/http/dispatch.ts 创建的分发器按 Koa 风格洋葱依次执行中间件错误处理 → 指标 → Origin 校验 → Content-Type 门禁 → 路由自带中间件 → 你的 handler兜底委托未匹配的旧路径会落到main.ts中保留的旧版handleApi阶梯API_DISPATCHlegacy可一键回滚。所以添加一个新 REST 接口的正确姿势不是往main.ts里塞 handler而是在业务域模块里声明一个RouteDef然后在注册表里登记。这也是项目的硬性模块规范见 server/http/CLAUDE.md 与 server/CLAUDE.md。看懂 RouteDef一个接口 一张声明卡片所有类型契约集中在 server/http/types.ts一个RouteDef长这样节选字段{ method: GET, // HTTP 方法 path: /api/characters/:id, // 路径模式支持 :参数 surface: api, // 决定默认响应信封 middleware: [...], // 路由级中间件洋葱 schema: ..., // 请求体/参数/查询的校验器 handler: (ctx) ... // 不碰 req/res 的纯 handler }理解这张卡片抓住四个设计点surface决定响应信封api默认走 RFC 9457problemjson错误格式admin走{ success, data, error }oauth走 RFC 6749单条路由可用meta.envelope覆盖比如返回一张二进制的玩家名片 PNG。handler 与 req/res 解耦handler 签名是(ctx: Ctx) 返回值读写统一走Ctx解析好的 query、路径参数、校验后的 body、鉴权后的账号。这让同一个核心逻辑可以复用到 WebSocket 侧也天然可单元测试。:id路由的所有权保护BOLA如果资源属于玩家声明meta.requireOwned并挂上require_owned加载器未授权时返回404防枚举管理员资源则返回 403。注册表构建时会做影子路由守卫漏了加载器直接构建失败。公开只读路由确实需要公开的:param路由比如按名字查角色面板标记meta.publicRead: true参考 server/leaderboard.ts 末尾的routes数组它是纯静态路由表 运行时注入的标准范例。五步快速添加你的第一个端点项目内置脚手架一条命令生成骨架npm run new:endpoint -- --domain my-domain --method GET --path /api/my-domain [--public]它由 scripts/new_endpoint.mjs 驱动会自动完成大部分繁琐工作在server/domain.ts里生成RouteDef桩和类型推导的校验 schema组合器来自 server/http/schema.tsobject/str/num/enum_/optional等向 server/http/error_codes.ts 追加一条domain.reason错误码并同步生成客户端英文文案与映射在 server/http/registry.ts 的两个锚点注释处自动插入 import——别手动删这些注释生成基于FakeDb的测试骨架。之后你只需按顺序爬梯填坑完整做法见 server/CLAUDE.md 的Adding an endpoint小节公开只读照抄server/leaderboard.ts——静态routes数组 configureDomainRuntime运行时注入避免 main.ts 循环依赖需要登录照抄 server/auth_routes.ts挂requireAccount守卫资源属主校验照抄 server/characters.ts中间件顺序是鉴权守卫 → 限流 →withBody→requireOwnedX→ handler。中间件洋葱全局帧 vs 路由本地帧洋葱执行器在 server/http/compose.ts它保证任何路径上都恰好发出一个响应——handler 正常返回走一条路抛异常走另一条路socket 永远不会挂起。中间件分两层边界很重要层次帧挂载方式全局with_errors、metric_sink、origin_check、content_type由 server/http/dispatch.ts 挂到每条匹配路由路由本地body/raw_body、require_*守卫、bearer_active_guard、turnstile、rate_limit在 RouteDef 的middleware数组里声明新增横切行为时正确位置是 server/http/middleware/ 下新建一个同构帧 同名测试绝不把逻辑内联进 dispatch。全局帧的顺序被onion_order.test.ts钉死改顺序要过测试。错误输出纪律只发稳定 CODE不发英文这是新手最容易踩的坑。REST handler 抛出HttpError定义在 server/http/errors.ts时必须携带domain.reason形式稳定错误码而不是英文句子——服务器是无语言的客户端负责本地化客户端用 src/ui/api_error_i18n.ts 的userFacingApiError把 code 逐字映射为apiError.domain.reason文案tests/api_error_code_parity.test.ts 会在服务端新增 code 却缺客户端 key 时红灯error_codes.ts是只增不改目录永不重排、改名或删除既有码AIP-193 纪律有快照测试把关如果新文案含 4 字母以上的英文单词同一提交里要补齐zh、zh_TW、ja、ko、ru五个非拉丁语翻译否则 i18n 完整性测试失败。写测试FakeDb 路线不是 pg 模拟端点测试不连数据库。项目约定用tests/server/helpers/工具包fakeCtx构造一个结构完整的冻结Ctx配FakeRes假响应FakeCharactersDb等类型级假实现零运行时pg依赖驱动方式直接调用域模块导出的routesconfigureDomainRuntime注入模拟真实请求。范例见 tests/server/leaderboard.test.ts先用 FakeDb 单测纯读函数再用fakeCtx驱动 handler。另外新增路由后还要手动在 tests/server/http/surface_inventory.ts 补上 (method, path) 台账行——脚手架不会替你生成而这个台账是 CI 的硬门禁任何一条路径两边都不服务completeness.test.ts直接失败。常用参考文件速查 想做什么去哪看类型契约RouteDef/Ctx/中间件server/http/types.ts管道全貌与模块职责表server/http/CLAUDE.md添加端点完整配方server/CLAUDE.md路由注册与影子守卫server/http/registry.ts洋葱执行器server/http/compose.ts分发器与 API_DISPATCH 开关server/http/dispatch.ts管道重架构的完整记录docs/api-pipeline/README.md脚手架脚本scripts/new_endpoint.mjs最后提醒两条铁律一、迁移中的路由在新旧两条臂上同时存在改行为必须双臂同改dual-edit 规则二、任何所有玩家看到的都一样的读排行榜、计数、聚合不要按请求直查数据库要用项目提供的缓存形态server/http/CLAUDE.md 的 Hot paths 一节有现成做法。把这两条守住你的第一个RouteDef就能安全上线。想要动手实践克隆仓库git clone https://gitcode.com/gh_mirrors/wo/world-of-claudecraft跑起npm run new:endpoint照着 leaderboard 范例填坑即可——祝开发顺利 ⚔️【免费下载链接】world-of-claudecraft项目地址: https://gitcode.com/gh_mirrors/wo/world-of-claudecraft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何为World of ClaudeCraft添加REST接口：server/http RouteDef管道完整开发者指南
如何为World of ClaudeCraft添加REST接口server/http RouteDef管道完整开发者指南【免费下载链接】world-of-claudecraft项目地址: https://gitcode.com/gh_mirrors/wo/world-of-claudecraftWorld of ClaudeCraft 是一款自研的多人在线 3D 网页 MMO 游戏其权威游戏服务器为 TypeScript 编写。想给它加一个 REST 接口吗本文带你在10 分钟内理解项目内建的server/http请求管道学会用RouteDef路由表注册端点、编写中间件洋葱、输出稳定错误码并跑通测试。无需任何外部框架——整套管道是项目自研的零依赖实现。先搞清楚REST 请求是怎么走到你的代码的游戏服务器启动后main.ts里的routeHttpRequest是一个前缀阶梯它把请求按前缀分发给四个入口——/api、/admin/api、/oauth、/internal。在默认的API_DISPATCHnew模式下每个入口都会先查询路由注册表注册表匹配server/http/registry.ts 把所有业务域模块导出的routes数组即RouteDef[]拼成一张扁平表按最具体优先排序后构建查表路由器洋葱执行匹配成功后server/http/dispatch.ts 创建的分发器按 Koa 风格洋葱依次执行中间件错误处理 → 指标 → Origin 校验 → Content-Type 门禁 → 路由自带中间件 → 你的 handler兜底委托未匹配的旧路径会落到main.ts中保留的旧版handleApi阶梯API_DISPATCHlegacy可一键回滚。所以添加一个新 REST 接口的正确姿势不是往main.ts里塞 handler而是在业务域模块里声明一个RouteDef然后在注册表里登记。这也是项目的硬性模块规范见 server/http/CLAUDE.md 与 server/CLAUDE.md。看懂 RouteDef一个接口 一张声明卡片所有类型契约集中在 server/http/types.ts一个RouteDef长这样节选字段{ method: GET, // HTTP 方法 path: /api/characters/:id, // 路径模式支持 :参数 surface: api, // 决定默认响应信封 middleware: [...], // 路由级中间件洋葱 schema: ..., // 请求体/参数/查询的校验器 handler: (ctx) ... // 不碰 req/res 的纯 handler }理解这张卡片抓住四个设计点surface决定响应信封api默认走 RFC 9457problemjson错误格式admin走{ success, data, error }oauth走 RFC 6749单条路由可用meta.envelope覆盖比如返回一张二进制的玩家名片 PNG。handler 与 req/res 解耦handler 签名是(ctx: Ctx) 返回值读写统一走Ctx解析好的 query、路径参数、校验后的 body、鉴权后的账号。这让同一个核心逻辑可以复用到 WebSocket 侧也天然可单元测试。:id路由的所有权保护BOLA如果资源属于玩家声明meta.requireOwned并挂上require_owned加载器未授权时返回404防枚举管理员资源则返回 403。注册表构建时会做影子路由守卫漏了加载器直接构建失败。公开只读路由确实需要公开的:param路由比如按名字查角色面板标记meta.publicRead: true参考 server/leaderboard.ts 末尾的routes数组它是纯静态路由表 运行时注入的标准范例。五步快速添加你的第一个端点项目内置脚手架一条命令生成骨架npm run new:endpoint -- --domain my-domain --method GET --path /api/my-domain [--public]它由 scripts/new_endpoint.mjs 驱动会自动完成大部分繁琐工作在server/domain.ts里生成RouteDef桩和类型推导的校验 schema组合器来自 server/http/schema.tsobject/str/num/enum_/optional等向 server/http/error_codes.ts 追加一条domain.reason错误码并同步生成客户端英文文案与映射在 server/http/registry.ts 的两个锚点注释处自动插入 import——别手动删这些注释生成基于FakeDb的测试骨架。之后你只需按顺序爬梯填坑完整做法见 server/CLAUDE.md 的Adding an endpoint小节公开只读照抄server/leaderboard.ts——静态routes数组 configureDomainRuntime运行时注入避免 main.ts 循环依赖需要登录照抄 server/auth_routes.ts挂requireAccount守卫资源属主校验照抄 server/characters.ts中间件顺序是鉴权守卫 → 限流 →withBody→requireOwnedX→ handler。中间件洋葱全局帧 vs 路由本地帧洋葱执行器在 server/http/compose.ts它保证任何路径上都恰好发出一个响应——handler 正常返回走一条路抛异常走另一条路socket 永远不会挂起。中间件分两层边界很重要层次帧挂载方式全局with_errors、metric_sink、origin_check、content_type由 server/http/dispatch.ts 挂到每条匹配路由路由本地body/raw_body、require_*守卫、bearer_active_guard、turnstile、rate_limit在 RouteDef 的middleware数组里声明新增横切行为时正确位置是 server/http/middleware/ 下新建一个同构帧 同名测试绝不把逻辑内联进 dispatch。全局帧的顺序被onion_order.test.ts钉死改顺序要过测试。错误输出纪律只发稳定 CODE不发英文这是新手最容易踩的坑。REST handler 抛出HttpError定义在 server/http/errors.ts时必须携带domain.reason形式稳定错误码而不是英文句子——服务器是无语言的客户端负责本地化客户端用 src/ui/api_error_i18n.ts 的userFacingApiError把 code 逐字映射为apiError.domain.reason文案tests/api_error_code_parity.test.ts 会在服务端新增 code 却缺客户端 key 时红灯error_codes.ts是只增不改目录永不重排、改名或删除既有码AIP-193 纪律有快照测试把关如果新文案含 4 字母以上的英文单词同一提交里要补齐zh、zh_TW、ja、ko、ru五个非拉丁语翻译否则 i18n 完整性测试失败。写测试FakeDb 路线不是 pg 模拟端点测试不连数据库。项目约定用tests/server/helpers/工具包fakeCtx构造一个结构完整的冻结Ctx配FakeRes假响应FakeCharactersDb等类型级假实现零运行时pg依赖驱动方式直接调用域模块导出的routesconfigureDomainRuntime注入模拟真实请求。范例见 tests/server/leaderboard.test.ts先用 FakeDb 单测纯读函数再用fakeCtx驱动 handler。另外新增路由后还要手动在 tests/server/http/surface_inventory.ts 补上 (method, path) 台账行——脚手架不会替你生成而这个台账是 CI 的硬门禁任何一条路径两边都不服务completeness.test.ts直接失败。常用参考文件速查 想做什么去哪看类型契约RouteDef/Ctx/中间件server/http/types.ts管道全貌与模块职责表server/http/CLAUDE.md添加端点完整配方server/CLAUDE.md路由注册与影子守卫server/http/registry.ts洋葱执行器server/http/compose.ts分发器与 API_DISPATCH 开关server/http/dispatch.ts管道重架构的完整记录docs/api-pipeline/README.md脚手架脚本scripts/new_endpoint.mjs最后提醒两条铁律一、迁移中的路由在新旧两条臂上同时存在改行为必须双臂同改dual-edit 规则二、任何所有玩家看到的都一样的读排行榜、计数、聚合不要按请求直查数据库要用项目提供的缓存形态server/http/CLAUDE.md 的 Hot paths 一节有现成做法。把这两条守住你的第一个RouteDef就能安全上线。想要动手实践克隆仓库git clone https://gitcode.com/gh_mirrors/wo/world-of-claudecraft跑起npm run new:endpoint照着 leaderboard 范例填坑即可——祝开发顺利 ⚔️【免费下载链接】world-of-claudecraft项目地址: https://gitcode.com/gh_mirrors/wo/world-of-claudecraft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考