Webiny 自定义 HTTP 路由完整指南：用 `＜Api.Route＞` 与 HttpRouteHandler 在 GraphQL API 旁添加 REST 端点

CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载导读本指南讲解 Webiny 框架中为 API 添加自定义 HTTP 路由的完整方案通过Api.Route扩展组件在webiny.config.tsx中注册路由通过HttpRouteHandler.createImplementation编写带完整依赖注入DI支持的路由处理器从而在既有 GraphQL 处理器旁边暴露自定义的 GET、POST、PUT 等 REST 端点。读完本文你将掌握路由注册 Props 的全部语义、路径参数与通配符的写法、传输无关的 Request/Response 抽象、以及用 DI 装饰器改写路由行为与路由定义的进阶能力并能在apps/api/graphql/src/extensions.ts与 API Pulumi 模块两层理解整个路由的生命周期。快速上手TL;DRWebiny 的自定义 HTTP 路由遵循一个清晰的模式编写一个实现HttpRouteHandler.Interface的处理器类在webiny.config.tsx中用Api.Route指向该处理器文件处理器通过构造函数获得完整的依赖注入DI无需自己从容器里手工解析。// extensions/MyRoute.ts import { HttpRouteHandler, Logger } from webiny/api; class MyRouteImpl implements HttpRouteHandler.Interface { constructor(private logger: Logger.Interface) {} async handle(request: HttpRouteHandler.Request, response: HttpRouteHandler.Response) { this.logger.info({ path: request.path }, Handling request); return response.status(200).json({ status: ok }); } } export default HttpRouteHandler.createImplementation({ implementation: MyRouteImpl, dependencies: [Logger] });注册它Api.Route method{POST} path{/my-route} src{/extensions/MyRoute.ts} /两个必须遵守的硬性规则src属性必须带.ts扩展名的完整文件路径写src{/extensions/MyRoute.ts}而不是src{/extensions/MyRoute}省略扩展名会导致构建失败。必须使用export default导出createImplementation()的返回值这里不支持具名导出。Api.RouteProps 参考Prop类型必填说明pathstring是路由路径必须以/开头methodstring是HTTP 方法见下文srcstring是处理器文件路径必须包含.ts扩展名routeNamestring否路由名称kebab-case。省略时由 path method 派生。同时充当 Pulumi 资源名和装饰器匹配的 id支持的方法DELETE、GET、HEAD、PATCH、POST、PUT、OPTIONS、ANY。使用ANY可匹配该路径下的所有方法。method与path两个 Props 同时驱动两层配置API Gateway 路由与路由器router的匹配定义。因此处理器文件内不得重复声明 method/path——二者以 Props 为唯一事实来源处理器中自行设置会被忽略且可能导致两侧不一致。路径参数路径参数有两种等价写法含义相同{orderId}是 API Gateway 的语法:orderId是路由器router的语法。扩展会在构建/部署时按各自消费方所需进行转换因此两种写法都能用且等价Api.Route method{GET} path{/orders/{orderId}} src{/extensions/GetOrderRoute.ts} / Api.Route method{GET} path{/orders/:orderId} src{/extensions/GetOrderRoute.ts} /在处理器中通过request.pathParameters读取路径参数class GetOrderRouteImpl implements HttpRouteHandler.Interface { constructor(private getOrder: GetOrderUseCase.Interface) {} async handle(request: HttpRouteHandler.Request, response: HttpRouteHandler.Response) { const order await this.getOrder.execute(request.pathParameters.orderId); return response.status(200).json(order); } } export default HttpRouteHandler.createImplementation({ implementation: GetOrderRouteImpl, dependencies: [GetOrderUseCase] });通配符是例外/files/*是路由器的写法{proxy}是 API Gateway 的写法两者的捕获行为不同。为你想适配的目标写对应的通配符路由——即如果该路由主要面向 API Gateway 部署就用{proxy}语法。从源码看路由器对:param参数的解析位于 HttpRouter.ts它按/切分 pattern 与真实路径:param段会通过decodeURIComponent解码后写入pathParameters普通段则要求与真实路径精确相等以/*结尾的 pattern 则按前缀匹配。这正是文档中:orderId是路由器的语法的底层实现依据。Request传输无关的请求抽象HttpRouteHandler.Request是传输无关的——你的代码中不会泄漏任何 API Gateway 或 Node 的类型interface Request { method: string; path: string; headers: Recordstring, string; query: Recordstring, string; pathParameters: Recordstring, string; body: any; /** Which route matched — { name, method, path }. */ route: MatchedRouteDefinition; }route字段是装饰器能够精确作用于某一条路由的关键见下文也让处理器可以读取自己的身份。需要注意语义区别route.method/route.path是路由的模式PATTERN例如/orders/:orderId顶层的method/path是请求的实际值例如/orders/abc123。从 HttpRouter.ts 的实现可以看到route对象正是在路由匹配成功后、调用handle之前由路由器组装进 request 的包含匹配到的定义的name、method、path三个字段。Response可链式调用的可变响应构建器HttpRouteHandler.Response是一个可变构建器相当于 Express 风格处理器中的res。每个方法都返回this因此调用可以链式串联方法用途status(code)设置状态码默认 200json(body)JSON 响应体 对应 content typetext(body)纯文本响应体send(body)原样发送响应体header(name, value)设置一个响应头getHeader(name)读取已设置的响应头cookie(name, value, options?)设置 CookieclearCookie(name, options?)使一个 Cookie 过期redirect(url, statusCode?)重定向sse(source)Server-Sent Events 流链式示例return response.status(201).cookie(sid, id, { httpOnly: true }).json({ id });关于返回值的几个要点返回构建器是可选的——只修改它而不返回任何值效果相同返回普通对象也可以构建器上设置的内容会合并到其下层冲突时以返回对象为准。⚠️注意maxAge单位差异cookie的maxAge单位是秒对应Max-Age属性这与 Express 使用毫秒的习惯不同。工作原理从构建到请求的两段式生命周期Api.Route实际做两件事构建时Build time——向apps/api/graphql/src/extensions.ts写入一条注册信息注册一个由你的method和path构建的HttpRouteDefinition指向你的处理器部署时Deploy time——在 API Pulumi 模块上调用addRoute({ name, path, method })创建 API Gateway 路由路径会转换为{param}语法。HttpRouteDefinition的构建逻辑可以在源码 createHttpRouteDefinition.ts 中看到它接收{ name, method, path, handler }四个字段生成一个实现了HttpRouteDefinition.Interface的定义类handler 是一个构造函数ConstructorIHttpRoute。该函数的注释明确说明Api.Route扩展正是在构建时根据webiny.config.tsx中的 Props 生成注册信息因此处理器文件永远不需要重复声明 method/path二者不可能漂移。请求时Request time路由器遍历容器中全部HttpRouteDefinition进行匹配。由于定义只持有method、path和处理器类三个字段匹配成本极低。只有当某条路由匹配成功时路由器才构建对应的处理器并注入其依赖——请求未命中的路由永远不会被构造。这一点在 HttpRouter.ts 的实现注释中有详细说明早期实现会为了读取path而把所有路由都解析成实例导致一次静态资源请求就会构建整个 GraphQL 引擎、全部上下文 schema 和 AI provider现在的实现通过resolveImplementation只解析恰好匹配的那条路由的类从其自身元数据读取依赖并注入同时应用为HttpRouteHandler注册的装饰器使路由始终保持可装饰状态。装饰一条路由有两个钩子都是普通的 DI 装饰器。改变路由的行为DOES装饰HttpRouteHandler。它作用于每一条路由通过request.route.name挑选你要处理的特定路由import { HttpRouteHandler } from webiny/api; export default HttpRouteHandler.createDecorator({ decorator: class implements HttpRouteHandler.Interface { constructor(private decoratee: HttpRouteHandler.Interface) {} async handle(request: HttpRouteHandler.Request, response: HttpRouteHandler.Response) { if (request.route.name ! my-route-get) { return this.decoratee.handle(request, response); } if (request.headers[x-api-key] ! expected) { return response.status(401).json({ message: Not authorized. }); } return this.decoratee.handle(request, response); } }, dependencies: [] });去掉name检查它就包裹了所有路由——这正是做耗时统计或日志记录时想要的。request.route是匹配到的路由的{ name, method, path }。name即routeName或由 path 和 method 派生的值/my-routeGET→my-route-get。路由也可以读取它来获知自己的身份。改变路由的定义IS当需要修改路由本身——例如指向不同的处理器或移动它的路径——就装饰HttpRouteDefinitionimport { HttpRouteDefinition } from webiny/api; export default HttpRouteDefinition.createDecorator({ decorator: class implements HttpRouteDefinition.Interface { readonly name: string; readonly method: string; readonly path: string; readonly handler: HttpRouteDefinition.Interface[handler]; constructor(decoratee: HttpRouteDefinition.Interface) { this.name decoratee.name; this.method decoratee.method; this.path decoratee.name my-route-get ? /moved : decoratee.path; this.handler decoratee.handler; } }, dependencies: [] });装饰器暴露与其所包裹对象相同的属性因此要原样透传未修改的属性。如果你更喜欢 getter 也可以——这些是普通属性而非方法用 getter 访问器同样可行。关键规则清单不要在处理器文件中声明method/path。它们来自 Props处理器自行设置会被忽略且两者可能不一致。导出处理器而不是导出定义。Api.Route会替你构建定义。构造函数参数顺序必须与dependencies数组完全一致。声明依赖不要注入容器并在handle()内部自行解析。每个文件一个处理器——每个src文件默认导出且仅导出一个实现。相对导入使用.js扩展名ESM 规范。运行时不要读取process.env——请使用BuildParams。API 代码中禁止console.*——注入Logger代替。快速参考速查表Import: import { HttpRouteHandler } from webiny/api; Interface: HttpRouteHandler.Interface Request: HttpRouteHandler.Request Response: HttpRouteHandler.Response Export: export default HttpRouteHandler.createImplementation({ implementation, dependencies }) Register: Api.Route method{POST} path{/my-route} src{/extensions/MyRoute.ts} / Deploy: yarn webiny deploy api --envdev相关技能导航webiny-api-architect—— DI 模式、服务、用例、特性feature组织webiny-custom-graphql-api—— 自定义 GraphQL 端点HTTP 路由的替代方案webiny-dependency-injection—— 可注入服务目录Logger、BuildParams 等webiny-infrastructure-extensions—— Pulumi 层的基础设施自定义。进一步阅读源码packages/event-handler-core/src/features/http/createHttpRouteDefinition.ts —— 路由定义的构建逻辑构建时由Api.Route生成packages/event-handler-core/src/features/http/HttpRouter.ts —— 路由器路径匹配、pathParameters解码、仅构造匹配路由、装饰器应用packages/event-handler-core/src/features/http/invokeHttpRoute.ts —— 处理器返回值与 Response 构建器的合并逻辑packages/event-handler-aws/src/handlers/ApiGatewayHttpRouterHandler.ts —— AWS API Gateway 侧的请求适配packages/event-handler-standalone/src/handlers/NodeHttpRouterHandler.ts —— 独立部署standalone模式下的 Node 原生适配packages/event-handler-core/tests/HttpRouteDecoration.test.ts —— 路由装饰器的测试验证packages/event-handler-core/tests/HttpRouterImpl.test.ts —— 路由匹配与处理流程的测试验证。赞分享CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载相关推荐Wasp 自定义 HTTP API 端点完全指南从 api 声明到 Express 路由的实战详解Wasp 自定义 HTTP API 端点完全指南从 api 声明到 Express 路由的实战详解 Wasp 默认通过 OperationsQuery/AcWeb框架后端前端CLI开发工具NoneBot2 驱动器路由指南为机器人添加自定义 HTTP 与 WebSocket 服务端接口NoneBot2 驱动器路由指南为机器人添加自定义 HTTP 与 WebSocket 服务端接口 NoneBot2 的服务端型驱动器本质上是基于 ASGI 的后端即时通讯calibre 电子书格式转换实操指南calibre 电子书格式转换实操指南 calibre 是一款开源免费的电子书管理软件核心能力是把 PDF、EPUB、MOBI、DOCX 等 30 多种格式互桌面应用后端上一篇剪辑师亲测douyin-downloader 免费去水印批量下载素材整理从 3 小时缩到 20 分钟下一篇不装 Steam 客户端也能拿创意工坊模组WorkshopDL 上手实测与选型建议创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考