encore-go-api

用途

encore-go-api 是一份面向 Encore Go 的 API 端点编写规范，用于指导开发者使用 //encore:api 注解在 Go 函数上定义类型化的 HTTP API 端点。它适用于使用 Encore Go 框架构建后端服务的场景，帮助统一端点的声明方式、参数来源和错误返回。

主要能力

基础端点定义

在函数上方使用 //encore:api 注解声明端点，请求参数为结构体指针，响应为结构体指针，错误作为最后一个返回值。示例：

//encore:api public method=GET path=/users/:id
func GetUser(ctx context.Context, params *GetUserParams) (*User, error) {
    return &User{ID: params.ID, Email: "user@example.com", Name: "John"}, nil
}

注解选项

注解支持以下选项：

public：可从外部访问
private：仅可被其他服务调用
auth：需要认证
method：HTTP 方法，取值 GET、POST、PUT、PATCH、DELETE
path：URL 路径，使用 :param 表示路径参数
sensitive：从追踪中隐藏请求/响应负载

示例：

//encore:api public method=GET path=/health
//encore:api private method=POST path=/internal/process
//encore:api auth method=GET path=/profile
//encore:api public sensitive method=POST path=/auth/login

请求参数来源

路径参数：路径中的 :id 会自动按名称映射到结构体字段。
查询参数：使用 query 标签，如 Limit int query:"limit"``。
请求头：使用 header 标签，如 Signature string header:"X-Webhook-Signature"``。
Cookie：使用 cookie 标签，类型为 *http.Cookie，如 SessionCookie *http.Cookie cookie:"session"``。

响应类型

标准响应：返回结构体指针。
无响应体：仅返回 error。
无请求参数：函数签名中省略 params。

错误处理

使用 encore.dev/beta/errs 包返回规范的 HTTP 错误响应：

return nil, &errs.Error{
    Code:    errs.NotFound,
    Message: "user not found",
}

常见错误码：

errs.NotFound：404，资源不存在
errs.InvalidArgument：400，输入错误
errs.Unauthenticated：401，缺少或无效认证
errs.PermissionDenied：403，不允许访问
errs.AlreadyExists：409，资源重复

敏感数据

可用 encore:"sensitive" 标签标记单个字段，或在注解中标记整个端点为 sensitive，使请求与响应在追踪中被脱敏。

type LoginParams struct {
    Email    string `json:"email"`
    Password string `json:"password" encore:"sensitive"`
}

自定义 HTTP 状态码

使用 encore:"httpstatus" 标签返回自定义状态码：

type CreateResponse struct {
    ID     string `json:"id"`
    Status int    `encore:"httpstatus"`
}

使用方式

在 Encore Go 项目中，按上述模式在函数上添加 //encore:api 注解，并定义对应的请求/响应结构体与标签。框架会依据注解自动完成路由与参数绑定。

适用场景

适用于使用 Encore Go 构建后端服务、需要声明类型化 HTTP API 端点的开发场景，包括公开接口、服务间私有接口、需认证接口以及需要脱敏处理的接口。

限制

请求参数必须为结构体指针或省略；响应必须为结构体指针或省略（无响应体）；错误必须作为最后一个返回值。资料未提供其他限制、收费、价格或平台信息。