<a name="intro"></a> Huma是一个现代、简单、快速且灵活的微框架，用于在Go中构建基于OpenAPI 3和JSON Schema的HTTP REST/RPC API。发音为IPA：/'hjuːmɑ/。该项目的目标是提供：

适用于具有现有服务的团队的渐进式采用
- 可使用自己的路由器（包括Go 1.22+）、中间件和日志/指标
- 可扩展的OpenAPI和JSON Schema层，用于记录现有路由
面向Go开发者的现代REST或HTTP RPC API后端框架
- 由OpenAPI 3.1和JSON Schema描述
防止常见错误的护栏
永不过时的文档
高质量生成的开发者工具

功能包括：

基于您选择的路由器的声明式接口：
- 操作和模型文档
- 请求参数（路径、查询、标头或cookie）
- 请求体
- 响应（包括错误）
- 响应标头
默认使用RFC9457和application/problem+json的JSON错误（但可以更改）
具有合理默认值的每个操作请求大小限制
服务器和客户端之间的内容协商
- 默认配置下通过Accept标头支持JSON（RFC 8259）和可选的CBOR（RFC 7049）内容类型。
条件请求支持，例如If-Match或If-Unmodified-Since标头实用工具。
可选的自动生成PATCH操作，支持：
- RFC 7386 JSON合并补丁
- RFC 6902 JSON补丁
- Shorthand补丁
用于输入和输出模型的带注释的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设计。

赞助商

衷心感谢我们当前和以前的赞助商！

<div> <img width="1000" height="0" /> <a href="https://zuplo.link/huma-gh "> <picture>  <img src="https://github.com/user-attachments/assets/aace5aa7-32bd-45cf-a8f8-2e352feaf017" alt="Zuplo" width="260" align="right"> </picture> </a> <h3>Zuplo：扩展、保护和产品化您的Huma API</h3> <p> 我们的API网关允许您保护API，全球扩展，从OpenAPI生成文档，并对用户进行货币化。 </p> <a href="https://zuplo.link/huma-gh ">免费开始</a> </div> <hr/>

用户评价

这是迄今为止我最喜欢的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 教程获取入门的分步指南。