Golang高效生成OpenAPI 3规范的Web框架插件Fuego的使用

Fuego是一个为忙碌的Go开发者设计的框架，它能自动从代码生成OpenAPI 3规范文档，而无需依赖注释或YAML文件。

主要特性

• 自动生成OpenAPI文档：直接从代码生成，无需额外注释
• 100%兼容net/http：可以无缝使用任何http.Handler中间件
• 内置路由：基于Go 1.22 net/http的路由系统
• 自动序列化/反序列化：支持JSON、XML和HTML表单
• 内置验证：基于go-playground/validator的验证系统
• 数据转换：通过InTransform和OutTransform接口实现
• 中间件支持：兼容标准net/http中间件
• 错误处理：遵循RFC 9457标准
• 渲染支持：内置html/template支持

快速入门示例

Hello World示例

package main

import "github.com/go-fuego/fuego"

func main() {
	s := fuego.NewServer()

	fuego.Get(s, "/", func(c fuego.ContextNoBody) (string, error) {
		return "Hello, World!", nil
	})

	s.Run()
}

简单POST请求示例

package main

import "github.com/go-fuego/fuego"

type MyInput struct {
	Name string `json:"name" validate:"required"`
}

type MyOutput struct {
	Message string `json:"message"`
}

func main() {
	s := fuego.NewServer()

	// 自动为这个路由生成OpenAPI文档
	fuego.Post(s, "/user/{user}", myController)

	s.Run()
}

func myController(c fuego.ContextWithBody[MyInput]) (*MyOutput, error) {
	body, err := c.Body()
	if err != nil {
		return nil, err
	}

	return &MyOutput{Message: "Hello, " + body.Name}, nil
}

数据转换和自定义验证

type MyInput struct {
	Name string `json:"name" validate:"required"`
}

// 在返回c.Body()之前调用
func (r *MyInput) InTransform(context.Context) error {
	r.Name = strings.ToLower(r.Name)

	if r.Name == "fuego" {
		return errors.New("fuego is not a valid name for this input")
	}

	return nil
}

完整OpenAPI文档示例

package main

import (
	"github.com/go-fuego/fuego"
	"github.com/go-fuego/fuego/option"
	"github.com/go/fuego/param"
)

func main() {
	s := fuego.NewServer()

	// 自定义OpenAPI选项
	fuego.Post(s, "/", myController,
		option.Description("This route does something..."),
		option.Summary("This is my summary"),
		option.Tags("MyTag"), // 根据返回类型自动设置标签(可禁用)
		option.Deprecated(),  // 在OpenAPI规范中标记为弃用

		option.Query("name", "Declares a query parameter with default value", param.Default("Carmack")),
		option.Header("Authorization", "Bearer token", param.Required()),
		optionPagination,
		optionCustomBehavior,
	)

	s.Run()
}

var optionPagination = option.Group(
	option.QueryInt("page", "Page number", param.Default(1), param.Example("1st page", 1), param.Example("42nd page", 42)),
	option.QueryInt("perPage", "Number of items per page"),
)

var optionCustomBehavior = func(r *fuego.BaseRoute) {
	r.XXX = "YYY"
}

标准库兼容示例

package main

import (
	"net/http"

	"github.com/go-fuego/fuego"
)

func main() {
	s := fuego.NewServer()

	// 标准net/http中间件
	fuego.Use(s, func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.Header().Set("X-Hello", "World")
			next.ServeHTTP(w, r)
		})
	})

	// 标准net/http处理器，自动生成OpenAPI路由声明
	fuego.GetStd(s, "/std", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello, World!"))
	})

	s.Run()
}

完整示例

package main

import (
	"context"
	"errors"
	"net/http"
	"strings"

	chiMiddleware "github.com/go-chi/chi/v5/middleware"
	"github.com/go-fuego/fuego"
	"github.com/rs/cors"
)

type Received struct {
	Name string `json:"name" validate:"required"`
}

type MyResponse struct {
	Message       string `json:"message"`
	BestFramework string `json:"best"`
}

func main() {
	s := fuego.NewServer(
		fuego.WithAddr("localhost:8088"),
	)

	fuego.Use(s, cors.Default().Handler)
	fuego.Use(s, chiMiddleware.Compress(5, "text/html", "text/css"))

	// Fuego处理器，自动生成OpenAPI、验证、(反)序列化和错误处理
	fuego.Post(s, "/", func(c fuego.ContextWithBody[Received]) (MyResponse, error) {
		data, err := c.Body()
		if err != nil {
			return MyResponse{}, err
		}

		c.Response().Header().Set("X-Hello", "World")

		return MyResponse{
			Message:       "Hello, " + data.Name,
			BestFramework: "Fuego!",
		}, nil
	})

	// 标准net/http处理器，自动生成OpenAPI路由声明
	fuego.GetStd(s, "/std", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello, World!"))
	})

	s.Run()
}

// 在使用c.Body()时调用InTransform
// 可用于转换实体和引发自定义错误
func (r *Received) InTransform(context.Context) error {
	r.Name = strings.ToLower(r.Name)
	if r.Name == "fuego" {
		return errors.New("fuego is not a name")
	}
	return nil
}

// 在发送数据前调用OutTransform
func (r *MyResponse) OutTransform(context.Context) error {
	r.Message = strings.ToUpper(r.Message)
	return nil
}

使用Fuego的优势

1. 从代码自动生成OpenAPI文档，无需维护额外文件
2. 内置数据验证和转换功能
3. 完全兼容标准net/http
4. 简化API开发流程
5. 提供丰富的OpenAPI定制选项

Fuego特别适合需要快速开发API并自动生成文档的项目，它减少了开发者的重复工作，同时保持了Go标准库的兼容性。