访问官网
Github
Huggingface
文档
论文
Huma是一个现代、简单、快速且灵活的微框架，用于在Go中构建基于OpenAPI 3和JSON Schema的HTTP REST/RPC API。发音为IPA：/'hjuːmɑ/。该项目的目标是提供：
- 适用于具有现有服务的团队的渐进式采用
- 可使用自己的路由器（包括Go 1.22+）、中间件和日志/指标
- 可扩展的OpenAPI和JSON Schema层，用于记录现有路由
- 面向Go开发者的现代REST或HTTP RPC API后端框架
- 防止常见错误的护栏
- 永不过时的文档
- 高质量生成的开发者工具
功能包括：
- 基于您选择的路由器的声明式接口：
- 操作和模型文档
- 请求参数（路径、查询、标头或cookie）
- 请求体
- 响应（包括错误）
- 响应标头
- 默认使用RFC9457和
application/problem+json的JSON错误（但可以更改） - 具有合理默认值的每个操作请求大小限制
- 服务器和客户端之间的内容协商
- 条件请求支持，例如
If-Match或If-Unmodified-Since标头实用工具。 - 可选的自动生成
PATCH操作，支持： - 用于输入和输出模型的带注释的Go类型
- 从Go类型生成JSON Schema
- 路径/查询/标头参数、正文、响应标头等的静态类型
- 自动输入模型验证和错误处理
- 使用Stoplight Elements生成文档
- 可选的内置CLI，通过参数或环境变量配置
- 可通过例如
-p 8000、--port=8000或SERVICE_PORT=8000设置 - 内置启动动作和优雅关闭
- 可通过例如
- 生成OpenAPI以访问丰富的工具生态系统
- 使用API Sprout或Prism进行模拟
- 使用OpenAPI Generator或oapi-codegen生成SDK
- 使用Restish生成CLI
- 以及更多工具
- 为每个资源生成JSON Schema，使用可选的
describedby链接关系标头以及返回对象中的可选$schema属性，集成到编辑器中进行验证和完成。
该项目受到FastAPI的启发。标志和品牌由Kari Taylor设计。
赞助商
衷心感谢我们当前和以前的赞助商！
用户评价
这是迄今为止我最喜欢的Go Web框架。它受到FastAPI的启发，同样出色，并符合许多Web相关的RFC ... 我非常喜欢它的功能集，它可以使用Chi，而且仍然相对简单易用。我尝试过其他框架，但它们都不能让我感到愉悦。 - Jeb_Jenky
使用#Golang一年多后，我偶然发现了Huma，这个受#FastAPI启发的Web框架。这简直是我一直期待的圣诞奇迹！这个框架拥有一切！ - Hana Mohan
我喜欢Huma。衷心感谢您提供这个出色的包。我已经使用它一段时间了，体验非常棒！ - plscott
感谢Daniel开发Huma。这是一个非常有用的项目，由于OpenAPI生成功能，为我们节省了大量时间和麻烦 — 类似于Python中的FastAPI。 - WolvesOfAllStreets
Huma非常棒，我最近开始使用它，使用体验非常愉快，非常感谢您的努力🙏 - callmemicah
我们用了3个月的时间用Python、FastAPI和SQL Alchemy构建我们的平台，但只用了3周就用Go、Huma和SQL C重写了它。一切都运行得很好，我很少需要调试，而在Python中我大部分时间都在调试。 - Bitclick_
安装
通过go get安装。注意，需要Go 1.20或更新版本。
# 在执行了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"
)
// CLI 的选项。可通过 `--port` 传递或设置 `SERVICE_PORT` 环境变量。
type Options struct {
Port int `help:"监听端口" short:"p" default:"8888"`
}
// GreetingOutput 表示问候操作的响应。
type GreetingOutput struct {
Body struct {
Message string `json:"message" example:"Hello, world!" doc:"问候消息"`
}
}
func main() {
// 创建一个接受端口选项的 CLI 应用。
cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
// 创建新的路由器和 API
router := chi.NewMux()
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
// 将操作处理器添加到 API。
huma.Get(api, "/greeting/{name}", func(ctx context.Context, input *struct{
Name string `path:"name" maxLength:"30" example:"world" doc:"要问候的名字"`
}) (*GreetingOutput, error) {
resp := &GreetingOutput{}
resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
return resp, nil
})
// 告诉 CLI 如何启动路由器。
hooks.OnStart(func() {
http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
})
})
// 运行 CLI。当没有传递命令时，它会启动服务器。
cli.Run()
}
[!提示] 将
chi.NewMux()替换为http.NewServeMux()，将humachi.New替换为humago.New，即可使用 Go 1.22+ 的标准库路由器。只需确保您的go.mod中列出了go 1.22或更新版本。其他一切保持不变！随时可以切换。
您可以使用 go run greet.go 测试它（可选择传递 --port 来更改默认值），并使用 Restish（或 curl）发送示例请求：
# 从服务器获取消息
$ 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/ 网站获取完整文档，该网站比此 README 更易于导航和搜索。您可以在此仓库的 docs 目录中找到网站源代码。
官方 Go 包文档始终可在 https://pkg.go.dev/github.com/danielgtaylor/huma/v2 找到。
文章与提及
- 使用 Huma 2.0 开发 Go 语言 API
- 减少 Go 依赖：Huma 中依赖减少的案例研究
- 在 Twitter/X 上分享的 Golang 新闻、库与工作
- 在 Go Weekly #495 和 #498 中被推荐
- Bump.sh 从 Huma 部署文档
- 在 使用泛型的可组合 HTTP 处理器 中被提及
如果您觉得项目有用，请给它加星！
