一个现代、简单、快速且灵活的微框架，用于在 OpenAPI 3 和 JSON Schema 支持的 Go 中构建 HTTP REST/RPC API。国际音标发音：/'hjuːmɑ/。该项目的目标是提供：
- 拥有现有服务的团队逐步采用
- 带上您自己的路由器（包括 Go 1.22+）、中间件和日志记录/指标
- 可扩展的 OpenAPI 和 JSON Schema 层来记录现有路由
- 适合 Go 开发人员的现代 REST 或 HTTP RPC API 后端框架
- 防止常见错误的护栏
- 不会过时的文档
- 生成的高质量开发人员工具
特点包括：
- 您选择的路由器之上的声明式接口：
- 操作和模型文档
- 请求参数（路径、查询、标头或 cookie）
- 请求正文
- 响应（包括错误）
- 响应标头
- 使用RFC9457和默认情况下的JSON 错误
application/problem+json（但可以更改） - 每个操作的请求大小限制与合理的默认值
- 服务器和客户端之间的 内容协商
- 条件请求支持，例如
If-Match或If-Unmodified-Sinceheader 实用程序。 - 可选的自动生成
PATCH操作支持： - 输入和输出模型的带注释的 Go 类型
- 从 Go 类型生成 JSON 模式
- 路径/查询/标头参数、正文、响应标头等的静态类型。
- 自动输入模型验证和错误处理
- 使用Stoplight Elements生成文档
- 可选的内置 CLI，通过参数或环境变量进行配置
-p 8000通过例如、--port=8000、 或设置SERVICE_PORT=8000- 内置启动操作和正常关闭
- 生成 OpenAPI 以访问丰富的工具生态系统
- 使用API Sprout或Prism进行模拟
- 带有OpenAPI Generator或oapi-codegen 的SDK
- CLI 与Restish
- 还有更多
- 使用可选
describedby链接关系标头以及$schema返回对象中的可选属性为每个资源生成 JSON 架构，这些属性集成到编辑器中以进行验证和完成。
该项目的灵感来自FastAPI。标志和品牌由卡里·泰勒设计。
非常感谢我们现任和前任的赞助商：
这是迄今为止我最喜欢的 Go Web 框架。它受到 FastAPI 的启发，这也很棒，并且符合常见 Web 事物的许多 RFC...我真的很喜欢这个功能集，它[可以使用] Chi，而且它在某种程度上仍然相对简单使用。我尝试过其他框架，但它们并没有给我带来快乐。 - Jeb_Jenky
使用 #Golang 一年多后，我偶然发现了 Huma，一个受 #FastAPI 启发的 Web 框架。这就是我一直期盼的圣诞奇迹！这个框架什么都有！- Hana Mohan
我爱胡玛。真诚地感谢您提供这个很棒的包裹。我已经使用它有一段时间了，效果非常好！ - plscott
谢谢丹尼尔为胡玛。非常有用的项目，并且由于 OpenAPI gen 为我们节省了大量的时间和麻烦——类似于 Python 中的 FastAPI。 - WolvesOfAllStreets
Huma 很棒，我最近开始使用它，很高兴，所以非常感谢您的努力🙏 - callmemicah
通过安装go get。请注意，需要 Go 1.20 或更高版本。
# After: go mod init ...
go get -u github.com/danielgtaylor/huma/v2这是 Huma 中的一个完整的基本 hello world 示例，展示了如何使用 CLI 初始化 Huma 应用程序、声明资源操作并定义其处理函数。
package main
import (
"context"
"fmt"
"net/http"
"github.com/danielgtaylor/huma/v2"
"github.com/danielgtaylor/huma/v2/adapters/humachi"
"github.com/danielgtaylor/huma/v2/humacli"
"github.com/go-chi/chi/v5"
_ "github.com/danielgtaylor/huma/v2/formats/cbor"
)
// Options for the CLI. Pass `--port` or set the `SERVICE_PORT` env var.
type Options struct {
Port int `help:"Port to listen on" short:"p" default:"8888"`
}
// GreetingOutput represents the greeting operation response.
type GreetingOutput struct {
Body struct {
Message string `json:"message" example:"Hello, world!" doc:"Greeting message"`
}
}
func main() {
// Create a CLI app which takes a port option.
cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
// Create a new router & API
router := chi.NewMux()
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
// Add the operation handler to the API.
huma.Get(api, "/greeting/{name}", func(ctx context.Context, input *struct{
Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
}) (*GreetingOutput, error) {
resp := &GreetingOutput{}
resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
return resp, nil
})
// Tell the CLI how to start your router.
hooks.OnStart(func() {
http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
})
})
// Run the CLI. When passed no commands, it starts the server.
cli.Run()
}Tip
替换chi.NewMux()→http.NewServeMux()和humachi.New→humago.New以使用 Go 1.22+ 中的标准库路由器。只需确保其中列出了您的或更新的go.mod版本即可。go 1.22其他一切都保持不变！当你准备好时就切换。
你可以用 go run greet.go 测试它（可选地传递 '--port' 来更改默认值），并使用 Restish（或 curl） 发出示例请求：
# Get the message from the server
$ restish :8888/greeting/world
HTTP/1.1 200 OK
...
{
$schema: "http://localhost:8888/schemas/GreetingOutputBody.json",
message: "Hello, world!"
}尽管示例很小，您也可以在http://localhost:8888/docs上看到一些生成的文档。生成的 OpenAPI 可在http://localhost:8888/openapi.json或http://localhost:8888/openapi.yaml获取。
查看Huma 教程，获取入门分步指南。
请参阅https://huma.rocks/网站，获取演示文稿中的完整文档，该演示文稿比本自述文件更易于导航和搜索。您可以在`docs`此存储库的目录中找到该站点的源代码。
官方 Go 包文档始终可以在 https://pkg.go.dev/github.com/danielgtaylor/huma/v2 找到。
- Go 中的 API 与 Huma 2.0
- 减少 Go 依赖：Huma 中减少依赖的案例研究
- 在 Twitter/X 上分享的 Golang 新闻、库和工作
- Go Weekly #495 & #498精选
- Bump.sh 从 Huma 部署文档
- 使用泛型的可组合 HTTP 处理程序中提到
如果您觉得该项目有用，请务必为该项目加注星标！