contract

type AdaptHandler ¶

type AdaptHandler[Q, B, R any] = func(context.Context, Q, B) (R, error)

AdaptHandler 统一 Handler 模板：

func(ctx context.Context, query Q, body B) (resp R, err error)

type Empty ¶

type Empty any

Empty 无响应数据的操作使用该类型占位（序列化为 data: null）

type FieldMeta ¶

type FieldMeta struct {
	Index    int
	Kind     reflect.Kind
	Path     string
	Query    string
	Form     string
	Header   string
	Def      string      // default 标签：绑定缺失时的运行时默认值（与文档 default 同步生效）
	Children []FieldMeta // 内嵌结构体递归展平
}

FieldMeta 绑定字段元数据（挂载期解析一次，请求期零反射）。 与框架无关：path/query/form/header/default 标签由各框架适配器按同一语义消费， 框架侧只保留"从请求取原始值"的取值函数（如 gin 的 c.Query / echo 的 c.QueryParam）。

func ParseFields(t reflect.Type) []FieldMeta

type FileStream ¶

type FileStream struct {
	Name        string // 下载文件名（Content-Disposition）
	Size        int64  // 内容长度
	ContentType string // 如 application/octet-stream、text/plain
	Reader      io.Reader
}

FileStream 二进制下载响应。运行时适配器识别该类型后直接输出流， 数据源可以是文件、go:embed 内存数据或任何 io.Reader（见 app/handlers/file.go 示例）。

type Group ¶

type Group struct {
	Prefix      string
	Description string
	Tags        []string
	Middlewares []any // 框架中间件函数；名字由反射派生（见 FuncName），文档侧按名匹配钩子
	Routes      []Route
	Children    []*Group
}

Group 路由分组（树形）：对应 gin.RouterGroup / echo.Group 的嵌套模型。

• Prefix 为空表示根组
• 组内 Route.Path 为相对组前缀的路径（列表路由用 "" 表示组根）
• Middlewares 沿树向子组继承（运行时与文档生成行为一致）
• 文档侧 Tags 合并：组 Tags + 路由 Tags

type InTransformer ¶

type InTransformer interface {
	InTransform(context.Context) error
}

InTransformer 入参转换接口：Q/B 绑定完成后、校验之前被适配器自动调用。 用于规范化输入（trim、大小写归一、默认值填充）；返回错误将短路请求。

实现建议使用指针接收者（与 B 的绑定值一致，修改直接生效）：

func (r *CreateUserReq) InTransform(ctx context.Context) error {
    r.Name = strings.TrimSpace(r.Name)
    return nil
}

type NoReq ¶

type NoReq any

NoReq 无入参的 Handler 使用该类型占位

type OutTransformer ¶

type OutTransformer interface {
	OutTransform(context.Context) error
}

OutTransformer 出参转换接口：Handler 返回后、序列化之前被适配器自动调用。 用于输出加工（脱敏、裁剪字段、补充计算字段）；返回错误将短路请求。

建议使用指针接收者；值接收者也可用（只读场景），但修改不会写回：

func (u *User) OutTransform(ctx context.Context) error {
    u.Password = "******"
    return nil
}

type ParamBinder ¶

type ParamBinder func(src []string) (any, error)

ParamBinder 把 query/path/header 的原始字符串解析为字段值。 src：原始值列表（单值参数长度 1；重复参数 ?ids=1&ids=2 与逗号串由实现自行处理）。 返回值必须可赋给字段声明类型；错误建议使用 StatusError（如 NotFound/BadRequest）， 会汇入统一错误链（HTTP 状态码 + 响应壳）。

注册方式（通常在 init 或装配阶段）：

contract.RegisterParamBinder(func(src []string) (IDs, error) { ... })

func BinderFor(t reflect.Type) (ParamBinder, bool)

type Response ¶

type Response[R any] struct {
	Status  int
	Headers map[string]string
	Cookies []*http.Cookie
	Data    R
}

Response 响应定制壳：业务层返回 contract.Response[R] 时， 适配器应用 Status/Headers/Cookies 后，Data 仍走统一 envelope {code, data, msg}。 例：return contract.Response[handlers.User]{Status: 201, Headers: ..., Data: u}, nil

func (r Response[R]) ResponseCookies() []*http.Cookie

func (r Response[R]) ResponseData() any

func (r Response[R]) ResponseHeaders() map[string]string

func (r Response[R]) ResponseStatus() int

type ResponseWrapper ¶

type ResponseWrapper interface {
	ResponseStatus() int
	ResponseHeaders() map[string]string
	ResponseCookies() []*http.Cookie
	ResponseData() any
}

ResponseWrapper 适配器识别接口：泛型实例通过该接口被统一处理

type Route ¶

type Route struct {
	Method            string
	Path              string
	Summary           string
	Description       string
	Tags              []string
	DefaultStatusCode int
	Deprecated        bool
	Envelope          response.Envelope
	Handler           any // func(context.Context, Q, B) (R, error)
}

Route 路由表条目（非泛型；Handler 由适配器通过反射消费，Q/B/R 泛型信息由 New 在构造期保证）

func New[Q, B, R any](m RouteMeta[Q, B, R]) Route

type RouteMeta ¶

type RouteMeta[Q, B, R any] struct {
	Method      string
	Path        string
	Summary     string
	Description string
	Tags        []string
	// DefaultStatusCode 成功响应默认 HTTP 状态码；0 → 200。
	// 动态覆盖优先级：contract.Response[R].Status > DefaultStatusCode > 200。
	// OpenAPI 文档生成器读取该值作为成功响应码（替代硬编码 200）。
	DefaultStatusCode int
	// Deprecated 弃用标记（运行时+文档共用层）：
	// 文档生成 op.Deprecated=true；运行时后续可在 dev 模式对弃用接口打日志。
	Deprecated bool
	// Envelope 路由级响应壳；nil → 服务级默认壳（server.SetEnvelope）。
	// 文档侧壳 schema 用 openapi.OptionWithEnvelopeSchema 配对配置。
	Envelope response.Envelope
	Handler  AdaptHandler[Q, B, R]
}

RouteMeta 路由注册描述（强类型）。 鉴权等中间件效果不在本结构声明：中间件挂载在所属 Group（见 Group.Middlewares）， 文档标注由 internal/openapi 按中间件函数名匹配文档钩子（RegisterMiddlewareDoc）。

type Server ¶

type Server interface {
	Mount(g any, groups []*Group)
}

Server 运行时适配器接口规范：各框架适配器（servergin / serverecho） 提供具体实现，业务装配层面向该接口编程时可互换适配器。 作为 server 实现的示范存在：适配器可参考其形态提供自己的 Mount 签名。

type StatusCoder ¶

type StatusCoder interface {
	error
	StatusCode() int
}

StatusCoder 最小契约：任何错误实现该接口即可携带 HTTP 状态码。 适配器错误路径按优先级识别：StatusError → StatusCoder → SetErrorMapper 全局映射

type StatusError ¶

type StatusError struct {
	Status int
	Code   int
	Msg    string
	Err    error
}

StatusError 携带状态码/业务码/对外信息的错误。 业务层直接返回：return nil, contract.NotFound("用户不存在")

字段规则：

• Status：HTTP 状态码；0 视为未设置，StatusCode() 兜底 500
• Code：业务码；0 视为未设置，适配器沿用默认约定 （HTTP 200 → 默认业务错误码；非 200 → 跟随状态码，与现有 ErrNotFound 映射一致）
• Msg：对外错误信息；空则回退 err.Error()
• Err：内部错误（不对外暴露），支持 errors.Unwrap 链路穿透

func (e *StatusError) Error() string

func (e *StatusError) StatusCode() int

func (e *StatusError) Unwrap() error