route.go
experimental
使用 route.go 文件约定构建实验性 Go API 端点的 API 参考。
route.go 使用 Go 的 net/http 请求和响应 API 在 App Router 中定义一个 Go Route Handler(API 端点)。
package main
import (
"encoding/json"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"message": "Hello from Go!"})
}小知识:
- Go Route Handlers 需要
experimental.goRoutes和 Turbopack。不支持 Webpack。- Go Route Handlers 始终动态执行。JavaScript 路由段配置、ISR 和
generateStaticParams不适用。- Go 处理程序以编译后的可执行文件形式运行。JavaScript 和 TypeScript 处理程序、React 渲染以及 Pages Router 页面继续使用 Node.js。
设置#
在 Next.js 配置中启用该实验性功能:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: { goRoutes: true },
}
export default nextConfigmodule.exports = {
experimental: { goRoutes: true },
}在 PATH 上安装 Go 1.24 或更高版本,或将 TURBOPACK_GO 设置为其可执行文件路径。next dev 和 next build 需要 Go。next start 无需 Go 编译器即可运行编译后的可执行文件。没有 Go 处理程序的应用程序不需要 Go。
参考#
HTTP 方法#
定义名为 GET、POST、PUT、PATCH、DELETE、HEAD 或 OPTIONS 的顶层函数。每个函数处理相应的 HTTP 方法,遵循与 route.ts 相同的方法约定。
每个函数必须按顺序接受 http.ResponseWriter 和 *http.Request,且不返回任何值。Go 编译器在编译路由时会验证函数签名。
| 方法 | 行为 |
|---|---|
| 存在匹配函数的方法 | 调用该函数。 |
没有 HEAD 函数的 HEAD | 如果定义了 GET,则以 r.Method == "HEAD" 调用 GET。HTTP 服务器会抑制响应体字节。否则,返回 405。 |
没有 OPTIONS 函数的 OPTIONS | 返回 204,并带有按字母顺序排序的 Allow 标头,列出支持的方法,包括 OPTIONS,以及在定义 GET 时的 HEAD 回退。 |
| 其他没有匹配函数的方法 | 返回 405。 |
例如,定义了 GET 和 POST 的路由会自动以 Allow: GET, HEAD, OPTIONS, POST 响应 OPTIONS。定义 HEAD 或 OPTIONS 可覆盖其自动实现。
参数#
w http.ResponseWriter#
使用 w 通过 Go 的 net/http API 写入响应:
w.Header()设置响应标头,包括Content-Type和Set-Cookie。w.WriteHeader(status)设置 HTTP 状态。如果没有显式状态,第一次写入响应体时会发送200。w.Write(body)写入响应体字节。
在调用 WriteHeader 或写入响应体之前设置标头。使用 http.Flusher 实现流式传输。
r *http.Request#
使用 r 读取传入的请求:
| API | 行为 |
|---|---|
r.Method | 读取 HTTP 方法。 |
r.PathValue("id") | 读取经过解码的动态参数。捕获所有(catch-all)段会用 / 连接。 |
r.URL.Query() | 读取查询参数,包括重复的值。 |
r.Header, r.Cookie() | 在 Next.js proxy 处理后读取传入的标头和 cookie。 |
r.Body | 读取流式请求体。 |
r.Context().Done() | 在客户端断开连接时观察取消信号。 |
在开发和自托管部署中,Next.js 会在路由、重写和 proxy.ts 处理之后选择处理程序。处理程序接收最终的目标 URL,包括其查询参数和任何 basePath。例如,被重写为 /users/123 的 /alias?sort=asc 到达 Go 时为 /users/123?sort=asc。r.URL、r.RequestURI 和动态参数都反映该目标。
ParamValues#
Next.js 在路由包中生成一个辅助函数,用于读取单个解码后的参数值:
package main
import (
"encoding/json"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(ParamValues(r, "slug"))
}ParamValues(r, name) 返回一个 []string。对于单个动态段,它返回一个值;对于捕获所有段,它返回各个值;对于不存在的参数,它返回 nil。
| 路由 | URL | r.PathValue("slug") | ParamValues(r, "slug") |
|---|---|---|---|
app/items/[slug]/route.go | /items/a | "a" | []string{"a"} |
app/blog/[...slug]/route.go | /blog/a/b | "a/b" | []string{"a", "b"} |
app/blog/[...slug]/route.go | /blog/a%2Fb/c | "a/b/c" | []string{"a/b", "c"} |
app/blog/[[...slug]]/route.go | /blog | "" | nil |
当你需要区分段内编码的斜杠与捕获所有段之间的分隔符时,请使用 ParamValues。
处理程序约定#
每个路由目录都是一个可执行的 package main。方法函数可以在 route.go 或同级的已编译 .go 文件中声明。Next.js 会生成方法分发和 main 函数。请勿自行定义 main 或创建 zz_next_route_*.go 文件,这些文件保留给生成的代码使用。
除 _test.go 之外的所有同级 .go 文件都会与 route.go 一起编译,且必须使用 package main。平台相关的文件名后缀和构建约束不会筛选这些同级文件。请将依赖于平台的实现放在导入的包中,由 Go 应用其常规的选择规则。共享包可以使用普通的模块导入,包括 internal 包。
直接使用 go run 和 go test 不会注入生成的包装器或 ParamValues 辅助函数。请通过 Next.js 运行路由以测试其集成。路由目录名称中的方括号和圆括号无需作为 Go 导入路径。
Go 路由支持 app、src/app、路由组和动态段。Go 处理程序不能与其他 Route Handler 或页面共享其 URL。
开发与错误处理#
Turbopack 会跟踪路由源文件、同级文件、本地导入的包、模块元数据和嵌入的资源。编辑会触发重新编译。编译失败会产生错误,而不是提供上一次成功的可执行文件。修复源代码后,后续请求即可恢复。
未更改的请求会复用已编译的进程。重新构建后,新请求使用替代进程,而在途请求可以在有限时间内于旧进程上完成。如果进程意外退出,活动请求会失败,后续请求会重新启动它。在开发环境中,启动失败会被缓存,直到源代码更改或服务器重启。在生产环境中,后续请求会重试失败的启动。
处理程序发生 panic 会中止其 HTTP 连接。只有在尚未发送响应标头时才能发送错误响应。
示例#
Cookies#
使用 r.Cookie 读取 cookie,并在写入响应前使用 http.SetCookie 设置它们:
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
theme := "light"
if cookie, err := r.Cookie("theme"); err == nil {
theme = cookie.Value
}
fmt.Fprint(w, theme)
}
func POST(w http.ResponseWriter, r *http.Request) {
http.SetCookie(w, &http.Cookie{
Name: "theme",
Value: "dark",
Path: "/",
HttpOnly: true,
SameSite: http.SameSiteLaxMode,
})
w.WriteHeader(http.StatusNoContent)
}要删除 cookie,请设置一个具有相同名称和路径且 MaxAge 为负数的 cookie。
Headers#
使用 r.Header.Get 读取请求标头,使用 w.Header().Set 设置响应标头:
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
w.Header().Set("Vary", "Accept-Language")
fmt.Fprint(w, r.Header.Get("Accept-Language"))
}使用 w.Header().Add 追加多个值,包括多个 Set-Cookie 标头。
重定向#
使用 http.Redirect 并提供目标地址和状态:
package main
import "net/http"
func GET(w http.ResponseWriter, r *http.Request) {
http.Redirect(w, r, "/login", http.StatusTemporaryRedirect)
}动态路由段#
使用 r.PathValue 读取动态段:
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Item %s", r.PathValue("slug"))
}对于 /items/a,r.PathValue("slug") 返回 "a"。对于捕获所有和可选捕获所有路由,请参阅 ParamValues。
URL 查询参数#
使用 r.URL.Query() 读取查询参数。Get 返回第一个值;对 map 进行索引会返回该键的所有值。
package main
import (
"encoding/json"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
query := r.URL.Query()
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]any{
"query": query.Get("query"),
"tags": query["tag"],
})
}对于 /api/search?query=hello&tag=go&tag=next,响应包含 "query": "hello" 和 "tags": ["go", "next"]。
流式传输#
使用 http.Flusher 写入并刷新每个响应块。观察请求上下文,以便在客户端断开连接时停止工作:
package main
import (
"fmt"
"net/http"
"time"
)
func GET(w http.ResponseWriter, r *http.Request) {
flusher, ok := w.(http.Flusher)
if !ok {
http.Error(w, "Streaming unavailable", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
ticker := time.NewTicker(200 * time.Millisecond)
defer ticker.Stop()
for i := 0; i < 3; i++ {
select {
case <-r.Context().Done():
return
case <-ticker.C:
if _, err := fmt.Fprintf(w, "Chunk %d\n", i+1); err != nil {
return
}
flusher.Flush()
}
}
}部署平台可能会应用其自己的缓冲和超时限制。
请求体#
使用 json.NewDecoder 解码 JSON 请求体:
package main
import (
"encoding/json"
"net/http"
)
func POST(w http.ResponseWriter, r *http.Request) {
var item struct {
Name string `json:"name"`
}
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
if err := json.NewDecoder(r.Body).Decode(&item); err != nil {
http.Error(w, "Invalid request body", http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(item)
}http.MaxBytesReader 限制处理程序读取的请求体字节数。
请求体 FormData#
使用 r.ParseMultipartForm 读取 multipart 表单数据。其参数限制保存在内存中的文件数据;使用 http.MaxBytesReader 限制请求体总大小。
package main
import "net/http"
func POST(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
if err := r.ParseMultipartForm(1 << 20); err != nil {
http.Error(w, "Invalid form data", http.StatusBadRequest)
return
}
defer r.MultipartForm.RemoveAll()
name := r.FormValue("name")
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
w.Write([]byte(name))
}对于 URL 编码的表单,请改用 r.ParseForm。
CORS#
在响应上设置 CORS 标头。当预检响应需要这些标头时,请显式定义 OPTIONS;自动的 OPTIONS 响应只提供 Allow。
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
setCORSHeaders(w)
fmt.Fprint(w, "Hello from Go!")
}
func OPTIONS(w http.ResponseWriter, r *http.Request) {
setCORSHeaders(w)
w.WriteHeader(http.StatusNoContent)
}
func setCORSHeaders(w http.ResponseWriter) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
}要为多个路由设置 CORS 标头,请使用 Proxy 或 next.config headers。
Webhooks#
在验证 webhook 签名之前读取原始请求体。JSON 解码可能会改变提供方签名的表示形式。
package main
import (
"io"
"net/http"
)
func POST(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "Invalid webhook body", http.StatusBadRequest)
return
}
// 在处理事件之前,根据 body 验证提供方的签名。
_ = body
w.WriteHeader(http.StatusNoContent)
}Go 处理程序直接读取 r.Body,不使用 Pages Router 的 bodyParser 配置。
非 UI 响应#
设置内容类型并写入响应体,以返回 XML 或其他非 UI 内容:
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/rss+xml; charset=utf-8")
fmt.Fprint(w, `<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"><channel>
<title>My Blog</title>
<link>https://example.com</link>
<description>Latest posts</description>
</channel></rss>`)
}共享响应逻辑#
方法函数可以调用未导出的辅助函数,同时设置不同的响应状态:
package main
import (
"fmt"
"net/http"
)
func GET(w http.ResponseWriter, r *http.Request) {
writeUser(w, r, http.StatusOK)
}
func POST(w http.ResponseWriter, r *http.Request) {
writeUser(w, r, http.StatusCreated)
}
func writeUser(w http.ResponseWriter, r *http.Request, status int) {
w.WriteHeader(status)
fmt.Fprintf(w, "User %s", r.PathValue("id"))
}路由段配置选项#
Go Route Handlers 始终动态执行。诸如 dynamic、revalidate、fetchCache 和 runtime 之类的 JavaScript 导出不会配置 Go 处理程序。Go 路由不支持 ISR、generateStaticParams、Server Actions 和 React 执行。
部署#
对于自托管,请使用 Turbopack 的 next build 和 next start。在同一操作系统和架构上迁移构建产物时,请复制完整的 .next 输出,并保留 .next/server/app 下的可执行权限。每个原生描述符都有一个 .native.json.nft.json 跟踪文件,列出其可执行文件。不支持静态导出和 output: 'standalone'。
Go Route Handlers 没有构建时预渲染模式,因此无法为 output: 'export' 生成静态响应文件。
适配器部署需要支持 runtime: 'go' 的适配器。有关打包和 HTTP 服务器契约,请参阅 Go 适配器产物和调用 Go 入口点。部署平台负责路由、重写和 proxy 执行。响应完成后执行的工作没有任何完成保证。
构建和运行时限制#
- 不支持 WebSocket 升级和 HTTP trailer。
- 运行时文件读取不会被跟踪。对于随 Go 处理程序一起提供的资源,请使用
go:embed。 - Go 处理程序读取进程环境变量。
next.config的环境变量内联不适用。 - Go 构建以构建主机的操作系统和架构为目标,并禁用 CGO。构建环境必须与部署运行时匹配。
- 依赖项必须在禁用 CGO 的情况下构建,并且已经下载到所选工具链的模块缓存中。构建不会下载依赖项,也不会修改
go.mod或go.sum。 - 不支持 Go 工作区、模块替换、vendor、源码符号链接和交叉编译。
- 同一实验性功能会启用
proxy.go。不支持 Go Pages API 路由、page.go和layout.go。
Go 路由支持 Turbopack 的文件系统缓存和 Go 的构建缓存。未更改的可执行文件可以跨服务器或构建进程复用。源文件、依赖项、嵌入的资源、生成的包装器、工具链设置和编译目标都会参与失效判断。