Encore 原始端点（Raw Endpoints）完全指南：在 Go 后端中直接操作 HTTP 请求-北京尧图网络

Encore 原始端点Raw Endpoints完全指南在 Go 后端中直接操作 HTTP 请求【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore本指南基于 Encore 官方 Go 文档 raw-endpoints.md深入讲解如何通过//encore:api public raw注解定义原始端点绕过 Encore 的类型化请求/响应封装直接访问底层http.ResponseWriter与*http.Request并配合仓库源码解析器校验、代码生成与运行时实现剖析其工作原理。读完本文你将掌握 raw endpoints 的定义方式、签名约束、路由规则、认证与安全注意事项以及它在接收 Webhook、处理 WebSocket 等场景下的落地用法。为什么要用 Raw EndpointsEncore 常规 API 端点Regular Endpoints提供了高度抽象化的开发体验函数签名只关心业务参数与返回值Encore 自动负责请求反序列化、响应序列化、路由匹配、参数校验等工作。但有些场景需要你降低抽象层级直接访问原始 HTTP 请求与响应。典型场景包括接收第三方服务如 GitHub、Stripe、Slack推送的Webhook这些回调往往带有自定义头部、签名校验或非 JSON 的请求体实现WebSocket升级握手需要直接操作http.ResponseWriter需要读取请求的原始字节流、自定义响应的每一个字节需要处理非标准 Content-Type 的请求体。对于这类需求Encore 提供了Raw Endpoints原始端点。定义一个 Raw Endpoint定义方式非常直观在普通函数上添加//encore:api注解并带上raw选项同时把函数签名改为标准的 Go HTTP handler 形式package service import net/http // Webhook receives incoming webhooks from Some Service That Sends Webhooks. //encore:api public raw func Webhook(w http.ResponseWriter, req *http.Request) { // ... operate on the raw HTTP request ... }有经验的 Go 开发者会立刻认出这就是一个标准的 Go HTTP handlerhttp.HandlerFunc。你可以完全按照net/http包的方式读取请求体、检查头部、向w写入响应。签名约束源码级校验虽然写法与net/http一致但 Encore 解析器会对签名做严格校验。在 v2/parser/apis/api/api.go 的initRawRPC函数中raw endpoint 的签名被限定为恰好两个参数且无返回值// Ensure signature is func(http.ResponseWriter, *http.Request). if !schemautil.IsNamed(params[0].Type, net/http, ResponseWriter) { errs.Add(errRawNotResponeWriter.AtGoNode(params[0].AST)) } if deref, n : schemautil.Deref(params[1].Type); n ! 1 || !schemautil.IsNamed(deref, net/http, Request) { errs.Add(errRawNotRequest.AtGoNode(params[1].AST)) }对应的编译期错误定义于 v2/parser/apis/api/errors.go包括违反规则错误提示参数数量不是 2Raw APIs must have a two parameters of type http.ResponseWriter and *http.Request, got %d parameters.声明了返回值Raw APIs must not return any results, got %d results.第一个参数不是http.ResponseWriterRaw APIs must have a first parameter of type http.ResponseWriter.第二个参数不是*http.RequestRaw APIs must have a second parameter of type *http.Request.这些错误还会附带统一的提示hint: signature must be func(http.ResponseWriter, *http.Request)并在编译阶段encore build/encore run直接报错而不是等到运行时才暴露问题。Raw 与 Private 的冲突需要注意一个限制raw endpoints 不能声明为 private。在 api.go 中有明确的检查逻辑if endpoint.Access Private endpoint.Raw { // We dont support private raw APIs for now. errs.Add(errRawEndpointCantBePrivate.AtGoNode(rawTag, ...)) return nil, false }对应错误为Private APIs cannot be declared as raw endpoints.见 errors.go。因此 raw endpoint 目前只支持public与auth两种访问级别。路由与 URL和其他 Encore API 端点一样raw endpoint 部署后同样会被暴露在统一的 URL 之下https://env-app-id.encr.app/service.Webhook路由规则也完全一致路径中默认使用函数名且支持:id参数段与*wildcard通配段。例如//encore:api public raw path/hooks/:id/* func Webhook(w http.ResponseWriter, req *http.Request) {}在解析器层面路径解析通过 api.go 中的resourcepaths.Parse完成并显式开启AllowWildcard与AllowFallback同时要求以/开头PrefixSlash: true。HTTP 方法默认值raw endpoint 如果没有显式指定method默认会匹配所有 HTTP 方法。在 api.go 中可以看到这个默认值逻辑if len(rpc.HTTPMethods) 0 { if rpc.Raw { rpc.HTTPMethods []string{*} } else { // For non-raw endpoints, if theres a request payload // default to POST-only. if rpc.Request ! nil { rpc.HTTPMethods []string{POST} } else { rpc.HTTPMethods []string{GET, POST} } } }这非常符合 Webhook 场景的需求——大多数 Webhook 服务商会用 POST 推送但你也可以在注解中通过method字段精确限定例如//encore:api public raw methodPOST。注意method值必须全部大写见 api.go 的 ALLCAPS 校验。路径测试用例佐证仓库的解析器测试 v2/parser/apis/api/api_test.go 验证了 raw endpoint 的完整解析结果{ name: raw, imports: []string{net/http}, def: //encore:api public raw path/raw func Raw(w http.ResponseWriter, req *http.Request) {} , want: Endpoint{ Name: Raw, Access: Public, Raw: true, HTTPMethods: []string{*}, }, },从中可以看到raw选项被正确解析、访问级别为public、HTTP 方法默认展开为*。底层实现从解析到运行的完整链路为了让读者更透彻地理解 raw endpoint 并非“黑魔法”下面结合仓库源码还原其完整生命周期。1. 注解解析在 api.go 中//encore:api指令的可选选项列表中包含了rawendpoint : Endpoint{ Raw: dir.HasOption(raw), } accessOptions : []string{public, private, auth} ok : directive.Validate(errs, dir, directive.ValidateSpec{ AllowedOptions: append([]string{raw, sensitive}, accessOptions...), AllowedFields: []string{path, method}, ... })raw与public/private/auth/sensitive一起作为合法选项被识别并通过HasOption(raw)设置Endpoint.Raw标志。2. 元数据标记在应用元数据生成阶段v2/app/legacymeta/legacymeta.goraw endpoint 会被标记为特殊的 RPC 类型if ep.Raw { rpc.Proto meta.RPC_RAW }这使得下游的代码生成器、API 文档与跟踪系统都能识别出这是一个原始端点。3. 代码生成在代码生成阶段v2/codegen/apigen/endpointgen/handlers.go为 raw endpoint 生成的 handler 是一个标准func(w http.ResponseWriter, req *http.Request)直接调用你的业务函数func (h *handlerDesc) Raw() *Statement { ep : h.ep if !ep.Raw { return Nil() } return Func().Params( Id(w).Qual(net/http, ResponseWriter), Id(req).Op(*).Qual(net/http, Request), ).BlockFunc(func(g *Group) { // If we have a service struct, initialize it first. if ss, ok : h.svcStruct.Get(); ok ep.Recv.Present() { g.List(Id(svc), Id(initErr)).Op(:).Add(ss.Qual()).Dot(Get).Call() g.If(Id(initErr).Op(!).Nil()).Block( Qual(encore.dev/beta/errs, HTTPErrorWithCode).Call(Id(w), Id(initErr), Lit(0)), Return(), ) fnExpr Id(svc).Dot(ep.Name) } else { fnExpr Id(ep.Name) } g.Add(fnExpr).Call(Id(w), Id(req)) }) }注意这段代码揭示了一个细节如果函数定义在带服务结构体的服务中Encore 会先通过svc.Get()初始化服务结构体再调用结构体上的方法初始化失败时通过encore.dev/beta/errs的HTTPErrorWithCode直接向响应流写错误。4. 运行时分发运行时层面runtimes/go/appruntime/apisdk/api/handler.go通过Desc结构区分两种端点// If raw is true, RawHandler is set and AppHandler and EncodeResp are nil. Raw bool RawHandler func(http.ResponseWriter, *http.Request)请求到达时运行时根据d.Raw分流见 handler.goif d.Raw { respCapturer newRawResponseCapturer(c.w, c.req) return d.invokeHandlerRaw(mwReq, c, respCapturer) } else { return d.invokeHandlerNonRaw(mwReq, reqData, d.AppHandler) }invokeHandlerRaw的实现handler.go会将你的处理函数包装成http.HandlerFunc直接执行——不做请求体反序列化、不做响应体序列化一切交给你的代码自行处理func (d *Desc[Req, Resp]) invokeHandlerRaw(mwReq middleware.Request, c IncomingContext, capturer *rawResponseCapturer) (mwResp middleware.Response) { ... capturer.InvokeHandler(http.HandlerFunc(d.RawHandler), httpReq) ... }同时raw endpoint 不参与 service-to-service 的内部调用——从代码中可以看到TODO: we dont currently support service-to-service calls of raw endpoints的注释handler.go对应的编译期错误为Raw APIs cannot be called from within an Encore application.见 errors.go。5. 流量捕获即使对于 raw endpointEncore 的追踪系统依然会尝试捕获请求与响应的原始内容用于开发面板展示。相关限制定义在 runtimes/go/appruntime/apisdk/api/capture.go// MaxRawRequestCaptureLen is the maximum buffer size to keep for // capturing the request body in the Encore development dashboard. MaxRawRequestCaptureLen 10 10 // 10 KiB MaxRawResponseCaptureLen 100 10 // 100 KiB即请求体最多捕获 10 KiB、响应体最多捕获 100 KiB超出部分会被截断避免大流量撑爆内存。实战接收 Webhook回到最初的动机——接收 Webhook。一个完整的例子如下package webhooks import ( encoding/json io net/http ) // GitHubWebhook receives push events from GitHub. //encore:api public raw methodPOST func GitHubWebhook(w http.ResponseWriter, req *http.Request) { // 1. 校验签名例如 X-Hub-Signature-256 // 2. 读取并解析请求体 body, err : io.ReadAll(req.Body) if err ! nil { http.Error(w, failed to read body, http.StatusBadRequest) return } defer req.Body.Close() var event map[string]any if err : json.Unmarshal(body, event); err ! nil { http.Error(w, invalid JSON, http.StatusBadRequest) return } // 3. 处理业务逻辑…… // 4. 向 Webhook 服务商返回 2xx 确认接收 w.WriteHeader(http.StatusOK) }由于函数签名为标准的 Go handler你可以在函数体内自由地用req.Header.Get(...)读取签名头并验证请求来源用req.URL.Query()解析查询参数用io.ReadAll(req.Body)/json.Decoder读取请求体用w.Header().Set(...)设置响应头w.WriteHeader(...)控制状态码直接w.Write(...)写响应体甚至执行 WebSocket 升级http.Hijacker等标准手段。关于接收 Webhook 与 WebSockets 的更多进阶内容包括对 Webhook 请求的加密签名验证可继续阅读 receiving regular HTTP requests guide。另外Encote 官方 Slack Bot 示例应用就是使用 raw endpoints 接收 Webhook 的典型参考实现。关键注意事项小结要点说明注解写法//encore:api public raw可再叠加methodPOST、path...函数签名func(w http.ResponseWriter, req *http.Request)不允许返回值访问级别仅支持public和auth不支持 privateHTTP 方法默认*全部方法可用method字段限定必须全大写路由能力支持:param与*wildcard路径段内部调用不能在 Encore 应用内部以 service-to-service 方式调用序列化Encore 不做任何请求/响应自动编解码全部由你的代码处理流量捕获开发面板最多捕获 10 KiB 请求体 / 100 KiB 响应体总结Raw Endpoints 是 Encore 在“抽象”与“控制”之间提供的灵活性出口当类型化的 API 封装无法满足 Webhook、WebSocket 等特殊场景时只需在注解中加一个raw选项即可把端点变成标准的 Go HTTP handler获得对 HTTP 层的完全控制权。从仓库源码可以看到这一能力从解析器签名校验、代码生成到运行时分发都有完整且严格的实现支撑既保留了 Encore 统一路由、统一 URL、自动部署与追踪的优势又不牺牲 Go 开发者熟悉的net/http编程体验。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Encore 原始端点（Raw Endpoints）完全指南：在 Go 后端中直接操作 HTTP 请求

相关推荐

PyTorch ResNet18 在 CIFAR-10 上复现 95.4% 准确率的工程实践

MQ、工作流引擎与分布式调度全解析：从选型到组合落地

Instructor 简单对象提取模式：用 Pydantic 定义 Schema，把非结构化文本转为类型安全的结构化对象

更多资讯

【NebulaGraph】NebulaGraph 各个服务组件（Metad, Storaged, Graphd）的关键配置文件有哪些？核心参数如何调优？

彻底清除TraffMonetizer和PacketStream：带宽劫持程序手动清理指南

三步实现安卓投屏：escrcpy完整上手实操指南

告别手动复制：文件夹同步备份与FreeFileSync实战指南

Hallmark 的边界：contract.md 如何定义 taste 技能不做什么（完整解读）

Encore 原始端点（Raw Endpoints）完全指南：在 Go 后端中直接操作 HTTP 请求

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？