注解参考

简介

Hiboot 使用结构体标签（注解）来配置控制器、依赖注入和 Swagger 文档。本参考文档记录了 at 包中所有可用的注解。

控制器注解

at.RestController

将结构体标记为 REST 控制器：

type userController struct {
	at.RestController
}

at.RequestMapping

定义控制器中所有方法的基础 URL 路径：

type userController struct {
	at.RestController
	at.RequestMapping `value:"/api/users"`
}

HTTP 方法注解

at.GetMapping

将方法映射到 HTTP GET：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
	},
	id uint64,
) (model.Response, error) {
	// 处理 GET /api/users/{id}
}

at.PostMapping

将方法映射到 HTTP POST：

func (c *userController) CreateUser(
	at struct {
		at.PostMapping `value:"/"`
	},
	request *CreateUserRequest,
) (model.Response, error) {
	// 处理 POST /api/users/
}

at.PutMapping

将方法映射到 HTTP PUT：

func (c *userController) UpdateUser(
	at struct {
		at.PutMapping `value:"/{id}"`
	},
	id uint64,
	request *UpdateUserRequest,
) (model.Response, error) {
	// 处理 PUT /api/users/{id}
}

at.DeleteMapping

将方法映射到 HTTP DELETE：

func (c *userController) DeleteUser(
	at struct {
		at.DeleteMapping `value:"/{id}"`
	},
	id uint64,
) (model.Response, error) {
	// 处理 DELETE /api/users/{id}
}

at.PatchMapping

将方法映射到 HTTP PATCH：

func (c *userController) PatchUser(
	at struct {
		at.PatchMapping `value:"/{id}"`
	},
	id uint64,
	request *PatchUserRequest,
) (model.Response, error) {
	// 处理 PATCH /api/users/{id}
}

依赖注入注解

inject

按类型或名称注入依赖：

type userController struct {
	at.RestController

	// 按类型注入
	UserService *service.UserService `inject:""`

	// 按名称注入
	PrimaryDB *gorm.DB `inject:"primaryDatabase"`
}

value

注入配置值：

type Config struct {
	AppName  string `value:"${app.name}"`
	Port     int    `value:"${server.port}"`
	LogLevel string `value:"${logging.level:info}"` // 带默认值
}

default

为字段设置默认值：

type Config struct {
	Timeout int    `default:"30"`
	Host    string `default:"localhost"`
	Enabled bool   `default:"true"`
}

Swagger/OpenAPI 注解

at.Operation

描述 API 操作：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
		at.Operation  `id:"getUserById" description:"根据 ID 获取用户"`
	},
	id uint64,
) (model.Response, error) {
	// ...
}
属性 描述
id 操作 ID（唯一）
description 操作描述
summary 简短摘要
tags 用于分组的 API 标签

at.Produces

指定响应内容类型：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
		at.Produces   `values:"application/json"`
	},
	id uint64,
) (model.Response, error) {
	// ...
}

at.Consumes

指定请求内容类型：

func (c *userController) CreateUser(
	at struct {
		at.PostMapping `value:"/"`
		at.Consumes    `values:"application/json"`
	},
	request *CreateUserRequest,
) (model.Response, error) {
	// ...
}

at.Parameter

描述参数：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
		Parameters    struct {
			Id struct {
				at.Parameter `name:"id" in:"path" type:"integer" description:"用户 ID" required:"true"`
			}
		}
	},
	id uint64,
) (model.Response, error) {
	// ...
}
属性 描述
name 参数名称
in 位置：path、query、header、body
type 数据类型
description 参数描述
required 是否必需

at.Response

描述 API 响应：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
		Responses     struct {
			Success struct {
				at.Response `code:"200" description:"成功"`
			}
			NotFound struct {
				at.Response `code:"404" description:"用户不存在"`
			}
		}
	},
	id uint64,
) (model.Response, error) {
	// ...
}
属性 描述
code HTTP 状态码
description 响应描述

at.Schema

描述响应模式：

func (c *userController) GetUser(
	at struct {
		at.GetMapping `value:"/{id}"`
		Responses     struct {
			Success struct {
				at.Response `code:"200" description:"成功"`
				at.Schema   `type:"object" ref:"User"`
			}
		}
	},
	id uint64,
) (model.Response, error) {
	// ...
}

配置注解

mapstructure

将 YAML 配置映射到结构体字段：

type configuration struct {
	app.Configuration

	DatabaseProps Properties `mapstructure:"database"`
}

在 application.yml 中：

database:
  host: localhost
  port: 5432

after

指定配置加载顺序：

type configuration struct {
	app.Configuration `after:"databaseConfiguration"`
}

missing

条件配置加载：

type configuration struct {
	app.Configuration `missing:"customConfiguration"`
}

CLI 命令注解

cli.RootCommand

将结构体标记为根 CLI 命令：

type RootCommand struct {
	cli.RootCommand
}

cli.SubCommand

将结构体标记为子命令：

type userCommand struct {
	cli.SubCommand
}

完整示例

package controller

import (
	"github.com/hidevopsio/hiboot/pkg/app"
	"github.com/hidevopsio/hiboot/pkg/at"
	"github.com/hidevopsio/hiboot/pkg/model"
)

type userController struct {
	at.RestController
	at.RequestMapping `value:"/api/users"`

	userService UserService `inject:""`
	appName     string      `value:"${app.name}"`
}

func init() {
	app.Register(newUserController)
}

func newUserController(userService UserService) *userController {
	return &userController{
		userService: userService,
	}
}

// GetById 处理 GET /api/users/{id}
func (c *userController) GetById(
	at struct {
		at.GetMapping `value:"/{id}"`
		at.Operation  `id:"getUserById" description:"根据 ID 获取用户"`
		at.Produces   `values:"application/json"`
		Parameters    struct {
			Id struct {
				at.Parameter `name:"id" in:"path" type:"integer" description:"用户 ID" required:"true"`
			}
		}
		Responses struct {
			Success struct {
				at.Response `code:"200" description:"找到用户"`
			}
			NotFound struct {
				at.Response `code:"404" description:"用户不存在"`
			}
		}
	},
	id uint64,
) (model.Response, error) {
	user, err := c.userService.GetUser(id)
	if err != nil {
		response := new(model.BaseResponse)
		response.SetCode(404)
		return response, nil
	}

	response := new(model.BaseResponse)
	response.SetData(user)
	return response, nil
}

下一步