Documentation
¶
Overview ¶
Package api 装配 huma：三平面分组、OpenAPI 配置、错误模型桥接与分页约定。
所有 REST 接口都经 huma.Register 注册：请求校验、problem+json 与 OpenAPI 3.1 由代码直接生成，模块不再直接接触 chi 路由。
Index ¶
Constants ¶
const ( // PrefixConsole 需会话或 PAT + 权限校验。 PrefixConsole = "/api/v1/console" // PrefixPublic 匿名只读已发布内容 + 发评论 + 搜索。 PrefixPublic = "/api/v1/public" // PrefixExtension 是 Extension 通用 CRUD，v1 内部使用。 PrefixExtension = "/apis" )
三平面路由前缀。
const ( // OpenAPIPath 加扩展名即规范地址：/api/openapi.json（3.1）与 /api/openapi-3.0.json（降级）。 OpenAPIPath = "/api/openapi" // DocsPath 是交互式文档页面。 DocsPath = "/api/docs" // SchemasPath 下按名称提供各 JSON Schema。 SchemasPath = "/api/schemas" )
规范与文档端点。放在 /api 下，避免与主题的路由空间冲突。
const ( SecuritySession = "session" SecurityBearer = "bearer" )
OpenAPI 安全方案名，供文档标注受保护的操作。
const ( // DefaultPageSize 是未指定 size 时的每页条数。 DefaultPageSize = 20 // MaxPageSize 是每页条数上限，防止一次拉取拖垮数据库。 MaxPageSize = 100 )
分页约定：v1 用 offset 分页，Console 表格需要跳页。
Variables ¶
This section is empty.
Functions ¶
func HTTPMiddleware ¶
func HTTPMiddleware(mw Middleware) func(huma.Context, func(huma.Context))
HTTPMiddleware 把标准 net/http 中间件适配为 huma 中间件。
阶段 2 已测试过的鉴权、CSRF 等中间件因此可以原样复用。中间件内部写出的响应 （如 401）直接送达客户端，huma 链随之终止；中间件放行时，它写入 context 的值 （如 Principal）随请求带回 huma 上下文，处理器经 ctx.Context() 可见。
限制：中间件不得替换 ResponseWriter（如包一层记录字节数的封装）， 因为后续写响应仍走 huma 持有的原始 writer。
Types ¶
type Options ¶
type Options struct {
// Title 与 Version 写入 OpenAPI 的 info。
Title string
Version string
// Resolve 解析凭据并注入 context，但不强制已认证；nil 表示不挂鉴权（仅用于测试骨架）。
Resolve Middleware
// CSRF 校验非安全方法的 CSRF 令牌。
CSRF Middleware
// RequireAuth 要求请求已认证。
RequireAuth Middleware
}
Options 是构造三平面所需的依赖。
type Page ¶
type Page[T any] struct { Items []T `json:"items" doc:"当前页的条目"` Page int `json:"page" doc:"当前页码"` Size int `json:"size" doc:"每页条数"` Total int `json:"total" doc:"总条数"` }
Page 是统一的分页响应体。
type PageParams ¶
type PageParams struct {
Page int `query:"page" default:"1" minimum:"1" doc:"页码，从 1 开始"`
Size int `query:"size" default:"20" minimum:"1" maximum:"100" doc:"每页条数，最大 100"`
}
PageParams 是统一的分页入参，嵌入到列表操作的输入结构体中即可。
func (PageParams) Normalize ¶
func (p PageParams) Normalize() PageParams
Normalize 把零值补成默认值，供绕过 huma 校验的调用路径使用。
type Planes ¶
type Planes struct {
// contains filtered or unexported fields
}
Planes 持有三平面的 huma 分组，实现 app.Router。
func NewPlanes ¶
NewPlanes 在根路由上创建 huma API 与三平面分组。
鉴权策略：
- Console：解析凭据 + CSRF + **强制已认证**；细粒度权限由各操作声明
- ConsolePublic：只解析凭据，仅供登录一类极少数免认证端点
- Public：解析凭据但不强制，匿名可读已发布内容；会话身份的写请求要过 CSRF
- Extension：解析凭据 + CSRF + 强制已认证
中间件挂在分组上，模块注册的每个操作自动继承，不存在「漏挂」的可能。 必须在根路由的全部 Use 之后调用：chi 不允许在注册路由后再添加中间件。
func (*Planes) ConsolePublic ¶
ConsolePublic 返回 Console 平面下免认证的注册面，仅供登录一类极少数端点。
Source Files