webiris

Documentation

Index

• Constants
• func AccessLog(ctx iris.Context)
• func CORS(allowedOrigins ...string) iris.Handler
• func Fail(ctx iris.Context, httpStatus, code int, message string)
• func OK(ctx iris.Context, data interface{})
• func RegisterHealth(app *iris.Application, ready func() error)
• func RequestID(ctx iris.Context)
• func SecurityHeaders(ctx iris.Context)
• type Config
• type PartyComponent
• type Response
• type WebBaseFunc
• type WebIris
  • func Init(timeFormat, port, logLevel string, components PartyComponent) *WebIris
  • func InitWithConfig(config Config, components PartyComponent) *WebIris
  • func New(config Config, components PartyComponent) (*WebIris, error)
  • func (w *WebIris) Application() *iris.Application
  • func (w *WebIris) Ready() <-chan struct{}
  • func (w *WebIris) Run(ctx context.Context) error
  • func (w *WebIris) StaticSource(fs http.FileSystem) error

Constants

const (
	// DefaultTimeFormat 是 Web 服务未指定时间格式时使用的默认格式。
	DefaultTimeFormat = "2006-01-02 15:04:05"
	// DefaultLogLevel 是 Iris 框架日志未指定级别时使用的默认级别。
	DefaultLogLevel = "info"
	// DefaultShutdownTimeout 是优雅关闭等待存量 HTTP 请求结束的默认时长。
	DefaultShutdownTimeout = 10 * time.Second
)

const RequestIDHeader = "X-Request-ID"

RequestIDHeader 是 Request ID 透传/写入的响应头名称。

Functions

func AccessLog

func AccessLog(ctx iris.Context)

AccessLog 中间件记录方法、路径、状态码、耗时、Request ID 与客户端地址。 用法：app.Use(AccessLog)

func CORS

func CORS(allowedOrigins ...string) iris.Handler

CORS 中间件添加跨域响应头。 不传 allowedOrigins 时允许所有来源；传入时仅放行匹配来源；OPTIONS 预检直接返回 204。 用法：app.Use(CORS()) 或 app.Use(CORS("https://trusted.example.com"))

func Fail

func Fail(ctx iris.Context, httpStatus, code int, message string)

Fail 返回失败响应并设置 HTTP 状态码。

func OK

func OK(ctx iris.Context, data interface{})

OK 返回成功响应。

func RegisterHealth

func RegisterHealth(app *iris.Application, ready func() error)

RegisterHealth 注册存活与就绪探针端点。 /health/live 始终返回 ok；/health/ready 在 ready 回调返回错误时响应 503。

func RequestID

func RequestID(ctx iris.Context)

RequestID 中间件为每个请求生成或透传 Request ID，并写入响应头与上下文。 透传来源：请求头 X-Request-ID；业务代码可通过 ctx.Values().GetString("request_id") 读取。 用法：app.Use(RequestID)

func SecurityHeaders

func SecurityHeaders(ctx iris.Context)

SecurityHeaders 中间件添加基础安全响应头。 用法：app.Use(SecurityHeaders)

Types

type Config

type Config struct {
	Address         string        // Address 是 TCP 监听地址。
	TimeFormat      string        // TimeFormat 控制 Iris 输出时间的格式。
	LogLevel        string        // LogLevel 控制 Iris 框架日志级别。
	ShutdownTimeout time.Duration // ShutdownTimeout 限制优雅关闭的最长等待时间。
}

Config 描述 Iris Web 服务的运行参数。 Address 必须是 host:port 格式，例如 :9528、127.0.0.1:9528 或 [::1]:9528。

type PartyComponent

type PartyComponent func(app *iris.Application)

PartyComponent 用于向 Iris Application 注册路由、中间件和错误处理器。 回调仅在 WebIris 初始化时执行一次，不应在其中启动无退出机制的 goroutine。

type Response

type Response struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

Response 是统一业务响应结构。 Code 为业务码（0 表示成功），Message 为可读信息，Data 为负载。

type WebBaseFunc

type WebBaseFunc interface {
	// Run 启动 Web 服务并阻塞到启动失败、运行失败或 Context 被取消。
	Run(ctx context.Context) error
	// StaticSource 在 Web 启动前注册静态文件系统。
	StaticSource(fs http.FileSystem) error
}

WebBaseFunc 是 Application Starter 启动 Web 服务所依赖的最小接口。

type WebIris

type WebIris struct {
	// contains filtered or unexported fields
}

WebIris 封装 Iris Application、运行配置和生命周期状态。 同一实例只允许运行一次，关闭后需要创建新实例才能再次启动。

func Init

func Init(timeFormat, port, logLevel string, components PartyComponent) *WebIris

Init 保留原有参数式构造 API，供已有依赖项目平滑升级。 无效配置不会被忽略，而是在后续 Run 调用时记录并返回。

func InitWithConfig

func InitWithConfig(config Config, components PartyComponent) *WebIris

InitWithConfig 保留单返回值和链式调用风格。 与 New 不同，该方法把配置错误保存在实例中，由 Run 统一处理。

func New

func New(config Config, components PartyComponent) (*WebIris, error)

New 创建并校验一个 Iris Web 服务。 新代码应优先使用该方法，在应用启动前处理配置错误。

func (*WebIris) Application

func (w *WebIris) Application() *iris.Application

Application 返回底层 Iris Application，供依赖方使用 Iris 原生高级能力。 路由和中间件仍需在 Run 前完成注册。

func (*WebIris) Ready

func (w *WebIris) Ready() <-chan struct{}

Ready 返回只读启动信号。 Iris Host 真正进入 Serve 阶段后该 Channel 会关闭，调用方无需固定 Sleep。

func (*WebIris) Run

func (w *WebIris) Run(ctx context.Context) error

Run 构建路由、监听 TCP 端口并阻塞等待服务退出。 Context 取消后执行限时优雅关闭，启动和关闭错误都会记录日志并返回调用方。

func (*WebIris) StaticSource

func (w *WebIris) StaticSource(fs http.FileSystem) error

StaticSource 将文件系统注册到根路径，用于提供 SPA 或其他静态资源。 该方法必须在 Run 前调用；启动后修改路由会直接返回错误。