NNext.js 中文网 GitHub

route.go

experimental

使用 route.go 文件约定构建实验性 Go API 端点的 API 参考。

route.go 使用 Go 的 net/http 请求和响应 API 在 App Router 中定义一个 Go Route Handler(API 端点)。

app/api/hello/route.go
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 配置中启用该实验性功能:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: { goRoutes: true },
}

export default nextConfig
next.config.js
module.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 在路由包中生成一个辅助函数,用于读取单个解码后的参数值:

app/blog/[...slug]/route.go
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。

路由URLr.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 设置它们:

app/api/cookies/route.go
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 设置响应标头:

app/api/headers/route.go
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 并提供目标地址和状态:

app/api/redirect/route.go
package main

import "net/http"

func GET(w http.ResponseWriter, r *http.Request) {
  http.Redirect(w, r, "/login", http.StatusTemporaryRedirect)
}

动态路由段#

使用 r.PathValue 读取动态段:

app/items/[slug]/route.go
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 进行索引会返回该键的所有值。

app/api/search/route.go
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 写入并刷新每个响应块。观察请求上下文,以便在客户端断开连接时停止工作:

app/api/stream/route.go
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 请求体:

app/items/route.go
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 限制请求体总大小。

app/api/form/route.go
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。

app/api/cors/route.go
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 解码可能会改变提供方签名的表示形式。

app/api/webhook/route.go
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 内容:

app/rss.xml/route.go
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>`)
}

共享响应逻辑#

方法函数可以调用未导出的辅助函数,同时设置不同的响应状态:

app/users/[id]/route.go
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 的构建缓存。未更改的可执行文件可以跨服务器或构建进程复用。源文件、依赖项、嵌入的资源、生成的包装器、工具链设置和编译目标都会参与失效判断。

Next.js 中文网