handler

Overview ¶

Package handler 提供声明式 HTTP handler 包装器:把 auth 策略 + 资源注入 + 错误归一化从业务 handler 上移到包装器,handler 只关心 (ctx, req) => (resp, error)。

声明式声明"这个 handler 需要什么"(认证策略、依赖),由包装器统一注入, 业务函数保持纯净——只接收 ctx 和解析好的请求,返回响应或 error。

这其实是 pkg/callbacks + pkg/middleware/auth + pkg/afterwork + DI 组合成一个 ergonomic 的 handler 装饰器:

• WithAuth(policy):在调业务函数前做认证/授权,User 注入 ctx;
• WithInject(deps):把任意依赖(DB、cache、client...)装入 ctx 供 handler 取;
• WithAfterwork:挂上 afterwork.Middleware,handler 里 afterwork.Defer(...) 投递的响应后副作用在响应返回后跑完;
• WithRatelimit:声明式限流;
• WithMiddleware:挂任意标准中间件(func(http.Handler) http.Handler)于最外层—— 核心不依赖 contrib,故可即插即用如 contrib/wasm 的过滤器等;
• 返回的 error 自动经 errors.WriteHTTP 归一化为统一错误响应。

用法:

type CreateOrderReq struct { UserID string; Sku string }
type CreateOrderResp struct { OrderID string }

h := handler.New[CreateOrderReq, CreateOrderResp](
    "POST /orders",
    func(ctx context.Context, req *CreateOrderReq) (*CreateOrderResp, error) {
        user := auth.GetUserFromContext(ctx)      // 认证后注入
        db := handler.MustGet[*sql.DB](ctx, "db") // 依赖注入
        id, err := createOrder(ctx, db, user.ID(), req.Sku)
        if err != nil { return nil, err }
        afterwork.Defer(ctx, func(c context.Context) { // 响应后副作用
            _ = webhook.Notify(c, orderEvent{id})
        })
        return &CreateOrderResp{OrderID: id}, nil
    },
    handler.WithAuth(authPolicy),
    handler.WithInject("db", orderDB),
    handler.WithAfterwork(),
)
mux.Handle("/orders", h)

泛型参数 I 是请求体类型(指针),O 是响应体类型(指针),均通过 JSON 编解码。 请求方法固定为方法字段(Method);query/path 参数由调用方自行从 *http.Request 取(本包装器只管 body + auth + error + 响应后副作用)。