Web Server

mhttp 是 Maltose 的 HTTP 服务器组件，基于 Gin 封装，补上了控制器绑定、标准响应、OpenAPI、指标和链路追踪等常用能力。

快速开始

package main

import "github.com/graingo/maltose/net/mhttp"

func main() {
    s := mhttp.New()

    s.GET("/ping", func(r *mhttp.Request) {
        r.String(200, "pong")
    })

    s.Run()
}

默认能力

mhttp.New() 会自动注册：

• Trace 中间件
• Recovery 中间件
• Metric 中间件
• DefaultResponse 中间件

如果需要统一 JSON 响应格式，再额外挂载：

s.Use(mhttp.MiddlewareResponse())

主要配置项

配置项	默认值	说明
address	8080	监听地址，运行时会规范化为 :8080
server_name	default	服务名
server_locale	zh	校验翻译语言
read_timeout	60s	读超时
write_timeout	60s	写超时
idle_timeout	60s	空闲超时
max_header_bytes	1048576	请求头大小上限
health_check	/health	健康检查路径
graceful_enable	true	是否启用优雅停机
graceful_timeout	30s	优雅停机超时
graceful_wait_time	5s	停机前等待中的连接缓冲时间
openapi_path	空	已加载 OpenAPI 文档的 HTTP 路径
openapi_file	空	文档文件；同时读取同名 .manifest.json
swagger_path	空	Swagger UI 路径
print_routes	false	是否打印路由

Run() 和 m.App 管理的 Start/Stop 使用同一套关闭逻辑。关闭优雅停机后，框架直接关闭连接；启用时会先等待 graceful_wait_time，再在调用方 context 与 graceful_timeout 中较早到期的时间内执行 Shutdown。

配置方式

直接设置

s := mhttp.New()
s.SetAddress(":9000")
s.SetServerName("my-app")

批量设置

s := mhttp.New()

if err := s.SetConfigWithMap(map[string]any{
    "address":       ":9000",
    "server_name":   "my-app",
    "read_timeout":  "5s",
    "write_timeout": "10s",
    "openapi_path":  "/api.json",
    "swagger_path":  "/swagger",
}); err != nil {
    panic(err)
}

常用扩展

静态文件

s.SetStaticPath("/assets", "./static")

PProf

s.EnablePProf()
// 或者
s.EnablePProf("/debug/pprof")

HTTP 测试

Server 实现了 http.Handler，无需占用固定端口：

server := mhttp.New()
server.GET("/ping", func(r *mhttp.Request) {
    r.String(http.StatusOK, "pong")
})

testServer := httptest.NewServer(server.Handler())
defer testServer.Close()

需要自行分配监听地址时，可调用 StartListener(ctx, listener)。

下一步

• 路由与控制器绑定：路由
• 响应统一包装：标准响应
• 自定义横切逻辑：中间件

启用文档前，从文件或 embed 加载 CLI 生成的文档和清单。完整声明、迁移和扩展方式见 API 契约。